[DOCS] Worktree-isolated subagents docs do not state that shell commands now run inside the subagent's own worktree (v2.1.203)

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/worktrees

Section/Topic

The "Isolate subagents with worktrees" section of worktrees.md, and the matching isolation: worktree row in the frontmatter table of https://code.claude.com/docs/en/sub-agents.

Current Documentation

From the "Isolate subagents with worktrees" section of https://code.claude.com/docs/en/worktrees:

Subagents can run in their own worktrees so parallel edits don't conflict. Ask Claude to "use worktrees for your agents", or set it permanently on a custom subagent by adding isolation: worktree to the frontmatter. Each subagent gets a temporary worktree that is removed automatically when the subagent finishes without changes.

From the supported-frontmatter table on https://code.claude.com/docs/en/sub-agents:

isolation | No | Set to worktree to run the subagent in a temporary git worktree, giving it an isolated copy of the repository branched by default from your default branch rather than the parent session's HEAD. The worktree is automatically cleaned up if the subagent makes no changes

The current prose describes "an isolated copy of the repository" and "parallel edits don't conflict" but never states explicitly that Bash and PowerShell tool calls inside a worktree-isolated subagent resolve their working directory from the subagent's worktree rather than from the parent session's checkout. Nothing in the page calls out which tool surfaces (file edits, Bash, PowerShell, MCP shell commands) are inside the isolation boundary.

What's Wrong or Missing?

A. The v2.1.203 shell-command path correction is not reflected anywhere

The v2.1.203 changelog states:

Fixed worktree-isolated subagents sometimes running shell commands in the parent checkout instead of their own worktree

Before v2.1.203, a subagent that opted into isolation: worktree could still see Bash and PowerShell tool calls resolve against the parent session's checkout. File edits were isolated, but shell commands could run in the wrong directory, which is exactly the failure mode the isolation name is supposed to prevent. After v2.1.203 the shell-command path also resolves inside the subagent's own worktree.

The worktrees page only frames the feature in terms of "parallel edits don't conflict", which undersells what the fix actually delivers and gives no operator a way to learn that the gap existed and was closed in v2.1.203. Users who hit a "command ran in the wrong checkout" symptom before v2.1.203 have no doc entry to point them at, and users adopting isolation: worktree after v2.1.203 have no explicit guarantee that shell commands are now inside the boundary.

B. The frontmatter row never mentions which tool surfaces are isolated

The isolation: worktree row in sub-agents.md lists two behaviors: an isolated copy of the repository branched from the default branch, and automatic cleanup when no changes were made. It says nothing about whether the isolation covers Bash and PowerShell tool calls or only file edits through Read/Write/Edit. Without that, an author who picks isolation: worktree for a subagent that runs npm test, pytest, or a build script cannot tell from the docs whether the script runs against the subagent's worktree or the parent's checkout.

C. The worktrees page does not cross-reference the v2.1.203 behavior

The same page already calls out other version-gated behaviors inline, for example:

{/ min-version: 2.1.198 /}As of v2.1.198, entering or exiting a worktree also relocates the session transcript to that directory's project storage, the same way /cd does {/ min-version: 2.1.200 /}Plugins installed at project scope from the main checkout also load in worktrees of the same repository, so you don't need to reinstall them per worktree

The v2.1.203 shell-command fix is the kind of user-visible correction that warrants a parallel inline note next to the "Isolate subagents with worktrees" section, and the page does not have one.

Suggested Improvement

Add a {/* min-version: 2.1.203 */} note immediately under the "Isolate subagents with worktrees" paragraph in worktrees.md that explicitly states the post-fix behavior:

{/ min-version: 2.1.203 /}As of v2.1.203, Bash and PowerShell tool calls inside a worktree-isolated subagent run against the subagent's worktree, not the parent session's checkout. Earlier versions could leave shell commands running in the parent checkout even when isolation: worktree was set.

Update the isolation: worktree row in the supported-frontmatter table on https://code.claude.com/docs/en/sub-agents to call out the same behavior, for example:

isolation | No | Set to worktree to run the subagent in a temporary git worktree, giving it an isolated copy of the repository branched by default from your default branch rather than the parent session's HEAD. As of v2.1.203, Bash and PowerShell tool calls run inside the worktree as well; earlier versions could leave shell commands running in the parent checkout. The worktree is automatically cleaned up if the subagent makes no changes

Also add a short clarifying sentence at the top of "Isolate subagents with worktrees" so the section name matches the actual capability:

Each subagent gets a temporary worktree that is removed automatically when the subagent finishes without changes. File edits, Bash, and PowerShell tool calls all run inside the worktree.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/worktrees | "Isolate subagents with worktrees" section never states that shell commands run inside the subagent's worktree |
| https://code.claude.com/docs/en/sub-agents | The isolation: worktree frontmatter row omits the v2.1.203 Bash/PowerShell scope clarification |

Total scope: 2 pages affected.

The v2.1.203 fix is the user-visible counterpart to the v2.1.154 fix for background sessions (issue #63315 covered that surface). The two fixes are related but distinct: v2.1.154 stopped background-session subagents from writing to the shared checkout when the parent session was not itself worktree-isolated; v2.1.203 stops worktree-isolated subagents from running shell commands in the parent checkout even when isolation is set. Both deserve explicit doc treatment so authors of isolation: worktree subagents can see what is and is not inside the boundary.

Version: v2.1.203