claude-code - 💡(How to fix) Fix [DOCS] Background session isolation docs omit non-git `WorktreeCreate` hook behavior

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"How file edits are isolated" in the background sessions / agent view docs

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 the worktree when:

• The session is already inside a linked git worktree, whether Claude created it under .claude/worktrees/ or you created it with git worktree add somewhere else
• The working directory isn't a git repository
• The write is outside the working directory

Outside a git repository, sessions write to the working directory directly and aren't isolated from each other, so avoid dispatching parallel sessions that edit the same files.

What's Wrong or Missing?

This section only describes git repositories and plain non-git directories. It does not explain how background-session isolation behaves when a project uses a non-git VCS and configures a WorktreeCreate hook.

That omission now makes the page misleading: the current wording implies that background sessions always skip isolation whenever the directory is not a git repository, even though Claude Code also documents WorktreeCreate hooks for SVN, Perforce, Mercurial, and other non-git setups.

For the v2.1.144 background-session isolation change, users need explicit guidance on whether the isolation guard applies when WorktreeCreate is configured, what behavior to expect before EnterWorktree, and when worktree.bgIsolation: "none" is still the right setting.

Suggested Improvement

Update the agent-view page so the isolation rules cover non-git VCS repositories with WorktreeCreate hooks configured.

At minimum:

1. Revise the "Claude skips the worktree when" list so it does not imply that every non-git repository bypasses isolation.
2. Add a short note explaining the background-session behavior when WorktreeCreate is present for non-git VCS users.
3. Cross-link the non-git VCS hook documentation from the background-session isolation section.
4. Clarify how this interacts with worktree.bgIsolation: "none".

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

This appears to need a docs update tied to the v2.1.144 background-session isolation change for non-git VCS users with WorktreeCreate hooks configured.