{"slug": "lightweight-inter-agent-coordination-sop-for-claude-code-worktrees", "title": "Lightweight inter-agent coordination SOP for Claude Code worktrees", "summary": "A developer published a lightweight inter-agent coordination SOP that lets multiple Claude Code sessions running in separate Git worktrees exchange SHA-pinned handoffs, acknowledgments and review phases without a human relaying messages between windows. The system stores immutable message and ack files under the repository's shared .git directory via a small `coord` CLI (send, handoff, inbox, read, ack, status), deliberately avoiding databases, daemons, MCP servers or background pushes, and keeps communication strictly separate from project authority such as merge, release and acceptance decisions.", "body_md": "A practical SOP for letting multiple Claude Code sessions in Git worktrees communicate directly, exchange SHA-pinned handoffs, and preserve blind/released review phases without making the human owner act as the clipboard.\n\nThis is designed as a lightweight transport and visibility layer, not a full agent orchestration framework.\n\nYou are Primary for a multi-worktree, multi-agent project.\n\nSET UP A LIGHTWEIGHT INTER-AGENT COMMUNICATION SYSTEM.\n\nMODEL RECOMMENDATION: Use Claude Opus 5.5 for implementing, testing, and integrating this coordination infrastructure. Do not spend the strongest research/reasoning model on this plumbing unless a genuinely difficult design problem emerges.\n\nGOAL\n\nAgents in separate Git worktrees must be able to communicate, hand off exact artifacts, acknowledge messages, and continue work without the owner manually copying messages between Claude Code windows.\n\nThe system must also support controlled information silos such as:\n\n- W1 may communicate with Primary.\n- W2 may communicate with Primary.\n- W1 and W2 may be kept blind from each other.\n- W3 may be blocked from W1/W2 results until an explicit release.\n- After release, W3 may challenge W1/W2 and they may reply.\n- Historical private traffic must remain private even after release.\n\nThis is a TRANSPORT AND VISIBILITY layer.\n\nIt is NOT the project's authoritative work-state machine.\n\nThe project's existing STATUS / ledger / protocol remains authoritative for:\n\n- assignments;\n- experiment/work-item state;\n- freeze state;\n- release authority;\n- acceptance;\n- merge authority;\n- claim status;\n- owner decisions.\n\nCommunication carries evidence. Communication does not confer authority.\n\n==================================================\n\n1. ARCHITECTURE ==================================================\n\nUse one Git repository with separate worktrees, for example:\n\nPrimary W1 W2 W3\n\nAgents communicate through a small CLI:\n\nbin/coord\n\nRequired commands:\n\ncoord send coord handoff coord inbox coord read coord ack coord status\n\n`status` is READ ONLY.\n\nDo NOT implement separate coord-owned commands for:\n\n- init;\n- freeze;\n- release;\n- experiment state transitions;\n- claim acceptance.\n\nThose belong to the canonical project protocol.\n\nDo NOT build:\n\n- Supabase;\n- database server;\n- dashboard;\n- daemon;\n- watcher;\n- MCP server;\n- hidden coordination branch;\n- background Git pushes;\n- agent group chat.\n\n1. STORAGE\n\nStore coordination traffic outside normal Git history in the repository's shared `.git` directory so all worktrees can access it.\n\nExample:\n\n.git/coord-lite/<WORK_ITEM>/ msgs/ 000001.json 000002.json acks/ ..json\n\nProperties:\n\n- One immutable file per message.\n- One immutable acknowledgment record per recipient/message.\n- Worktrees share the same store.\n- Messages are not normal project commits.\n- Messages are not pushed to GitHub.\n- No `coord/state` branch exists.\n- coord creates no refs.\n- coord performs no automatic fetch/push.\n- coord starts no background process.\n- coord makes no network connection.\n\nThe direct store is an implementation detail.\n\nPROTOCOL RULE:\nAgents must use `coord`, not inspect `.git/coord-lite` manually.\n\nThis is a protocol boundary, not a hostile security sandbox.\n\n1. MESSAGE IDENTITY\n\nEvery message belongs to an explicit experiment/work item.\n\nExample:\n\nE001-M0007\n\nMessages should record at least:\n\n- message id;\n- experiment/work-item id;\n- sender;\n- recipients;\n- type;\n- subject;\n- body;\n- artifact SHA when applicable;\n- artifact path when applicable;\n- epistemic provenance when applicable;\n- send ordering/timestamp;\n- acknowledgment state.\n\nUseful message types:\n\n- NOTE\n- QUESTION\n- HANDOFF\n- REVIEW_REQUEST\n- REVIEW_RESULT\n- RELEASE_NOTICE\n- BLOCKER\n\nDo not infer authority from message type.\n\n1. AUTHORITY\n\nSeparate communication from authority.\n\nExamples:\n\nW1 → W3 may convey:\n\n- evidence;\n- a question;\n- a counterexample;\n- a frozen artifact after release.\n\nIt may NOT authorize:\n\n- merging;\n- acceptance;\n- release;\n- changing another lane's assignment;\n- changing project state;\n- changing experiment rules.\n\nPrimary/owner retains those authorities according to the project protocol.\n\n1. SHA-PINNED HANDOFFS\n\nMathematical/code/research handoffs must point to an exact Git commit SHA.\n\nNever review \"whatever is currently on W1.\"\n\nReview:\n\n<exact 40-character SHA>\n\nA handoff should capture enough information to detect accidental mutation, preferably:\n\n- commit SHA;\n- artifact path;\n- tree or file hash;\n- provenance/status;\n- source lane;\n- destination;\n- work-item id.\n\nBranch movement after handoff must NOT change the reviewed artifact.\n\nThe branch is a convenience. The SHA is identity.\n\n1. BLINDNESS MODEL\n\nSupport three conceptual lane states.\n\nA. SEALED\n\nThe lane remains listed as blind and has no released artifact.\n\nMeaning:\n\n- its private work cannot cross to blinded lanes;\n- other blinded lanes cannot inspect it;\n- W3/reviewer cannot inspect it;\n- it may communicate with Primary according to policy.\n\nB. RELEASED\n\nThe lane remains listed as blind, BUT canonical project state records one or more exact released SHAs.\n\nMeaning:\n\n- the lane may participate in authorized post-release dialogue;\n- ONLY explicitly released commits, or history canonically authorized by policy, may cross the boundary;\n- later repair/draft commits do NOT cross automatically;\n- a later repair commit needs its own explicit release.\n\nThis is the preferred state for adversarial review because it permits dialogue without opening the lane's entire history.\n\nC. LIFTED\n\nThe lane is removed from the blind set.\n\nMeaning:\n\n- blindness is over entirely according to project policy.\n\nDo not use LIFTED merely to enable normal post-release critique if RELEASED is sufficient.\n\n1. CANONICAL RELEASE POLICY\n\nThe project protocol / STATUS file owns releases.\n\nExample canonical policy entries:\n\nblind: W1 W2 released: W1 released: W2\n\ncoord READS this policy.\n\ncoord does NOT independently decide release state.\n\nA release record must be part of canonical project history.\n\nIf release is withdrawn or a lane is re-blinded, visibility must change on the NEXT READ, not merely on future sends.\n\nTherefore authorization must be checked:\n\n- when sending;\n- AND again when reading.\n\nThis prevents an old message from remaining visible after policy changes.\n\n1. HISTORICAL PRIVACY\n\nRelease of one artifact must NOT reveal a lane's historical private messages.\n\nExample:\n\nDuring blindness:\n\nW1 → Primary: \"Here is my private derivation.\"\n\nAfter release:\n\nreleased: W1\n\nW3 may receive the explicitly released artifact.\n\nW3 must NOT suddenly gain access to W1's old private W1→Primary message.\n\nRecipient/thread authorization remains meaningful after release.\n\nRelease is not \"make everything W1 ever said public.\"\n\n1. CRITICAL ARTIFACT-VISIBILITY RULE\n\nThis rule exists because Math Adventure found a real information leak here.\n\nBEFORE coord does anything that can reveal information about an attached artifact, it must verify that the SENDER is authorized to inspect that artifact.\n\nCorrect order:\n\n1. parse request;\n2. determine visibility/ownership sufficiently to decide whether sender may inspect the artifact;\n3. reject unauthorized sender generically;\n4. only then inspect path/tree/content details.\n\nDo NOT:\n\n1. resolve foreign commit;\n2. test file existence;\n3. print SHA;\n4. then check sender authorization.\n\nThat leaks information.\n\nAn unauthorized sender must not be able to learn:\n\n- foreign lane SHA;\n- whether a ref exists;\n- whether a path exists;\n- whether an object exists;\n- tree contents;\n- ancestry details;\n- commit-message-search results;\n- distinguishable error behavior.\n\nUse one generic refusal for unauthorized/unavailable artifacts, e.g.:\n\nrefused: artifact not available (it does not resolve, or you may not inspect it)\n\nThe refusal must not contain:\n\n- foreign SHA;\n- path existence;\n- object identity;\n- other secret metadata.\n\nExisting path and missing path probes against an unauthorized artifact must look the same.\n\n1. LANE OWNERSHIP / ANCESTRY\n\nDo not determine lane ownership using only current branch names.\n\nMath Adventure found another real defect here.\n\nA sensitive commit may survive only through:\n\n- tags;\n- merges;\n- old ancestry;\n- handoff history.\n\nOwnership/visibility logic must not be defeated by:\n\n- moving a commit to a differently named branch;\n- deleting its original branch;\n- retaining it under a tag;\n- merging it into another branch;\n- forwarding through Primary;\n- reply-chain laundering;\n- attaching a full SHA instead of a symbolic ref;\n- abbreviated SHA;\n- rev expressions;\n- commit-message searches;\n- CC fields;\n- borrowed/spoofed lane identity.\n\nTest these explicitly.\n\n1. SENDER AND RECIPIENT VISIBILITY\n\nDo not check only recipients.\n\nThe sender must also be authorized to see what it is sending.\n\nOtherwise:\n\nW2 could say:\n\n\"send this W1 artifact to Primary\"\n\nand learn W1's SHA or metadata even if Primary is authorized.\n\nInvariant:\n\nA sender may not attach, probe, forward, or describe an artifact it is not itself authorized to inspect.\n\n1. ACKNOWLEDGMENTS\n\nKeep message lifecycle distinctions explicit.\n\nAt minimum:\n\nSENT ACKNOWLEDGED\n\nDo not rewrite the original message when acknowledging.\n\nACK should be a separate immutable record.\n\nIf project workflow needs richer states, keep them in the canonical project protocol, not in coord.\n\nDo not silently turn:\n\nSENT\n\ninto:\n\nACCEPTED\n\nor:\n\nEXECUTED.\n\nCommunication is not acceptance.\n\n1. OPERATIONAL INBOX CONVENTION\n\nEvery active lane should check its authorized coord inbox:\n\n1. at task/session start;\n2. before beginning a materially new research/work step;\n3. after completing a milestone;\n4. before stopping or going idle.\n\nThis allows agents to pick up new authorized instructions without the owner copying messages between windows.\n\nExample:\n\nbin/coord inbox E001\n\nThen:\n\nbin/coord read E001-M0013 bin/coord ack E001-M0013\n\nDuring blind phases:\n\n- W1/W2 communicate with Primary;\n- W1/W2 do not see each other's private work;\n- W3 sees no unreleased mathematical/research artifacts.\n\nAfter release:\n\n- W3 may communicate directly with W1/W2 if project policy permits;\n- W1/W2 may respond;\n- unreleased follow-up commits still remain private.\n\n1. EPISTEMIC PROVENANCE\n\nFor research/analysis projects, preserve why a claim is believed.\n\nUseful provenance values include:\n\nDERIVED_INDEPENDENTLY DERIVED_AFTER_READING REPRODUCED COUNTEREXAMPLE_FOUND COMPUTATIONALLY_CHECKED LITERATURE_SUPPORTED PRIMARY_SYNTHESIS\n\nThese labels do not themselves prove anything.\n\nThey describe the evidence path.\n\nImportant:\n\n\"Lane says it proved X\" means: CLAIMED / DERIVED\n\nnot: INDEPENDENTLY VERIFIED.\n\nIndependent verification must be separately recorded.\n\n1. BLIND EXPERIMENT PATTERN\n\nA strong default workflow is:\n\nPHASE 1 — INDEPENDENT\n\nW1 attacks question independently. W2 attacks question independently.\n\nThey may communicate with Primary.\n\nThey may NOT read each other's work.\n\nWhen done:\n\nW1 freezes exact SHA. W2 freezes exact SHA.\n\nPrimary records both.\n\nPHASE 2 — INDEPENDENT COMPARISON\n\nPrimary canonically releases only those exact frozen SHAs to W3.\n\nW3 reads ONLY those released artifacts.\n\nW3:\n\n- reconstructs both arguments;\n- compares them;\n- attacks them;\n- records convergence/conflict;\n- freezes its own comparison.\n\nDuring this first comparison W3 should not:\n\n- ask W1/W2 questions;\n- see director synthesis;\n- see novelty/literature notes derived from their outputs;\n- see post-freeze repairs.\n\nPHASE 3 — ADVERSARIAL CROSS-TALK\n\nAfter W3 freezes:\n\nW3 ↔ W1 W3 ↔ W2\n\nmay open for:\n\n- challenges;\n- counterexamples;\n- clarification;\n- repairs;\n- simplification.\n\nRepairs crossing the boundary receive new explicit released SHAs.\n\nThis preserves independent convergence before cross-pollination.\n\n1. MANAGEMENT BY EXCEPTION\n\nPrimary should not read dozens of routine status messages.\n\nPrefer summaries such as:\n\n3 lanes healthy 1 frozen 1 waiting for release 0 conflicts OWNER ACTION: none\n\nEscalate only:\n\n- authorization requirement;\n- contradiction;\n- failed invariant;\n- ambiguous research decision;\n- genuine blocker;\n- acceptance/release decision.\n\n1. THREAT MODEL\n\nThis is NOT a hostile sandbox.\n\nAll worktrees share the same Git object database.\n\nA sufficiently malicious agent with arbitrary shell access may be able to inspect:\n\n- sibling branches;\n- Git objects;\n- `.git/coord-lite` ;\n- tags;\n- files outside the supported interface.\n\nThe system is designed to prevent:\n\n- accidental leakage;\n- normal tool-mediated leakage;\n- coordination mistakes;\n- premature cross-pollination;\n- ambiguous handoffs.\n\nPROTOCOL must explicitly prohibit agents from directly inspecting:\n\n- sibling worktrees;\n- unauthorized branches;\n- unauthorized commits;\n- `.git/coord-lite` .\n\nIf cryptographic/hostile isolation becomes necessary, use separate clones/containers/accounts later.\n\nDo not add that complexity unless the research/workflow genuinely requires it.\n\n1. REQUIRED ACCEPTANCE TESTS\n\nBefore adopting coord-lite, test behaviorally using throwaway repositories/worktrees.\n\nA. BASIC MESSAGE\n\n- W1 sends Primary a message.\n- Primary sees it.\n- Primary reads it.\n- Primary ACKs it.\n- ACK does not mutate original message.\n\nB. EXACT HANDOFF\n\n- W1 hands off exact SHA + file.\n- Branch moves afterward.\n- Recipient still resolves exact original artifact.\n\nC. BLIND W1/W2\n\nTest:\n\n- W1→W2 direct;\n- W2→W1 direct;\n- forwarding;\n- reply threads;\n- CC;\n- merge commits;\n- foreign SHA;\n- foreign branch;\n- tag-only commit;\n- moved branch;\n- abbreviated SHA;\n- rev expression.\n\nAll unauthorized content must remain unavailable.\n\nD. W3 BEFORE RELEASE\n\n- W3 sees neither frozen result.\n- Primary cannot simply forward blind content to W3 before canonical release.\n\nE. RELEASE\n\nAfter canonical release of:\n\nW1 SHA-A W2 SHA-B\n\nW3 sees exactly SHA-A and SHA-B.\n\nW3 must NOT see:\n\n- later W1 draft SHA-C;\n- later W2 draft SHA-D;\n- historical private W1→Primary messages;\n- historical private W2→Primary messages.\n\nF. POST-RELEASE DIALOGUE\n\n- W3 sends challenge to W1.\n- W1 replies.\n- W3 sends challenge to W2.\n- W2 replies.\n\nBut W1/W2 unreleased repair commits remain blocked.\n\nG. WITHDRAW / RE-BLIND\n\nTest the exact documented reversal semantics.\n\nIf reversal means:\n\n- remove release;\n- AND re-mark lane blind;\n\nthen test exactly that.\n\nVisibility should update at read time.\n\nH. SENDER ARTIFACT ORACLE\n\nFor unauthorized foreign artifacts test:\n\n- existing path;\n- missing path;\n- nonexistent ref;\n- symbolic ref;\n- exact SHA;\n- abbreviated SHA;\n- rev expression;\n- send;\n- handoff.\n\nAll failures must be indistinguishable and reveal:\n\n- no SHA;\n- no path existence;\n- no object existence.\n\nI. SIDE EFFECTS\n\ncoord must:\n\n- create no Git refs;\n- create no coord branch;\n- perform no push;\n- perform no fetch;\n- perform no network call;\n- modify no STATUS file;\n- modify no worktree.\n\n1. MUTATION TESTS\n\nDo not trust only positive tests.\n\nDeliberately disable critical guards and confirm tests fail.\n\nAt minimum:\n\nMutation A: disable text/blindness guard.\n\nExpected: multiple blindness tests fail.\n\nMutation B: disable artifact visibility guard.\n\nExpected: artifact-leak tests fail.\n\nThe point is to prove the tests are actually protecting the claimed invariant.\n\n1. INDEPENDENT HOSTILE REVIEW\n\nThe person/agent who writes coord-lite should NOT be the final verifier.\n\nAfter implementation:\n\ngive another lane the exact candidate SHA.\n\nReviewer should:\n\n- inspect execution path;\n- attack sender identity;\n- forwarding;\n- replies;\n- attached SHAs;\n- tags;\n- merge history;\n- stale releases;\n- path probes;\n- ref probes;\n- side effects.\n\nReviewer returns only:\n\nACCEPT\n\nor:\n\nBLOCK + minimal reproduction.\n\nIf BLOCK: fix only demonstrated defect. Produce new exact candidate. Rerun hostile review.\n\nDo not endlessly harden speculative threats.\n\n1. CURRENT LIMITATION: NO AUTOMATIC WAKE-UP\n\nCurrent accepted system provides:\n\nYES:\n\n- durable direct agent messaging;\n- controlled visibility;\n- inter-agent handoffs;\n- active sessions checking inbox;\n- owner no longer acting as clipboard.\n\nNOT YET:\n\n- waking a completely idle/stopped Claude Code process.\n\nAn active Claude session can pick up messages at inbox checkpoints.\n\nIf the Claude process has ended, nothing automatically starts it.\n\nDo not pretend messaging equals process supervision.\n\n1. NEXT OPTIONAL PRIMITIVE: COORD WAIT\n\nDo NOT build this until base coord-lite is accepted.\n\nNext proposed command:\n\ncoord wait <WORK_ITEM>\n\nGoal:\n\n- current Claude process calls coord wait;\n- command blocks locally;\n- consumes effectively no repeated model turns;\n- waits until an AUTHORIZED ACTIONABLE message becomes visible;\n- returns;\n- Claude continues.\n\nDesired flow:\n\nClaude ↓ coord wait E001 ↓ local process blocks ↓ authorized message arrives ↓ command returns ↓ Claude reads inbox ↓ Claude continues work\n\nIt must:\n\n- obey same blindness policy;\n- leak no unauthorized metadata;\n- require no daemon initially.\n\nTest:\n\n1. lane enters coord wait;\n2. leave it alone 30–60 minutes;\n3. another lane sends authorized message;\n4. confirm lane resumes with zero owner intervention.\n\nThen separately test:\n\n- Mac sleep/wake.\n\nOnly build a daemon/supervisor if this experiment shows one is actually needed.\n\nComputer shutdown/crash/manual session close are acceptable limitations unless the project explicitly requires unattended recovery.\n\n1. WHAT SUCCESS LOOKS LIKE\n\nRun one complete trial:\n\nW1 and W2 independently work. ↓ Both freeze exact SHAs. ↓ Primary records canonical release. ↓ W3 receives exact artifacts automatically through coord. ↓ W3 compares them. ↓ W3 sends questions back after release. ↓ W1/W2 reply directly. ↓ Owner copies ZERO inter-agent messages.\n\nSuccess criterion:\n\nTHE OWNER IS NO LONGER THE HUMAN CLIPBOARD.\n\nBlindness is preserved where required. Authority remains explicit. Every artifact has exact identity. Every communication has provenance. No second project-state machine exists.\n\n1. IMPLEMENTATION PRINCIPLE\n\nKeep this primitive boring.\n\nGit owns artifacts. Project protocol owns state. coord owns transport.\n\nDo not combine those responsibilities.\n\nThe value is not fancy agent chat.\n\nThe value is:\n\ncontrolled information flow + exact artifact identity + durable handoffs + independent derivation + adversarial verification + minimal human relay.\n\nImplement the smallest system that satisfies those invariants.\n\nWhen complete, report:\n\n- exact implementation SHA;\n- commands implemented;\n- storage location;\n- policy mechanism;\n- acceptance-test totals;\n- mutation-test result;\n- hostile-review verdict;\n- known limitations;\n- whether the owner can now run the complete W1→Primary→W3→W1 workflow without manually copying messages.\n\nSTOP before building coord wait or a daemon unless separately authorized.", "url": "https://wpnews.pro/news/lightweight-inter-agent-coordination-sop-for-claude-code-worktrees", "canonical_source": "https://gist.github.com/amarcus10028/0e58cf69a15c9eb7e3f0dd6325e0d59c", "published_at": "2026-10-03 07:19:32+00:00", "updated_at": "2026-10-03 07:36:15.969795+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "agent-protocols", "ai-tools"], "entities": ["Claude Code", "Git", "Anthropic"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/lightweight-inter-agent-coordination-sop-for-claude-code-worktrees", "markdown": "https://wpnews.pro/news/lightweight-inter-agent-coordination-sop-for-claude-code-worktrees.md", "text": "https://wpnews.pro/news/lightweight-inter-agent-coordination-sop-for-claude-code-worktrees.txt", "jsonld": "https://wpnews.pro/news/lightweight-inter-agent-coordination-sop-for-claude-code-worktrees.jsonld"}}