Lightweight inter-agent coordination SOP for Claude Code worktrees

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.

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. This is designed as a lightweight transport and visibility layer, not a full agent orchestration framework. You are Primary for a multi-worktree, multi-agent project. SET UP A LIGHTWEIGHT INTER-AGENT COMMUNICATION SYSTEM. MODEL 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. GOAL Agents 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. The system must also support controlled information silos such as: - W1 may communicate with Primary. - W2 may communicate with Primary. - W1 and W2 may be kept blind from each other. - W3 may be blocked from W1/W2 results until an explicit release. - After release, W3 may challenge W1/W2 and they may reply. - Historical private traffic must remain private even after release. This is a TRANSPORT AND VISIBILITY layer. It is NOT the project's authoritative work-state machine. The project's existing STATUS / ledger / protocol remains authoritative for: - assignments; - experiment/work-item state; - freeze state; - release authority; - acceptance; - merge authority; - claim status; - owner decisions. Communication carries evidence. Communication does not confer authority. ================================================== 1. ARCHITECTURE ================================================== Use one Git repository with separate worktrees, for example: Primary W1 W2 W3 Agents communicate through a small CLI: bin/coord Required commands: coord send coord handoff coord inbox coord read coord ack coord status status is READ ONLY. Do NOT implement separate coord-owned commands for: - init; - freeze; - release; - experiment state transitions; - claim acceptance. Those belong to the canonical project protocol. Do NOT build: - Supabase; - database server; - dashboard; - daemon; - watcher; - MCP server; - hidden coordination branch; - background Git pushes; - agent group chat. 1. STORAGE Store coordination traffic outside normal Git history in the repository's shared .git directory so all worktrees can access it. Example: .git/coord-lite/<WORK ITEM / msgs/ 000001.json 000002.json acks/ ..json Properties: - One immutable file per message. - One immutable acknowledgment record per recipient/message. - Worktrees share the same store. - Messages are not normal project commits. - Messages are not pushed to GitHub. - No coord/state branch exists. - coord creates no refs. - coord performs no automatic fetch/push. - coord starts no background process. - coord makes no network connection. The direct store is an implementation detail. PROTOCOL RULE: Agents must use coord , not inspect .git/coord-lite manually. This is a protocol boundary, not a hostile security sandbox. 1. MESSAGE IDENTITY Every message belongs to an explicit experiment/work item. Example: E001-M0007 Messages should record at least: - message id; - experiment/work-item id; - sender; - recipients; - type; - subject; - body; - artifact SHA when applicable; - artifact path when applicable; - epistemic provenance when applicable; - send ordering/timestamp; - acknowledgment state. Useful message types: - NOTE - QUESTION - HANDOFF - REVIEW REQUEST - REVIEW RESULT - RELEASE NOTICE - BLOCKER Do not infer authority from message type. 1. AUTHORITY Separate communication from authority. Examples: W1 → W3 may convey: - evidence; - a question; - a counterexample; - a frozen artifact after release. It may NOT authorize: - merging; - acceptance; - release; - changing another lane's assignment; - changing project state; - changing experiment rules. Primary/owner retains those authorities according to the project protocol. 1. SHA-PINNED HANDOFFS Mathematical/code/research handoffs must point to an exact Git commit SHA. Never review "whatever is currently on W1." Review: <exact 40-character SHA A handoff should capture enough information to detect accidental mutation, preferably: - commit SHA; - artifact path; - tree or file hash; - provenance/status; - source lane; - destination; - work-item id. Branch movement after handoff must NOT change the reviewed artifact. The branch is a convenience. The SHA is identity. 1. BLINDNESS MODEL Support three conceptual lane states. A. SEALED The lane remains listed as blind and has no released artifact. Meaning: - its private work cannot cross to blinded lanes; - other blinded lanes cannot inspect it; - W3/reviewer cannot inspect it; - it may communicate with Primary according to policy. B. RELEASED The lane remains listed as blind, BUT canonical project state records one or more exact released SHAs. Meaning: - the lane may participate in authorized post-release dialogue; - ONLY explicitly released commits, or history canonically authorized by policy, may cross the boundary; - later repair/draft commits do NOT cross automatically; - a later repair commit needs its own explicit release. This is the preferred state for adversarial review because it permits dialogue without opening the lane's entire history. C. LIFTED The lane is removed from the blind set. Meaning: - blindness is over entirely according to project policy. Do not use LIFTED merely to enable normal post-release critique if RELEASED is sufficient. 1. CANONICAL RELEASE POLICY The project protocol / STATUS file owns releases. Example canonical policy entries: blind: W1 W2 released: W1 released: W2 coord READS this policy. coord does NOT independently decide release state. A release record must be part of canonical project history. If release is withdrawn or a lane is re-blinded, visibility must change on the NEXT READ, not merely on future sends. Therefore authorization must be checked: - when sending; - AND again when reading. This prevents an old message from remaining visible after policy changes. 1. HISTORICAL PRIVACY Release of one artifact must NOT reveal a lane's historical private messages. Example: During blindness: W1 → Primary: "Here is my private derivation." After release: released: W1 W3 may receive the explicitly released artifact. W3 must NOT suddenly gain access to W1's old private W1→Primary message. Recipient/thread authorization remains meaningful after release. Release is not "make everything W1 ever said public." 1. CRITICAL ARTIFACT-VISIBILITY RULE This rule exists because Math Adventure found a real information leak here. BEFORE coord does anything that can reveal information about an attached artifact, it must verify that the SENDER is authorized to inspect that artifact. Correct order: 1. parse request; 2. determine visibility/ownership sufficiently to decide whether sender may inspect the artifact; 3. reject unauthorized sender generically; 4. only then inspect path/tree/content details. Do NOT: 1. resolve foreign commit; 2. test file existence; 3. print SHA; 4. then check sender authorization. That leaks information. An unauthorized sender must not be able to learn: - foreign lane SHA; - whether a ref exists; - whether a path exists; - whether an object exists; - tree contents; - ancestry details; - commit-message-search results; - distinguishable error behavior. Use one generic refusal for unauthorized/unavailable artifacts, e.g.: refused: artifact not available it does not resolve, or you may not inspect it The refusal must not contain: - foreign SHA; - path existence; - object identity; - other secret metadata. Existing path and missing path probes against an unauthorized artifact must look the same. 1. LANE OWNERSHIP / ANCESTRY Do not determine lane ownership using only current branch names. Math Adventure found another real defect here. A sensitive commit may survive only through: - tags; - merges; - old ancestry; - handoff history. Ownership/visibility logic must not be defeated by: - moving a commit to a differently named branch; - deleting its original branch; - retaining it under a tag; - merging it into another branch; - forwarding through Primary; - reply-chain laundering; - attaching a full SHA instead of a symbolic ref; - abbreviated SHA; - rev expressions; - commit-message searches; - CC fields; - borrowed/spoofed lane identity. Test these explicitly. 1. SENDER AND RECIPIENT VISIBILITY Do not check only recipients. The sender must also be authorized to see what it is sending. Otherwise: W2 could say: "send this W1 artifact to Primary" and learn W1's SHA or metadata even if Primary is authorized. Invariant: A sender may not attach, probe, forward, or describe an artifact it is not itself authorized to inspect. 1. ACKNOWLEDGMENTS Keep message lifecycle distinctions explicit. At minimum: SENT ACKNOWLEDGED Do not rewrite the original message when acknowledging. ACK should be a separate immutable record. If project workflow needs richer states, keep them in the canonical project protocol, not in coord. Do not silently turn: SENT into: ACCEPTED or: EXECUTED. Communication is not acceptance. 1. OPERATIONAL INBOX CONVENTION Every active lane should check its authorized coord inbox: 1. at task/session start; 2. before beginning a materially new research/work step; 3. after completing a milestone; 4. before stopping or going idle. This allows agents to pick up new authorized instructions without the owner copying messages between windows. Example: bin/coord inbox E001 Then: bin/coord read E001-M0013 bin/coord ack E001-M0013 During blind phases: - W1/W2 communicate with Primary; - W1/W2 do not see each other's private work; - W3 sees no unreleased mathematical/research artifacts. After release: - W3 may communicate directly with W1/W2 if project policy permits; - W1/W2 may respond; - unreleased follow-up commits still remain private. 1. EPISTEMIC PROVENANCE For research/analysis projects, preserve why a claim is believed. Useful provenance values include: DERIVED INDEPENDENTLY DERIVED AFTER READING REPRODUCED COUNTEREXAMPLE FOUND COMPUTATIONALLY CHECKED LITERATURE SUPPORTED PRIMARY SYNTHESIS These labels do not themselves prove anything. They describe the evidence path. Important: "Lane says it proved X" means: CLAIMED / DERIVED not: INDEPENDENTLY VERIFIED. Independent verification must be separately recorded. 1. BLIND EXPERIMENT PATTERN A strong default workflow is: PHASE 1 — INDEPENDENT W1 attacks question independently. W2 attacks question independently. They may communicate with Primary. They may NOT read each other's work. When done: W1 freezes exact SHA. W2 freezes exact SHA. Primary records both. PHASE 2 — INDEPENDENT COMPARISON Primary canonically releases only those exact frozen SHAs to W3. W3 reads ONLY those released artifacts. W3: - reconstructs both arguments; - compares them; - attacks them; - records convergence/conflict; - freezes its own comparison. During this first comparison W3 should not: - ask W1/W2 questions; - see director synthesis; - see novelty/literature notes derived from their outputs; - see post-freeze repairs. PHASE 3 — ADVERSARIAL CROSS-TALK After W3 freezes: W3 ↔ W1 W3 ↔ W2 may open for: - challenges; - counterexamples; - clarification; - repairs; - simplification. Repairs crossing the boundary receive new explicit released SHAs. This preserves independent convergence before cross-pollination. 1. MANAGEMENT BY EXCEPTION Primary should not read dozens of routine status messages. Prefer summaries such as: 3 lanes healthy 1 frozen 1 waiting for release 0 conflicts OWNER ACTION: none Escalate only: - authorization requirement; - contradiction; - failed invariant; - ambiguous research decision; - genuine blocker; - acceptance/release decision. 1. THREAT MODEL This is NOT a hostile sandbox. All worktrees share the same Git object database. A sufficiently malicious agent with arbitrary shell access may be able to inspect: - sibling branches; - Git objects; - .git/coord-lite ; - tags; - files outside the supported interface. The system is designed to prevent: - accidental leakage; - normal tool-mediated leakage; - coordination mistakes; - premature cross-pollination; - ambiguous handoffs. PROTOCOL must explicitly prohibit agents from directly inspecting: - sibling worktrees; - unauthorized branches; - unauthorized commits; - .git/coord-lite . If cryptographic/hostile isolation becomes necessary, use separate clones/containers/accounts later. Do not add that complexity unless the research/workflow genuinely requires it. 1. REQUIRED ACCEPTANCE TESTS Before adopting coord-lite, test behaviorally using throwaway repositories/worktrees. A. BASIC MESSAGE - W1 sends Primary a message. - Primary sees it. - Primary reads it. - Primary ACKs it. - ACK does not mutate original message. B. EXACT HANDOFF - W1 hands off exact SHA + file. - Branch moves afterward. - Recipient still resolves exact original artifact. C. BLIND W1/W2 Test: - W1→W2 direct; - W2→W1 direct; - forwarding; - reply threads; - CC; - merge commits; - foreign SHA; - foreign branch; - tag-only commit; - moved branch; - abbreviated SHA; - rev expression. All unauthorized content must remain unavailable. D. W3 BEFORE RELEASE - W3 sees neither frozen result. - Primary cannot simply forward blind content to W3 before canonical release. E. RELEASE After canonical release of: W1 SHA-A W2 SHA-B W3 sees exactly SHA-A and SHA-B. W3 must NOT see: - later W1 draft SHA-C; - later W2 draft SHA-D; - historical private W1→Primary messages; - historical private W2→Primary messages. F. POST-RELEASE DIALOGUE - W3 sends challenge to W1. - W1 replies. - W3 sends challenge to W2. - W2 replies. But W1/W2 unreleased repair commits remain blocked. G. WITHDRAW / RE-BLIND Test the exact documented reversal semantics. If reversal means: - remove release; - AND re-mark lane blind; then test exactly that. Visibility should update at read time. H. SENDER ARTIFACT ORACLE For unauthorized foreign artifacts test: - existing path; - missing path; - nonexistent ref; - symbolic ref; - exact SHA; - abbreviated SHA; - rev expression; - send; - handoff. All failures must be indistinguishable and reveal: - no SHA; - no path existence; - no object existence. I. SIDE EFFECTS coord must: - create no Git refs; - create no coord branch; - perform no push; - perform no fetch; - perform no network call; - modify no STATUS file; - modify no worktree. 1. MUTATION TESTS Do not trust only positive tests. Deliberately disable critical guards and confirm tests fail. At minimum: Mutation A: disable text/blindness guard. Expected: multiple blindness tests fail. Mutation B: disable artifact visibility guard. Expected: artifact-leak tests fail. The point is to prove the tests are actually protecting the claimed invariant. 1. INDEPENDENT HOSTILE REVIEW The person/agent who writes coord-lite should NOT be the final verifier. After implementation: give another lane the exact candidate SHA. Reviewer should: - inspect execution path; - attack sender identity; - forwarding; - replies; - attached SHAs; - tags; - merge history; - stale releases; - path probes; - ref probes; - side effects. Reviewer returns only: ACCEPT or: BLOCK + minimal reproduction. If BLOCK: fix only demonstrated defect. Produce new exact candidate. Rerun hostile review. Do not endlessly harden speculative threats. 1. CURRENT LIMITATION: NO AUTOMATIC WAKE-UP Current accepted system provides: YES: - durable direct agent messaging; - controlled visibility; - inter-agent handoffs; - active sessions checking inbox; - owner no longer acting as clipboard. NOT YET: - waking a completely idle/stopped Claude Code process. An active Claude session can pick up messages at inbox checkpoints. If the Claude process has ended, nothing automatically starts it. Do not pretend messaging equals process supervision. 1. NEXT OPTIONAL PRIMITIVE: COORD WAIT Do NOT build this until base coord-lite is accepted. Next proposed command: coord wait <WORK ITEM Goal: - current Claude process calls coord wait; - command blocks locally; - consumes effectively no repeated model turns; - waits until an AUTHORIZED ACTIONABLE message becomes visible; - returns; - Claude continues. Desired flow: Claude ↓ coord wait E001 ↓ local process blocks ↓ authorized message arrives ↓ command returns ↓ Claude reads inbox ↓ Claude continues work It must: - obey same blindness policy; - leak no unauthorized metadata; - require no daemon initially. Test: 1. lane enters coord wait; 2. leave it alone 30–60 minutes; 3. another lane sends authorized message; 4. confirm lane resumes with zero owner intervention. Then separately test: - Mac sleep/wake. Only build a daemon/supervisor if this experiment shows one is actually needed. Computer shutdown/crash/manual session close are acceptable limitations unless the project explicitly requires unattended recovery. 1. WHAT SUCCESS LOOKS LIKE Run one complete trial: W1 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. Success criterion: THE OWNER IS NO LONGER THE HUMAN CLIPBOARD. Blindness is preserved where required. Authority remains explicit. Every artifact has exact identity. Every communication has provenance. No second project-state machine exists. 1. IMPLEMENTATION PRINCIPLE Keep this primitive boring. Git owns artifacts. Project protocol owns state. coord owns transport. Do not combine those responsibilities. The value is not fancy agent chat. The value is: controlled information flow + exact artifact identity + durable handoffs + independent derivation + adversarial verification + minimal human relay. Implement the smallest system that satisfies those invariants. When complete, report: - exact implementation SHA; - commands implemented; - storage location; - policy mechanism; - acceptance-test totals; - mutation-test result; - hostile-review verdict; - known limitations; - whether the owner can now run the complete W1→Primary→W3→W1 workflow without manually copying messages. STOP before building coord wait or a daemon unless separately authorized.