# Narrated runs — engine notes for Will (2026-07-13)

Source half: commit aa67f86 on feat/agent-phase1-soul (run-progress ledger,
`/api/run-progress/<sid>` route, narration on the pause envelope, config display
default). E2E-verified via the compiled test bed on Tim's clean profile.

Compiled-form-only fixes (in `neuron-container-build/soul-narrated-runs-20260713.patch`,
applies ON TOP of `soul-webfix-20260711.patch` — these need porting to chat.el when the
webfix itself is ported):

1. **pause_turn + tool_use interleave**: a pause_turn response can ALSO carry a client
   tool_use; resuming verbatim leaves it unpaired → Anthropic 400 "tool_use ids were
   found without tool_result". Fix: tool-bearing pause rounds are tool turns
   (dispatch + pair); verbatim resume only when the round has no client tool.
2. **Agentic toolset scope**: agentic_tools_all() fed EVERY connector/MCP tool (Notion,
   code-execution…) into the loop. Code-execution flips the API into programmatic
   tool calling, whose pairing protocol the single-tool manual loop does not speak —
   source of the dangling-pair 400s AND the bash_code_execution workspace-dodge.
   Fix: handle_chat_agentic declares builtins + ONE server web_search only.
   Connector tools return when the loop gains real multi-tool/programmatic support.
3. **disable_parallel_tool_use: true** on agentic requests — the loop captures only the
   first tool_use per round; Opus-class models parallel-call. Enforce the invariant.
4. **web_search server-tool default variant → web_search_20250305 (GA)**. The 20260209
   variant couples to code-execution ⇒ programmatic mode (see #2, and the June note:
   "inert unless code-execution attached").
5. **Homegrown web_search removed** from the tool catalog (server-side is the one tool).

Known engine debts this work surfaced (not fixed):

- **Poisoned session history**: a failed run persists the malformed assistant turn; every
  later turn in that session replays it and 400s. Needs history sanitation on load.
- **Huge-history invalid-escape 400** (~346KB request) — likely the same poisoned blob.
- **macOS note**: replacing a binary in place invalidates its ad-hoc signature (instant
  silent SIGKILL, looks like exit 0). `rm + cp + codesign -f -s -` is the swap ritual.