Ticket #225: tool retirement and contract shrink — verification
- Date: 2026-11-11
- Branch:
ticket/225-tool-retirement - Base:
integration/native-firstat8923d99; merged8458417(#218/#226) before final verification - Spec: parent #209; ticket #225
- ADRs: 0004, 0011
- Unit gate:
npm run verify(strict typecheck + full test suite)
Behavior
The native-first path now treats the final native text as the group message and $Name as the routing operator. A workspace native user message or agent final text routes normal peer turns with server-assigned budgets; the explicit send_message tool is no longer part of that path. The service injects one compact ensemble_turn block each native turn with the roster, conversation, and dispatch-budget numbers, so an agent does not call read-only roster tools.
The send_message, workspace_info, list_workspaces, and list_agents tools remain only on the legacy surface (and send_message is described there as a compatibility shim). delegate and handoff also stay on that surface until the native path has live loop and budget evidence. The decision tools remain on both surfaces: task_status, review, ask_person, remember, and share.
Exact tool surface
| Surface | Tools |
|---|---|
Native (default when nativeFirst: "on") | task_status, review, ask_person, remember, share |
Legacy (rollback; nativeFirst off/shadow or toolSurface: "legacy") | workspace_info, list_workspaces, list_agents, send_message, handoff, delegate, task_status, review, ask_person, remember, share |
Benchmark
npm run benchmark:tools renders a fixed 12-member, 20-message fixture through the pre-#225 contract and the current contract. Token counts are the documented chars/4 estimate; schema characters are exact JSON.
| Measurement | Before | After | Reduction |
|---|---|---|---|
| Ensemble tool schemas | 4,821 chars / 1,206 tok / 11 tools | 1,843 chars / 461 tok / 5 tools | 61.8% tokens |
| Injected identity + contract | 10,620 chars / 2,655 tok | 5,899 chars / 1,475 tok | 44.4% |
| Per-turn context (12 members, 20 messages) | 2,768 chars / 692 tok | 1,528 chars / 382 tok | 44.8% |
| Total prompt | 13,388 chars / 3,347 tok | 7,427 chars / 1,857 tok | 44.5% |
| Sender tool calls | 1 | 0 | — |
| Sender model round-trips | 2 | 1 | — |
Live fake-host sample (npm run test:live:tool-surface, one run, poll granularity 50 ms; measurement only, not a latency gate):
| Surface | Wall clock | Streaming round-trips | Tool calls | Ensemble tools | Ensemble schema | Full request estimate |
|---|---|---|---|---|---|---|
| Native final text | 387 ms | 2 | 0 | 5 | 2,143 chars / 536 tok | 7,723 tok |
Legacy send_message | 462 ms | 3 | 1 | 11 | 5,481 chars / 1,371 tok | 8,558 tok |
The provider request contained the injected ensemble_turn block and the dispatch-budget block on both surfaces (turnContextInjected and budgetContextInjected are true in the benchmark JSON).
The live round-trip count includes the routed peer's answer on both surfaces; the sender path itself is one model turn native versus two legacy. The live wall-clock difference is dominated by fake-provider and poll granularity, so the schema and round-trip counts are the stronger evidence.
Flag and rollback
nativeFirst: "on"selects the native surface;offandshadowkeep the explicit surface.settings.toolSurface: "native" | "legacy"is a validated override for one release. It is the rollback path and is accepted even while native ingestion is on, so an operator can restore the old tools without rolling back durable ingestion.- A surface change disposes and re-registers the tool transform for every attached host location; it does not wait for a restart.
- Rolling back never deletes durable messages, native turns, bindings, dispatch groups, or Work history.
Tests
npm run verify on this branch: strict typecheck passed; 1798 tests passed, 0 failed, 0 skipped.
tool-surface.test.ts: surface selection, exact native/legacy tool sets, and the explicit override.tool-registrar.test.ts: native availability, legacy rollback, thesend_messagecompatibility description, and the unchangedmaxHopscontract for delegate/handoff.service.test.ts: settings validation and live re-registration; a native workspace turn injects the compact roster/conversation/budget block; final text and thesend_messageshim create equivalent peer work.turn-context.test.ts: group, direct, and home conversation shapes, compact roster and budget rendering, and the one-to-one direct rule.prompt-benchmark.test.ts: prompt-size regression thresholds, tool-schema size, tool calls, and model round-trips.- Existing
#219/#220/#221routing tests still pass; the explicit-tool rollback test now enablestoolSurface: "legacy"explicitly.
Live matrix
npm run test:live:fake:all: PASS after the #218/#226 merge — fake 466 s, fake-empty 8 s, 2 passed, 0 failed, 0 skipped.npm run test:live: the real host run stops at the workspace wizard on both this branch and the unchangedintegration/native-firstbaseline. That is a pre-existing environment/real-catalog condition, not a #225 regression, and is reported as not run for this ticket.npm run test:live:tool-surface: PASS — the live benchmark above.
Conflict risk
- #218 reconciliation: merged after this ticket's first commit with no conflicts. Reconciliation does not call
injectNativeTurnContext; recovered terminal turns do not need a model prompt. The shared points arestartNativeTurnand the native instruction entry key, which #218 leaves to this ticket. - #226 legacy DM contract: merged with no conflicts. It removed
SnapshotState.dmTranscriptsand the legacy DM readers; this ticket touched the tool registrar,updateSettings,init-block.ts,execution.tscontext, and the tool handler surface instead. If a later change removessend_message, it should delete the legacy registrar branch in the same change. - #222 Work history: untouched. No history, paging, or card code changed.