[DOCS] Worktree docs never describe the multi-repo / nested-repository case that v2.1.203 fixed for `--worktree` and background-session isolation

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The "Start Claude in a worktree" section of worktrees.md, and the "How file edits are isolated" section of agent-view.md that describes background-session worktree creation.

Current Documentation

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

A git worktree is a separate working directory with its own files and branch, sharing the same repository history and remote as your main checkout. Running each Claude Code session in its own worktree means edits in one session never touch files in another, so you can have Claude building a feature in one terminal while fixing a bug in a second. Pass --worktree or -w to create an isolated worktree and start Claude in it. By default, the worktree is created under .claude/worktrees/<value>/ at your repository root, on a new branch named worktree-<value>

From https://code.claude.com/docs/en/agent-view ("How file edits are isolated"):

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 page frames the workspace as a single git repository with a clean root. Nothing in either page describes what happens when the working directory contains nested git repositories (subdirectories that are themselves git repos, vendored libraries with their own .git directories, monorepo packages with separate origin URLs, or workspaces that overlay multiple git repos). The worktrees page never addresses multi-repo workspaces at all.

What's Wrong or Missing?

A. The multi-repo / nested-repository workspace scenario is completely undocumented

The v2.1.203 changelog states:

Fixed worktree creation rejecting nested repositories in multi-repo workspaces, leaving background sessions unable to isolate and edit

Before v2.1.203, running claude --worktree <name> from inside a directory whose tree contains a nested git repository (for example vendor/foo/.git/ or apps/web/.git/ inside a larger workspace) was rejected outright, and the same rejection applied to the automatic worktree move that background sessions perform before they edit files. The result, for affected users, was that they could not start an isolated session at all from such a workspace. After v2.1.203, worktree creation succeeds.

The worktrees page never acknowledges the multi-repo workspace shape at all. Its "Start Claude in a worktree" section only describes the single-repo case ("sharing the same repository history and remote as your main checkout"), and the --worktree / EnterWorktree paragraphs never say what happens when the working directory sits above more than one git repo. A user who is working from the workspace root and reading the docs has no signal that the nested-repo shape is supported, let alone that it used to break worktree creation.

B. Background-session isolation has the same gap

The "How file edits are isolated" paragraph in agent-view.md describes the isolation move as a precondition for editing files. It does not mention the workspace shape that triggered the v2.1.203 rejection, so an operator who dispatches a background session from a multi-repo workspace root could not tell from the docs why the session used to fail to isolate and why it now succeeds.

A user running claude agents from a directory that contains nested repositories has no way to learn that:

1. The isolation move uses a temporary worktree under .claude/worktrees/.
2. That move previously failed in multi-repo workspaces, leaving background sessions unable to isolate.
3. The same fix in v2.1.203 also resolves that scenario for both --worktree and the background-session isolation move.

C. The page already cross-references related version-gated behaviors

worktrees.md already carries inline {/* min-version: ... */} notes for related version-gated fixes:

{/ 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 nested-repository fix is the same kind of user-visible correction (a path that previously failed and now succeeds), and worktrees.md has no parallel {/* min-version: 2.1.203 */} note next to the "Start Claude in a worktree" paragraph that fixes it.

Suggested Improvement

Add a {/* min-version: 2.1.203 */} note under the "Start Claude in a worktree" section of worktrees.md that explicitly names the multi-repo case:

{/ min-version: 2.1.203 /}If your working directory contains nested git repositories (for example, vendor libraries with their own .git/ or a monorepo where individual packages are also git repos), claude --worktree succeeds and creates the session worktree at the repository root. Earlier versions rejected nested-repository workspaces entirely, leaving sessions unable to isolate.

Add a matching inline note in agent-view.md under "How file edits are isolated":

{/ min-version: 2.1.203 /}Background sessions launched from a workspace that contains nested git repositories now isolate normally. Earlier versions rejected the isolation move when the workspace root overlaid multiple git repos, leaving background sessions unable to isolate and edit.

Optionally, add a short paragraph to the "Start Claude in a worktree" section that defines the multi-repo workspace shape for users who do not already know it, for example:

A multi-repo workspace is any directory whose tree contains more than one git repository — vendored libraries with their own .git/ directories, monorepo packages with separate origins, or workspaces that overlay multiple repos. --worktree and the background-session isolation move operate on the outermost git repository and ignore nested .git/ directories inside.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/worktrees | "Start Claude in a worktree" never describes the multi-repo / nested-repository case the v2.1.203 fix unblocks |
| https://code.claude.com/docs/en/agent-view | "How file edits are isolated" never explains that the background-session isolation move used to reject nested-repository workspaces |

Total scope: 2 pages affected.

Version: v2.1.203

Related: The v2.1.203 worktree-isolated-subagents shell-command fix (separate entry in the same release) addresses the isolation: worktree boundary for shell commands. The nested-repository fix here is a different surface: it makes --worktree and the background-session isolation move succeed at all in workspaces that contain more than one git repository. The two fixes share the same version and the same primary documentation page, and they should be documented together so users adopting --worktree or claude agents from a workspace root can see both contracts at once.