Skip to content

Isolate review subagents in throwaway git worktrees - #91

Open
mattmenefee wants to merge 2 commits into
mainfrom
isolate-review-agents-in-worktrees
Open

Isolate review subagents in throwaway git worktrees#91
mattmenefee wants to merge 2 commits into
mainfrom
isolate-review-agents-in-worktrees

Conversation

@mattmenefee

Copy link
Copy Markdown
Owner

Summary

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. This adds the discipline that makes those grants safe, and fixes two harness defaults that would have quietly undermined it.

  • home/.claude/CLAUDE.md gains a # Git Worktrees section 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-in Explore and Plan skip it), so one copy reaches every agent in every project
  • All seven agents gain a short ## Working Alongside Other Agents section — advise rather than fix, verify only inside an isolated checkout, return the shared tree untouched
  • All seven agents also gain EnterWorktree and ExitWorktree. Without these the instruction above would be unusable: an explicit tools: list is a whitelist, not an addition to the default pool, so the tool was not actually reachable
  • worktree.baseRef is set to head. The default, fresh, branches an isolated agent from origin/<default branch> rather than the work under review — reviewers would have analyzed main while reporting on a feature branch, with nothing in their output to reveal it
  • wt / wtl are hardened. git worktree list sorts linked worktrees by directory basename, so the harness's .claude/worktrees/agent-<id> checkouts sorted ahead of alice2alice8 and renumbered them mid-session. Both now read through a wtlist helper that lists those entries last
  • /doc-review gains a ## Reviewing Without Editing section: the only file the documentation-expert should write is the review, and accuracy checks that would modify the repository belong in a worktree
  • .gitignore now covers /.claude/worktrees/, which was showing up as untracked

Test plan

  • git worktree list ordering confirmed empirically in a throwaway repo: git sorts linked worktrees by basename, so agent-<id> landed at position 2 ahead of main2/main8
  • With the wtlist helper, the same repo lists the agent worktree last, and wt 2 resolves to the second permanent worktree rather than the agent's
  • zsh -n ~/.zshrc parses; wtl and wt 2 exercised end to end in a real zsh
  • settings.json is valid JSON
  • All 7 agent files parse as YAML frontmatter, with EnterWorktree and ExitWorktree present in every tools: list
  • markdownlint clean on every changed Markdown file
  • No new line exceeds 100 characters
  • Not yet exercised: a full /local-review run with reviewers actually spawned under isolation: "worktree"

Requires source ~/.zshrc to pick up wtlist.

@mattmenefee mattmenefee self-assigned this Aug 4, 2026
@mattmenefee
mattmenefee force-pushed the isolate-review-agents-in-worktrees branch 2 times, most recently from 34ff75f to 4c80941 Compare August 5, 2026 22:46
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
mattmenefee force-pushed the isolate-review-agents-in-worktrees branch from 4c80941 to 1cc21d1 Compare August 5, 2026 22:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant