Subagent worktree instruction (`wt switch`) conflicts with sandbox write restrictions

[K1-R1]

Problem

The claude-md-template.md recommends wt switch <branch> for subagent worktree isolation:

Parallel subagents require worktrees. Each subagent MUST work in its own worktree (wt switch <branch>), not the main repo. Never share working directories.

The README recommends sandbox mode, where writes are restricted to the current working directory and its subdirectories.

These conflict: wt's default worktree-path template creates sibling directories (../repo.branch-name/), which are outside the sandbox write allowlist. When a sandboxed session runs wt switch --create <branch>, Seatbelt (macOS) or bubblewrap (Linux) blocks the write. The failure is silent or produces a confusing permission error, and Claude falls back to git checkout -b in the same directory, defeating the isolation that worktrees provide.

A separate issue applies even if wt is configured with an in-repo worktree-path: wt switch changes the directory via a shell function, but Claude Code's Bash tool runs each command as a subprocess so the cd doesn't persist between tool calls. More importantly, Claude Code's built-in tools (Read, Edit, Write, Glob, Grep) all resolve paths relative to the session's working directory, which wt cannot change. Only EnterWorktree or claude -w can change the session CWD. This means wt switch cannot achieve worktree isolation inside a Claude Code session regardless of path configuration.

Reproduction

1. Follow the setup guide (sandbox enabled, claude-md-template.md copied to ~/.claude/CLAUDE.md)
2. Start a Claude Code session with /sandbox enabled
3. Ask Claude to use parallel subagents -- it reads the CLAUDE.md instruction and attempts wt switch --create <branch>
4. Observe: Seatbelt blocks the write to ../repo.branch/

Context

merge-dependabot.md already has a similar carve-out for shallow clones: "Do NOT use wt switch -- shallow clones do not support worktrees reliably. Use git checkout directly when evaluating each PR."

Claude Code has built-in worktree mechanisms that are sandbox-compatible and handle CWD correctly:

• isolation: "worktree" on the Agent tool -- automatic per-subagent worktree isolation with cleanup
• claude -w <name> / EnterWorktree -- session-level worktree isolation

The wt Claude Code plugin (worktrunk.dev/claude-code/) provides a skill and activity tracking, but doesn't resolve the sandbox write restriction or the cd persistence problem. The plugin is designed for launching Claude into worktrees from outside (wt switch -x claude), not for switching worktrees from within a session.

Suggested fix

See the accompanying PR. Three changes:

1. CLI tools table -- scope wt to terminal use, note that subagents use isolation: "worktree"
2. Hooks and worktrees section -- replace wt switch with isolation: "worktree" on the Agent tool
3. Sandbox section in README -- note that tools creating directories outside CWD will be blocked

wt remains in the CLI tools table , the change only affects the in-session subagent instruction.

[m13v]

the sandbox vs worktree conflict is a real daily pain for us. we run 20+ parallel Claude Code agents and worktrees are essential for isolation, but the sandbox restriction kills it exactly as you describe - worktrees land outside the project root by default.

our workaround: we configure git to create worktrees inside a .worktrees/ directory at the repo root instead of sibling dirs. explicit paths like git worktree add .worktrees/feature-branch feature-branch keeps everything inside the sandbox boundary. the bigger issue you identified about cd not persisting across Bash tool calls is unavoidable without EnterWorktree, so we handle all worktree switching at the orchestrator level before spawning agents, never from within agent prompts themselves.

the silent fallback to git checkout -b is the real danger though. the agent thinks it has isolation but it's working directly in the main checkout. we added a pre-flight check in our orchestrator that verifies the CWD is actually a worktree (checking .git file vs .git directory) before letting an agent start any write operations.

[m13v]

our parallel agent orchestrator that handles worktree creation, session isolation, and the coordination needed for 20+ concurrent agents: https://github.com/m13v/tmux-background-agents/blob/main/SKILL.md

and the flock-based lock script that prevents agents from fighting over shared resources like browser sessions: https://github.com/m13v/browser-lock/blob/main/playwright-lock.sh