claude-code - 💡(How to fix) Fix [DOCS] `worktree.bgIsolation` setting missing from settings docs and agent-view still describes worktree isolation as unconditional

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Worktree settings

Current Documentation

The settings page currently documents only these worktree keys:

| worktree.baseRef | Which ref new worktrees branch from. "fresh" (default) branches from origin/<default-branch> for a clean tree matching the remote. "head" branches from your current local HEAD, so unpushed commits and feature-branch state are present in the worktree. Applies to --worktree, the EnterWorktree tool, and subagent isolation | "head" | | worktree.symlinkDirectories | Directories to symlink from the main repository into each worktree to avoid duplicating large directories on disk. No directories are symlinked by default | ["node_modules", ".cache"] | | worktree.sparsePaths | Directories to check out in each worktree via git sparse-checkout. Only the listed directories plus root-level files are written to disk, which is faster in large monorepos | ["packages/my-app", "shared/utils"] |

Related agent-view guidance currently says:

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.

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?

The docs do not document the new worktree.bgIsolation: "none" setting added in v2.1.143.

That creates two gaps with the same root cause:

A. The settings reference has no discoverable entry for the new key

Users reading Worktree settings cannot learn that background sessions can be configured to edit the main working copy directly when git worktrees are impractical.

B. Agent-view now overstates background-session edit isolation

The current agent-view page says background sessions in git repos move into an isolated worktree before editing files, with only non-git repositories called out as an exception. After v2.1.143, that is no longer the whole story because worktree.bgIsolation: "none" lets background sessions edit the working copy directly without EnterWorktree.

Suggested Improvement

Add worktree.bgIsolation to the Worktree settings table in settings with a description similar to:

worktree.bgIsolation - Controls how background sessions isolate file edits. Set "none" to keep background sessions in the main working copy instead of moving them into a git worktree before edits. This is useful for repositories where worktrees are impractical.

If additional values are supported, list them all and identify the default explicitly.

Then update agent-view so the isolation description matches the setting. For example, change the prose from an unconditional rule to guidance that background sessions normally use worktree isolation, but can be configured with worktree.bgIsolation: "none" to edit the working copy directly.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Version context: https://code.claude.com/docs/en/changelog for v2.1.143 says: Added worktree.bgIsolation: "none" setting to let background sessions edit the working copy directly without EnterWorktree, for repos where worktrees are impractical.