Spike: wake an idle Claude Code session over its own socket, and make mail delivery transport-aware

[Wirasm]

Spike: wake an idle Claude Code session over its own socket, and make the mailbox's delivery transport-aware. Prove it, record what is true, and only then decide what to build.

Why now

The Claude Code half of helm's mailbox is built on a premise that has expired.

hooks/helm-mail.mjs delivers on UserPromptSubmit and the notice then spends thirteen lines teaching the agent to arm its own watch — including that an unmatched zsh glob is fatal, that Monitor needs persistent: true and no timeout_ms, and "this is the last time you are told any of the above." All of that exists to work around one sentence in AGENTS.md:

Nothing outside a Claude Code session can [start a turn], so the notice instead tells the agent to arm its own watch; being notified is the wake.

That is no longer true. Claude Code 2.1.224+ ships cross-session messaging: per-session Unix sockets under /tmp/cc-socks/<pid>.sock, disk-based discovery, and — decisively — a message delivered to an idle session's socket arrives as a new user turn and wakes it. github.com/ray-amjad/peer-sessions is a worked example of a fleet built on exactly this, and this session is itself using the mechanism to steer subagents by name.

So the most elaborate machinery in the mailbox may be replaceable by a socket write.

Scope

In: claude → claude, claude → pi, pi → pi, pi → claude.

Out, deliberately: codex. It has no mailbox integration at all today — codex appears nowhere in hooks/, pi/extensions/ or either mail skill — so it is a claim problem before it is a wake problem. Solve it when it is wanted. Nothing in this spike should make it harder; note anything that would.

The framing that makes this small

Sending is already runtime-neutral: it is writing a JSON file into a directory, and anything that can write a file can send. What is per-runtime is only two things — claiming a mailbox so you are addressable, and waking you when you are idle.

So this is not an N×M problem. It is N claims + N wakes, and only the wake half is in question here.

runtime	claim	wake today	wake proposed
claude	✅ hook	arm-a-watch (Monitor), or none while idle	socket poke
pi	✅ extension	in-process sendUserMessage	unchanged
codex	❌ none	—	out of scope

The record does not change. The file mailbox stays canonical and runtime-neutral; only delivery becomes transport-aware. That keeps every rule bought with an incident: notice carries the path and never the body, operator reserved, retire-never-delete.

Assumptions to prove — each is a measurement, not a discussion

1. A socket poke wakes a genuinely idle helm-hosted session, as a new user turn, with no watch armed. Measure in a helm pane, not only in a bare terminal.
2. helm can resolve handle → pid → socket reliably. owner.json records the pid and Swift still joins owners on the pid, and the claim can record a pid that was never the agent's #247 fixed how it is recorded. Confirm it is the pid whose socket exists, not an ancestor or a wrapper.
3. What happens when the socket is stale or absent — a session that exited, a pid reused, a session started before the feature. The fallback must engage silently and correctly.
4. Deliver-before-turn still works as the fallback, so the change is strictly additive: if the socket path changes in a Claude release, worst case is exactly today's behaviour.
5. Whether Claude Code's own loop throttling is sufficient. It ships inbound policies and loop throttling; helm adding a second cap on top may be redundant or may conflict. Measure before building one.
6. THE ONE MOST LIKELY TO BITE — whether a socket-delivered wake is distinguishable, from inside the session, from the operator typing. See below.
7. Whether the sender or helm should poke. helm already reads owner.json, knows the pid and owns the pane, so a sender need never learn the recipient's runtime. Confirm nothing forces the sender to know.

The wake cap, and why it is the sharp end

hooks/helm-mail.mjs says it plainly:

THERE IS NO WAKE CAP, and its absence is a consequence rather than an omission. kild's DEFAULT_WAKE_CAP = 3 existed because delivering on Stop CONTINUED a turn… Delivering on UserPromptSubmit spends nothing — the notice rides a prompt the operator just typed — so there is no runaway to cap.

The cap is unnecessary today precisely because Claude cannot be woken. This spike succeeding is what creates the need. pi carries WAKE_CAP = 3 for exactly the reason that would now apply to Claude: sendUserMessage starts a turn from nothing, so two agents replying to each other burn until the money runs out.

And pi's counter is "consecutive wakes with no operator-driven turn between them" (index.ts:703), reset when the operator speaks. A socket-delivered message arrives as a user turn. If that is indistinguishable from the operator typing, the reset fires on every wake and the cap can never trip — a cap that looks present and counts nothing. Assumption 6 exists to catch that, and it is the one worth measuring first.

Note also that AGENTS.md currently claims both runtimes cap at 3. Only pi does. That doc line is wrong today and gets more wrong if this lands.

Deliverables

• A written record in ~/.prp/<key>/research/ naming, per assumption: what was measured, how, and what was true. A refuted assumption is a result — say so rather than quietly working around it.
• A recommendation on where the wake cap belongs if one is needed at all: helm (once, for every runtime), the runtimes (as now, twice and inconsistently), or nowhere because the platform already throttles.
• A recommendation on courier vs sender.
• No production change in this ticket. If the spike says build it, that is a second ticket with this one's measurements as its argument.

Acceptance

• Every assumption above has a verdict backed by something that was run.
• The codex gap is described precisely enough that the later ticket does not have to rediscover it.
• If the socket path proves unstable or undocumented in a way that makes it a poor foundation, that is a valid and useful outcome — record it and the arm-a-watch dance stays.

[Wirasm]

Spike result — CONDITIONAL. The mechanism works, and helm's own spawn posture is the one configuration where it silently does not.

Claude Code 2.1.226, peerProtocol: 1, macOS 26.6.1 arm64. No production change, git status clean, no PR.
Full report: ~/.prp/helm-3ec376fc/research/spike-320-socket-wake-claude.md · harness: ~/.prp/helm-3ec376fc/spikes/socket-wake-claude/ (7 re-runnable scripts).

#	assumption	verdict
1	socket poke wakes a genuinely idle helm-hosted session	CONDITIONAL
2	helm can resolve handle → pid → socket reliably	PROVEN
3	stale/absent socket degrades silently and correctly	PROVEN
4	deliver-before-turn still works; strictly additive	PROVEN
5	Claude Code's own loop throttling is sufficient	DISPROVEN
6	a wake is distinguishable from the operator typing	DISPROVEN at the hook
7	nothing forces the sender to know the recipient's runtime	PROVEN

A1 — CONDITIONAL. It wakes, unless the session bypasses permissions, which is what helm spawns.

run	mode	idle?	woke	latency
bare pty	default	yes	yes	0.12 s
bare pty	--dangerously-skip-permissions	yes	no	—
helm pane A	helm's real posture via the real spool	yes	no	—
helm pane B	same + crossSessionInbound: "accept"	yes	yes	1.01 s

No watch armed in any run. The bypass runs did not error — the socket accepted the bytes and returned cleanly. The pane showed this instead:

Held peer message — from an unidentified session [verified pid 74271]; preview: «Reply with exactly: BRAVO» — not delivered to Claude (1 held). The sender did not attest its permission mode and this session bypasses prompts. Review it below, or set "crossSessionInbound" to "accept".
❯ Deny — drop it and tell the sender it was declined / Deliver this message to Claude

That is #179 again. A modal in a pane nobody is watching is indistinguishable from an agent that never started, and the sender sees success. With no setting in force, Claude Code infers from permission mode: a prompting receiver accepts, a bypass receiver holds. SpoolUnattendedPolicy puts every spawned claude in bypass, so helm's whole fleet is the held case.

The lever is one helm already controls — --settings on the spawn argv, exactly as --dangerously-skip-permissions already is. It must be user/managed/--settings scope; a project settings file cannot supply it, because project/local may only tighten on the accept < hold < refuse ladder. (The other lever — attesting from-mode — lives in an undocumented canonicalised envelope inside the message body. Forging it would be helm asserting a permission posture on a sender's behalf. Rejected.)

A2 — PROVEN, three ways.

Read-only survey of the live fleet: 4/4 mailbox owners, the owner.json pid is the pid whose socket exists, is the registry pid, and comm is claude — not an ancestor, not the wrapper, not the shell. Confirmed again through the full helm → login → zsh → claude chain (pane A: spool pid 83634, /tmp/cc-socks/83634.sock present), and a third time with helm's real claude-session-start. helm needn't guess the path: the registry records messagingSocketPath, plus procStart (the pid-reuse guard) and status. The spool result already carries {"status":"ready","pid":…,"handle":…,"sessionId":…}.

A3 — PROVEN. Every failure is an instant, catchable errno; nothing hangs.

ConnectionRefusedError (stale, 0 ms), FileNotFoundError (absent), ENOTSOCK. Socket files leak, the registry does not — both dead sockets on disk had no registry entry, so liveness is the registry, not the file. Two free guards: procStart, and an optional session_id in the message which the receiver checks against its own (Dropping user message: session_id mismatch) — pin it and pid reuse becomes unreachable.

A4 — PROVEN, and stronger than asked: the socket only has to be a doorbell.

UserPromptSubmit fires for a socket-delivered message, so helm's existing notice rides a socket-woken turn unchanged. Proved end-to-end with helm's real hooks: mail written to the file mailbox → poke carrying only "(helm: you have mail)", no body → woke in 0.20 s → claude-user-prompt-submit delivered the notice and moved the message to read/. The record stays canonical and runtime-neutral; only the ring becomes transport-aware. Notice-carries-the-path, operator reserved, retire-never-delete all survive untouched.

A5 — DISPROVEN. Complementary, not sufficient.

burst	sends	turns started
8 identical	8	1
8 distinct	8	8

Identical repeats coalesce; distinct ones do not. A ping-pong between two agents produces different text every round — precisely what the platform dedup cannot see. The 50-unread / 100-held caps are queue ceilings, not a brake on a loop. (Also: the socket applies backpressure rather than dropping — 4 sends blocked ~5 s on recv while the queue drained, and all 4 had already been delivered. A courier needs a send timeout and must not read a blocked write as a failure.)

A6 — DISPROVEN at the hook. This is the one that bit, exactly as predicted.

The UserPromptSubmit payload for a socket message is shape-identical to an operator-typed one — same seven keys, in a bare pty and in a helm pane:
['cwd','hook_event_name','permission_mode','prompt','prompt_id','session_id','transcript_path']
No origin, no from, no sender, no flag; prompt is the raw body (the hook doesn't even see the wrapper Claude Code adds afterwards).

The distinction exists one layer in, in the transcript JSONL — origin:{"kind":"human"} / promptSource:"typed" versus origin:{"kind":"peer","from":…,"verifiedPeerPid":…} / promptSource:"system" / isMeta:true — a file Anthropic documents as "internal to Claude Code and changes between versions."

Consequence, measured rather than inferred. pi's cap is correct only because of an in-process flag: pi.on("agent_start", () => { if (waking) waking = false; else wakes = 0; }) (index.ts:982) — pi's waker and pi's counter are the same process. For Claude Code they would not be: the poker is helm, the counter would be a hook, and there is no flag to carry between them. A naive port resets on every wake and the cap can never trip. Present, counting, counting nothing.

Also: AGENTS.md says both runtimes cap at 3. Only pi does. That line is wrong today.

A7 — PROVEN: no. And A6 makes helm-as-courier load-bearing rather than merely convenient.

owner.json already carries runtime ("claude" on all four live owners). helm reads the mailbox, knows the pid, owns the pane. And if helm pokes, helm knows it poked — the same way pi's waking flag knows — so the counter can sit beside the act that needs counting.

Where the wake cap belongs

In helm, once, for every runtime — as a property of the poke, not of the woken session. It is the only place that knows a wake happened because it caused it; it is runtime-neutral; and it is unaffected if the socket format shifts. Not in a hook (measured: the hook cannot tell). Not left to the platform (A5). Reset needs care — pi resets on an operator turn; where that isn't observable to a courier, a time-based decay is honest and cheap.

Recommended second ticket, in order

1. SpoolUnattendedPolicy gains crossSessionInbound: "accept" via a helm-managed --settings file. Without it every measurement says the poke is held. This is the whole conditional.
2. Courier in helm: owner.json → pid → registry → messagingSocketPath → one JSON line, with session_id pinned.
3. Wake cap in the courier, decay-based reset. Fix the AGENTS.md "both cap at 3" line.
4. Fall back on any errno — worst case is exactly today's behaviour, which A4 proves still works.
5. Only then trim the arm-a-watch notice, and keep it for the fallback path.

Do not: forge from-mode; put the cap in a hook; parse the transcript in production.

Stability — the honest risk

The feature is documented (code.claude.com/docs/en/cross-session-messaging, shipped 2.1.224, macOS/Linux only, not Bedrock/Vertex/Foundry, not native Windows) and crossSessionInbound is a documented setting — but the wire format is not published anywhere. What was used here is Claude Code's own debug line: [uds-messaging] Inject messages: echo '{"type":"user","message":{"role":"user","content":"hello"}}' | socat - UNIX-CONNECT:<sock>. The one worked example (ray-amjad/peer-sessions) never writes to the socket at all — it asks a live Claude to call the real SendMessage tool. That is the argument for the doorbell shape: the poke carries nothing that matters, so if the format shifts helm loses the ring and keeps the mail.

codex (out of scope, described so it needn't be rediscovered)

No claim anywhere in hooks/, pi/extensions/, or either mail skill — so no handle, no owner.json, nothing to resolve a pid from. A claim problem before a wake problem. Nothing here makes it harder: the courier resolves handle → pid → transport, and codex would slot in as a third runtime with its own transport or none.

Limits

8 messages per burst; a real two-agent ping-pong was not run (one sender hammering one receiver bounds the throttle question without reproducing a live loop). claude ↔ pi and pi ↔ pi wakes not run end-to-end. Pid reuse not actually forced. Linux differs — macOS can verify peer credentials only while the sending process is still alive. haiku throughout.

One environmental confound, found and removed: the first in-pane run failed because oh-my-zsh's "Would you like to update? [Y/n]" ate the pasted launch line and left the pane at quote>. Fixed with DISABLE_AUTO_UPDATE=true in helm's environment. Unrelated to sockets — but a real hazard for any spool spawn, and possibly worth its own ticket.

Safety

Every session was spawned by this spike; nothing pre-existing was poked. All runs isolated with HELM_MAIL_DIR (plus HELM_DEFAULTS_SUITE=spike320 where a helm was launched). Negative control: ~/.helm/mail held 156 entries before and after, mtime unchanged, zero handles from any spike session. ~/.helm/spool-spike320 and ~/.helm/bench-spike320 removed afterwards. Nothing left running — ps shows no helm and no spike process.

[Wirasm]

Correction to the verdicts above — A6 changes, and the method changed to get there

The operator's methodological correction landed after the first comment: this is agent capability, so every verdict must be reached from an agent's position — and A6 in particular can only be answered from inside a session that received a wake. My first pass answered A6 by reading hook payloads and transcript JSONL from outside. That is inference, not testimony, and it was wrong in a way that mattered.

Re-run and corrected. The report is updated: ~/.prp/helm-3ec376fc/research/spike-320-socket-wake-claude.md.

First: position, measured rather than asserted

Everything in this spike ran through the Bash tool, never an interactive shell. That is now measured with the four checks push.sh's header documents, from the same call that issued every poke:

tty : not a tty | ps session : 0 | ps tty : ?? | [ -t 1 ] : false | /dev/tty : NOT openable

That is exactly push.sh's agent-tool-call signature. Position is now part of each verdict:

#	verdict	position
1	CONDITIONAL	agent tool call → real helm pane (+ pty control arm)
2	PROVEN	agent tool call, read-only + real helm pane
3	PROVEN	agent tool call, read-only
4	PROVEN	agent tool call → real helm pane, agent testimony
5	DISPROVEN	agent tool call → allocated pty
6	DISPROVEN at the hook / PROVEN in the agent's context	agent tool call → real helm pane, agent testimony
7	PROVEN	agent tool call, read-only + reasoning

A6 — the verdict changes. There are three observation points, not two.

observation point	can it distinguish?	rests on
UserPromptSubmit hook payload	NO	a documented contract
the agent's own context	YES	product behaviour, delivered as prose
transcript JSONL origin.kind	YES	internal, "changes between versions"

I found the first and third by reading files. The middle one only appeared when I asked a real agent.

A fixture agent, spawned through the real spool into a real helm pane, poked twice from an agent tool call. Never told a socket existed, never told anything unusual would happen, explicitly asked not to read its transcript or any log, and told plainly that cannot_tell was a welcome answer:

{"n":1, "origin":"operator_typed",
 "evidence":"Prompt file path specified in launch instructions with explicit instruction:
             'Read it now, in full, and act on it as if it had just been typed to you.'"}
{"n":2, "verbatim":"This is message two. Apply the protocol.", "origin":"other_process",
 "evidence":"System-reminder states: 'This came from another Claude session — not typed by
              your user, but very likely working on their behalf.'"}
{"n":3, "verbatim":"This is message three. Apply the protocol.", "origin":"other_process",
 "evidence":"System-reminder states: 'This came from another Claude session — …'"}

2/2 on the pokes, correct on the control, and it named its evidence. Claude Code puts the peer framing where the model can see it, so an agent can tell without reading a single file.

One honest nuance: the control's operator_typed judgement cited helm's own launch-line wording, not a platform signal. For a genuinely operator-typed message there is no positive marker — the signal is the absence of the peer system-reminder.

What survives unchanged, and still decides the recommendation: the hook payload is shape-identical either way (same seven keys, no origin, prompt is the raw body). So a cap in a hook still cannot work. And a cap in the agent should not: the signal is prose rather than a field, and an agent policing its own loop is exactly what stops working under the pressure a cap exists for. Legible is not countable. The courier-side cap is now more strongly indicated, not less — it is the only place that is neither blind nor unreliable nor unstable.

A4 — re-run in a pane (it had only been proved in an allocated pty), now with testimony

Real hooks, real spool, real pane, isolated mail root. owner.json pid 19856 == spool pid == socket pid. Mail written to the file mailbox; poke carried only "(helm: you have mail)", no body; it woke; message moved to read/, inbox empty. The agent's own words:

"saw_mail": true — "UserPromptSubmit hook success: helm-mail: 1 message waiting for you. from spike320 — doorbell in a pane <…>/read/…json. The notice gave me only a file path; I had to read it to get the message BODY."

That is notice-carries-the-path-never-the-body confirmed from inside by the agent it protects, rather than inferred from the hook's source.

What I am NOT claiming

• A5 and the bare-pty arm of A1 ran into a pty the harness allocated, not a pane. A5's subject is the receiving session's inbound queue, which has no knowledge of what terminal hosts it — so the pty is a fair place to measure it, but that is an argument, not a measurement, and it is the one claim here no pane run has confirmed.
• A7 is partly reasoning: that owner.json carries runtime and helm can resolve the socket are measured; that nothing forces the sender to know is an argument from those plus no counter-example.
• The testimony rests on 2 pokes plus 1 control, not a large sample.

Incidental, both unrelated to the mechanism, both cost a re-run

• An API safeguard flagged my first fixture prompt on the default model (Fable 5) — the session errored instead of answering. Re-run with a plainer prompt and --model haiku.
• The first in-pane spawn died on oh-my-zsh's "Would you like to update? [Y/n]", which ate the pasted launch line and left the pane's shell at quote>. Fixed with DISABLE_AUTO_UPDATE=true in helm's environment. This is a real hazard for any spool spawn into a fresh cwd and may deserve its own ticket.
• The agent worktree this spike started in was deleted out from under the session mid-run, taking the first helm build with it and dropping cwd back to the shared checkout. Nothing lost; recreated at .worktrees/spike-320-socket-wake (branch spike/socket-wake-claude, no commits) and rebuilt.

Safety, re-verified

Every session poked was one this spike created. ~/.helm/mail holds zero spike handles — every claim landed under the run's own HELM_MAIL_DIR. ~/.helm/spool-spike320 and ~/.helm/bench-spike320 removed. Nothing left running.