claude-code - 💡(How to fix) Fix [DOCS] Background session docs omit worktree-isolation behavior for spawned subagents

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-view

Section/Topic

"How file edits are isolated" and the interaction between background sessions and subagents.

Current Documentation

The Agent View page says background sessions isolate file edits before writing:

Every background session, whether started from agent view, /bg, or claude --bg, starts in your working directory. Before editing files, Claude moves the session into an isolated git worktree under .claude/worktrees/, so parallel sessions can read the same checkout but each writes to its own.

It also says backgrounded sessions can start subagents:

Once in the background, the session can start new subagents, monitors, and background commands, and those keep running across later detach and reattach.

The Subagents page documents background subagents, but only covers permission behavior:

Background subagents run concurrently while you continue working. They run with the permissions already granted in the session and auto-deny any tool call that would otherwise prompt.

What's Wrong or Missing?

Claude Code v2.1.154 fixed subagents in background sessions bypassing the worktree-isolation guard and writing to the shared checkout.

The current docs document background-session worktree isolation and subagent background execution separately, but they do not state what happens when those features overlap:

A. Subagent file-write isolation inside background sessions is not explicit

Users can see that a background session should move into an isolated worktree before editing, but the docs do not say that subagents spawned by that background session are also covered by the same guard before they write files.

B. The shared-checkout failure mode is not ruled out

The release fix shows that a background-session subagent could previously bypass the guard and write to the shared checkout. The docs do not clearly state the intended current behavior: with worktree.bgIsolation at its default, background-session subagents should not edit the shared checkout directly.

C. The worktree.bgIsolation: "none" exception is ambiguous for subagents

The settings page says "none" lets background jobs edit the working copy directly, but it does not explicitly say whether "background jobs" includes subagents spawned from a background session. Users need to know whether disabling isolation applies to the whole background-session process tree, including subagents.

Suggested Improvement

Add a short note to Agent View's "How file edits are isolated" section:

Subagents spawned by a background session use the same worktree-isolation guard as the parent background session. With the default worktree.bgIsolation: "worktree" behavior, a background-session subagent must enter the session's isolated worktree before it can edit files under the repository, so it does not write to the shared checkout directly. If worktree.bgIsolation is set to "none", subagents spawned by that background session may edit the working copy directly along with the parent session.

Also add a cross-reference from the Subagents page's "Run subagents in foreground or background" section so users looking at background subagents can discover the file-isolation behavior.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version context: Claude Code v2.1.154 release entry: "Fixed subagents in background sessions bypassing the worktree-isolation guard and writing to the shared checkout."