> ## Documentation Index
> Fetch the complete documentation index at: https://vietbui.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Worktree-Isolation Guard

> When a Claude Code session is isolated in a worktree (EnterWorktree, isolation: 'worktree' subagents, background jobs), the harness statically checks every B…

# Claude Code Worktree-Isolation Guard

When a Claude Code session is isolated in a worktree (`EnterWorktree`, `isolation: "worktree"` subagents, background jobs), the harness statically checks every Bash command before it runs. If it cannot prove that git operations stay inside the session's own worktree, it refuses the command with "Refusing to run it — a worktree-isolated session's git operations must target its own worktree." Since 2.1.222 this applies to every session type, and it cannot be switched off. Evidence: Claude Code Worktree Guard Issues.

The guard is conservative by design: it does not run or simulate the command, so anything whose target directory or executable is only known at runtime counts as unverifiable.

## Refusal classes (as of 2.1.304)

| Class | Example | Status |
| - | - | - |
| Launcher-wrapped git | `rtk git status` (from the rtk hook rewrite), `rtk proxy git …` | Refused. rtk PR #3879 stops the rewrite in worktrees; typing `rtk git` yourself stays refused |
| Tilde paths | `git -C ~/repo/wt status` | Refused (#88550, open). `$HOME/…` passes |
| git aimed outside the worktree | `git -C <main checkout>`, `cd <main> && git …`, `GIT_DIR=…` | Refused by design (2.1.216) |
| Interpreter builtins | `source x.sh`, `. x.sh`, `eval …` | Refused by denylist (#84530) |
| Runtime-computed paths | `cd $(…)`, `$T` in a path | Often refused |
| Nested expansions | `"$(… $(…) …)"` | Refused again since 2.1.274 |
| The word "git" inside argument prose | `pueue add "… git …"`, `--body "…git…"` | Can be refused; text is scanned |

No longer refused (fixed 2.1.257/2.1.259): plain loops, heredocs, `$VAR` reads and `"$(…)"` that never touch git. `&&`, pipes and redirects pass on their own.

## Workaround matrix

| Workaround | Effect | Keep isolation? |
| - | - | - |
| Hook wrapper: skip the rtk rewrite when cwd is under `*/.claude/worktrees/*` | Removes the commonest refusal at the source | Yes |
| Call `/usr/bin/git` by absolute path | rtk does not rewrite it | Yes |
| `$HOME` or absolute paths instead of `~` | Satisfies the path check | Yes |
| Commit message and PR body in files (`git commit -F`, `gh pr create --body-file`) | Keeps "git" prose out of arguments | Yes |
| Canonical commit funnel (`python3 git-commit.py`) that checks worktree root, branch, staged paths and message | Passes (probed 2.1.304); turns prose rules into an engineering control (Reddit Complex Git Claude Code) | Only if the funnel itself refuses to leave the session's worktree |
| Multi-step logic in a script run as `bash script.sh` | Passes, but hides the commands from the check | Technically, but it defeats the check rather than satisfying it |
| `ExitWorktree(keep)` then `cd` into the worktree | Guard no longer applies | No; needs explicit user consent |
| Disable isolation, WorktreeCreate hooks | Not possible / no effect | — |

## Removal criteria

These are bandaids for specific bugs. Remove each one when its bug is fixed:

* rtk stable release containing PR #3879 → drop the hook wrapper and the `/usr/bin/git` rule.
* claude-code#88550 closed → drop the "no `~`" rule.
* The other rules (no git outside own worktree, no `source`) are by design and stay.

## Related

* [rtk (Rust Token Killer)](/entities/rtk) — the PreToolUse rewrite that collides with the guard.
* [Worktree Isolation](/concepts/worktree-isolation) — the isolation model the guard enforces.
* [Agent Subagents](/concepts/agent-subagents) — `isolation: "worktree"` subagents.
* [Agentic Sandbox Controls](/concepts/agentic-sandbox-controls) — the broader sandboxing picture.
* Local record: `mistakes/2026-10-20-claude-code-worktree-guard-compound-bash.md`; dotfiles workflow `docs/workflows/worktree-guard-bandaid.md`.

## Linked pages

* [Agent Subagents](/concepts/agent-subagents)
* [Agentic Sandbox Controls](/concepts/agentic-sandbox-controls)
* [rtk (Rust Token Killer)](/entities/rtk)
* [Worktree Isolation](/concepts/worktree-isolation)

Knowledge graph (visual). The same links are listed under Linked pages.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.