chore(agents): enforce worktree-first discipline with a PreToolUse guard#1839
Merged
Conversation
Multiple agents work this repo in parallel. The shared `main` checkout has its HEAD switched and the tree reset under an agent mid-task, silently clobbering uncommitted edits (a full session's work was reverted twice). AGENTS.md already recommended one-worktree-per-task, but it was a soft "prefer" buried below the Prime Directives and nothing enforced it. - Add `.claude/hooks/guard-main-checkout.sh` (PreToolUse, wired in `.claude/settings.json`): blocks Edit/Write/NotebookEdit whenever HEAD is on `main`, with an actionable message; `OS_ALLOW_MAIN_EDITS=1` overrides for a deliberate non-task fix. - Promote worktree-first to AGENTS.md Prime Directive #11 and harden the Multi-agent working discipline section ("prefer" -> mandatory; main is not a supported fallback). Tooling/docs only — no package version impact. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
size/s
documentation
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
2 participants
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.
Why
Multiple agents work this repo in parallel. The shared
maincheckout gets its HEAD switched and the tree reset under an agent mid-task, silently clobbering uncommitted edits — a full session's work was reverted twice during #1837. AGENTS.md already recommended one-worktree-per-task, but it was a soft "prefer" buried below the Prime Directives, and nothing enforced it. The gap was adherence, not clarity — so this adds a guardrail.What
.claude/hooks/guard-main-checkout.sh(new) — a PreToolUse hook wired in.claude/settings.jsonthat blocksEdit/Write/NotebookEditwhenever the session's checkout HEAD is onmain, with an actionable message telling the agent to create a worktree first. Exits 0 (allow) on any feature branch / non-git dir.OS_ALLOW_MAIN_EDITS=1overrides for a deliberate, non-task human fix.maincheckout is explicitly not a supported fallback).Verification
Hook tested locally across all three paths:
maincheckout → exit 2 (block) with guidancemain+OS_ALLOW_MAIN_EDITS=1→ exit 0 (allow)Tooling/docs only — no package version impact (empty changeset).
🤖 Generated with Claude Code