Isolate review subagents in throwaway git worktrees - #91
Open
mattmenefee wants to merge 2 commits into
Open
Conversation
10 tasks
mattmenefee
force-pushed
the
isolate-review-agents-in-worktrees
branch
2 times, most recently
from
August 5, 2026 22:46
34ff75f to
4c80941
Compare
Every user-level subagent carries Edit and Write access, and a /local-review run puts several of them to work against one checkout at the same time. A reviewer that edits a file to test an assertion changes what its siblings are reading, and leaves changes in the working tree that nobody asked for. Record the worktree discipline once in the global CLAUDE.md — how to isolate an agent, how to bootstrap a fresh checkout, what a worktree still shares with the real repository, and how to clean up — then give every agent a short section telling it to advise rather than fix, and to verify only inside an isolated checkout. The agents also gain EnterWorktree and ExitWorktree, without which that instruction would be unusable: an explicit tools list is a whitelist, not an addition to the default pool. Set worktree.baseRef to head so an isolated agent branches from the work under review. The default branches from origin's default branch, which would have had reviewers analyzing main while reporting on a feature branch, with nothing in their output to reveal it. Finally, git worktree list sorts linked worktrees by directory name, so the harness's agent-<id> checkouts sorted ahead of the numbered ones and renumbered them mid-session. wt and wtl now read through a wtlist helper that lists .claude/worktrees entries last, so wt 2 reaches the same checkout whether or not an agent is running.
mattmenefee
force-pushed
the
isolate-review-agents-in-worktrees
branch
from
August 5, 2026 22:47
4c80941 to
1cc21d1
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Every user-level subagent carries Edit and Write access, and a
/local-reviewrun puts several of them to work against one checkout at the same time. A reviewer that edits a file to test an assertion changes what its siblings are reading, and leaves changes in the working tree that nobody asked for. This adds the discipline that makes those grants safe, and fixes two harness defaults that would have quietly undermined it.home/.claude/CLAUDE.mdgains a# Git Worktreessection holding the procedure once: how to isolate an agent, how to bootstrap a fresh checkout, what a worktree still shares with the real repository, and how to clean up. Custom subagents load the whole CLAUDE.md hierarchy (only the built-inExploreandPlanskip it), so one copy reaches every agent in every project## Working Alongside Other Agentssection — advise rather than fix, verify only inside an isolated checkout, return the shared tree untouchedEnterWorktreeandExitWorktree. Without these the instruction above would be unusable: an explicittools:list is a whitelist, not an addition to the default pool, so the tool was not actually reachableworktree.baseRefis set tohead. The default,fresh, branches an isolated agent fromorigin/<default branch>rather than the work under review — reviewers would have analyzedmainwhile reporting on a feature branch, with nothing in their output to reveal itwt/wtlare hardened.git worktree listsorts linked worktrees by directory basename, so the harness's.claude/worktrees/agent-<id>checkouts sorted ahead ofalice2–alice8and renumbered them mid-session. Both now read through awtlisthelper that lists those entries last/doc-reviewgains a## Reviewing Without Editingsection: the only file the documentation-expert should write is the review, and accuracy checks that would modify the repository belong in a worktree.gitignorenow covers/.claude/worktrees/, which was showing up as untrackedTest plan
git worktree listordering confirmed empirically in a throwaway repo: git sorts linked worktrees by basename, soagent-<id>landed at position 2 ahead ofmain2/main8wtlisthelper, the same repo lists the agent worktree last, andwt 2resolves to the second permanent worktree rather than the agent'szsh -n ~/.zshrcparses;wtlandwt 2exercised end to end in a realzshsettings.jsonis valid JSONEnterWorktreeandExitWorktreepresent in everytools:list/local-reviewrun with reviewers actually spawned underisolation: "worktree"Requires
source ~/.zshrcto pick upwtlist.