Agent-comms harness

Stopping concurrent sessions from clobbering shared .claude edits.

Stream: agent-comms-harness · closed 2026-07-03

The question

  • Concurrent Claude sessions share one tree (Code/) and one set of hot files.
  • This sprint three sessions collided on .claude/hooks/* — settings.json, board_hygiene_stop.py.
  • No CLAIM was ever posted. Why doesn't the coordination happen?

Root cause

  • tasks/AGENT_COMMS.md is a well-formed append-only coordination log.
  • Its rules are right — CLAIM before editing, commit only your pathspec.
  • But agents don't USE it — it is written, never read.
  • Same failure CLAUDE.md names for prose: a doc you "should" check is non-binding and rots.
  • Enforcement belongs in the harness, not in prose.

New terminology

No new terms coined or pinned this stream.

CLAIM, the RELEASE: convention, the SessionStart injector and the Stop-hook ownership fix are harness conventions and code identifiers — not independently sourced in notes/terminology.md, so they get no slide.

The fix — Feature 1: CLAIM injector

  • New claims_inject.py on the SessionStart hook chain.
  • Reads AGENT_COMMS.md, extracts the ACTIVE CLAIMs, prints them as context.
  • Active = a CLAIM: with no later matching RELEASE: on the same paths.
  • Ambiguous parse → show it (fail toward visible). Empty set → print nothing.
  • Pure active_claims(comms_text) plus a thin main; selfcheck green.

The fix — Feature 2: Stop-hook ownership

  • The Stop hook nagged about EVERY dirty .claude file — including other sessions'.
  • _session_claude_edits(transcript_path) scans the whole transcript for this session's writes under .claude/.
  • Nag only on dirty ∩ mine; the finding says "commit YOUR lines by pathspec".
  • Unreadable transcript → flag ALL (fail visible, never silently miss our own).
  • board_hygiene_stop.py:331; selfcheck and end-to-end green.

The fix — immediate stopgap

  • Before either hook shipped, a zero-build guard went up first.
  • Serialize all .claude edits to a single owner for the sprint.
  • Posted straight to AGENT_COMMS.md — bought time while the hooks were built and reviewed.

What we learned

  • Coordination docs rot like any prose rule — bind them in the harness or they don't happen.
  • Fail toward visible: an ambiguous parse should over-report (show the CLAIM, flag all dirty).
  • Attribute ownership from the WHOLE transcript, not just the last turn.
  • Don't collide while fixing the collision: Feature 1 (new file) first, Feature 2 waited for the peer workstream's release.

Side effects

  • The RELEASE: convention is new — a CLAIM can now be closed, not only posted.
  • No code beyond the two hooks and their selfcheck fixtures was recorded as touched.
  • Landed via the existing propose-then-approve guard (preflight_guard.py returns ask on a new .claude/hooks file) — reused, not modified.

What comes next

  • Both in-scope features are live; the stream's done-condition is met.
  • Deferred and explicitly retired from the board (2026-07-03 — a fresh design decision, not a queued build):
    • PreToolUse soft-lock claim-check.
    • Worktree-per-agent / partitioned ownership (structural).
  • No queued build remains — reopening either is a new design decision.