Skip to content

Ticket #225: tool retirement and contract shrink — verification ​

  • Date: 2026-11-11
  • Branch: ticket/225-tool-retirement
  • Base: integration/native-first at 8923d99; merged 8458417 (#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 ​

SurfaceTools
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.

MeasurementBeforeAfterReduction
Ensemble tool schemas4,821 chars / 1,206 tok / 11 tools1,843 chars / 461 tok / 5 tools61.8% tokens
Injected identity + contract10,620 chars / 2,655 tok5,899 chars / 1,475 tok44.4%
Per-turn context (12 members, 20 messages)2,768 chars / 692 tok1,528 chars / 382 tok44.8%
Total prompt13,388 chars / 3,347 tok7,427 chars / 1,857 tok44.5%
Sender tool calls10—
Sender model round-trips21—

Live fake-host sample (npm run test:live:tool-surface, one run, poll granularity 50 ms; measurement only, not a latency gate):

SurfaceWall clockStreaming round-tripsTool callsEnsemble toolsEnsemble schemaFull request estimate
Native final text387 ms2052,143 chars / 536 tok7,723 tok
Legacy send_message462 ms31115,481 chars / 1,371 tok8,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; off and shadow keep 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, the send_message compatibility description, and the unchanged maxHops contract 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 the send_message shim 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/#221 routing tests still pass; the explicit-tool rollback test now enables toolSurface: "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 unchanged integration/native-first baseline. 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 are startNativeTurn and the native instruction entry key, which #218 leaves to this ticket.
  • #226 legacy DM contract: merged with no conflicts. It removed SnapshotState.dmTranscripts and the legacy DM readers; this ticket touched the tool registrar, updateSettings, init-block.ts, execution.ts context, and the tool handler surface instead. If a later change removes send_message, it should delete the legacy registrar branch in the same change.
  • #222 Work history: untouched. No history, paging, or card code changed.

Released under the MIT License.