claude-code - 💡(How to fix) Fix [DOCS] Subagent docs omit working-directory isolation and `cwd:` override behavior [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

Supported frontmatter fields and the interaction between subagent isolation and the parent session's Bash working directory

Current Documentation

The docs currently say:

The frontmatter defines the subagent's metadata and configuration. The body becomes the system prompt that guides the subagent's behavior. Subagents receive only this system prompt (plus basic environment details like working directory), not the full Claude Code system prompt.

| isolation | No | Set to worktree to run the subagent in a temporary git worktree, giving it an isolated copy of the repository. The worktree is automatically cleaned up if the subagent makes no changes |

And the worktree guide says:

Subagents can also use worktree isolation to work in parallel without conflicts. Ask Claude to "use worktrees for your agents" or configure it in a custom subagent by adding isolation: worktree to the agent's frontmatter. Each subagent gets its own worktree that is automatically cleaned up when the subagent finishes without changes.

And the Bash tool reference says:

The Bash tool runs each command in a separate process with the following persistence behavior:

• Working directory persists across commands. Set CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 to reset to the project directory after each command.

No documentation currently explains whether a subagent's worktree or working-directory override is scoped only to that subagent, and the subagent docs do not document a cwd: override at all.

What's Wrong or Missing?

Changelog v2.1.97 includes this fix:

Fixed subagents with worktree isolation or cwd: override leaking their working directory back to the parent session's Bash tool

The current docs describe subagent worktree isolation and Bash working-directory persistence separately, but they never document the expected boundary between them.

A. Missing scoping contract

Users need an explicit statement that a subagent's working directory is local to that subagent. Running a subagent in a worktree should not change the parent session's Bash working directory after the subagent finishes.

B. Missing cwd: override documentation

The changelog references a subagent cwd: override, but the sub-agents page does not explain where that override can be set, what values it accepts, or how it interacts with isolation: worktree and the parent session.

Suggested Improvement

Add a short "Working directory behavior" subsection to sub-agents and cross-link it from common-workflows and tools-reference.

That subsection should document:

1. isolation: worktree changes the working directory only inside the subagent.
2. Any subagent cwd: override is also scoped to the subagent and does not modify the parent session's Bash working directory.
3. After a subagent exits, the parent session's Bash tool continues from its own prior working directory unless CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 resets it.
4. If cwd: override is only available in specific contexts (for example SDK or programmatic agent definitions), say that explicitly and link to the relevant reference.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 7 pages affected

Source: Changelog v2.1.97

Exact changelog entry: Fixed subagents with worktree isolation or \cwd:` override leaking their working directory back to the parent session's Bash tool`