claude-code - 💡(How to fix) Fix [DOCS] Agent view docs still imply background sessions only reuse `.claude/worktrees/` paths

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"How file edits are isolated"

Current Documentation

The docs currently say:

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. Claude skips this when the session is already under .claude/worktrees/, when the working directory isn't a git repository, or for writes outside the working directory.

The parallel-agents overview also says:

Agent view automatically moves each dispatched session into its own worktree when it needs to edit files, and a session you're working in can spawn subagents that each get their own worktree.

What's Wrong or Missing?

This description is now too narrow after changelog v2.1.142.

The release entry says background sessions were fixed to recognize pre-existing git worktrees so Edit would no longer be blocked while EnterWorktree refused to create a duplicate. But the agent-view docs still describe the reuse condition as a path-specific special case: only directories already under .claude/worktrees/ are called out.

That leaves out a user-visible case that now works: starting or backgrounding a session from any existing linked git worktree, including manually created worktrees outside .claude/worktrees/. Readers can still infer that Claude will try to create another worktree unless they happen to be inside Claude's default .claude/worktrees/ location.

Suggested Improvement

Update the isolation description to describe behavior in terms of git worktree detection, not only the .claude/worktrees/ path.

Suggested direction:

Before:

Claude skips this when the session is already under .claude/worktrees/...

After:

Claude skips creating a new worktree when the session is already running inside an existing linked git worktree, including worktrees created manually with git worktree add or ones under .claude/worktrees/.

If the implementation still distinguishes Claude-managed worktrees from manually created ones for cleanup, add one sentence explaining that only Claude-created background-session worktrees are auto-removed when the session is deleted.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Version context: The changelog entry for v2.1.142 says: "Fixed background sessions not recognizing pre-existing git worktrees, blocking Edit while EnterWorktree refused to create a duplicate".