feat(hooks): add worktree_guard.py to block stacked agent worktrees (#485)

[zackees]

Problem

Claude Code's Agent tool with isolation: "worktree" creates the new git worktree relative to the calling agent's cwd. When the calling agent is itself already running inside a worktree, the new worktree lands at .claude/worktrees/<parent>/.claude/worktrees/<child>/. Each sub-agent compounds the nesting; #485 reports a 4-deep stack at ~220 chars before any source file is appended. On Windows that pushes paths past MAX_PATH (260), breaks cargo build scripts (cc-rs for bzip2-sys / libz-sys) with fatal error C1081: 'file name too long', and the retry loop floods stderr with kilobyte PATH dumps that can overflow the session's context window (#481 / #482).

PR #483 proposed the local mitigation but was closed without merging. This adds it back.

Fix

New ci/hooks/worktree_guard.py — a PreToolUse hook scoped to the Agent matcher. It denies any Agent call combining isolation: "worktree" with a session cwd already inside .claude/worktrees/<name>/. The deny message tells the user how to proceed (re-spawn without isolation, or run from the main checkout) and points at #485 so they can track the upstream harness fix.

Registered in .claude/settings.json with the same guarded-existence shape every other hook uses, so orphan-branch worktrees that legitimately don't have the script cannot wedge the harness.

Tests

24 unit tests in ci/hooks/test_worktree_guard.py:

• path normalization (Windows backslashes → POSIX)
• worktree-segment detection at any depth, including stacked cases
• isolation-field parsing (case-insensitive, whitespace-tolerant)
• session-cwd lookup precedence (payload > env > getcwd())
• main() end-to-end on the deny path AND the allow paths

$ uv run --no-project --script ci/hooks/test_worktree_guard.py
........................
Ran 24 tests in 0.009s
OK

Smoke test of the deny path: feeding the hook a payload with isolation: "worktree" + a .claude/worktrees/parent cwd emits the expected hookSpecificOutput.permissionDecision: "deny" JSON with the actionable error message.

Retirement

Once the upstream Claude Code harness anchors worktree paths at the repo root (git rev-parse --show-toplevel), this hook can retire and #485 can close on the upstream fix. Until then, shipping it unblocks nested-agent sessions on Windows.

Closes #485

[coderabbitai]

Warning

Review limit reached

@zackees, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 26 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9c29acf9-6002-426b-9ed0-0a3f0725bde9

📥 Commits

Reviewing files that changed from the base of the PR and between 62f99f8 and 3bce462.

📒 Files selected for processing (3)

• .claude/settings.json
• ci/hooks/test_worktree_guard.py
• ci/hooks/worktree_guard.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/485-worktree-guard-hook

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}