feat(delegation): every caller is taught that a receipt means running — never re-send on silence (abilityai/trinity-enterprise#568)

[webmixgamer]

Summary

• One text, taught wherever a caller reads it. The delegation contract — a receipt means the work is running; never re-send because a call timed out or its delivery could not be confirmed; read with get_execution_result or park with set_reminder; an error without an execution_id, agent_busy included, is checked against list_recent_executions before a word-for-word re-send; pending_approval is not retried; parallel=true, async=true for long work — lives byte-identically in the platform prompt (§Agent Collaboration: every agent, every turn, no rebuild) and in src/mcp-server/src/delegation_contract.ts. The chat_with_agent and every dynamic chat_with_<agent> description carry it verbatim; fan_out and send_message repeat its rule sentence and point at it.

• Inside Claude Code's 2,048-character description cap. Claude Code shows the model only the first 2,048 characters of an MCP tool description (CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH). bug(execution): a chat turn continues whatever session was persisted last — after a long scheduled run it inherits that run's context, pays its compaction, and the execution record says nothing #2958 (2026-09-24) took the chat_with_agent description from 2,035 to 2,424 characters, so since then Claude Code has cut its tail — the list_recent_executions advice and "prefer parallel=true, async=true" — before the model read it. Before bug(execution): a chat turn continues whatever session was persisted last — after a long scheduled run it inherits that run's context, pays its compaction, and the execution record says nothing #2958 the whole text arrived (it was 1,436 characters during the 2026-09-08 cascade); other runtimes' MCP clients were not measured. It now publishes at 1,940 characters (lead + modes + contract); per-mode detail moved into parameter descriptions, which are not cut.

• The receipt says it too. Every execution_id receipt a chat_with_* caller gets carries "Do not re-send: read the outcome with get_execution_result(agent_name=…, execution_id=…)":

  • the queued_timeout that chat() and task() write when they give up, and the 409 in-flight replay — each adds one sentence after it;
  • the receipts the backend wrote — async accepted / queued, and a replayed sync-/task queued_timeout — whose REST-only "Poll GET …" line runAgentChat replaces. Those leads claim nothing about liveness ("Accepted by 'worker' as — it may still be running or already done."), because the backend replays its async receipt for 24 h, after the run may have finished or failed (bug: an async /task keeps replaying its accepted receipt for 24 h after the run fails, so an exact retry returns the failed run #3245).

  fan_out_timeout keeps its own bug(mcp): fan_out has no gateway-timeout receipt — the third route of the #914 class, and the one that runs longest #2670 wording, which says to poll get_fan_out_result instead of re-sending. The unverified "concurrent-duplicate guard will kill mid-execution" claim is gone — no such guard exists.

• Cost. Every dynamic chat_with_<agent> tool carries the full contract, so tools/list grows by about 1.6 KB per exposed agent. Deliberate: a client may read only the dynamic tool (AC2).

Acceptance criteria

• AC1 — §Agent Collaboration states the contract. replayed is deliberately not named, although AC1 lists it: no dispatch route emits it until ent#566 ships intent-scoped dedupe (only ask_operator answers replayed), and test_every_status_the_contract_names_is_emitted_by_a_dispatch_route admits only statuses a dispatch route really emits. A replay is still covered by "whatever its status" and "an exact repeat is normally answered with the original" — observed live: an identical repeat answered in 28 ms with the first call's execution_id, and one task ran. Recorded in requirements §37.5.
• AC2 — the same words in chat_with_agent and every dynamic chat_with_<agent> tool (byte parity pinned by a test that parses the TS array).
• AC3 — fan_out and send_message carry the rule sentence and point at the contract.
• AC4 — reviewed against the prompt-authoring conventions in platform_prompt_service.py (the tool description is the single source; always-render only for turn discipline no description can carry; capability-fact phrasing; bare tool names; byte-identical VERBOSE). No new ### section; §Agent Collaboration stays shorter than §Operator Communication (pinned).
• AC5 — verified on localhost after a backend reload, with no agent rebuild: the agent quoted the contract verbatim from its injected prompt.
• AC6 — after merge (below).

Changes

• src/backend/services/platform_prompt_service.py — DELEGATION_CONTRACT, spliced into §Agent Collaboration; the contract's tools added to the Codex orientation.
• src/mcp-server/src/delegation_contract.ts (new) — the shared text, DELEGATION_RULE, readNotResend.
• src/mcp-server/src/tools/chat.ts, tools/dynamic-agents.ts, tools/messages.ts, client.ts — descriptions and receipt messages.
• .github/workflows/mcp-server-test.yml — the ESM boot smoke also imports dist/tools/dynamic-agents.js (reached only from index.ts).
• Docs: requirements §37.5 (+ §37.1 correction, cross-links from core-agent.md and mcp.md), architecture/mcp-server.md and architecture/execution.md, the feature flows that teach delegation, the agent guides' stale "will fail after 60 seconds" sections, user docs.

Review round (6ac2a69, a9217b0)

/review found no critical issues and ten informational ones, six of them claims the code contradicts. All are fixed:

• The cap history above. The first commit's message (9105e14) still says the advice "never reached a model" — please don't carry that line into the squash message.
• agent_busy is not "nothing ran": the SUB-003 usage-limit 429 is raised after the turn ran, and the client labels it agent_busy (bug: chat_with_agent reports a usage-limit 429 as agent_busy although the turn already ran, so a retry repeats its side effects #3244). Contract bullet 4 now routes it through the same list_recent_executions check. The new wording is the same length, so the published figures are unchanged.
• The receipt leads no longer claim liveness, and the backend's sync-/task queued_timeout replay is rewritten too (bug: an async /task keeps replaying its accepted receipt for 24 h after the run fails, so an exact retry returns the failed run #3245).
• "Every receipt ends with readNotResend" is corrected: fan_out_timeout has its own wording, and two receipts add a sentence after it.
• The synchronous /chat route is the one path that emits no agent.task.* event. execution.md, task-completion-events.md and the user docs now say so.
• §37.1 is finished. The guides' 60 s (now 25 s) and "a long call does not fail" overclaims are fixed, and so are seven stale lines that told MCP callers to poll REST, use async=true without parallel=true, or omit agent_name.
• Tests: the mutations that survived are now caught (below), and a row timestamp that was set at import time is built per test.

Coordination with #3238

#3238 adds a budget test over every published tool description with a shrink-only PENDING entry for chat_with_agent owned by this issue — and an entry that fits the cap fails. Whichever PR lands second deletes chat_with_agent from PENDING in src/mcp-server/src/tool-description-budget.test.ts.

Test plan

• cd tests && pytest unit/test_ent568_delegation_contract.py -v — 31 passed
• node --import tsx --test src/delegation-contract.test.ts (in src/mcp-server) — 22 passed; full MCP suite 704/704; tsc build + ESM boot smoke
• Mutations — 15 wiring mutations before the review (the splice, the Codex names, each description, the factory, the registration wrapper, each receipt builder, a drifted TS copy) and 10 after it (a dropped async, swapped or optimistic leads, a skipped rewrite per session kind, a factory that ignores the backend line, both queued_timeout branches, TS-only contract drift) — each goes red
• This PR's suite plus the existing prompt and docs suites (feat: MAX_REDELIVERY cap + async operator-queue human-gate lever (lease-reaper backstop) #1402, ent#243, Inject reporting (MCP report tool) guidance into the agent platform prompt #1535, ent#536, bug: agents route "run a loop" to Claude Code's built-in /loop + ScheduleWakeup — success is reported, nothing ever fires in headless runs #2454, ScheduleWakeup is offered in one-shot headless runs — it schedules a wakeup that never fires and tells the model it WILL be re-invoked #2468, feat(tests): journey catalog (intent only) + generated JOURNEYS.md #2338, docs: consolidate docs/testing — 17 files to STRATEGY.md plus pointers #2339, runtime, unit) — 282 passed after the review round
• /verify-local --skip-agent --skip-unit on a05b1fc — build + import smoke, boot, preflight, integration (70 passed, 13 agent/Postgres-gated skips, 2 known false fails). Stage 1's 42 order-dependent failures are identical on a clean origin/dev worktree. Not re-run after the review round, whose only backend change is the text of one string constant.
• Localhost eyeball (before the review round) — prompt quoted verbatim; published descriptions chat_with_agent 1,940 / fan_out 1,892 / send_message 868 characters; async receipt wording; identical repeat answered with the original execution_id. Since then, bullet 4 (same length) and the receipt leads have changed.
• /review — no critical findings, ten informational, all fixed (above); /cso --diff — no findings (docs/security-reports/cso-diff-2026-10-05-ent568-delegation-contract.md)

Follow-ups filed while building this: #3232, #3233, #3234 (in review as #3238). From the review: #3244 (a usage-limit 429 is reported as agent_busy after the turn ran), #3245 (an async receipt is replayed for 24 h after its run failed).

Debt adjacency, nothing paid down here: chat.ts carries #1074 (removing the deprecated timeout_seconds will also drop the sync-parallel note moved into that parameter's description), messages.ts carries #3087, client.ts carries #1029.

After merge

• Set status-in-dev on abilityai/trinity-enterprise#568 by hand — the status workflow does not promote a cross-tracker issue
• AC6 — ask trinity-pm, which owns the canon, to make canon/protocols/playbook-call.md cite §Agent Collaboration's delegation contract instead of restating it
• Deploy: rebuild the mcp-server image (tool descriptions are baked in); the prompt reaches agents with the backend deploy, no agent rebuild

Fixes abilityai/trinity-enterprise#568

🤖 Generated with Claude Code