[spacedragon]

Summary

sendMessage had a 4363-character description and a 9484-character schema built on a top-level oneOf. OpenAI-hosted function tools are reported to cap a description at 1024 characters. This PR implements docs/designs/send-message-guide.md:

• Required action (§3–§7). sendMessage takes a required action (callAgent, startTask, messageTask, replyToSession, postMessage) and a flat schema. Detailed usage moves into a new getToolGuide tool. A call without action is rejected before any effect, and the error points to the guide. The description is now 971 characters and the schema 1956.
• Tasks replace background sub-sessions (§2.1, §8).
  • startTask {message} starts a task of the current session, and messageTask {taskId, message} sends more work to it across work rounds.
  • Each round reports automatically.
  • stopTask {taskId} replaces stopSubsession: the owning session may stop its own task on any of its turns, and every other caller gets the unknown-id answer.
  • A self callAgent without channel, or a messageTask without taskId, is rejected. The error contains the exact startTask call and the startTask guide.
• Existing peer sessions and replies by message id (§9).
  • callAgent with sessionId calls an existing peer session, any number of times.
  • Every message one session sends another carries an id and trusted metadata: source session, source agent, return route, kind, and whether a reply is requested.
  • replyToSession {messageId, message} is authorized and routed by that message's record alone. A message may be answered more than once, and reply obligations are tracked per message.
  • A session's origin now only records who created it.
  • Store schema v52 replaces the earlier reply-source tables and migrates each existing origin into one message record.
  • The relay forwards the new frame fields only to daemons advertising session-message-v1 and strips them for an older daemon, so calls between versions keep working.
• Glossary. GLOSSARY.md gains the terms Conversation, Session, Task, Owning session, Session message, and Reply, and reworded entries for Origin session and Reply obligation.

Breaking change for reviewers and operators

Calls without action are rejected; there is no transition period (§4). Agent descriptions, knowledge articles, and skills that show the old sendMessage forms must be updated by hand when this is deployed. The same applies to replyToSession {sessionId}, messageSubsession, and stopSubsession.

Verification

• typecheck passes for daemon, protocol, relay and control-plane.

• eslint reports 0 errors on the changed files, and prettier passes.

• Daemon: the 40 test files this branch touches, plus the §7.6 baseline suites, all pass: 1358 passed, 13 skipped. That includes a Postgres run of the store migration test.

• Relay agent-msg-router tests pass (41), and so do protocol tests (747).

• Live runtime matrix (packages/daemon/test/acp-matrix/send-message-probe.ts, 7 comparable scenarios × 2 reps), compared with the pre-change baseline:

  Runtime	Baseline (pass/scored)	After
  claude-acp	14/14	14/14
  cursor	14/14	14/14
  devin	13/14	14/14
  github-copilot-cli	13/14	13/14 ¹
  opencode	13/14	13/14 ¹
  codex-acp	6/6 (8 unavailable)	14/14
  omp	14/14	not measured ²
  qwen-code	5/14	not measured ²

  ¹ Both misses passed 2/2 on recheck. The copilot miss was a host "Too many open files" error; the opencode miss was a plain channel post instead of callAgent.
  ² Every turn from these two runtimes failed at the model provider with "402 Insufficient Balance", in about one second and with no tool call. They need a rerun once the provider account is topped up.

  No scenario that passed 2/2 in the baseline now fails 2/2.

Not done: product conventions, assistant-mode §5.6–§5.8, and the console's Sub-sessions tab still say "sub-session". Renaming them is a follow-up (§11 questions 10–11).

🤖 Generated with Claude Code · Opus 5.5

[agentconnect-md-test]

Architecture review of fa6eb6f (merge of base b94e1e1 verified locally).

Verdict: request changes, one blocking item

The runtime shape is aligned with the architecture and with send-message-guide.md as written. What blocks is documentation drift that this PR itself introduces into the file CLAUDE.md names as the authority for product behaviour.

Blocking: docs/product-conventions.md describes a sendMessage contract the daemon at this head rejects

This PR edits the file to name forms that never shipped or that the same PR removes:

• Lines 699–700 and 1262: "a postless messageSubsession call" / "sendMessage with action messageSubsession". messageSubsession is not a sendMessage action at this head (SEND_MESSAGE_ACTIONS is callAgent, startTask, messageTask, replyToSession, postMessage) and never existed on main (git grep messageSubsession on the base is empty). The shipped form is startTask {message}.
• Line 704: sendMessage({"action":"replyToSession","sessionId":"<parent>", …}). At this head replyToSession with sessionId is an argument error by design (§3.5, §9.8); the contract is messageId.
• Lines 1274–1277: "A later messageSubsession with the childSessionId it returned". The shipped form is messageTask {taskId}.
• Line 130 and lines 1300–1310 (unchanged text, changed behaviour): stopping a sub-session "follows the !stop sender rule", "only on a turn a person there started, and only for someone !stop accepts there … A sub-session, patrol, approved task, hook or scheduled run cannot stop one." This PR removes the person-started-turn and !stop sender gates and makes the owning session the sole authority on any of its turns, hook and scheduled runs included (§8.7, §12 item 4, assistant-subsessions.ts). The convention now states a gate that no longer exists.

The design's §11 question 10 defers vocabulary (sub-session versus task) to a follow-up, and that is a reasonable scope cut. These are not vocabulary: they are call shapes and an authority rule, and the PR's own body says agent descriptions, knowledge articles and skills must be hand-migrated from the docs. The authoritative doc has to carry the shipped contract in the same change that makes the break. Please update those passages (the sub-session wording can stay for now if you prefer; the call forms and the stop rule must be the shipped ones).

Same category, not blocking on its own but should be fixed or bannered here the way session-concept.md was:

• docs/designs/assistant-mode.md §5.6 line 676 "a postless self-call opens one" (now refused) and §5.8 (stop gates removed).
• docs/designs/send-message-routing-rework.md line 519 "sendMessage({"sessionId":"<parent>"…}) remains authorized". The new design names this doc as its baseline, so a reader following the pointer lands on a contradicted rule.

Architecture confirmations (no action)

• Data-plane invariant holds. session_message / session_message_sent live in the daemon store (SQLite or the shared PostgreSQL dialect); bodies stay in transcripts; there is no control-plane change. The relay forwards messageId/messageKind/inReplyTo/targetSessionId/callerAskers as metadata and persists nothing. callerAskers is asserted by the authenticated source daemon exactly like lineage, so no new trust root.
• Versioned seam. New frame fields are optional and gated on agent-session-call-v1 / session-message-v1; session-call fails closed on an older relay or daemon, and the pre-id compatibility path is explicit and bounded.
• Reply authority is the record alone. replyToSession resolves the received-message row, checks recipient key and agent, and refuses with one wording; an owner's reply into its own task is routed through messageTask admission so the ownership and round accounting cannot be bypassed. Remote replies land only in the session the sent-message record names. The origin is written once and read for nothing but status.
• Peer-session admission reuses the existing read rule (judgeSessionParticipation over askerMayRead/checkPlaceRead) rather than inventing a second authorization vocabulary, and a turn no person is behind is refused. Good.
• stopTask authority is the persistent index row (parent key and outward id), not turn state. The trade recorded in §6/§11 Q9 (a peer's reply text can now lead the owner to stop a task) is bounded because a stop undoes nothing and messageTask reopens; acceptable, but it is a product-level change and belongs in product-conventions (covered above).

Non-blocking notes

1. Compatibility code for the branch's own intermediate contract. coordinator.ts rewrites persisted reports naming messageSubsession, and subsession-approval.ts strips LEGACY_TASK_START_WRAPPER. Neither text was ever produced by a main build. Unless an intermediate build was deployed somewhere you need to carry, remove these so "legacy" in this codebase keeps meaning "a released daemon". If it was deployed, say so in a comment with the removal condition.
2. Relay now shapes message text. agent-msg-router.ts prefixes From <label>: for a daemon without session-message-v1. It is a defensible compatibility shim, but it moves sender framing from the daemons into the relay. Please record its removal condition (daemon floor at or above session-message-v1) so the relay returns to pure forwarding.
3. session-concept.md banner approach. The file now carries two "the passages below describe the earlier design" layers. Fine for this PR; schedule a rewrite of §2.3/§5 so the session definition does not depend on the reader applying overlays.
4. Design doc and implementation in one PR. send-message-guide.md is new here with status "implemented". Acceptable given the parity audit in §7 and the implementation records in §7.8/§8.9/§9.8, which are thorough. Future revisions of this line should land the design first so review can hold the code to a reviewed design rather than the reverse.

Re-request review after the product-conventions fix; the rest can follow in the tracked §11 Q10/Q11 follow-up.

_{sent by architect (Claude Agent · claude-fable-5-1) · open in session}

[agentconnect-md-test]

messageSubsession is not an action at this head (and never was on main). The shipped form for postless self-work is startTask {message}; a self callAgent without channel is refused with that call. This file is the product authority CLAUDE.md points to, so it has to name the shipped contract.

[spacedragon]

Fixed in 92fa64d: the postless self-call sentence now says a self-call without a channel is refused with the startTask call, and startTask opens the background sub-session.

[agentconnect-md-test]

Confirmed in d19ccaeb: the text now describes the refused self-call and the startTask alternative correctly. The approval stands.

_{sent by review-bot (Codex · gpt-6-astra) · open in session}

[agentconnect-md-test]

At this head replyToSession with sessionId is an argument error by design (§3.5, §9.8). The contract is {"action":"replyToSession","messageId":"<id of the message being answered>", …}.

[spacedragon]

Fixed in 92fa64d: the section now shows replyToSession with messageId and states that the reply is authorized and routed by the answered message alone.

[agentconnect-md-test]

Confirmed in d19ccaeb: the section uses replyToSession with messageId and correctly ties authorization and routing to the answered message. This finding is resolved.

_{sent by review-bot (Codex · gpt-6-astra) · open in session}

[agentconnect-md-test]

Same as above: the shipped action is startTask, taking only action and message.

[spacedragon]

Fixed in 92fa64d: startTask with only a message.

[agentconnect-md-test]

Confirmed in d19ccaeb: the section now specifies action: "startTask" with only message. This finding is resolved.

_{sent by review-bot (Codex · gpt-6-astra) · open in session}

[agentconnect-md-test]

The shipped continuation is messageTask {taskId}; the receipt names the handle taskId, not childSessionId (§8.6, §12 item 2). Also worth stating here, since it is a behaviour change this PR makes: the owning session may stop its task with stopTask on any of its turns, and the !stop sender / person-started-turn gates described at lines 130 and 1300–1310 no longer apply to that tool (§8.7).

[spacedragon]

Fixed in 92fa64d: continuation is messageTask with the taskId from startTask, and the stop paragraph (and the line-130 exception list) now state the shipped stopTask rule: the owning conversation on any of its turns, no !stop sender gate, every other caller refused in the unknown-id words.

[agentconnect-md-test]

Confirmed in d19ccaeb: continuation uses messageTask {taskId}, and stopTask is authorized by owning-session identity on any turn, without the !stop sender gate. Both documentation points are resolved.

_{sent by review-bot (Codex · gpt-6-astra) · open in session}

[agentconnect-md-test]

Reviewed fa6eb6f. Two introduced correctness issues need fixes:

1. [P2] Settle the peer wait when a remote reply is admitted — packages/daemon/src/collab/coordinator.ts:664–668

   When a task calls a peer on another daemon with needsReply: true, its originating daemon stores a remote link with replyState: 'awaiting'. The returning handleRelayAgentMsg path admits the reply but never updates that link; markChildParentReply runs on the replier's daemon. Consequently awaitsPeerReply remains true after the task processes the reply and finishes. The new round settlement guard suppresses its completion report, retains its concurrency slot, and eventually the idle sweep reports a failure. Reconcile the originating task's outstanding call when its reply is admitted, using the message correlation.

2. [P2] Forward the submission ID for existing-session calls — packages/daemon/src/mcp/ops/send-message-actions.ts:235–237

   callPeerSession omits submissionId: deps.callId, although the other send paths forward it. Replaying the same MCP request therefore reaches callExistingSession without a submission ID, so messageIdFor mints a fresh ID each time. The receiver admits another message and can repeat the requested work instead of returning the original receipt. Forward the stable call ID here as well. The coordinator-level replay test supplies submissionId directly and does not exercise this missing tool-layer wiring.

Validation: isolated execution of the changed methods with mocked dependencies reproduced both issues: an admitted remote reply left the wait true, and two existing-session tool calls with the same callId both omitted the submission ID. git diff --check passed. Full daemon tests were not run because dependency setup remained incomplete. No tracked files were changed.

_{sent by review-bot (Codex · gpt-6-astra) · open in session}

[spacedragon]

Addressed in 92fa64d and d19ccae.

Architecture review

• Blocking, product conventions: now names the shipped forms: startTask {message}, messageTask {taskId}, replyToSession {messageId}, and the refused self-call without a channel. The stop rule is now the owning session's stopTask, allowed on any of its turns without the !stop sender gate; the exception list near the top is updated to match. The sub-session vocabulary stays for the §11 Q10 follow-up.
• Other affected docs: assistant-mode.md §5.6 and §5.8, and §7 of send-message-routing-rework.md, now open with an update note that points to send-message-guide.md for the new contract.
• Note 1, branch-only compatibility code: removed the rewrite of messageSubsession hints in persisted reports, and the branch-only task-start wrapper. The wrapper the review named, LEGACY_TASK_START_WRAPPER, is the one released main produced (in v2.4.0), so its stripping stays.
• Note 2, relay framing: the shim now carries its removal condition. Once the supported daemon floor advertises session-message-v1, the fallback and the From <label>: framing are removed and the relay goes back to forwarding only.
• Notes 3–4: recorded for the follow-up.

review-bot

1. A remote reply now ends the wait. When a peer's reply is admitted through the relay, the waiting link that matches the answered messageId (from the sent-message record) is marked answered. A peer without message ids is matched by lineageReplyTo and its agent instead. Locally, a reply ends only the wait for the message it answers. Regression tests: a task calls a remote peer and its round reports finished once the reply arrives, with and without message ids.
2. callPeerSession now forwards submissionId. A tool-layer test sends the same callId twice and gets one recorded message, the first receipt, and one prompt to the target.

[agentconnect-md-test]

Reviewed d19ccae. Both findings from my previous review are resolved:

• Admitted remote replies now settle the matching peer wait, allowing the task round to complete. Message correlation prevents an older reply from settling a newer wait.
• Existing-session calls forward the stable submission ID, and replaying an answered call preserves its settled state.

The product-convention corrections now describe the shipped actions and stop authority. No remaining blocking findings.

Validation: focused execution of the changed methods with mocked dependencies passed for submission-ID forwarding, remote-reply settlement, message correlation, settled-call replay, and legacy replies. Reviewed the added regression tests; git diff --check passed. Full daemon tests were not run because this checkout still lacks a complete dependency installation.

_{sent by review-bot (Codex · gpt-6-astra) · open in session}

[agentconnect-md-test]

Architecture review of d19ccae (exact head checked out locally; two commits since fa6eb6f: 92fa64d docs, d19ccae daemon fixes).

Verdict: approve

The blocking finding from the previous round is resolved, and the follow-up notes are either addressed or recorded.

Blocking item: resolved

docs/product-conventions.md now states the shipped contract: a self-call without a channel is refused with the startTask call; background self-work is startTask with only a message; continuation is messageTask with the taskId startTask returned; the parent-reply section shows replyToSession {messageId} and says the reply is authorized and routed by the answered message alone. The stop rule is the owning conversation's stopTask on any of its turns, with the !stop sender gate explicitly not applying, and the exception list near the top of the file was updated to match. The sub-session vocabulary stays for the §11 Q10 follow-up, which is the scope cut I accepted.

Follow-up notes: verified

• assistant-mode.md §5.6 and §5.8, and send-message-routing-rework.md §7, now open with an update note pointing at send-message-guide.md for the new contract, the same pattern session-concept.md uses. Acceptable for this PR; the rewrite of those sections stays a follow-up.
• Branch-only compatibility code: the messageSubsession report rewrite and the branch-only TASK_START_WRAPPER are gone. LEGACY_TASK_START_WRAPPER is kept, and I confirmed it is the wrapper the base (main) produces, so stripping it from approval-card labels is genuine released-daemon compatibility.
• The relay framing shim now carries its removal condition in the comment (daemon floor advertising session-message-v1).

review-bot's findings

Both fixes are consistent with the architecture rather than patched around it: the in-memory peer-wait link now carries the messageId it waits on, a remote reply admitted through the relay ends exactly that wait (correlated through the sender's own sent-message record, with a lineage fallback for pre-id peers), and callPeerSession forwards the MCP callId so a replayed existing-session call keeps one message id and one receipt. That keeps "replies are correlated by message, never by session state" true across daemons. I read the fixes and the added tests; I did not run the daemon suites in this sandbox.

Still open for later PRs (non-blocking, recorded)

• §11 Q10/Q11: product and assistant-mode vocabulary (sub-session vs task; approved proposals called tasks).
• §11 Q9: a peer's reply text can lead an owning session to stop a task; revisit if this is abused.
• Rewrite session-concept.md §2.3/§5 and the bannered sections instead of stacking update notes.
• Other oversized tool descriptions (§11 Q6) may want to join getToolGuide.

_{sent by architect (Claude Agent · claude-fable-5-1) · open in session}

[agentconnect-md-test]

Verified both fixes at d19ccaeb and already submitted APPROVE. Focused checks passed for remote-reply settlement and submission-ID forwarding; no remaining blockers from my review.

_{sent by review-bot (Codex · gpt-6-astra) · open in session}

[agentconnect-md-test]

Verified at d19ccae before approving: all four product-conventions passages now state the shipped forms, the stop paragraph and the line-130 exception list carry the owner-only stopTask rule, and the update notes on assistant-mode §5.6/§5.8 and routing-rework §7 point at the new design. On note 1, I confirmed on the base that LEGACY_TASK_START_WRAPPER is the text released main produces, so keeping that strip is correct; the branch-only rewrite and wrapper are gone. The relay shim's removal condition is recorded.

The two review-bot fixes read as consistent with the design's rule that replies are correlated by message rather than session state, including across daemons. I read the fixes and the added regression tests but did not run the daemon suites here.

My APPROVE at d19ccae stands. Remaining items are the recorded follow-ups: §11 Q10/Q11 vocabulary, Q9 owner stop on peer-reply turns, and rewriting the bannered sections of session-concept.md, assistant-mode and routing-rework rather than stacking more update notes.

_{sent by architect (Claude Agent · claude-fable-5-1) · open in session}