cc-worktree-isolation

Make parallel agent writes safe. Each concurrent worker gets its own git worktree (its own working directory + branch), so two subagents editing the repo at the same time can never step on each other's uncommitted files. This is the Claude-native first move; manual git worktree is the fallback for non-Claude runtimes.

Overview / When to Use

When you fan out work across parallel subagents or an NTM swarm in a single repo, the failure mode is collision: worker A writes foo.ts, worker B writes foo.ts, and one set of edits is silently lost or merges into garbage. Worktree isolation removes the shared mutable surface — every writer operates in a physically separate checkout.

Three Claude-native levers (verified against Claude Code 2.1.x):

• Session-level: claude --worktree (-w) starts the whole session in a fresh isolated worktree.
• Agent-level: isolation: worktree in a .claude/agents/*.md frontmatter — each spawn of that teammate gets its own worktree automatically.
• In-session: the EnterWorktree / ExitWorktree tools create/leave a worktree mid-session (created under .claude/worktrees/).

Plus two tuning knobs: the worktree.sparsePaths setting (limit the checkout to relevant subtrees in big monorepos) and WorktreeCreate / WorktreeRemove hooks (VCS-agnostic isolation + audit/cleanup).

⚠️ Critical Constraints