Adopt Claude Code cross-session messaging as ground-truth liveness + delivery (replaces screen-scraping) — Claude-only, needs a driver seam

[tu11aa]

Summary

Claude Code v2.1.224+ shipped cross-session messaging: sessions register themselves on disk, bind a per-session Unix inbox socket, and can list/message each other via the ListAgents and SendMessage tools. Announced 2026-08-07 (@ClaudeDevs, docs).

This is a first-party, ground-truth replacement for two things squadrant currently reverse-engineers by scraping terminal pixels:

1. "Is this agent idle or busy?" — today: glyph matching + LivenessRegistry + pid floor.
2. "Did my message actually get submitted?" — today: confirmedSendToPane paste → settle → Enter → re-read screen.

Both are the source of a long tail of shipped bugs: #447, #455, #466, #484, #492, #516, #566, #590, and the currently-open #514/#657.

Local evidence (verified on this machine, 2026-08-08)

claude --version → 2.1.226 (feature requires ≥ 2.1.224; macOS + Linux only, which matches our macOS-only stance).

Every running Claude Code session writes ~/.claude/sessions/<pid>.json:

{"pid":37511,"sessionId":"bb38bbd8-...","cwd":"/Users/q3labsadmin/me/squadrant",
 "startedAt":1786167988194,"version":"2.1.226","peerProtocol":1,
 "kind":"interactive","entrypoint":"cli",
 "messagingSocketPath":"/tmp/cc-socks/37511.sock",
 "name":"squadrant-e8","nameSource":"derived",
 "status":"busy","updatedAt":1786168376031,"statusUpdatedAt":1786168376031}

The squadrant captain session is itself registered. Captains are launched by squadrant into cmux panes, exactly the same way crews are — so squadrant-spawned Claude sessions bind an inbox socket and are addressable with no changes on our side. Feasibility for the --agent claude path is already proven; nothing needs to be built to make sessions discoverable.

ListAgents from the squadrant captain right now returns live peers with liveness state:

oneplanapp-61 [10fa68]        · interactive · idle   · started 8m ago
observer-sessions-0d [ed69b3] · interactive ·        · started 7s ago
career-stack-f6 [3effa4]      · interactive · idle   · started 6m ago

Note peerProtocol: 1 — the registry is explicitly versioned, so it is a contract rather than an incidental artifact.

Opportunity A — status field replaces liveness screen-scraping

~/.claude/sessions/<pid>.json carries status: "idle" | "busy" plus statusUpdatedAt, self-reported by the agent. That is strictly better than inferring activity from pane output, because it is the agent's own account of whether it is mid-turn rather than a guess from whether glyphs changed.

This is the cheap, high-value half: read a JSON file. No protocol reverse-engineering, no new transport. It slots straight into the existing LifecycleSource port from #333 as a fourth source alongside CmuxStore, NativeHook, and CodexAppServer.

Directly relevant to #567 (liveness trusts its own event history over observable reality) and #618 (adopt structured APIs as ground truth). See "Relationship to #618" below — these are complementary, not competing.

Opportunity B — inbox socket replaces confirmedSendToPane

packages/workspaces/src/crew-pane.ts:152 is the paste-settle-Enter machine, wired in at packages/cli/src/commands/crew.ts:70. Its own doc comment enumerates four hardening steps and three separate bug references, and the body carries #455, #484, #516 guards inline. It infers delivery from whether an input box emptied after a draft was seen.

The peer channel replaces that inference with a real answer. Delivery resolves to one of three documented outcomes — delivered, held, or refused — and, for same-machine sends, the sender is notified: a notice when the message is held, and a follow-up when the receiver later delivers, denies, or lets it expire.

That is precisely the receipt #551 asks for (ping has no delivery or read receipt) and precisely the false-negative that #514/#657 is about.

The seam already exists: crew.ts:70 injects sendToPane, so a ClaudePeerSocket delivery driver can slot in behind it without touching call sites.

⚠️ Hard limitation — this does NOT fix #514/#657

Cross-session messaging is Claude Code only. It does nothing for codex, opencode, or gemini crews.

This matters more than it first appears:

• Crew default is currently --agent opencode (operator is out of Claude credit).
• codex crews false-negative on first-turn delivery confirmation — spurious 'CREW UNDELIVERED' + auto-resend (claude-only #470/#472 fix doesn't cover codex) #514/crew send reports 'not delivered' for messages that were actually delivered — false negative recommends a harmful re-send #657 — our top open delivery blocker, which fired ten times in the 2026-08-07 session alone — is the opencode false negative.

So this work would fix the delivery path we are currently using least, and leave the one we use most untouched. Adopting it naively would also re-commit the exact mistake CLAUDE.md warns about and that #657 already diagnosed once: "the v0.13.3 UserPromptSubmit fix was Claude-only and never got a cross-agent migration path." Shipping a second Claude-only delivery path without a seam would repeat that, one layer down.

Therefore: this must be built as a capability behind the existing driver seam, never as a special case. AgentDriver should expose something like supportsPeerMessaging() / peerAddress(), with the pane-scraping path retained as the fallback for agents that lack it.

Open questions (spike needed)

1. Socket wire format. The docs explicitly say to read the inbox-socket section "when you want a script or hook to post into a session", and export CLAUDE_CODE_MESSAGING_SOCKET to hooks and Bash commands (confirmed: our captain has /tmp/cc-socks/37511.sock). But the payload format is not publicly documented and there is no claude CLI subcommand for posting. The daemon is a Node process, not a Claude session — it has no SendMessage tool. Determining whether the daemon can post directly to the socket is the single blocking unknown for Opportunity B.
2. Sender identity / inbound controls. The daemon is not a child process of the crew session, so the "own-child" verification path does not apply (and on macOS that check only works while the posting process is still running). Delivery then falls to crossSessionInbound. Crews launch with --permission-mode auto, which counts as prompting, so the default should deliver — but we should set crossSessionInbound: "accept" explicitly in crew settings rather than rely on a default we did not choose.
3. Rate limiting is a real hazard for us. Claude Code "drops identical repeats arriving within a short window" and caps unread messages at 50. Our retry logic re-sends the same text. A silently-dropped retry would look exactly like the false negative we are trying to eliminate. Needs explicit handling.
4. Feature-flag fragility. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, DO_NOT_TRACK, and DISABLE_GROWTHBOOK each disable the feature. We must detect capability at runtime, never assume it.
5. Plain text only. No structured protocol across sessions. Fine for prompt delivery; rules out using it as a typed control-plane transport.
6. Channels as an alternative for Opportunity B. Channels are the documented way to push external events into a running session, which is literally what the daemon does. But: research preview, requires --channels at launch, requires Bun, requires an allowlisted plugin (custom needs --dangerously-load-development-channels), and the flag syntax and protocol contract may change. Heavier and less stable than the socket, but officially sanctioned. Worth evaluating against option 1 rather than assumed inferior.

Relationship to #618

#618 proposes adopting cmux structured session/feed APIs as ground truth. These are complementary rather than alternatives, and the distinction is worth stating plainly:

Source	Truth it reports	Coverage
cmux structured APIs (#618)	terminal-level — pane activity	all agents
Claude peer registry (this issue)	agent-level — the agent's own idle/busy	Claude only

The Claude registry is the more accurate signal where it applies, because an agent knows whether it is mid-turn and a terminal can only guess. cmux is the more universal one. A LifecycleSource that prefers the peer registry when present and falls back to cmux otherwise gets both.

Immediate usable win — captain ↔ captain chat

Independent of any crew delivery work, this is usable today with zero code: captains are Claude Code sessions, they already appear in each other's ListAgents, and they can message each other directly with real delivery receipts.

That is a better transport than what squadrant ping does today (#551: ✔ Pinged only means "sent into the void") and is the closest thing yet to the cross-captain channel #552 asks for. Worth validating with a live captain-to-captain round trip before committing to any of the above.

Proposed phasing

• Phase 0 — spike (small). Answer Q1 and Q2 empirically on the liveness-lab throwaway project: spawn a --agent claude crew, confirm it registers, attempt a socket post from a plain Node process, observe the outcome. Per the v0.18.0 lesson — smoke test is the real gate, not the test count — this must be run live, not unit-tested.
• Phase 1 — liveness (low risk, high value). Add ClaudePeerRegistry as a LifecycleSource, reading status from the registry files. Read-only, no delivery changes, immediately improves Daemon must detect a cmux/system restart and REMAP everything — liveness trusts its own event history over observable reality #567.
• Phase 2 — delivery (gated on Phase 0). Only if the spike proves the daemon can post: add a peerMessaging capability to AgentDriver and a ClaudePeerSocket delivery driver behind the sendToPane seam, with confirmedSendToPane retained as the fallback.
• Phase 3 — captain↔captain. Reconsider ping/dispatch transport now that real receipts exist (ping has no delivery or read receipt — '✔ Pinged' only means 'sent into the void' #551, No first-class cross-captain artifact channel — captains resort to writing files into each other's vaults, with no notification #552).

#514/#657 stays open and separately prioritised regardless — none of this touches the opencode path.

References

• Docs: cross-session messaging · channels
• Announcement: @ClaudeDevs · 9to5Mac coverage
• Upstream friction: anthropics/claude-code#78706 — per-message approval friction for a coordinator-session pattern, which is exactly our topology
• Code: packages/workspaces/src/crew-pane.ts:152 · packages/cli/src/commands/crew.ts:70 · packages/core/src/liveness.ts
• Related: Adopt cmux structured session/feed APIs as ground-truth (no upgrade) — delivery safety (#484) + captain targeting (#564) + liveness (#567) #618, Daemon must detect a cmux/system restart and REMAP everything — liveness trusts its own event history over observable reality #567, codex crews false-negative on first-turn delivery confirmation — spurious 'CREW UNDELIVERED' + auto-resend (claude-only #470/#472 fix doesn't cover codex) #514, crew send reports 'not delivered' for messages that were actually delivered — false negative recommends a harmful re-send #657, ping has no delivery or read receipt — '✔ Pinged' only means 'sent into the void' #551, No first-class cross-captain artifact channel — captains resort to writing files into each other's vaults, with no notification #552, runtime read-screen <project> returns whichever tab has focus, not the captain — the target is ambiguous #564, Design: driver-agnostic agent-lifecycle via a LifecycleSource port (cmux-store adapter + native-hook core) #333

[tu11aa]

Phase 0 spike — partial results (live, 2026-08-08)

Ran the round trip for real: spawned a --agent claude --shared crew (peer-probe) from the squadrant captain and exchanged messages both directions.

✅ What works

Registration is automatic. The squadrant-spawned crew bound an inbox socket within ~12s of spawn with zero squadrant involvement:

13797 squadrant-3d | idle | /Users/q3labsadmin/me/squadrant

Bidirectional delivery works, with no screen contact at all. Captain → crew arrived while the crew was idle and started a new turn on its own — exactly as documented. The crew's reply came back to the captain wrapped as:

<cross-session-message from="uds:/tmp/cc-socks/13797.sock"
                       from-name="Cross-session messaging test target"
                       from-mode="prompting">

No paste, no settle loop, no Enter keystroke, no glyph matching, no parseDraftFromScreen. The entire confirmedSendToPane hardening stack is bypassed.

Reply address is the raw socket path (uds:/tmp/cc-socks/<pid>.sock) — a stable addressing primitive squadrant already has, since it can read the same registry files.

No per-message approval friction in our topology. The crew's outbound reply showed Allowed by auto mode classifier under --permission-mode auto. Upstream claude-code#78706 describes approval-per-message pain, but that is the desktop MCP session-management tool, not the native SendMessage path we'd use. from-mode="prompting" is carried on the message, matching the documented inbound-control classes.

Crews can see and address their captain. The probe's own ListAgents listed squadrant-e8 — our captain.

🔴 Blocker found: naming is unusable as-is

The crew could not reliably identify which peer was its own captain. Verbatim from its reply:

"squadrant-e8 is the only squadrant-project peer and the most plausible candidate for you, but I cannot confirm the socket-to-name mapping from this output."

Three separate naming defects, all from squadrant never setting a name:

1. Names are cwd-derived, so squadrant identities collide. Captain = squadrant-e8, crew = squadrant-3d. Both derive from the same folder. With --shared they share a cwd outright, so even the docs' "tell same-named sessions apart by working directory" tiebreaker fails. Add a few crews and this is unnavigable.

2. The registry name and the on-message name disagree. Registry said name: "squadrant-3d", nameSource: "derived", but the message arrived with from-name: "Cross-session messaging test target" — derived from the crew's task text. Two different identities for one session; neither is squadrant's.

3. Cross-session sends require an explicit [ref] to confirm. The first SendMessage to squadrant-3d was rejected:

   'squadrant-3d' is not an agent in this conversation. Re-send with the ref to confirm you mean: squadrant-3d [735535]

   A sensible safety step, but it means a sender must resolve name → ref before sending. With colliding derived names, that resolution is exactly what's unreliable.

Consequence for the design: squadrant must pass Claude Code's --name flag when launching captains and crews, so peers carry stable squadrant identity (squadrant-captain, squadrant-crew-peer-probe) instead of cwd- or content-derived names that collide and drift. This is a small change to the launch path and it is a prerequisite for Phase 2, not a nicety — without it, a captain cannot deterministically address its own crew, which is the entire use case.

Still unanswered

Q1 remains open and still blocks Phase 2. This probe proved messaging works between two Claude sessions, both of which have the SendMessage tool. It did not test whether the daemon — a plain Node process with no tools — can post to /tmp/cc-socks/<pid>.sock directly. That is still the deciding question for replacing confirmedSendToPane, and the wire format is still undocumented.

Phase 1 (liveness via the status field) is unaffected and remains the low-risk starting point.

[tu11aa]

Phase 0 is answered: yes — an external process can post. Phase 2 is unblocked.

Full writeup: squadrant-hub/spokes/squadrant/findings/2026-08-08-cc-peer-messaging-protocol.md (plus an HTML architecture explainer, an interactive swimlane, and runnable snippets — each with a Vietnamese twin).

Determined two ways that agree: reading the uds-messaging module out of the shipped bundle, and probing a live throwaway session spawned under a pty in /tmp/cc-lab. No message was sent to any real working session. Claims below are marked [verified] (observed on the wire or in a transcript) or [source] (read in the bundle, not executed).

A plain Node process — no SendMessage tool, not a Claude session, not in the target's process tree — connected to a session's inbox socket, wrote one newline-delimited JSON object, and the text arrived as a real user turn in that session's transcript. [verified]

The protocol

Framing is newline-delimited JSON. One object, one \n. That is the whole framing. [verified]

Claude Code prints the recipe in its own debug log:

[uds-messaging] Inject messages: echo '{"type":"user","message":{"role":"user","content":"hello"}}' | socat - UNIX-CONNECT:<path>

The full envelope:

{
  "msgV": 1,
  "msg_id": "<uuid v4>",
  "type": "user",
  "priority": "next",
  "session_id": "<receiver's sessionId>",
  "from": "uds:/tmp/cc-socks/<ours>.sock",
  "message": { "role": "user", "content": "<non-empty string>" }
}

Only type and message.content are required. Notable fields:

• session_id — mismatch against the receiver's own id ⇒ silently dropped. This is the pid-reuse guard, and we want it. [verified]
• from — reply address for receipts. The receiver refuses to send a receipt to an address outside its own socket namespace, so the daemon must bind its own socket under /tmp/cc-socks/ ending in .sock to receive anything back. [verified]
• msg_id — required if you want to correlate receipts; they echo it as orig_msg_id.

Buffer cap is 1 MiB per line. Non-JSON is logged and discarded, connection stays open. The server never sends anything on the inbound connection — no greeting, no ACK. Connect succeeding is the entire in-band signal. [verified]

The <cross-session-message ...> wrapper is content, not framing — it lives inside message.content and exists as provenance for the receiving model. Omit it and the message still arrives, attributed to unknown. [verified]

Four things that change the plan

1. --messaging-socket-path <path> exists. 🎯 [verified] Claude Code accepts an explicit socket path at launch. If crew spawn passes a squadrant-chosen path, the daemon knows the address before the process registers — no readdir, no name resolution, and no spawn/registry race. This also dissolves the naming blocker from the earlier probe: we stop caring what Claude names the session, because we address it by a path we chose. Guardrails: ≤ ~103 bytes, and Claude Code refuses to start if the path is already live rather than stealing it.

2. CLAUDE_CODE_HARBOR_KITE=1 force-enables the feature. [source] The gate is !windows && (growthbook "tengu_harbor_kite" || env CLAUDE_CODE_HARBOR_KITE). This addresses open question #4 — set it at crew launch and capability stops depending on a remote rollout. Runtime detection is still required in general; the honest check is "does connect() succeed at the expected path", never a version comparison.

3. Open question #2 resolves favourably — no settings change needed. [verified] Crews launch --permission-mode auto, which classifies as prompting, not bypass. An unattested external daemon walks the gate to accept, confirmed live. Setting crossSessionInbound: "accept" is still worth doing to remove reliance on a default we didn't choose, but it is not a prerequisite. The daemon must not attest from-mode="bypass" — that trips the parity check and holds every message.

4. Liveness is richer than this issue assumed. [verified] status has four values, not two: idle | busy | shell | waiting — and waiting carries waitingFor, e.g. "permission prompt".

That last one matters a lot for Phase 1. "Blocked on an approval prompt" has no observable signature from outside a terminal, which is precisely why the #484/#590 class of bugs was possible. The registry states it outright.

Two caveats for the LifecycleSource implementation:

• entrypoint: "sdk-cli" sessions have no status field at all. Absence must map to unknown, never idle — otherwise we report an unknown session as ready for work.
• A crashed session's last status is frozen and looks fresh forever. kill(pid, 0) is mandatory; statusUpdatedAt alone is not enough. Clean exits do remove both .json and .sock.

⚠️ Two hazards to design around

The accept path is silent. [verified] — a message was sent from a socket-bound daemon and confirmed delivered in the transcript, but no receipt arrived after 20s. Only held produces one. So the guarantee an external poster gets is exactly:

a process was listening at this path and accepted one line of bytes

Far stronger than reading a terminal, but not "the agent read it" and not "the agent acted on it". And absence of a receipt is ambiguous — delivered or refused or silently dropped.

The 30-second dedup window is a live hazard for us. [source] Limits are bucketCapacity: 30, refillPerSecond: 0.5, dedupWindowMs: 30000. Our retry path re-sends the same text — byte-identical from the same sender inside 30s is silently dropped, which is indistinguishable from the exact false negative this migration exists to remove. Any retry on this transport must vary the body (nonce or attempt counter) or wait out the window.

Phase 2 design sketch

ClaudePeerSocket delivery driver (behind the existing sendToPane seam):

  spawn:   launch crew with --messaging-socket-path <deterministic>
                       and CLAUDE_CODE_HARBOR_KITE=1
  bind:    daemon binds /tmp/cc-socks/squadrantd-<n>.sock   (required for receipts)
  send:    { msgV:1, msg_id:<uuid>, type:"user", priority:"next",
             session_id:<from registry>,          // pid-reuse guard
             from:"uds:<daemon inbox>",           // receipt address
             message:{ role:"user", content: wrap(text, from-mode:"prompting") } }
  confirm: write completed         => delivered-or-held
           receipt status:"held"   => surface to operator, do NOT retry
           receipt status:"denied" => hard fail
           ENOENT/ECONNREFUSED     => session gone, fall back to pane
  retry:   MUST vary the body (30s dedup window)

The confirm step is the whole point: it replaces confirmedSendToPane's paste → settle → re-read inference with a syscall result.

What could not be determined

Stated plainly so nobody builds on a guess:

• Approve/deny of a held message was never exercised. The held receipt was observed and the receiver flipped to waitingFor: "permission prompt", but it was never approved in the UI — so no delivered-after-hold or denied receipt was seen crossing the wire. The handling code and reason strings are in the bundle, but that is weaker than having seen it.
• priority only partly established. Three values exist and "now" bypasses the async queue; only "next" was ever sent.
• file_attachments untested. Accepted and materialized with sha256 verification; exact shape unprobed.
• hop-chain / from-session read, not exercised. Relay-loop detection; irrelevant to a single-hop daemon.
• Cross-version stability is unknowable from here. peerProtocol: 1 and msgV: 1 signal an intended contract, but nothing says the NDJSON field set is public. Neither --messaging-socket-path nor CLAUDE_CODE_HARBOR_KITE appears in --help. Treat as version-pinned; a capability probe plus pane fallback is not optional.

Version note

The writeup was produced against 2.1.226; the machine is now on 2.1.227. Spot-checked on the new version: both --messaging-socket-path and CLAUDE_CODE_HARBOR_KITE are still present in the 2.1.227 bundle, and the registry reader still runs correctly against live sessions (status showing all four values in the wild). A full re-run of the probe suite on 2.1.227 has not been done.

[tu11aa]

Follow-up filed as #669 — squadrant sessions / whoami, a read-only registry-backed introspection command.

It's the lookup both phases here need (Phase 1 reads status/waitingFor; Phase 2 resolves a crew to its messagingSocketPath), and it carries the trap list — pgrep omitting self, pid instability vs sessionId, frozen status on crashed sessions, sdk-cli sessions having no status at all. Landing it first means the LifecycleSource work here inherits a tested reader instead of growing its own.

[tu11aa]

Operator decisions, 2026-08-15 — the two open spec questions are now closed and the spec is approved.

Q1 — security items: SPLIT. The two live holes (unauthenticated opencode crew port; unattested captain inbox socket + socket-dir permissions) are now #675 and are out of scope for #667. Both are live in shipped code today, depend on nothing here, and should not wait on this issue's shadow-mode schedule.

Q2 — shadow-mode cutover: on evidence, not the calendar. Shadow runs until we have logged a meaningful volume of send/observe events and reviewed every disagreement class — no fixed number of days, no time cap. The concrete threshold gets set once slice 2 lands and real event volume is visible, rather than guessed now. Rationale: this design exists because 10+ bugs shipped on unmeasured inference; cutting over on a calendar would repeat exactly that.

Status: spec approved. Next step is the implementation plan against the four slices already defined in docs/specs/2026-08-13-agent-control-channel-design.md (1 Liveness, read-only / 2 Port + opencode delivery / 3 Claude delivery, needs 1+2 / 4 Chat, needs 3 — with the security half of the original slice 4 now living in #675). Slices 1 and 2 are independent and can run as parallel crews. Slice 1 remains the priority fallback: it alone removes two of the five false signals recorded on 2026-08-13 and changes no behaviour.