# WO-30: Tool execution must come from structured calls

**Status:** complete in repository; verified for user publication
**Priority:** P1
**Program:** [September 5 tool-quality and live-behavior follow-up](TOOL-QUALITY-2026-09-05.md)

## Observed failure

Live descriptive text containing “shell tool interface” triggered two escalating call corrections. Source review additionally found automatic execution of bash/sh/shell/zsh response fences through a direct shellTool.execute path, bypassing normal tool validation, interruption receipts, and mutation accounting.

## Evidence and code locations

- Installed runtime: Omnius 1.0.695, active run telegram-64ac9937dc7647a8-1788593533269-1.
- Observation window: 2026-09-05 00:32–00:41 PDT.
- Live evidence: sibling telegram_test/.omnius/context-window-dumps/ and context/steering-ledger.jsonl; sanitized reproductions must avoid private conversation bodies.
- packages/orchestrator/src/agenticRunner.ts; packages/orchestrator/tests/edit-transport-guidance.test.ts

## Root repair

Remove prose/fence-to-execution and tool-name keyword coercion. Keep ordinary assistant prose and examples as text. Execute only actual structured tool calls through the existing admission path. Update the advertised protocol.

## Acceptance

- [x] A documentation fence executes no shell; descriptive tool names cause no coercion; genuine structured calls still execute and receive ordinary receipts.
- [x] Reproduce before repair with deterministic tests.
- [x] Focused regressions, affected typechecks, and workspace build pass.
- [x] Independent review is resolved and scoped commits delivered to origin/main.

## Implementation and verification ledger

Removed the entire response-fence execution path, the keyword narration classifier, its escalation counter and obsolete file-write heuristic. Updated the runtime protocol. Added structured-tool-authority.test.ts with four shell-language fences, descriptive tool discussion, and a genuine structured-call control. Replaced the obsolete source assertion in edit-transport-guidance.test.ts.

Baseline replay: five of six behavioral tests failed against 835fda0f (all four fences executed; descriptive text caused a coercive correction); structured execution passed. After repair: nine tests across both files passed. Logs: /tmp/omnius-wo30-before.log and /tmp/omnius-wo30-test.log. Aggregate build/review and final delivery are recorded in the program ledger.

## Runtime boundary

Repair the repository. Preserve live Telegram state, installed package, existing publish/ and docs/DISCOVERY.* changes. No live inference, GPU workloads, service restart, package publication, or external messaging. The user owns publication and later live validation.

### Independent review: XML protocol admission

Review reproduced a second bypass: parseTextToolCalls promoted XML examples from arbitrary prose into actions, including for native Qwen requests. The parser now requires explicit host opt-in and a complete standalone envelope sequence. Fenced/prose examples remain intact and inert, malformed batches reject as a whole, and each accepted call receives a unique transaction ID. Thirteen model-profile tests pass (/tmp/omnius-wo30-xml.log). Runner provider/stream and explicit JSON text-mode integration is recorded below.

### Runner protocol integration

Provider adapters now normalize only actual wire `tool_calls`. Canonical runner dispatch selects XML from the host's Hermes profile, or JSON from explicit text mode/the individual tools-unsupported retry. Whole standalone envelopes enter ordinary argument validation, tool accounting, interruption, steering, and completion handling. Native transactions take precedence. Code fences, prose, malformed sequences, and structured-output contracts do not grant text-call authority.

Removed the retry's fenced-JSON extraction and direct execution branch. Restored the constructor's omitted `textToolMode` option; explicit text mode advertises the standalone JSON grammar and keeps API tools disabled after exposure refreshes. Streaming uses the same admission rules and preserves inert XML examples. A chunk-ending newline no longer becomes an empty internal-marker prefix, preserving fenced output across arbitrary chunk widths.

**110 tests passed across seven suites**, including 38 production/provider authority cases, 34 typed-output tests, 22 evidence-steering tests (primary/brute and crash-point recovery), 13 model-profile tests, and three guidance tests. Orchestrator typecheck passed. Logs: `/tmp/omnius-wo30-final.log` and `/tmp/omnius-wo30-types-final.log`. The final explicit-mode exposure-refresh assertion is checked separately in `/tmp/omnius-wo30-json-final.log`. All tests use synthetic workspaces and mocked transports; no live inference or Telegram requests.

Final independent review confirmed whole-payload admission and native-call precedence, and found that text catalogs omitted argument schemas. Both text surfaces now serialize host-prepared definitions with full public parameters and a final profile filter. The updated **40 authority cases passed**, including allowed-schema/denied-tool assertions for both explicit mode and the unsupported-tools retry; final orchestrator typecheck passed. Log: `/tmp/omnius-wo30-schema-final.log`. Review findings are resolved; parent owns aggregate clean build and delivery.

Aggregate follow-up: keep hidden think blocks out of the visible provider answer while leaving XML tool examples inert. Removing content-derived invocation had also removed the older incidental reasoning strip; the provider boundary now applies only the dedicated reasoning-strip helper. All 67 tests across provider pool/recovery and the 40-case structured-tool authority matrix passed; /tmp/omnius-wo30-think-recovery.log.

## Repository closure — September 5

All confirmed findings and independent review follow-ups in this order are resolved. The [program verification ledger](TOOL-QUALITY-2026-09-05.md#verification-ledger) records the final full suites and clean build. Earlier pending integration notes above are historical and superseded by this closure.

Scoped repair commits delivered to origin/main: d2cbec82, e0da0aa6, 4465c9b2, 49f34183. Publication and subsequent live acceptance remain with the user.

Source and integration locations:

- [packages/orchestrator/src/agenticRunner.ts](../../../packages/orchestrator/src/agenticRunner.ts)
- [packages/orchestrator/src/modelProfile.ts](../../../packages/orchestrator/src/modelProfile.ts)
- [packages/orchestrator/src/typed-model-output.ts](../../../packages/orchestrator/src/typed-model-output.ts)
