feat(agent): agent-to-agent callback routing (reply_to) — orchestrator substrate

[unforced]

What

Request/response between agent threads, built ON the thread-as-container (#122) + pending-inbound (#121) substrate. When an agent sends a message to ANOTHER agent and wants to know when it's done, it sets a callback address on the message. When the recipient finishes its turn, the daemon delivers a lightweight callback back to the sender's channel — a NOTIFICATION + a LINK to the result, not the full result duplicated. The sender (an orchestrator) is woken by the callback and PULLS the full result if it wants.

Summary + link, orchestrator pulls (the explicit design choice): cleaner (callback notes stay small/uniform) + a better security boundary (the orchestrator reaches the result through its own read scope; the callback carries only opaque ids).

No new transport, no new backend — additive metadata + one new daemon→registry seam.

The model

reply_to on inbound (the SEND side)

An #agent/message/inbound note MAY carry, in metadata:

• reply_to — the sender's channel name (where to deliver the callback). Absent → no callback (ordinary turn).
• correlation_id — (optional) opaque id the sender matches replies to requests with; echoed verbatim.
• delegation_depth — (optional, default 0) hop count; the loop-guard counter.

These ride note.metadata → ingestInbound flattens into meta → contextFor.emit extracts via callbackFieldsFromMeta → onto QueuedMessage → the drain. The pending buffer carries them too (a delegated request that arrives before its recipient is live still calls back on replay).

Callback on turn-completion (the core)

In the drain, after a turn completes on BOTH ok and error (the orchestrator MUST learn about failures), IF the message had reply_to, the daemon writes a NEW #agent/message/inbound note to the reply_to channel (wakes the sender through the normal vault-trigger path).

Metadata contract:

Field	Value
callback	"true"
status	"ok" | "error"
source_channel	the recipient channel/def that finished
source_thread	the recipient's per-turn #agent/thread id (pull the full thread record)
source_message	the recipient's OUTBOUND reply note id, when a reply landed (absent on error/empty turn)
correlation_id	echoed when present
delegation_depth	incoming + 1

Brief content ([callback] <ch> finished (ok) — see source_message / source_thread …), never the duplicated reply. source_message is captured by widening WriteOutbound's return to Promise<{ id?: string } | void> (back-compat — void is in the union, so every existing recorder still satisfies it).

Loop safety (3 layers, defense-in-depth)

1. The callback note never carries reply_to (structural — no ping-pong). Enforced at the daemon wiring AND stripped defensively in VaultTransport.writeCallback.
2. delegation_depth ceiling (MAX_DELEGATION_DEPTH = 8): a message at/past the ceiling delivers NO callback (logged loudly). Bounds any chain even if layer 1 were defeated. The turn still runs + records.
3. Unknown / not-live reply_to channel reuses the fix(agent): pending-inbound queue + replay (#121) and thread-as-container working-ensure #122 own-it-don't-strand posture: buildWriteCallback logs + returns WITHOUT throwing — never crashes the recipient's drain.

A callback delivery failure is best-effort: logged, never thrown, never re-runs the (completed) turn.

Concurrency (verified, not re-architected)

#122 already gives it. N callbacks returning to one orchestrator channel arrive as inbound notes, queue FIFO, and drain ONE at a time via the per-channel serial #draining invariant — never two concurrent claude -p for one channel, so the orchestrator's single-threaded --resume session carries state across them, none lost. A test simulates N callbacks draining FIFO with maxConcurrent === 1.

Files

• src/backends/registry.ts — QueuedMessage gains replyTo/correlationId/delegationDepth; WriteCallback seam + CallbackMeta + MAX_DELEGATION_DEPTH; maybeDeliverCallback at all four drain terminal points; WriteOutbound returns the note id.
• src/daemon.ts — callbackFieldsFromMeta; contextFor.emit threads the fields (enqueue + pending); buildWriteCallback; buildWriteOutbound returns the note id.
• src/transport.ts — Transport.writeCallback? + CallbackMetadata.
• src/transports/vault.ts — VaultTransport.writeCallback; writeInbound optional extraMeta.
• design/2026-06-20-agent-callbacks.md.

Tests / gate

bun run test (typecheck + bun test ./src) green — 1017 pass, 0 fail. New coverage: all four drain terminal points, the depth guard at ceiling + ceiling-1, no-reply_to → no callback (regression), unwired/throwing sink, FIFO concurrency, callbackFieldsFromMeta coercion, end-to-end contextFor.emit threading, buildWriteCallback own-it, the full vault callback-note metadata contract + reply_to-strip, and the ingestInbound flatten round-trip.

Independent reviewer pass: LGTM, no critical issues, no must-fix bugs (the two comment-clarity nits applied; the shared-type-refactor nit left as a noted follow-up since the duck-type is typecheck-guarded).

Deferred

• A dedicated delegate MCP tool that fills in reply_to/correlation_id/delegation_depth so an orchestrator doesn't hand-stamp them (SEND-side ergonomics).
• Single-threaded source_thread is a per-turn correlation id (the deterministic thread-note-by-stable-path linkage is the same gap that already exists for metadata.thread).

No version bump (per instructions).

🤖 Generated with Claude Code