claude-code - 💡(How to fix) Fix [DOCS] Agent SDK docs omit `subagent_type: "claude"` worktree and output persistence behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-sdk/typescript

Section/Topic

AgentInput reference for the Agent tool, especially subagent_type and isolation.

Current Documentation

The TypeScript SDK reference currently defines the Agent tool input as:

subagent_type: string; isolation?: "worktree";

It then says:

Launches a new agent to handle complex, multi-step tasks autonomously.

The Agent SDK subagents guide also explains that Claude can spawn the built-in general-purpose subagent, but it does not describe a subagent_type: "claude" agent type or its filesystem/worktree behavior.

What's Wrong or Missing?

A. subagent_type: "claude" is not explained

The release notes for Claude Code v2.1.153 mention a fix for the Agent tool with subagent_type: 'claude', but the Agent SDK reference only documents subagent_type as an arbitrary string. Users do not have an authoritative place to learn whether "claude" is a supported built-in type, when it is used, and how it differs from general-purpose or custom subagents.

B. Worktree and output persistence expectations are not explicit

The same release note says the previous behavior involved an undocumented temporary worktree that could silently discard outputs written to gitignored paths. The docs mention isolation?: "worktree" as an option, but they do not clearly state the default working-directory behavior for subagent_type: "claude" or whether files written by that agent persist when they are gitignored or untracked.

C. SDK users need a safety boundary for generated artifacts

This matters for SDK callers that ask subagents to write reports, generated files, logs, or other artifacts that may be ignored by git. Without clear persistence guidance, users cannot tell whether those outputs are safe to write from the subagent or should be redirected to a known parent-session path.

Suggested Improvement

Add a short note near the AgentInput reference and link it from the subagents guide:

subagent_type may reference a built-in or custom subagent type. Document the built-in values, including when claude is valid. Unless isolation: "worktree" is set or another worktree isolation mode applies, subagent file writes use the documented session working-directory behavior and are not placed in an implicit temporary worktree. If worktree isolation is enabled, note how untracked and gitignored outputs are preserved or cleaned up.

Also add an SDK subagent example or note that tells users where generated files should be written when persistence matters.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version context: Claude Code v2.1.153 changelog entry: "Fixed Agent tool with subagent_type: 'claude' running in an undocumented temporary worktree, which could silently discard outputs written to gitignored paths."