zidane 7.0.14 → 7.0.16

package/docs/ARCHITECTURE.md

@@ -1,5 +1,9 @@
 # Zidane Architecture
 
+Internal execution model of the agent loop: how a run boots, how a turn streams, how a tool call is gated/executed/transformed, and the hook contracts that hold it together. Read this when you're modifying `src/agent.ts` / `src/loop.ts`, writing a hook that depends on firing order, or diagnosing a prompt-cache break. For the public API surface (createAgent, presets, hooks, sessions) see `docs/SKILL.md`.
+
+Contents: [Agent Lifecycle](#agent-lifecycle) · [Turn Loop](#turn-loop) · [Single Turn](#single-turn) · [Tool Execution](#tool-execution) · [Tool ergonomics defaults](#tool-ergonomics-defaults) · [Prompt caching](#prompt-caching) · [Tool aliasing](#tool-aliasing-wire-vs-canonical) · [Skills activation lifecycle](#skills-activation-lifecycle) · [Progressive tool disclosure](#progressive-tool-disclosure) · [Hook Firing Order](#hook-firing-order) · [Dependency Graph](#dependency-graph) · [Presets](#presets) · [Option Precedence](#option-precedence)
+
 ## Agent Lifecycle
 
 ```mermaid
@@ -7,51 +11,48 @@ flowchart TB
     subgraph Creation ["createAgent()"]
         C1[Create hooks] --> C2[Merge config]
         C2 --> C3["Provider + Tools + Options"]
-        C3 --> C4["eager: true?"]
+        C3 --> C4["eager: true AND\n(MCP servers or skills configured)?"]
         C4 -->|yes| C4B["Kick off warmup()\nin background"]
         C4 -->|no| C5[Return Agent]
         C4B --> C5
     end
 
-    subgraph FirstRun ["First run() — lazy init"]
-        L1["executionContext.spawn()"] --> L2["warmup()\nawait in-flight OR\nconnect MCP servers\nin parallel (Promise.all)"]
-        L2 --> L3["resolveSkills()"]
-        L3 --> L4["buildCatalog() → system prompt"]
-    end
-
     subgraph RunSetup ["run() setup"]
-        R1["Validate prompt\n(required unless session has turns)"] --> R2["session.startRun()"]
-        R2 --> R3["Resolve behavior\n(maxTurns, maxTokens, thinkingBudget, cache)"]
-        R3 --> R4["Build system prompt\n(agent system + skills catalog)"]
-        R4 --> R5["Build tools\n(agent tools + MCP)"]
-        R5 --> R6["Build turns\n(resume session + system + prompt?)"]
-        R6 --> R7["runLoop()"]
+        R1["Resolve model fallback chain\nValidate prompt / resume preconditions"] --> R2["Resolve behavior\n(maxTurns, maxTokens, thinkingBudget, cache)"]
+        R2 --> R3["session.startRun() → session:start hook"]
+        R3 --> R4["ensureExecutionHandle()\n(spawn execution context, idempotent)"]
+        R4 --> R5["warmup(): Promise.all(\n  connect MCP servers,\n  resolveSkills() → buildCatalog())\nidempotent, shared promise"]
+        R5 --> R6["Build tool aliases + formatted tool specs"]
+        R6 --> R7["Build system prompt\n(agent system + skills catalog)"]
+        R7 --> R8["Build turns (resume + seed prompt)\n→ session:turns hook"]
+        R8 --> R9["runLoop()"]
     end
 
     subgraph PostRun ["Post-loop"]
         P1{"Aborted?"} -->|yes| P2["session.abortRun()"]
         P1 -->|no| P3["session.completeRun()"]
-        P2 --> P4["agent:done hook"]
+        P2 --> P4["finalizeSession() → session:end hook"]
         P3 --> P4
-        P4 --> P5["Return AgentStats"]
+        P4 --> P5["agent:done hook"]
+        P5 --> P6["Return AgentStats"]
     end
 
-    Creation --> FirstRun
-    FirstRun --> RunSetup
+    Creation --> RunSetup
     RunSetup --> PostRun
 
     style Creation fill:#1a1a2e,stroke:#e94560,color:#fff
-    style FirstRun fill:#16213e,stroke:#0f3460,color:#fff
-    style RunSetup fill:#1a1a2e,stroke:#e94560,color:#fff
+    style RunSetup fill:#16213e,stroke:#0f3460,color:#fff
     style PostRun fill:#16213e,stroke:#0f3460,color:#fff
 ```
 
+`ensureExecutionHandle()` and `warmup()` do real work only on the first `run()` / `warmup()` / `activateSkill()` call — both are idempotent and memoize on a shared in-flight promise, so every later call in the process fast-paths through.
+
 ## Turn Loop
 
 ```mermaid
 flowchart TB
     START((runLoop)) --> ABORT1{Aborted?}
-    ABORT1 -->|yes| DONE["agent:done hook\nReturn stats"]
+    ABORT1 -->|yes| DONE["agent:abort hook (if not already fired)\nReturn stats to agent.run()"]
     ABORT1 -->|no| TURN["executeTurn()"]
 
     TURN --> STATS["Accumulate usage"]
@@ -73,6 +74,8 @@ flowchart TB
     style TURN fill:#1a1a2e,stroke:#533483,color:#fff
 ```
 
+`runLoop` never fires `agent:done` — that's `agent.run()`'s job after the loop returns (see Agent Lifecycle above). The loop fires `agent:abort` itself at the two abort checks shown; `agent.run()`'s own catch block fires it a third way for a mid-stream throw, and the two firing sites are mutually exclusive per run.
+
 ## Single Turn
 
 ```mermaid
@@ -112,8 +115,7 @@ flowchart TB
     subgraph TOOLS ["Tool Execution"]
         direction TB
         TE1["Push assistant turn\n(with tool calls)"] --> TE2["executeToolBatch:\nWalk calls in submission order.\nSafe tools fan out as a fleet\n(cap = maxConcurrentTools);\nunsafe tools barrier (drain → run alone → unblock).\nAbort/steer between dispatches → synthesize\nInterrupt/Skipped results for unstarted calls.\nshell error cascades a sibling abort."]
-        SEQ --> TE3["Push tool results turn\n+ fire tool-results:after"]
-        PAR --> TE3
+        TE2 --> TE3["Push tool results turn\n+ fire tool-results:after"]
     end
 
     TOOLS --> RET["Return ended: false"]
@@ -129,7 +131,7 @@ flowchart TB
     T1["tool:gate hook\n(block | result | runToolCounts)"] --> BLOCKED{"block?\n(wins over result)"}
     BLOCKED -->|yes| T2["Return 'Blocked: reason'\n(does NOT increment runToolCounts)"]
     BLOCKED -->|no| RES{result?}
-    RES -->|yes| RES1["increment runToolCounts\nfire tool:transform → tool:after\n(skip validate / tool:before / execute)"]
+    RES -->|yes| RES1["increment runToolCounts\nfire tool:transform → lift artifacts → tool:after\n(skip validate / tool:before / execute)"]
     RES1 --> RES2["Return substitute"]
     RES -->|no| INC["increment runToolCounts"]
     INC --> T3{Tool\nexists?}
@@ -153,7 +155,8 @@ flowchart TB
     T8 -->|error| T9["tool:error hook\n(can substitute result)"]
     T8 -->|ok| T10["tool:transform hook\n(can mutate result;\nctx.outputBytes pre-mutation)"]
     T9 --> T10
-    T10 --> T10B["stripImagesForNonVision()\n(replace image blocks with marker\nwhen provider.meta.capabilities.vision === false)"]
+    T10 --> T10A["recordArtifactsFromMetadata()\nlift ctx.metadata.artifacts → session.addArtifact\n→ fire artifact:recorded per artifact"]
+    T10A --> T10B["stripImagesForNonVision()\n(replace image blocks with marker\nwhen provider.meta.capabilities.vision === false)"]
     T10B --> T11["tool:after hook\n(ctx.outputBytes post-mutation, runToolCounts)"]
     T11 --> T12["Return { id, content: string | ToolResultContent[] }"]
 
@@ -163,94 +166,55 @@ flowchart TB
     style RES1 fill:#1a1a2e,stroke:#533483,color:#fff
 ```
 
-**`tool:gate` mutations.** Set `block` to refuse (`Blocked: reason`), `result` to substitute and skip execute, or neither to run normally. `block` wins over `result` so a policy gate always beats a consumer cache. The substitute path skips `tool:before` + validate + execute but fires `tool:transform` + `tool:after` — budgets and telemetry stay consistent with executed calls.
-
-**Per-call cancellation.** Each dispatch registers an `AbortController` in `LoopContext.toolCancels` (a `ToolCancelRegistry`, see `src/tool-cancel.ts`) keyed by `callId`; the tool body's `ctx.signal` is the run signal composed with the per-call signal via manual `linkAbortSignal` listeners (NOT `AbortSignal.any`, which would accumulate dependent-signal registrations on the long-lived run signal until GC — the composed signal is disposed in a `finally`). `agent.cancelTool(callId, reason?)` flips the per-call signal, the body promise races against the cancellation, the loop emits `tool:cancelled`, and the wire result becomes `TOOL_USE_CANCELLED_MESSAGE` with `isError: true`. A cancel that arrives before the call dispatches (the host saw the id in the streamed turn) is parked in a bounded FIFO and applied at registration rather than dropped; the agent clears parked kills at each run start. Other in-flight tools in the same batch keep running — distinct from `agent.abort()` (whole-run abort → `INTERRUPT_MESSAGE_FOR_TOOL_USE` at the batch layer) and `TOOL_USE_SKIPPED_MESSAGE` (steered out before dispatch). The live entry is removed in a `finally` so it only ever holds currently-dispatching calls; the body promise gets a no-op `.catch` so misbehaving tools that ignore the signal can't surface as unhandled rejections after the loop has moved on.
-
-**`runToolCounts`** is a frozen pre-call snapshot, scoped to `runId`. Includes dedup + gate-`result` substitutes; excludes blocked calls. Resumed sessions reset the counter. Concurrent fleets see the same pre-batch snapshot — built-in budget/dedup middleware uses its own gate-time reservation counter so `behavior.toolBudgets` stays atomic across the fleet.
-
-**Output shape.** `string | ToolResultContent[]`. Text tools return strings; multimodal tools (MCP browsers, screenshots) return `[{ type: 'text' }, { type: 'image', mediaType, data }]`. Providers with `capabilities.imageInToolResult: true` (Anthropic, OpenAI Codex) route arrays natively; OpenAI-compat emits a companion `user` message with `image_url` parts. Non-vision providers swap image blocks for a text marker before the hook fires.
-
-**`outputBytes`** populates `tool:after`, `tool:transform`, `mcp:tool:after`, `mcp:tool:transform` — UTF-8 byte length for text, base64 char length for images. This is a **wire-payload-size proxy**, not a token count (vision encoders tokenize decoded pixels, geometry-dependent). Use it for byte-budget heuristics; defer to provider-side context management for token-accurate accounting. Reproduce via `toolOutputByteLength(content)`.
+- **`tool:gate` mutations.** Set `block` to refuse (`Blocked: reason`), `result` to substitute and skip execute, or neither to run normally. `block` wins over `result`. The substitute path skips `tool:before` + validate + execute but still fires `tool:transform` → artifact lift → `tool:after`, so budgets and telemetry stay consistent with executed calls.
+- **Artifact lift.** Any `tool:transform` handler that appends `SessionArtifactInput[]` to `ctx.metadata.artifacts` gets it normalized and stored by `recordArtifactsFromMetadata` (`src/loop.ts`) right after `tool:transform`, before `tool:after`. Best-effort: a store failure never fails the tool call. See `docs/ARTIFACTS.md`.
+- **Per-call cancellation.** Each dispatch registers an `AbortController` in `LoopContext.toolCancels` keyed by `callId` (`src/tool-cancel.ts`). `agent.cancelTool(callId, reason?)` flips it, the loop fires `tool:cancelled`, and the wire result becomes `TOOL_USE_CANCELLED_MESSAGE` with `isError: true`. Other in-flight tools in the batch keep running. A cancel that arrives before the call dispatches is parked in a bounded FIFO and applied at registration instead of dropped.
+- **Distinct interrupt paths.** `agent.abort()` (whole-run) → `INTERRUPT_MESSAGE_FOR_TOOL_USE` at the batch layer. Steered-out-before-dispatch → `TOOL_USE_SKIPPED_MESSAGE`. Per-call cancel → `TOOL_USE_CANCELLED_MESSAGE`. All three are `isError: true`.
+- **`runToolCounts`** is a frozen pre-call snapshot, scoped to `runId`. Includes dedup + gate-`result` substitutes; excludes blocked calls. Resumed sessions reset the counter.
+- **Output shape.** `string | ToolResultContent[]`. Multimodal tools (MCP browsers, screenshots) return `[{ type: 'text' }, { type: 'image', mediaType, data }]`. Providers with `capabilities.imageInToolResult: true` (Anthropic, OpenAI Codex) route arrays natively; OpenAI-compat emits a companion `user` message with `image_url` parts. Non-vision providers swap image blocks for a text marker before `tool:transform` fires.
+- **`outputBytes`** populates `tool:after` / `tool:transform` / `mcp:tool:after` / `mcp:tool:transform` — UTF-8 byte length for text, base64 char length for images. It's a wire-payload-size proxy, not a token count. Reproduce via `toolOutputByteLength(content)`.
 
 ### Concurrency scheduler
 
 `executeToolBatch` (`src/loop.ts`) walks the assistant turn's tool calls in submission order and decides per-call whether to fan out:
 
-- **Per-tool flag.** Every `ToolDef.isConcurrencySafe` (`boolean | ((input) => boolean)`) declares the safety verdict. Default `false` — fail-closed. Resolved once per call before dispatch begins.
-- **Fleet vs. barrier.** Safe calls join a running concurrent fleet up to `behavior.maxConcurrentTools` (default `10`). Unsafe calls (and any call when the fleet already contains an unsafe sibling or is at the cap) **barrier**: drain the in-flight fleet, run alone, then unblock the queue.
-- **Order preserved at yield time.** Results are written to `results[i]` slots in submission order; concurrent completion order is invisible to the model.
-- **Sibling abort controller.** One `AbortController` per batch carries both the parent abort (forwarded so a user-issued abort still tears in-flight tools down) and the `shell`-cascade signal. Cancelled siblings get a `Cancelled: a sibling \`shell\` call …` tool_result; non-shell errors are isolated.
-- **Abort + steer between dispatches.** Re-checked after each in-iteration drain so a tool that aborts mid-batch doesn't dispatch one extra call. Unstarted slots are filled with `INTERRUPT_MESSAGE_FOR_TOOL_USE` / `TOOL_USE_SKIPPED_MESSAGE` (both `isError: true`) so the assistant turn's `tool_use` ids never go orphan.
-- **`shell` is conditional.** `shell.isConcurrencySafe(input)` parses the command via `isReadOnlyShellCommand` — strict allow-list of read-only command bases (`ls`, `cat`, `git status`, `rg`, …) plus a `git` subcommand allow-list. Rejects pipes, redirects, command chains, and subshell expansions.
+- **Per-tool flag.** `ToolDef.isConcurrencySafe` (`boolean | ((input) => boolean)`) declares the safety verdict, resolved once per call before dispatch. Default `false` — fail-closed.
+- **Fleet vs. barrier.** Safe calls join a running fleet up to `behavior.maxConcurrentTools` (default `10`). Unsafe calls — or any call once the fleet has an unsafe sibling or is at cap — barrier: drain in-flight, run alone, unblock the queue.
+- **Order preserved at yield time.** Results land in `results[i]` by submission order regardless of completion order.
+- **Sibling abort.** One `AbortController` per batch carries the parent abort plus a `shell`-cascade signal: a `shell` error cancels siblings with a `Cancelled: a sibling \`shell\` call …` result; non-shell errors stay isolated.
+- **Abort + steer re-checked** after each drain, so a mid-batch abort doesn't dispatch one extra call. Unstarted slots get `INTERRUPT_MESSAGE_FOR_TOOL_USE` / `TOOL_USE_SKIPPED_MESSAGE`.
+- **`shell` is conditional** — `isReadOnlyShellCommand` allow-lists read-only bases (`ls`, `cat`, `git status`, `rg`, …) plus a `git` subcommand allow-list; pipes, redirects, chains, and subshells are rejected.
 
-Forcing fully sequential dispatch (for deterministic debugging / eval-grade runs) is one knob: `behavior.maxConcurrentTools: 1`. Every call then barriers regardless of its `isConcurrencySafe` flag.
+Force fully sequential dispatch (deterministic debugging, eval-grade runs) with `behavior.maxConcurrentTools: 1` — every call then barriers regardless of `isConcurrencySafe`.
 
 ## Tool ergonomics defaults
 
-Built-in tools are opinionated about output sizes — drop your v2 `tool:transform` truncation polyfills.
+Built-in tools are opinionated about output sizes — drop your own `tool:transform` truncation polyfills.
 
 | Tool | Default behavior |
 |---|---|
-| `read_file` | Line-paginates: `offset=1`, `limit=2000`, `maxBytes=262144` (256 KiB). Footer documents paging (`re-read with offset=N+1`). Binary files (NUL byte / `0xFFFD`-heavy) return a marker. `limit: 0` / `maxBytes: 0` disable. With `behavior.readLineNumbers` (default on), each line gets a `<N>\t` prefix; `edit` strips it on match so the model can paste verbatim. |
-| `shell` | Tail-priority truncation at `maxOutputBytes=32768` (32 KiB, combined stdout+stderr). Head trim marker: `…(N bytes truncated from head)…`. `0` disables. UTF-8 never splits mid-codepoint. Appends `(exit N, Nms)` footer + surfaces non-empty stderr by default (`metadata: false` opts out). |
-| `write_file` | Reads existing content; returns `Created` / `Updated` / `No change needed: …` so the model detects no-ops without a separate read. Race window in shared docker/sandbox contexts documented and accepted. |
-| `edit` | Fails clearly on non-unique `old_string` (unless `replace_all: true`). On not-found, includes a nearest-match preview so the model recovers without re-reading. |
-| `multi_edit` | Sequential edits to one file. **Best-effort, per-hunk** — each step runs against the file as left by the previous APPLIED step; a per-step failure (`old_string` not found, ambiguous without `replace_all`, identical strings, malformed input) is reported in the result but doesn't block siblings. Writes the file iff at least one step applied. All-applied returns the legacy `Edited <path>: applied N edits (M replacements).` so the renderer's success-suppression keeps the diff alone; any failure emits `Edited <path>: applied N of M edits …` (or `multi_edit error: no edits applied to <path> (M attempted).` when nothing landed) plus per-failure lines + an `<edit-outcomes>` block. Approval is a host concern: the chat layer's `tool:gate` rebinds `ctx.input.edits` to the approved subset (rebind, not mutate — the model's original `tool_call` block in `session.turns` stays untouched), and a `tool:transform` hook merges the body's subset-keyed outcomes with the approval-side denied/skipped entries (`mergeApprovalAndBodyOutcomes`) before appending the canonical `<edit-outcomes>` block. `parseEditOutcomesFromResult` re-parses it on reload. See CHAT.md → Per-edit approval. |
-| `grep` | Wraps `rg` when present (with explicit `.` path to avoid stdin hangs). `find`-via-`exec` fallback otherwise. Skips git-ignored files by default (`gitignore` arg, default `true`): `rg` natively, fallback by intersecting with `git ls-files`; `gitignore:false` adds `rg --no-ignore` / keeps the full `find` listing. `head_limit=250`, `offset` paginates. |
-| `glob` | Default path intersects the pattern with `git ls-files --cached --others --exclude-standard`, so git-ignored trees (`node_modules`, build dirs) are skipped and no filesystem walk runs (`gitignore` arg, default `true`). Fallback (gitignore off / non-repo / `../`-escaping pattern) is a native scanner — `Bun.Glob().scan()` under Bun (`node:fs/promises.glob` buffers the whole walk and hangs), `fs.glob` under Node — recovering via a limit/signal-aware portable walk if the scanner throws on a pathological tree. 20 s tool-level timeout backstop. |
-
-## Per-edit approval — harness purity
-
-The harness has no notion of "partial approval"; per-hunk DENIAL lives entirely above the loop. `edit` / `write_file` are single-mode (one hunk, succeed-or-error). `multi_edit` is best-effort, per-hunk on the BODY side — it reports `applied` / `failed` per step in its result text and is the only edit tool whose body emits an `<edit-outcomes>` block on its own (when any step failed). The chat layer merges that body-side block with approval-side decisions before the canonical block lands on the wire.
-
-Four loop-visible artifacts carry the decision through:
-
-1. **Input rebind at `tool:gate`** — the host's gate handler (`src/tui/app.tsx`'s `applyGate`) computes the approved subset, then assigns a fresh shallow-clone to `ctx.input` whose `edits` array is filtered. The model's original `tool_call.input` in `session.turns` is never mutated (the rebind produces a new object); the tool body sees the smaller, all-approved batch and runs unchanged.
-2. **Pending-annotation map** — keyed by `tool_call.id`, holds the 1:1 `EditOutcome[]` (over the model's ORIGINAL hunks). Lives in the host's React tree (`pendingAnnotationsRef` in the TUI).
-3. **Body-side outcomes** — `multi_edit`'s best-effort body emits an `<edit-outcomes>` block in its result whenever any step failed, keyed against the approved SUBSET it actually saw (in subset-position order).
-4. **`tool:transform` annotation merge** — the host strips the body's block (when present), merges it into the approval-side 1:1 outcomes via `mergeApprovalAndBodyOutcomes` (each approval `applied` placeholder is replaced by the body's next outcome), rewrites the body's header so subset-relative `N of M edits` becomes original-total (`rewriteMultiEditHeader`), and appends the canonical merged block. The merged outcomes also flow back into the in-flight `'tool'` event (`updateToolEventOutcomes`) so live diff badges reflect the post-merge truth without waiting for a session reload. Bubbles to `child:tool:transform` for subagent-issued calls via `BUBBLED_MUTABLE_EVENTS`.
-
-**Wire format** (canonical shape for live emit + persisted replay):
-
-```
-Edited path/to/foo.ts: applied 2 edits (3 replacements).
-
-<edit-outcomes>
-#1 applied
-#2 denied: denied by user
-#3 applied
-</edit-outcomes>
-```
-
-- Opening + closing tags each on their own line.
-- One line per hunk: `#<1-based-index> <kind>[: <reason>]`.
-- `kind ∈ {applied | denied | skipped | failed}`. `failed` originates in `multi_edit`'s body (per-step tool-level rejection); `denied` / `skipped` originate at the gate; `applied` is the resolved positive outcome.
-- Block emitted ONLY when at least one hunk is NOT applied. All-applied calls fall through to the legacy summary alone.
-
-A fully-denied call (every hunk rejected) skips the substitute path; the harness writes `Blocked: User denied this tool call` as the tool_result and the host emits a synthetic `tool-result` event with body `[fully denied] <edit-outcomes>…</edit-outcomes>` for live display only (persisted history stays terse).
-
-Replay path: `parseEditOutcomesFromResult(text)` (from `zidane/chat`) recovers the `EditOutcome[]` from the annotation block. `eventsFromTurns` pairs `tool_call` ↔ `tool_result` by `callId` and re-attaches the outcomes onto the `'tool'` event so reloaded transcripts paint identical per-hunk badges.
+| `read_file` | `offset=1`, `limit=2000` lines, `maxBytes=262144` (256 KiB). `limit:0`/`maxBytes:0` disable. Binary content returns a marker. `readLineNumbers` (default on) prefixes each line `<N>\t`; `edit` strips it on match. |
+| `shell` | Tail-priority truncation, `maxOutputBytes=32768` (32 KiB combined stdout+stderr), `0` disables. Appends `(exit N, Nms)` footer + non-empty stderr by default (`metadata:false` opts out). |
+| `write_file` | Reads existing content first; returns `Created` / `Updated` / `No change needed: …` so the model detects no-ops without a separate read. |
+| `edit` | Fails clearly on non-unique `old_string` unless `replace_all: true`. Not-found includes a nearest-match preview. |
+| `multi_edit` | Sequential, best-effort per-hunk edits to one file; a per-step failure doesn't block siblings. Approval and the `<edit-outcomes>` annotation contract are the chat layer's — see `docs/CHAT.md` § Per-edit approval. |
+| `grep` | Wraps `rg` when present, `find`-via-`exec` fallback otherwise. Skips git-ignored files by default (`gitignore`, default `true`). `head_limit=250`, `offset` paginates. |
+| `glob` | Default path intersects the pattern with `git ls-files` so ignored trees are skipped (`gitignore`, default `true`). Falls back to a native scanner otherwise. 20s tool-level timeout. |
+| `record_artifact` | `artifacts` preset tool (`src/tools/record-artifact.ts`); explicit path for artifacts detection can't see (background-shell PRs, deployments, issues). Input `{ kind, uri, label?, meta? }`, idempotent per `(kind, uri)`. See `docs/ARTIFACTS.md` § Producers. |
 
 ## `StreamEvent.callId` pairing contract
 
-`StreamEvent` carries `callId?: string` on `'tool'` / `'tool-result'` (and any tool-scoped `'error'`) events. The value is verbatim `tool_use.id` from the originating assistant turn's `tool_call` block. It's the canonical pairing key for out-of-process consumers (GUI, SDK, logger, replayer) — pairing by tool name + arrival order silently swaps results the moment two parallel calls share a tool name (`read_file`, `edit`, `multi_edit`).
-
-Live emit stamps `callId` from `ToolHookContext.callId` (and from `McpToolHookContext.callId` for MCP tool results) on every `tool:before` / `tool:after` / `mcp:tool:after` / `child:tool:before` / `child:tool:after` synthesis, plus on the chat-layer gate's synthetic `'tool'` / `'tool-result'` emits (denied + partial paths). Replay reads `tool_call.id` / `tool_result.callId` straight off the persisted block, so reloaded transcripts pair identically to the live ones. The field stays absent for non-tool events and for session / provider-level error events that have no callId in scope.
+`StreamEvent` carries `callId?: string` on `'tool'` / `'tool-result'` (and tool-scoped `'error'`) events — verbatim `tool_use.id` from the originating assistant turn. It's the canonical pairing key for out-of-process consumers (GUI, SDK, logger, replayer): pairing by tool name + arrival order silently swaps results the moment two parallel calls share a tool name (`read_file`, `edit`, `multi_edit`). Live emit stamps it from `ToolHookContext.callId`; replay reads `tool_call.id` / `tool_result.callId` straight off the persisted block, so reloaded transcripts pair identically to live ones. Absent on non-tool events and on session/provider-level errors with no callId in scope.
 
 ## Tool argument auto-coercion
 
 `validateToolArgs` runs between `tool:gate` and `tool:before`:
 
-1. **Required-field presence** — missing/null required fields fail outright.
-2. **Type-aware coercion** on top-level properties:
-   - `"true"` / `"yes"` / `"1"` → `true`; `"false"` / `"no"` / `"0"` → `false`.
-   - Numeric strings → numbers/integers.
-   - JSON-encoded strings → arrays/objects.
-   - Numbers/booleans → strings (when schema declares `string`).
+1. Required-field presence — missing/null required fields fail outright.
+2. Type-aware coercion on top-level properties: `"true"`/`"yes"`/`"1"` → `true` (and the `false` equivalents); numeric strings → numbers; JSON-encoded strings → arrays/objects; numbers/booleans → strings when the schema declares `string`.
 3. Reject only when no coercion succeeds; fires `validation:reject` so consumers count broken-call attempts separately from runtime errors.
 
-`tool:execute` always receives the coerced input.
+`toolDef.execute` always receives the coerced input.
 
 ## Data Flow
 
@@ -295,35 +259,26 @@ native error
      null                      → AgentProviderError (fallback)
 ```
 
-`agent.abort()` and aborted `AbortSignal` always produce `AgentAbortedError`. Match on `instanceof`, not on `err.message`.
+`agent.abort()` and an aborted `AbortSignal` always produce `AgentAbortedError`. Match on `instanceof`, not on `err.message`.
 
 ## Prompt caching
 
-When `behavior.cache: true` (default), zidane injects `cache_control: { type: 'ephemeral' }` breakpoints on three stable prefixes:
-
-1. **System prompt** — `cache_control` on the static prefix (see boundary marker below); single block when no marker is present.
-2. **Tool definitions** — last tool in the array.
-3. **Conversation** — last content block of the last message, skipping trailing `thinking` / `redacted_thinking` blocks that can't carry `cache_control`.
-
-Three of Anthropic's four allowed breakpoints; headroom left for a future thinking-block breakpoint. Next turn, the longest matching prefix is served from cache; only the new suffix is billed at full input rate.
-
-Provider semantics:
+When `behavior.cache: true` (default), zidane injects `cache_control: { type: 'ephemeral' }` on three stable prefixes: the system prompt's static half, the last tool definition, and the last cacheable content block of the last message. That's 3 of Anthropic's 4 allowed breakpoints, leaving headroom for a future thinking-block breakpoint. Next turn, the longest matching prefix is served from cache; only the new suffix bills at full input rate.
 
 | Provider | Behavior |
 |---|---|
 | `anthropic` | Breakpoints honored natively. |
-| `anthropic({ bedrock })` | Same breakpoints, sent through `@anthropic-ai/bedrock-sdk` (SigV4; auth via the AWS credential chain, no Anthropic key). Bedrock accepts `cache_control` for supported Claude models (live-verified: creation on run 1, reads on run 2). Beta headers are not sent, so `cacheTtl: '1h'` degrades to the default TTL; `countTokens` returns `null` (no endpoint). Thinking uses the legacy `thinking: { type: 'enabled', budget_tokens }` shape — Bedrock's translation layer 400s the 4.6 surface (`output_config.effort`, adaptive), so effort tiers degrade to fixed budgets (`BEDROCK_THINKING_BUDGETS`), clamped strictly under the model's output ceiling (Anthropic requires `budget_tokens < max_tokens`; live-verified 400 otherwise). `nativeWebSearch` is NOT advertised — AWS doesn't host Anthropic's server-side search (live-verified 400), so a `web_search` ToolDef rides as a client-side function tool. Region: `bedrock.region` → `AWS_REGION` → `us-west-2`. Live coverage: `test-inference/bedrock.inference.test.ts`; anti-stall guarantees are deterministic in `test/bedrock.test.ts`. |
+| `anthropic({ bedrock })` | Same breakpoints over `@anthropic-ai/bedrock-sdk`. No beta headers, so `cacheTtl: '1h'` degrades to the default TTL and `countTokens` returns `null`. Thinking uses the legacy `budget_tokens` shape, clamped under the model's output ceiling. `nativeWebSearch` is not advertised. |
 | `openrouter` | Breakpoints forwarded; Anthropic + Gemini routes honor them, others ignore. |
-| `arcee` / `local` / `openaiCompat` | Factory-gated via `cacheBreakpoints: boolean` (default **off**). `openrouter` flips it on; Arcee/local/bare `openaiCompat` stay off so strict OpenAI-compatible endpoints don't reject unknown fields. |
-| `cerebras` | Off (factory doesn't enable breakpoints). |
-| `openai` (Codex) | Not affected — separate wire format (pi-ai). |
+| `arcee` / `local` / `openaiCompat` | Factory-gated `cacheBreakpoints: boolean`, default off. `openrouter` flips it on. |
+| `cerebras` | Off. |
+| `openai` (Codex) | Not affected — separate wire format. |
 
-Cache-read + cache-write counts surface on `TurnUsage.cacheRead` / `TurnUsage.cacheCreation`,
-populated from Anthropic's native fields and from OpenRouter's `prompt_tokens_details`.
+Cache-read/write counts surface on `TurnUsage.cacheRead` / `TurnUsage.cacheCreation`.
 
 ### System-prompt boundary
 
-Per-turn churn in the system prompt (e.g. `<env>` cwd/date rewrites) used to invalidate the entire cached prefix — `cache_control` on the last block covered the whole text. The `SYSTEM_PROMPT_BOUNDARY` marker splits it into two:
+Per-turn churn in the system prompt (`<env>` cwd/date rewrites) used to invalidate the whole cached prefix. `SYSTEM_PROMPT_BOUNDARY` splits it structurally:
 
 ```
 ┌──────────────┐  cache_control: ephemeral
@@ -333,118 +288,69 @@ Per-turn churn in the system prompt (e.g. `<env>` cwd/date rewrites) used to inv
 └──────────────┘  (no cache_control)
 ```
 
-The static prefix rides the prompt cache across turns/sessions; the dynamic suffix re-bills per turn. The marker is structural metadata — providers strip it from the wire bytes before the model sees the prompt.
-
-**Public API** (`zidane`):
+The static half rides the prompt cache across turns/sessions; the dynamic suffix re-bills per turn. Providers strip the marker from wire bytes before the model sees the prompt.
 
 | Symbol | Purpose |
 |---|---|
-| `SYSTEM_PROMPT_BOUNDARY` | The literal marker. Embed it in your system prompt to opt in. |
-| `splitSystemPrompt(s)` | Returns `{ static, dynamic }`. Marker-free input ⇒ everything is static. |
+| `SYSTEM_PROMPT_BOUNDARY` | The literal marker; embed it in a system prompt to opt in. |
+| `splitSystemPrompt(s)` | `{ static, dynamic }`. Marker-free input ⇒ everything is static. |
 | `joinSystemPrompt(static, dynamic)` | Compose; marker omitted when `dynamic` is empty. |
-| `appendStaticSection(s, extra)` | Append to the static half (used internally for skills + lazy tool catalogs). |
-| `appendDynamicSection(s, extra)` | Append to the dynamic half (used by hosts for per-turn state). |
-| `replaceDynamicSection(s, next)` | Replace the dynamic half wholesale (used by the TUI's env rewriter). |
+| `appendStaticSection` / `appendDynamicSection` | Append to one half (skills/lazy catalogs use static; hosts use dynamic for per-turn state). |
+| `replaceDynamicSection(s, next)` | Replace the dynamic half wholesale. |
 | `renderSystemForWire(s)` | Strip the marker for providers that can't honor `cache_control`. |
 | `hasSystemPromptBoundary(s)` | Boolean probe. |
 
-The built-in profiles (`buildBuildSystem` / `buildPlanSystem` in `zidane/chat`) emit the boundary automatically when `cwd` is provided. Custom callers calling `createAgent({ system })` directly stay marker-free by default — zero overhead, identical wire bytes to before.
-
-**Provider integration:**
-
-- `anthropic` — `applyAnthropicCacheBreakpoints(params, originalSystem)` splits string system prompts on the marker. The OAuth path skips the split (the canonical CC prompt occupies `params.system`; the user doctrine lives in an injected user message).
-- `openaiCompat` — `toOAIMessages` strips the marker; `applyOAICacheBreakpoints(messages, originalSystem, ttl)` splits the leading system message into static + dynamic content parts when caching is on, stamping `cacheTtl` on each breakpoint (forwarded as-is; OpenRouter's Anthropic-family routes honor it without a beta header — measured).
-- `openai` (Codex), `cerebras`, `arcee`, `local`, and any cache-disabled route — marker is collapsed via `renderSystemForWire` so it never reaches the model.
+Built-in profiles (`buildBuildSystem` / `buildPlanSystem` in `zidane/chat`) emit the boundary automatically when `cwd` is provided. `createAgent({ system })` callers stay marker-free by default.
 
 ### Cache-stable configuration
 
-A prefix cache breaks at the first differing byte: the provider hashes tools → system → messages cumulatively, so a change at position N invalidates every breakpoint at or after N. Everything in this section follows from one principle — **the wire must be append-only** — and from provider facts that were measured live rather than assumed (the measurements are pinned in `test-inference/cache-stability.inference.test.ts`, so a provider-side change surfaces as a test failure, not a bill).
-
-Measured facts (Anthropic, Sonnet, ~25k-token seeded transcript):
-
-| Change between turns | Cache effect |
-|---|---|
-| Nothing (append-only wire) | ~99.9% hit rate; `cacheRead` grows with the transcript |
-| One interpolated counter in the system prompt | Partial break every turn: `cacheRead` pinned to the scaffold constant, conversation re-bills — ~12% hit rate |
-| A `read_file` result rewritten in place (`elideStaleReads: 'stub'`) | Partial break at the read's position; bounded to one per read→edit transition (stubbing is idempotent) |
-| `thinking.budget_tokens` changed | **Total** loss: `cacheRead: 0`, scaffold included — the budget is part of the cache key |
-| >5 min idle | Entry expired; full re-write on the next turn regardless of wire stability |
-
-The knobs, and the cache-aware setting for each:
+A prefix cache breaks at the first differing byte — the wire must be append-only. Provider facts are pinned live in `test-inference/cache-stability.inference.test.ts`, so a provider-side change surfaces as a test failure, not a bill.
 
 | Knob | Cache-aware setting | Why |
 |---|---|---|
-| `elideStaleReads` | `'notice'` | Append-only: a persisted `<system-reminder>` naming the stale path rides the mutating tool's own result. Zero prefix rewrites. `'stub'` (= legacy `true`) reclaims the stale bytes from context instead, at one full-prefix re-bill per read→edit transition — only worth it when context-window pressure outweighs cache cost (break-even ≈ `12.5 × prefix / staleBytes` turns). |
-| `thinkingDecay` | Step form `{ afterTurn, floor }` | Every distinct budget a schedule emits is one total cache loss. Step emits one change per run; the geometric form (`factor`) emits one per halving; a per-turn function disables caching entirely for the rest of the run. |
-| `cacheTtl` | `'1h'` for interactive hosts | The 5-minute TTL is the dominant cache cost for a human-paced session — one long pause forfeits the whole prefix. `'1h'` (2× write cost, ~0.1× reads) converts idle-loss into a cheap read. Honored by the native `anthropic` provider (ttl + beta header) and forwarded on `openrouter` routes (no beta needed there). Headless back-to-back runs should stay on `'5m'`. Caveat: the wire shape is byte-verified, but our 2026-07 live measurement saw a 1h entry evicted within 6 minutes — run the gated idle test (`INFERENCE_SLOW=1`) against your own credentials before counting the savings. |
-| `compactStrategy` / `mediaKeepTurns` | Keep windows equal, chunk-aligned | The two frontier-quantized passes (tail compaction, media age-out) snap to `COMPACT_CHUNK_TURNS` so a window costs one invalidation, not two. Stale-read elision is deliberately NOT quantized — measured worse (it is already idempotent per read). |
-| `thinking` level | Constant for the whole run | Toggling thinking on/off mid-run forfeits the prefix even with an unchanged transcript — the thinking config, like the budget, is part of the cache key. Pick a level per run and keep it. |
-| `system:transform` handlers | Byte-stable output only | Anything per-turn (counters, timestamps, tallies) belongs in the transcript as immutable history, not in the system prompt — see the hook's docstring for the incident this rule comes from. |
+| `elideStaleReads` | `'notice'` | Append-only: a `<system-reminder>` rides the mutating tool's own result, zero prefix rewrites. `'stub'` reclaims stale bytes at one full-prefix re-bill per read→edit transition. |
+| `thinkingDecay` | Step form `{ afterTurn, floor }` | Every distinct budget is one cache loss; step emits one change per run, geometric emits one per halving, a per-turn function disables caching for the rest of the run. |
+| `cacheTtl` | `'1h'` for interactive hosts, `'5m'` for headless back-to-back runs | The 5-minute default TTL is the dominant cache cost for a human-paced session. |
+| `compactStrategy` / `mediaKeepTurns` | Keep windows equal, chunk-aligned (`COMPACT_CHUNK_TURNS`) | A window then costs one invalidation, not two. |
+| `thinking` level | Constant for the whole run | The thinking config is part of the cache key like the budget; toggling it mid-run forfeits the prefix. |
+| `system:transform` handlers | Byte-stable output only | Per-turn counters/timestamps belong in the transcript, not the system prompt. |
 
-The built-in chat profiles (`BUILD_AGENT` / `PLAN_AGENT`, consumed by the TUI, GUI, and ACP server) ship the cache-aware settings; `test/chat-cache-behavior.test.ts` pins them. What remains outside configuration's reach: TTL expiry beyond `'1h'`, context-window-forced compaction (one intentional break when it happens), provider fallback switching models mid-run, and provider-side eviction. The realistic target is **zero self-inflicted breaks** — one cold write on turn 1, plus whatever the wall clock and the context window force.
+- One interpolated counter in the system prompt drops the hit rate from ~99.9% to ~12% — `cacheRead` pins to the scaffold constant and the conversation re-bills every turn.
+- `thinking.budget_tokens` changes cause **total** cache loss (`cacheRead: 0`); >5 min idle expires the entry regardless of wire stability.
+- TTL eviction inside the window is not guaranteed even at `'1h'` — verify against live credentials (gated idle test, `INFERENCE_SLOW=1`) before counting savings.
+- The target metric is prefix **carry-forward** (`cacheRead(n) === cacheRead(n-1) + cacheCreation(n-1)`), not hit *rate* — a short run with large tool outputs can carry its prefix perfectly while scoring a mediocre ratio.
 
-The end-to-end proof lives in the live suite's *golden configuration* case: a real model driving the real file tools through the loop under the settings above, asserted on **perfect prefix carry-forward** — every turn's `cacheRead` equals the previous turn's `cacheRead + cacheCreation`, i.e. writes only ever cover new transcript. Carry-forward is the metric to reach for over hit *rate*: a short run with large tool outputs can carry its prefix perfectly while scoring a mediocre ratio, because the ratio measures transcript proportions, not cache health.
+Built-in chat profiles (`BUILD_AGENT` / `PLAN_AGENT`) ship these settings; `test/chat-cache-behavior.test.ts` pins them.
 
 ### Affinity routing (`promptCacheKey`)
 
-Everything above assumes the second request reaches the machine that cached the first. That is not guaranteed: providers pick a replica by hashing the head of the prompt (OpenAI documents ~the first 256 tokens), so under load a session's traffic can spill onto a cold replica and the prefix is re-billed for reasons the wire cannot explain. `promptCacheKey` is the opt-in hint against that — a stable per-session value the server combines with its own prefix hash to make routing sticky. It is a routing hint, never a cache handle: it cannot make a provider keep or fetch an entry.
-
-Supported on both provider families, off by default (when unset, requests are byte-identical to before the option existed):
+Providers pick a cache replica by hashing the head of the prompt, so under load a session's traffic can spill onto a cold replica. `promptCacheKey` is a routing hint (never a cache handle) that makes routing sticky — off by default, byte-identical wire when unset.
 
 | Provider | Wire shape |
 |---|---|
 | `openaiCompat` (and `openrouter` / `baseten`) | `prompt_cache_key` body field; `promptCacheKeyField: 'user'` for legacy routes |
 | `anthropic` | `metadata.user_id`, merged onto any caller-supplied `metadata` |
-| either | `promptCacheKeyHeader: 'x-…'` additionally mirrors it into a header, for gateways that route on one |
+| either | `promptCacheKeyHeader: 'x-…'` additionally mirrors it into a header |
 
-`promptCacheKey: true` derives the key as `sha256(system + first user message)`, 32 hex chars. Deriving beats threading a session id through `StreamOptions`: the derived value is stable for a session's lifetime yet distinct between sessions, needs no plumbing in the loop, and — because the GUI/daemon shares one provider instance across sessions — a construction-time constant would bucket unrelated sessions onto a single replica. It moves exactly when the routable prefix moves (new session, different profile, a compaction that rewrites the head), which are the cases where the old replica's cache is worthless anyway. A hash also keeps prompt text and user identifiers out of a field that leaves the process, which is what Anthropic asks for on `metadata.user_id`. Pass a string or a `(ctx) => string | undefined` resolver instead when the host has a real session id.
-
-What it actually buys, per route — worth knowing before enabling it:
+`promptCacheKey: true` derives `sha256(system + first user message)` (32 hex chars) — stable per session, distinct across sessions, no plumbing needed. Pass a string or `(ctx) => string | undefined` when the host has a real session id.
 
 | Route | Effect |
 |---|---|
-| OpenAI / Azure | Real. Combined with the prefix hash; newer model families require it for the more reliable matching path. |
-| OpenRouter | Real. Read as its sticky-routing key, complementing the stickiness it already applies after a cached request. |
-| Baseten Model APIs | ~None. Their load balancer is already KV-cache-aware (routes on replica cache state) and caching is unconditional. |
-| 1P Anthropic | ~None. Cache entries are scoped per organization/workspace and matched purely by prefix; there is no client-side routing knob. |
-| Proxy / AI gateway in front of either (`baseURL`) | Real — this is the case that motivates plumbing it on Anthropic at all. |
-
-A note on reading the live suite's Baseten case: when Baseten reports no `cached_tokens` at all (cold replica, eviction under load) the cache assertions cannot run, so the case records an explicit `UNVERIFIED` entry and warns rather than passing quietly. `INFERENCE_STRICT=1` promotes that to a failure — use it for a release gate, where "could not verify" must not read as green.
+| OpenAI / Azure, OpenRouter, proxy/gateway in front of either | Real — combines with the provider's own prefix hash. |
+| Baseten Model APIs, 1P Anthropic | ~None — their routing/cache scoping doesn't use a client-side key. |
 
-Two operational notes. OpenAI documents a ceiling of roughly **15 requests/minute per key** before traffic spills anyway; a per-session key sits comfortably under it, a shared constant would not. And a gateway that sets the field itself always wins: a value already present via `extraBodyParams` (or the header via `extraHeaders`) is never overwritten, so "we route" and "the gateway routes" compose instead of fighting. `test/prompt-cache-key.test.ts` pins the derivation, the per-turn stability, and every no-clobber path.
+A gateway that sets the field itself always wins (never overwritten via `extraBodyParams`/`extraHeaders`). `test/prompt-cache-key.test.ts` pins the derivation and every no-clobber path.
 
 ### Cache-break diagnosis
 
-`installCacheBreakLogger(hooks, options?)` hashes per-request dimensions (`system`, `tools`, `model`, `thinking`, `thinkingBudget`, `messagePrefix`) at `turn:before` and compares against the previous turn on `turn:after`. When a break is detected on turn 2+ and dimensions differ, it logs the responsible dimension(s) — turning "cache broke" into "tools array changed at turn 7 because MCP server X loaded".
-
-```ts
-import { installCacheBreakLogger } from 'zidane'
-
-const uninstall = installCacheBreakLogger(agent.hooks, {
-  log: line => logger.debug(line),   // defaults to console.error
-  verbose: !!process.env.ZIDANE_DEBUG?.includes('cache'),
-})
-```
-
-Two thresholds decide what counts as a break:
-
-- `expectedReadAtLeast` (default `1`) — absolute floor. On its own this only catches *total* cache loss.
-- `expectedReadRatio` (default `0.8`) — relative floor, compared against the prefix the previous turn established (`cacheRead + cacheCreation`). This is what catches a **partial-prefix break**, where the scaffold still matches so `cacheRead` stays large and non-zero (pinned to a constant) while the whole conversation re-bills at the cache-write rate. Set `0` to restore absolute-only behavior. Skipped until the previous prefix exceeds 1024 tokens, below which the ratio is noise.
-
-The `messagePrefix` dimension keeps one hash *per message* (`messageHashes`) and diffs them positionally over the range both turns share — so appending messages, which every healthy turn does, is silent, and any in-place rewrite of a shared position (including the previous turn's last message) is reported with its index. It is what catches compaction, stale-read elision, media age-out, and host-side history trimming rewriting the transcript mid-run, none of which touch `system`, `tools`, or the model id.
+`installCacheBreakLogger(agent.hooks, options?)` hashes per-request dimensions (`system`, `tools`, `model`, `thinking`, `thinkingBudget`, `messagePrefix`) at `turn:before` and diffs against the previous turn at `turn:after`, naming the dimension that changed instead of just "cache broke".
 
-Besides the text `log` line, the installer emits the typed **`'cache:break'`** agent hook on every detected break (consumer handler errors are try/caught and routed to `onEmitError`, defaulting into `log` — hosts that count `log` invocations as dimension changes should pass a dedicated sink), carrying a structured `CacheBreakInfo` (`turn`, `model`, `cacheRead`, `cacheCreation`, the floor that tripped, `rebilledTokens` — the approximate re-billed prefix — and the `changed` dimensions + human-readable `details`). Pair `rebilledTokens` with `estimateRebilledCostUsd(provider, model, tokens)` from `providers/cost` to price the break in dollars; it returns `undefined` on a rate miss rather than fabricating $0. Two deliberate asymmetries with the text line: the hook fires even when NO dimension changed — an empty `changed` on a byte-stable request is the TTL-expiry / provider-eviction signature, which grep-oriented logs have always skipped — and it only exists while the installer is attached (like `compact:*`, the loop itself never emits it). The TUI consumes it for its footer chip; hosts can drive metrics or alerts from the same payload.
+- **Thresholds:** `expectedReadAtLeast` (default `1`) catches total loss; `expectedReadRatio` (default `0.8`, relative to the previous prefix, skipped below 1024 prefix tokens) catches a partial-prefix break where `cacheRead` stays pinned to the scaffold while the conversation re-bills.
+- **`messagePrefix`** hashes per-message and diffs positionally: appended messages are silent, an in-place rewrite of a shared position is reported by index — catches compaction, stale-read elision, media age-out, host-side history surgery.
+- Emits `'cache:break'` on every detected break (`CacheBreakInfo`: `turn`, `model`, `cacheRead`, `cacheCreation`, tripped floor, `rebilledTokens`, `changed` dimensions) — pair `rebilledTokens` with `estimateRebilledCostUsd(provider, model, tokens)` from `providers/cost`. Also emits a predictive `'cache:drift'` at `turn:before`, computed from request bytes alone, so it works even on providers that report no cache usage.
+- **Format-casting gateways** (OpenAI Responses/Chat Completions, Bedrock Converse in front of an Anthropic-shaped request) report `cache_creation: 0` always — only the read rate is trustworthy there. `'cache:break'` skips providers that never report `cacheRead` (Codex/Cerebras); `'cache:drift'` still works since it needs no usage data.
 
-Alongside the confirmed-cost hook, the installer emits the predictive **`'cache:drift'`** hook at `turn:before` whenever the outgoing request diverges from the previous completed turn's — computed from the request bytes alone, so it works on providers that report no cache usage and on format-casting gateways where zidane's wire is the last observable point before the cast. The payload (`CacheDriftInfo`) carries the changed dimensions and, for in-place prefix rewrites, the diverged message index. Intentional rewrites drift by design — that is the attribution channel for planned invalidations: tail compaction and media age-out cut on chunk-aligned indices, stale-read stubbing rewrites the read's own position, host-side history surgery lands anywhere. Drift followed by a healthy `cacheRead` means the provider absorbed the change; drift plus a `'cache:break'` on the same turn hands the break its cause. The append-only contract itself is pinned by `test/wire-prefix-monotonicity.test.ts`, which drives every history-touching feature through the real loop and asserts each request is a strict positional prefix of the next.
-
-Per-turn cache accounting needs no extra plumbing: `turn:after`'s run rollup (`RunUsageMirror`) already carries `totalCacheRead` / `totalCacheCreation` and the full per-turn `turnUsage[]`, and session turns carry `createdAt` for inter-turn wall-clock gaps (the TTL-expiry dimension).
-
-**Known limitation on format-casting gateways.** When a downstream gateway casts the Anthropic-format request into another provider's shape (OpenAI Responses / Chat Completions, Bedrock Converse), two things degrade by construction:
-
-- Those vendors have no cache-*write* concept, so their responses map back as `cache_creation: 0`. `previousPrefixTokens` then tracks `cacheRead` alone — the ratio floor underestimates the real prefix, and a carry-forward check (`read(n) === read(n−1) + write(n−1)`) is not evaluable on those routes. The read *rate* remains trustworthy; the write side simply doesn't exist.
-- The tracked dimensions cover the request **before** the cast. A transform that isn't prefix-monotonic — `transform(prefix + delta)` must extend `transform(prefix)` byte-for-byte — breaks the vendor's automatic caching while every dimension here reads stable, surfacing as recurring empty-`changed` breaks. That pattern indicts the gateway's cast, not this agent; the gateway should run the same positional hashing (`hashMessages`) on its *output* to name the churn.
-
-Heuristic only. The confirmed-cost path (`'cache:break'`, the log line) skips providers that don't report `cacheRead` (Codex / Cerebras); the drift path works everywhere because it never needs usage data — on those routes the installer is drift-only, not inert. Pure helpers `snapshotCacheDimensions`, `diffCacheDimensions`, `hashMessages`, and `fnv1a32` are exported for custom telemetry that needs to stamp the same hashes onto spans.
+Per-turn accounting needs no extra plumbing — `turn:after`'s `RunUsageMirror` already carries `totalCacheRead` / `totalCacheCreation` and per-turn `turnUsage[]`.
 
 ## Tool aliasing (wire vs. canonical)
 
@@ -507,60 +413,43 @@ agent.reset()                              → skills:deactivate (reason: 'reset
 
 session-resume rehydration:
   last-mode-wins per skill across history's skills_use blocks
-  → trailing mode:'deactivate' STAYS deactivated; activate/deactivate/activate ends active
 ```
 
-**allowed-tools.** When any active skill declares `allowed-tools`, a `tool:gate` handler blocks calls outside the union (the three skills tools are always implicitly allowed). Block-list (`- entry`) and flow-list (`[a, b]`) authoring shapes both normalize to `string[]` via the frontmatter parser's array-aware path; `AgentToolNotAllowedError.message` carries a recovery hint pointing the model at `skills_use({ mode: 'deactivate', name })` to release the offending skill without waiting for a run boundary.
-
-**Body-only delivery.** `skills_use` returns the body (frontmatter stripped) wrapped in `<skill_content>` for host-SDK context protection. Body includes shell-interpolated instructions (`` !`cmd` ``, fresh per activation), the skill directory, the resource listing (not eagerly loaded), and compatibility + allowed-tools when present.
-
-**Source precedence.** `SkillConfig.source: 'project' | 'user' | 'inline' | 'builtin'`. Project beats user; first-found wins within scan order. `trustProjectSkills: false` drops project-scoped skills.
+- **`allowed-tools`.** When any active skill declares `allowed-tools`, a `tool:gate` handler blocks calls outside the union (the three skills tools are always implicitly allowed). `AgentToolNotAllowedError.message` points the model at `skills_use({ mode: 'deactivate', name })`.
+- **Body-only delivery.** `skills_use` returns the body (frontmatter stripped) wrapped in `<skill_content>`. Includes shell-interpolated instructions (`` !`cmd` ``, fresh per activation), the skill directory, and the resource listing (not eagerly loaded).
+- **Source precedence.** `SkillConfig.source: 'project' | 'user' | 'inline' | 'builtin'` — project beats user, first-found wins within scan order. `trustProjectSkills: false` drops project-scoped skills.
 
 ## Progressive tool disclosure
 
-`behavior.toolDisclosure: 'lazy'` (default `'eager'`) replaces upfront MCP schemas with a name-only catalog and auto-injects a `tool_search` native tool. Native + skill tools always stay eager — only MCP is eligible. Per-server `McpServerConfig.disclosure: 'eager' | 'lazy'` overrides the agent-wide default.
+`behavior.toolDisclosure: 'lazy'` (default `'eager'`) replaces upfront MCP schemas with a name-only catalog and auto-injects a `tool_search` native tool. Native + skill tools always stay eager — only MCP is eligible. Per-server `McpServerConfig.disclosure` overrides the agent-wide default.
 
 ```
 per run() when toolDisclosure === 'lazy' and ≥1 MCP tool is lazy:
 
-partitionToolDisclosure(toolsBySpecName, mcpToolNames, servers, mode, aliases)
-  → lazyEntries (wire name + canonicalName + description + inputSchema + server?)
-  → eagerCanonicalNames
+partitionToolDisclosure(...) → lazyEntries (wire name + canonicalName + description + inputSchema)
+                              → eagerCanonicalNames
 
 initialUnlocked = new Set(eagerCanonicalNames)   // never mutated — phase-1 filter
 unlocked        = new Set(eagerCanonicalNames)   // mutated as tools surface
 dynamicUnlockOrder = []                          // append-only log
 
-if (lazyEntries && toolSearch.tool !== false && !host-defined tool_search):
-  tools.tool_search = createToolSearchTool({ catalog: lazyEntries, unlocked, addUnlock, defaultLimit })
-  unlocked.add('tool_search')
-  initialUnlocked.add('tool_search')   // pinned to the cached prefix
-
-system += buildSearchableCatalog(lazyEntries)   // wire names, XML-escaped, no inputSchema
-installLazyDisclosureGate                       // tool:gate refuses lazy ∉ unlocked
+tools.tool_search = createToolSearchTool({ catalog: lazyEntries, unlocked, addUnlock })
+system += buildSearchableCatalog(lazyEntries)    // wire names, XML-escaped, no inputSchema
+installLazyDisclosureGate                        // tool:gate refuses lazy ∉ unlocked
 
 per turn — buildFormattedTools() emits in two phases:
   1. registry-order walk filtered by initialUnlocked  ← byte-stable cached prefix
   2. dynamicUnlockOrder, in unlock order              ← append-only tail
 
-tool_search({ names | query | server, limit? }):
-  for each match: unlocked.add(canonical); addUnlock(canonical)
-                  (addUnlock is the framework-supplied recorder that
-                   appends to dynamicUnlockOrder; legacy hosts that only
-                   pass `unlocked` still work, just lose tail-ordering.)
-  return <tool_search_results>…<input_schema>{json}</input_schema>…
-    (inputSchema JSON inlined with `<` → `\u003c` so a hostile schema can't break the envelope)
+tool_search({ names | query | server, limit? }): unlocks matches, returns inlined input_schema JSON
 
 run end: uninstallLazyDisclosureGate; per-run state GC-eligible on next run()
 ```
 
-**Aliasing.** `LazyToolEntry.name` is the wire name (the only one the provider accepts). `LazyToolEntry.canonicalName` keys `unlocked` and dispatches `ctx.tools[name]`. `session.turns`, `ToolHookContext.name`, and `ctx.tools` keys stay canonical throughout.
-
-**Hard gate vs. provider validation.** Production providers (Anthropic, OpenAI) refuse `tool_use` blocks for tools absent from the request — the gate is mostly redundant there. It exists for custom / mock / lenient providers and makes the lazy boundary observable via `tool:gate`. Refusal points at the discovery tool's wire name.
-
-**Cache-stable injection.** Every successful `tool_search` invalidates only the SUFFIX of the wire tools array starting at the first new schema — the eager-tool + `tool_search` prefix never moves. Providers cache the prefix on the first turn and serve it from cache every subsequent turn regardless of how many discovery waves the model runs. Mid-array insertion would break the prefix; the two-phase emit above is what keeps it stable. The system-prompt catalog is byte-stable (alphabetical) so it rides the system-prompt cache cleanly.
-
-**Host-defined `tool_search`.** A host tool named `tool_search` (or aliased to that wire name) shadows the auto-injection. The host implementation must call `createToolSearchTool({ catalog, unlocked, addUnlock? })` to drive the unlock flow — bare implementations leave the gate refusing every lazy call. Pass the same `addUnlock` callback the framework supplies (or a moral equivalent) to keep tail-ordering. For custom flows, prefer `toolSearch.tool: false`.
+- **Aliasing.** `LazyToolEntry.name` is the wire name; `.canonicalName` keys `unlocked` and dispatches `ctx.tools[name]`. `session.turns` / `ToolHookContext.name` stay canonical throughout.
+- **Hard gate vs. provider validation.** Anthropic/OpenAI already refuse `tool_use` blocks for tools absent from the request; the gate exists for lenient/custom/mock providers and makes the lazy boundary observable via `tool:gate`.
+- **Cache-stable injection.** Every `tool_search` call invalidates only the wire tools array's SUFFIX starting at the first new schema — the eager + `tool_search` prefix never moves.
+- **Host-defined `tool_search`.** A host tool named `tool_search` shadows auto-injection; it must call `createToolSearchTool({ catalog, unlocked, addUnlock? })` to drive unlocks, or use `toolSearch.tool: false` for a fully custom flow.
 
 ## Hook Firing Order
 
@@ -577,11 +466,9 @@ Every run ends with an implicit deactivate-all pass (`reason: 'run-end'`); activ
 
 ### Per turn
 
-All tool hooks carry `turnId` + `callId`. Typed via `ToolHookContext` / `McpToolHookContext`. Both expose `name` (canonical) and `displayName` (wire / aliased; defaults to `name`).
-
-Hooks marked **[mutable]** have ctx fields that affect downstream behavior when handlers mutate them. Last-writer wins.
+All tool hooks carry `turnId` + `callId`, typed via `ToolHookContext` / `McpToolHookContext`, both exposing `name` (canonical) and `displayName` (wire; defaults to `name`). Hooks marked **[mutable]** have ctx fields handlers can mutate; last-writer wins.
 
-> **Ordering note:** `context:transform` fires **before** `turn:before` — "transform the context that will be sent". For per-turn observation, use `turn:before`. For editing messages just before the provider call, use `context:transform` — it lands upstream of the defensive pairing repair (`ensureToolResultPairing` + `ensureEndsWithUserMessage`) so a mutation can't strand orphan `tool_use` / `tool_result` blocks on the wire. `turn:before` is `[mutable: options]` too as a last-mile escape hatch (per-turn reminders, audit-tag wrappers); the loop re-runs both defenses after the hook so the same guarantee holds, at the cost of one extra walk over the message list. Downstream consumers building provider requests **outside** `agent.run()` should use `session.toMessages({ provider })` / `toWireMessages(turns, { provider })` — these apply the same repair so raw `session.turns` never reach a provider as the `tool_result must be preceded by a tool_call with the same toolCallId` 400.
+> **Ordering note:** `context:transform` fires **before** `turn:before` — it lands upstream of the defensive pairing repair, so a mutation can't strand orphan `tool_use`/`tool_result` blocks on the wire. `turn:before` is `[mutable: options]` too as a last-mile escape hatch; the loop re-runs both repair passes after it. Consumers building provider requests outside `agent.run()` should use `session.toMessages({ provider })` / `toWireMessages(turns, { provider })`, which apply the same repair.
 
 ```
 context:transform     [mutable: messages]       ← edit messages before LLM call
@@ -590,21 +477,22 @@ turn:before                                      ← turn starts
   oauth:refresh                                  ← (when provider supports it)
   stream:thinking (n) / stream:text (n)          ← each streamed chunk
   stream:end                                     ← text complete (if text present)
-  stream:retry (n)                               ← retryable error caught; sleep then re-enter stream (only fires on intermediate failures)
-  model:fallback                                 ← terminal failure advanced the run's provider+model fallback chain (run-sticky; only the LAST target's failure reaches stream:error)
-  stream:error                                   ← provider rejected terminally (omitted on user-initiated aborts and on retries that recover)
+  stream:retry (n)                               ← retryable error caught; sleep then re-enter stream
+  model:fallback                                 ← terminal failure advanced the run's fallback chain (only the LAST target's failure reaches stream:error)
+  stream:error                                   ← provider rejected terminally (omitted on user aborts and recovered retries)
 turn:after                                       ← always fires (incl. errors); SessionTurn + toolCounts
   tool:gate           [mutable: block, reason, result?]  ← refuse / substitute / run
   tool:unknown        [mutable: result?, suppressError]  ← no toolDef registered
   validation:reject   / validation:coerce        ← arg validation outcomes
-  tool:before                                    ← (input coerced; coercions? when present; priorContent? for write_file)
+  tool:before                                    ← (input coerced; coercions? when present)
     mcp:tool:gate     [mutable: block, reason, result?]
     mcp:tool:before
     mcp:tool:transform [mutable: result]         ← + outputBytes pre-mutation
     mcp:tool:after                               ← + outputBytes post-mutation
   tool:transform      [mutable: result, isError] ← + outputBytes pre-mutation
+  artifact:recorded                              ← per artifact lifted from ctx.metadata.artifacts (docs/ARTIFACTS.md)
   tool:after                                     ← + outputBytes post-mutation
-  tool:error          [mutable: result?]         ← on execute throw; ctx.result substitutes
+  tool:error                                     ← on execute throw; ctx.result substitutes
   tool:cancelled                                 ← agent.cancelTool(callId); skips transform/after; wire = TOOL_USE_CANCELLED_MESSAGE
 tool-results:after                               ← after the tool-results user turn is pushed (persistence seam)
 usage                                            ← running totals
@@ -613,70 +501,51 @@ budget:exceeded / tool-budget:exceeded           ← byte / per-tool caps trippe
 repeat-guard:exceeded                            ← repeat-guard block/steer/abort (behavior.repeatGuard)
 ```
 
-**`tool-results:after`** is the durable-persistence seam. The assistant turn carrying `tool_use` blocks and the user turn carrying matching `tool_result` blocks must be persisted as a pair — otherwise a process death between turns leaves an orphan `tool_use` that Anthropic rejects on resume. Subscribe here to write the pair atomically. The scheduler also synthesizes `Interrupt: …` / `Skipped: …` tool_results for any unstarted calls when abort / steering interrupts a batch (and `synthesizeMissingToolResults` in `src/agent.ts` covers the `turn:after` throw path), so the assistant turn's `tool_use` ids always stay matched.
-
-**Unknown-tool path.** When no `toolDef` matches the call name, the loop fires `tool:before` with `ctx.unknown: true` first (so UI consumers binding `tool:before` still see the model's attempt as a card), then `tool:unknown` (substitute / suppressError seam), then `tool:error` (unless `suppressError`), then `tool:dispatched` with `outcome: 'unknown'`. `tool:after` is NOT in the chain — the body never executed. The model receives either the consumer's substitute or `Tool error: Unknown tool: <name>`. `validation:reject` fires after coercion attempts fail.
+- **`tool-results:after`** is the durable-persistence seam: the assistant turn's `tool_use` blocks and the matching `tool_result` user turn must persist as a pair, or a process death between them leaves an orphan `tool_use` that Anthropic rejects on resume.
+- **Unknown-tool path.** `tool:before` fires first with `ctx.unknown: true`, then `tool:unknown`, then `tool:error` (unless `suppressError`), then `tool:dispatched` with `outcome: 'unknown'`. `tool:after` never fires — the body never executed.
 
 ### Per run
 
 ```
 session:start                        ← run begins
-session:turns                        ← seeded user turn persisted (fires before the first turn:before
-                                       when run({ prompt }) seeds a user turn; skipped on promptless resume)
-system:before                        ← per-run only when run({ system }) is set. Observational —
-                                       the loop reads options.system directly; ctx mutations are dropped.
-                                       Use system:transform for actual mutation.
+session:turns                        ← seeded user turn persisted (before the first turn:before;
+                                       skipped on promptless resume)
+system:before                        ← per-run only when run({ system }) is set; observational
   [turn hooks above, repeated]
-  session:turns                      ← after turns persisted (includes SessionTurn[] of appended turns)
+  session:turns                      ← after turns persisted (SessionTurn[] of appended turns)
   steer:inject                       ← if steering/follow-up message injected
-agent:abort                          ← agent.abort() called mid-run
-agent:done                           ← run finished (all exit paths), includes stats.output
-session:end                          ← run finished (completed | aborted | error)
+agent:abort                          ← fires once if the run was aborted (loop's between-turn
+                                       check, or agent.run()'s mid-stream-throw catch — mutually exclusive)
+session:end                          ← run finished (completed | aborted | error);
                                        includes turnRange [start, end] for cleanup
+agent:done                           ← always fires last (all exit paths); includes stats.output
 ```
 
 ### Background task lifecycle
 
-Fires when the model invokes `shell({ run_in_background: true })`. The shell tool dispatches via `ExecutionContext.execBackground`, which spawns a process group, opens a `WriteStream` to `<userDir>/sessions/<sessionId>/tasks/<task-id>.<context-timestamp>.log` (the timestamp segment is `YYYYMMDD-HHMMSS-mmm` UTC, shared by every task in the same `ExecutionContext` so two contexts on the same session never collide), and returns immediately with a `TaskHandle`. The agent listens to `background:exit` and queues a `<task-notification>` block for injection into the next user turn (see "Notification queue" below).
-
-**Host opt-in / opt-out.** Background mode is auto-disabled at the schema level (the `run_in_background` field is dropped from the `shell` tool's input schema and the related description paragraphs are stripped) when either `behavior.tasksDir` is unset or `behavior.disableBackgroundTasks: true` is set. `createAgent` performs the rewrite once per run as it indexes tools by spec name — only for the identity-equal framework `shell` constant, so host-customized shell-named tools are left untouched. The runtime check in `runBackground` stays as defense-in-depth (forged inputs that smuggle the flag in past the schema fall through to a clean error, not a silent fallthrough to foreground). Hosts that want explicit control should call `createShellTool({ allowBackground })` and register the tailored variant directly.
+Fires when the model invokes `shell({ run_in_background: true })`. Full mechanics (spawn, log files, notification queue, destroy ordering, orphan reaping) live in `docs/RUN_IN_BACKGROUND.md`.
 
 ```
-background:start     ← spawn succeeded; payload carries taskId + pid + outputPath
-                       (observational; tools don't wait on listeners)
-background:exit      ← at-most-once per task; the context's settle latch
-                       guarantees no duplicate fires (close-or-error race-safe)
+background:start     ← spawn succeeded; payload carries taskId + pid + outputPath (observational)
+background:exit      ← at-most-once per task
 execution:ready      ← once per agent when the execution handle binds
-                       (spawned or host-injected via AgentOptions.handle)
 ```
 
-**Notification queue.** The agent owns a `Map<taskId, TaskExitInfo>` populated by the `background:exit` listener. At the start of every `agent.run()`, the queue drains and each entry becomes a leading `text` block on the seeded user turn (`<task-notification>…</task-notification>` XML — see `renderTaskNotificationXml` in `src/agent.ts`). The same agent listens to `tool:after` for `shell_kill` (deletes by `task_id` from input) and `read_file` / `read` (deletes by matching the `path` argument against any pending entry's `outputPath`) so the model never receives a redundant signal when it already learned about the exit through other means. The drain happens once per entry — `Map.set` overwrites by id, so a defensive double-enqueue can't multiply notifications.
-
-**Replay synthesis.** `eventsFromTurns` detects the `<task-notification>` XML in persisted user-turn text blocks (anchored regex — no false positives mid-prompt) and emits a structured `'task-notification'` `StreamEvent` instead of the generic `user-prompt` event. The XML text block is dropped from the rendered stream so the banner doesn't double-paint alongside the raw XML. Field decoding is tolerant — every tag falls back to a safe default if the persisted block predates a later schema addition.
-
-**Destroy ordering.** `agent.destroy()` runs cleanup INSIDE-the-session first (notification queue, per-call cancels) then NEEDED-by-the-session (MCP connection, execution handle, skills cache). The execution context's own `destroy(handle)` walks its background-task registry, SIGTERMs each survivor's process group, and only resolves once every output stream has flushed + closed. The reverse order would tear down the handle underneath still-flushing tasks and corrupt log files. The queue is re-cleared AFTER `executionContext.destroy()` because the `background:exit` hook listener stays bound for the agent's lifetime and may re-populate the map mid-teardown.
-
-**Orphan reaper.** `ProcessContext` lazy-registers a `process.on('exit')` handler on the first `execBackground` call that synchronously SIGTERMs every still-running task's process group. Without it, the `detached: true` spawn flag (required for the kill-tree semantics) would leak children when the host process exits without calling `destroy()` (Ctrl+C, uncaught exception, OOM kill). The handler deregisters in `destroy()` so reconstructed contexts don't accumulate listeners.
-
 ### Where MCP servers run (`scope: 'host' | 'context'`)
 
-An MCP server is an ordinary program: its `fs.readFileSync` / `fs.writeFile` hit whatever filesystem it was spawned on. By default (`scope: 'host'`) stdio servers are spawned as children of the agent process via `StdioClientTransport`, so under a sandboxed execution context the agent's own tools and its MCP servers see **different filesystems** — a path the model found with `list_files` doesn't exist for the server, and an MCP write lands where `read_file` can't see it.
-
-`McpServerConfig.scope: 'context'` relocates a stdio server into the execution context through the optional `ExecutionContext.execStream` seam (`capabilities.stream`). `createTransport` then builds `createContextStdioTransport` (`src/mcp/context-transport.ts`) instead, reusing the SDK's own `ReadBuffer` / `serializeMessage` for newline framing — `ReadBuffer` decodes only at newline boundaries, which is why the seam carries bytes: decoding per chunk would corrupt any multibyte codepoint split across a boundary.
+By default (`scope: 'host'`) stdio MCP servers spawn as children of the agent process, so under a sandboxed execution context the agent's tools and its MCP servers see **different filesystems**. `McpServerConfig.scope: 'context'` relocates a stdio server into the execution context via `ExecutionContext.execStream` (see `docs/EXECUTION_CONTEXT.md` for the context types).
 
-Opt-in rather than automatic, because it's wrong for most servers: a GitHub / Linear / Sentry MCP wants the host's credentials and only talks to the network. Only workspace-touching servers (filesystem, git, build tooling) want `'context'`. Two consequences: the context's image must contain the server's runtime (`node`, `uvx`, …), and this buys filesystem **coherence, not isolation** — remote-transport MCP servers can never be relocated, so the agent's reach is still not bounded by the sandbox. A `scope: 'context'` server on a context without `execStream` is a bootstrap error, never a silent fallback to a host spawn.
+- Opt-in per server — remote-transport and credentialed servers (GitHub/Linear/Sentry) stay host-side; only workspace-touching servers (filesystem, git, build tooling) want `'context'`. A `scope: 'context'` server on a context without `execStream` is a bootstrap error, never a silent host-spawn fallback. Buys filesystem **coherence, not isolation**.
+- Lazy binding (`getHandle()`) — `warmup()` still fans MCP connect and skills out in parallel with no ordering special case. Subagents reuse the parent's live connection instead of cold-booting a sandbox per spawn. Reconnect after a mid-session server death rebuilds through `execStream`, never a host-spawn fallback; the transport is branded `__contextScoped` so pid-based kill utilities refuse to touch it.
 
-**Ordering.** The agent always hands the connector an `McpExecutionBinding`, but the binding is **lazy**: it carries `getHandle()` rather than a resolved handle, and `createTransport` calls it only when a `scope: 'context'` stdio server actually builds its transport. So `warmup()` keeps fanning MCP connect and skills out in parallel, host-only setups never spawn, and there is no ordering special case — the handle necessarily exists by the time `execStream` runs because the same call site awaits it. This also matters for sub-agents: `spawn` hands the child the parent's inherited `mcpServers` alongside a `nonOwningMcpConnector` that reuses the parent's live connection, so the child builds no transport and must not cold-boot a sandbox per spawn.
-
-**Lifecycle.** Reconnect after a mid-session server death goes through `makeLazyConnector`, which captures the binding in its closure and rebuilds the transport through `execStream` — a reconnect can never silently fall back to a host spawn. `connection.close()` reaches `StreamHandle.kill()`, so no server survives in the sandbox to accumulate across reconnects. The context transport is branded `__contextScoped`, and `stdioPidOf` refuses to read a pid from it: `killStdioChild` signals **host** pids, and a sandbox pid (often a small number like `77`) names an unrelated host process.
-
-**Per-context backing.** `process` uses a piped `spawn`. `docker` uses the `docker exec -i` **CLI**, not dockerode: dockerode's hijacked exec (the only HTTP-API route to a writable stdin) rides on docker-modem's HTTP 101 upgrade handling, which hangs under Bun — verified working under Node, so it's a runtime incompatibility rather than misuse. `e2b` uses `commands.run({ background: true, stdin: true, timeoutMs: 2^31-1 })` + `sendStdin` — all three options non-default and each load-bearing (no `stdin` → immediate EOF; the 60s default `timeoutMs` → the server is killed mid-session; and NOT `timeoutMs: 0`, which `@connectrpc/connect`'s deadline signal treats as already expired). `daytona` must use a **PTY**, since its process/session API has no stdin at all; that forces `stty raw -echo` (terminal echo would return our own writes as responses; canonical mode rewrites `\n`→`\r\n` and caps lines near 4096 bytes) and a stderr redirect to a file (one terminal stream means stderr would otherwise interleave into the protocol). The real command lives in an uploaded script — the typed launch line is itself subject to canonical-mode echo and the line cap, so it stays short and constant — and the stderr file is polled back through the exec API onto `StreamHandle.stderr` (the poll carries a `ZEOF-<token>:<wc -c>` suffix so the next offset comes from the file's real size rather than from possibly-transformed content), then removed on teardown.
-
-**Two non-obvious behaviours, both found only by running against live infrastructure.**
-
-*Daytona's PTY is `lazyStart`: the shell does not exist when you type into it.* The launch line is buffered, then the login shell boots, prints a prompt, and replays the input through its line editor — so the raw stream opens with the echoed launch line, the echoed first request, bracketed-paste escapes and a `%` prompt. An MCP client parses that echoed request as a message and the handshake collapses. `execStream` therefore gates the stream on a readiness sentinel the *child* prints (`printf 'Z-%s-READY\n' <token>`) and discards every byte before it. The sentinel is assembled at runtime so the echoed source line — which contains the format string, not the result — cannot false-match it.
+| Backend | Transport | Load-bearing quirk |
+|---|---|---|
+| `process` | Piped `spawn` | — |
+| `docker` | `docker exec -i` CLI, not dockerode | Dockerode's hijacked-exec stdin hangs under Bun (works under Node). |
+| `e2b` | `commands.run({ background, stdin: true, timeoutMs })` + `sendStdin` | Default 60s `timeoutMs` kills the server mid-session; `0` is treated as already-expired. |
+| `daytona` | PTY (`stty raw -echo`) + stderr redirected to a polled file | No stdin API; shell is `lazyStart` and echoes the launch line, so the stream gates on a ready sentinel the child prints. |
 
-*Killing a context-scoped server needs a process group, and neither sandbox gives you one for free.* `npx`-style launchers fork the real server as a grandchild that survives a pid-only kill and accumulates across reconnects. Both `docker` and `e2b` therefore launch under `setsid -w` (with a runtime probe falling back to a plain exec on images whose setsid lacks `-w`; bare `setsid` is not an option, as its parent exits immediately and tears the stream down) and record the session leader's pid, which is then the PGID. On E2B this is a safety requirement, not an optimisation: the pid E2B reports runs in **envd's own process group**, so a group kill on it would take down the sandbox agent. The group signal is `kill -TERM -$pid` with no `--` — dash's kill builtin rejects it.
+`docker` and `e2b` launch under `setsid -w` and record the session leader's pid as the kill target — a pid-only kill leaves `npx`-style grandchildren running, and on E2B the reported pid is envd's own process group, so killing it directly would take the sandbox agent down too.
 
 ### Once (lazy on first `warmup()` / `run()` / `activateSkill()` — or eager when `eager: true`)
 
@@ -684,17 +553,17 @@ Opt-in rather than automatic, because it's wrong for most servers: a GitHub / Li
 mcp:bootstrap:start / mcp:bootstrap:end  ← per server, always fires (durationMs + ok/toolCount | error)
 mcp:connect                              ← per server bootstrapped OK
 mcp:error                                ← per server that failed (fatal: connect/transport)
-mcp:warn                                 ← per server diagnostic line (non-fatal; currently: stdio child stderr, one event per line)
+mcp:warn                                 ← per server diagnostic line (non-fatal; e.g. stdio child stderr)
 skills:resolve                           ← after discovery
 skills:catalog  [mutable: catalog]       ← after catalog build
 skills:activate                          ← during run, when a skill file is read
 ```
 
-`warmup()` fans MCP connect + skills resolution out in parallel; both sides are idempotent and share an in-flight promise across concurrent callers. Hooks registered after `warmup()` resolves may miss `skills:resolve` / `skills:catalog` — register before any `warmup()` / `run()` / `activateSkill()` call (or before `createAgent` returns when using `eager: true`). Use `mcp:bootstrap:end` for cold-start attribution — not wall-clock diffs against `mcp:connect`, which is skipped on failure.
+`warmup()` fans MCP connect + skills resolution out in parallel; both sides share an in-flight promise. Hooks registered after `warmup()` resolves may miss `skills:resolve`/`skills:catalog` — register before any `warmup()`/`run()`/`activateSkill()` call (or before `createAgent` returns with `eager: true`).
 
 ### Spawn lifecycle
 
-Fires when a parent invokes the `spawn` tool. Children inherit the parent's preset (tools, system, aliases, mcpServers, skills, behavior) by default — see SKILL.md "Sub-agent Spawning" to restrict.
+Fires when a parent invokes the `spawn` tool. Children inherit the parent's preset (tools, system, aliases, mcpServers, skills, behavior) by default.
 
 ```
 spawn:before          ← child agent created, before run
@@ -702,7 +571,7 @@ spawn:complete        ← child finished successfully, includes AgentStats
 spawn:error           ← child run threw
 ```
 
-The child's lifecycle also bubbles to the parent hook surface with `childId` + `depth`, so nested UI renders without subscribing on the child:
+The child's lifecycle also bubbles to the parent hook surface with `childId` + `depth`:
 
 ```
 child:stream:text / child:stream:thinking / child:stream:end / child:stream:error
@@ -713,19 +582,10 @@ child:tool:before / child:tool:after / child:tool:error
 child:turn:after
 ```
 
-`BUBBLED_MUTABLE_EVENTS` (`src/tools/spawn.ts`) is the canonical list: `tool:gate`, `mcp:tool:gate`, `tool:transform`. The bubbled ctx is the same reference the child loop awaits on, so a parent listener can refuse / substitute / annotate a subagent's tool call without registering on the child agent. The chat layer's per-edit annotation flow registers on both `tool:transform` and `child:tool:transform` so subagent-issued `multi_edit` calls also get `<edit-outcomes>` blocks appended to their results.
-
-**Subagent type registry** (`createSpawnTool({ subagents })`). When set, the spawn tool's input schema gains a `subagent_type` enum (the registered keys plus the always-available `'general-purpose'` fallback). The matching `SubagentDef` overlays the parent's resolved config for that one dispatch:
+`BUBBLED_MUTABLE_EVENTS` (`src/tools/spawn.ts`) lists `tool:gate`, `mcp:tool:gate`, `tool:transform` — the bubbled ctx is the same reference the child loop awaits on, so a parent listener can refuse/substitute/annotate a subagent's tool call without registering on the child.
 
-- `system` — preset system prompt. Per-call `input.system` still wins (model specialization beats preset defaults).
-- `model` — default model for this subagent type (e.g. an Explore preset pinned to a cheap model). Precedence: per-call `input.model` > this > `SpawnToolOptions.model` > inherit the parent run's model.
-- `tools: readonly string[]` — restrict the child to this canonical-name allow-list (strict subset of the parent's tools; unknown names silently dropped). Matched on `tool.spec.name`, not registry key.
-- `readonly: true` — convenience for `tools: ['read_file', 'grep', 'glob', 'list_files']`. `tools` wins when both are set.
-- `description` — short blurb rendered into the schema field so the model can pick a type without round-tripping through docs.
-
-Unknown `subagent_type` values are routed to `'general-purpose'` (no overlay) — Claude-Code-trained models emitting `subagent_type: 'Verification'` against hosts that didn't wire that type still run, just with the parent's defaults. Empty / unset registry omits the `subagent_type` schema field entirely (historical schema).
-
-**Subagent model catalog** (`createSpawnTool({ models })` / `spawnTool.withModels(catalog)` for hosts whose provider list is only known at agent-build time). When set, the schema gains an optional `model` field so the parent can delegate to cheaper models per call. ≤ 8 entries embed id + pricing + context window in the field description; larger catalogs defer to a host-registered `model_search` tool (`createModelSearchTool(catalog)`). Each entry carries the `Provider.name` that serves it, and the child is routed to that provider (resolved via `ToolContext.providers`, the run's fallback-chain provider list). Unknown ids reject with closest matches so the model can self-correct; no catalog keeps the historical schema and children always inherit the parent's model.
+- **Subagent type registry** (`createSpawnTool({ subagents })`) adds a `subagent_type` enum to the schema; the matching `SubagentDef` overlays `system`, `model`, `tools` (allow-list), `readonly` (shorthand for `['read_file','grep','glob','list_files']`), and `description` for that one dispatch. Unknown types route to `'general-purpose'`.
+- **Subagent model catalog** (`createSpawnTool({ models })`) adds an optional `model` field so the parent can delegate to cheaper models. ≤ 8 entries embed pricing in the schema; larger catalogs need a host-registered `model_search` tool.
 
 ## Dependency Graph
 
@@ -769,98 +629,61 @@ flowchart TB
 
 ## Presets
 
-A `Preset` is `Omit<Partial<AgentOptions>, 'provider' | 'execution' | 'session' | 'mcpConnector'>` — a reusable slice of agent config that consumers spread into `createAgent`:
+A `Preset` is `Omit<Partial<AgentOptions>, 'provider' | 'execution' | 'session' | 'mcpConnector'>` — a reusable slice of agent config consumers spread into `createAgent`:
 
 ```ts
 createAgent({ ...basic, provider })
 ```
 
-Excluded fields are all ambient / per-invocation runtime wiring (`provider`, `session`, `execution`, and `mcpConnector` — the MCP connection seam, often closure-bound to a transport / auth provider). Everything else — `name`, `system`, `tools`, `toolAliases`, `behavior`, `mcpServers`, `skills`, `eager`, **`hooks`** — is preset-shareable.
-
-### `hooks` field
+Excluded fields are ambient/per-invocation runtime wiring. Everything else — `name`, `system`, `tools`, `toolAliases`, `behavior`, `mcpServers`, `skills`, `eager`, **`hooks`** — is preset-shareable.
 
-`AgentOptions.hooks` (typed `AgentHookMap`) is registered for the **lifetime of the agent**: identical in effect to calling `agent.hooks.hook(event, fn)` immediately after `createAgent` returns. Handlers fire across every `run()`. Unknown event names throw at construction (typo guard). For per-run handlers that auto-detach at run end, use `AgentRunOptions.hooks` instead — same shape, different scope.
+`AgentOptions.hooks` registers for the agent's lifetime (same effect as `agent.hooks.hook(event, fn)` right after `createAgent`); unknown event names throw at construction. `AgentRunOptions.hooks` is the per-run, auto-detaching equivalent.
 
-Each entry accepts a single handler or an array. The array form is what `composePresets()` emits when multiple presets target the same event.
-
-### `composePresets(...presets)` — field-aware merge
-
-Bare `...spread` is shallow: `{ ...a, ...b }` overwrites every key `b` defines, including `hooks`. Two presets that both register a `turn:before` handler would silently lose `a`'s handler. `composePresets` is the explicit composition primitive:
+Bare `...spread` is shallow — two presets both registering `turn:before` would silently lose one handler. `composePresets(...)` is the explicit merge primitive:
 
 ```ts
 createAgent({ ...composePresets(basic, telemetry, mine), provider })
 ```
 
-Merge rules:
-
-| field                                    | rule                                                  |
-| ---------------------------------------- | ----------------------------------------------------- |
-| `name`, `system`, `eager`, `skills`      | last-defined wins                                     |
-| `tools`, `toolAliases`, `behavior`       | shallow-merge (later keys override per field)         |
-| `mcpServers`                             | concat with last-wins on `name` collision (a later preset can override an earlier preset's `github` server) |
-| `hooks`                                  | per-event concat — every handler fires, in preset order |
-
-`hooks` always emerges as `event → handler[]` so `createAgent` sees a uniform shape regardless of whether the source was a single handler or an array. Handler order within an event follows preset order: earlier presets register first.
-
-### When to reach for what
+| Field | Rule |
+|---|---|
+| `name`, `system`, `eager`, `skills` | Last-defined wins. |
+| `tools`, `toolAliases`, `behavior` | Shallow-merge (later keys override per field). |
+| `mcpServers` | Concat, last-wins on `name` collision. |
+| `hooks` | Per-event concat — every handler fires, in preset order. |
 
-- **One preset, no overlap with consumer code** → spread directly: `createAgent({ ...preset, provider })`.
-- **Multiple presets** → `composePresets(...)` first. Spread alone gives you last-wins on `hooks` and `behavior` field-overrides you probably didn't intend.
-- **Dynamic registration after creation** → `agent.hooks.hook(event, fn)` (returns an `unregister` fn). Preset hooks are "baked in"; runtime hooks are dynamic.
-- **Per-run, auto-detached** → `agent.run({ hooks: { … } })`. Same `event → fn | fn[]` shape.
+Use `agent.hooks.hook(event, fn)` for dynamic post-creation registration (returns an `unregister` fn), and `agent.run({ hooks })` for per-run auto-detached handlers.
 
 ## Option Precedence
 
-`run.behavior` > `agent.behavior` > defaults (field-by-field merge).
-
-Defaults: unlimited turns (set `maxTurns` as a safety net), model-driven output (`maxTokens` unset → Anthropic sends the model's max output since the field is mandatory, OpenAI-style providers omit it so the model runs to a natural stop; set a number for a hard per-turn cap), level-based thinking; `cache: true`, `dedupReads: true`, `requireReadBeforeEdit: false`, `maxConcurrentTools: 10`, `compactStrategy: 'off'`, `compactThreshold: 128 KiB`, `compactKeepTurns: 4`, `toolDisclosure: 'eager'`, `readLineNumbers: true`, `elideStaleReads: false`, `surfaceMcpInstructions: true`, `maxConsecutivePauseTurns: 0` (unlimited — empty-pause exhaustion no longer ends a live run by default), `persistTurns: true`, `providerStreamStartTimeoutMs: 300000`, `providerStreamTimeoutMs: 1800000`, and `mcpConnectTimeoutMs: 120000` for custom connectors. `persistTurns: true` means incremental per-turn store sync; set `false` to persist once at run end instead — trades mid-run crash granularity for O(1) writes per run on stores whose `appendTurns` re-serializes the session. All other knobs (`toolOutputBudget`, `dedupTools`, `toolBudgets`, `repeatGuard`, `thinkingDecay`, `thinkingOverrunPolicy`, `readFileDefaults`, `writeFileExistingPolicy`, `textToolCallRescue`, `unknownToolRecovery`, `progressNudges`, `maxTurnsWarningMessage`, `toolSearch`, `mediaKeepTurns`, `autoCompact`, `persistThreshold`, `persistDir`, `persistExcludeTools`, `persistMaxBytes`, `maxCostUsd`, `maxTotalTokens`, `resumeOnMaxTokens`, `retry`, `toolBatchTimeoutMs`) are `undefined` (`retry` defaults to 3 attempts with 1s → 30s exponential backoff when absent). The chat-layer profiles (`BUILD_AGENT` / `PLAN_AGENT`) override several of these (including turning `requireReadBeforeEdit` **on**, enabling `repeatGuard` in `mode: 'both'`, and setting `mediaKeepTurns: 8`) — see CHAT.md → Agents.
-
-**`toolOutputBudget`** (off by default). The loop sums every tool result's `outputBytes` after `tool:transform`, so consumer truncation counts. On overshoot, a synthetic user message is appended:
-
-> `[Tool output budget exceeded: N bytes returned in this turn (cap: M). Summarize the salient findings before calling more tools.]`
-
-`budget:exceeded` fires with `{ turn, turnId, bytes, budget }`. The next turn picks up the message as latest input — model self-compacts instead of being cut.
-
-**`compactStrategy: 'tail' | CompactFunction`** — client-side companion for non-Anthropic providers. `'tail'` sums tool-result bytes after `sanitizeStoredToolResults` and before `context:transform`; on overshoot, `tool_result` blocks older than `compactKeepTurns` are replaced with a stub. Text and image blocks pass through; `session.turns` is untouched. Anthropic users should prefer the server-side `context-management-2025-06-27` beta (token-accurate) via `anthropic({ extraBetas, contextManagement })`. Pluggable form: pass a `(messages, { threshold, keepTurns, totalBytes }) => messages | Promise<messages>` for LLM-summary or custom semantic compaction — same wire-only contract, must preserve `tool_use ↔ tool_result` adjacency and the trailing user message. Throws degrade gracefully (logged via `console.error`, original payload survives).
-
-**`mediaKeepTurns`** - wire-only media age-out for long image/document sessions. When set, inline top-level `image` / `document` blocks and media nested in `tool_result` outputs older than the last `mediaKeepTurns` messages are replaced on the provider wire with a short marker carrying an `attachment://<hash>` handle. The persisted `session.turns` still keep the original base64 bytes; `read_file path="attachment://<hash>"` resolves the handle from session history and re-inlines the media for that turn. This is separate from `compactStrategy: 'tail'`: tail compaction only stubs old `tool_result` text and deliberately does not trim media bytes. The frontier is chunk-snapped for prompt-cache stability, so aged media drops out in batches rather than one message at a time. SDK default is off; chat profiles set `mediaKeepTurns: 8` to align with their `compactKeepTurns`. Proactive age-out requires the `read_file` tool to be registered, so the marker is actionable. Reactive `context_exceeded` recovery may still strip media even without `read_file`; in that case the marker says the handle is saved but cannot be re-opened in the current run.
-
-**`autoCompact`** — loop-native auto-compaction (`boolean | AutoCompactConfig`). At each turn boundary the loop computes the last turn's effective input (`input + cacheRead + cacheCreation`, so prompt caching can't hide a full window) and, once it crosses `threshold` (default `0.85`) of the effective context window, runs a real summary over the older turns (`compactConversation`, `scope: 'tail'`), appends a `compact-summary` marker plus optional file/skill restoration (`buildPostCompactAttachments`) to the session, and continues — the next turn's `applyCompactSummaryCutoff` elides the summarized turns. Fires mid tool-loop AND at end-of-run (so a resumed session starts compacted). Window source is `autoCompact.contextWindow` → `provider.meta.contextWindow`; with neither it's inert (the SDK core has no model catalog, so chat hosts inject the picked model's window). A hysteresis floor (`minGrowthFraction`, default `0.1`) stops post-compact thrashing and a consecutive-failure circuit breaker (`maxFailures`, default `2`) disables it for the run if the summary keeps failing. Distinct from `compactStrategy` (per-turn wire-only tool-output trim) and the always-on reactive `context_exceeded` recovery; observe via the `compact:start` / `compact:end` hooks. SDK default off; chat profiles enable it (`{ threshold: 0.85 }`) and the TUI/GUI inject the window + honor the user's enable/threshold settings per run.
-
-**`modelCatalog`** — override model metadata (output ceiling, per-MTok rates, context window, `reasoning`) for models pi-ai's bundled registry gets wrong or has never heard of: gateway aliases, private deployments, post-pin releases, non-Anthropic models served over the Anthropic wire. Accepts a table keyed `"<provider>:<modelId>"` or a `{ get, list }` source (`src/providers/model-catalog.ts`). Resolution is first-hit-wins: **run `behavior.modelCatalog` → agent `behavior.modelCatalog` → process-wide `setModelCatalog()` → pi-ai registry → local fallback tables** (`EXTRA_COST_RATES`, `defaultAnthropicMaxTokens`). Entries merge **field-level** over the bundled entry (`cost` merges per-rate), so `{ maxTokens: 128000 }` corrects one field and inherits the rest. Everything stays keyed by `(provider, modelId)` — overriding one provider leaves the others fully bundled. `get` returning `undefined` falls through; `list` returning an array claims **ownership** of that provider's picker (so it can hide as well as add, and suppresses our `extraModels` stopgap), `[]` empties it, `undefined` keeps the bundled list. The table form only ever overlays, and an id-less `list` entry is dropped with a one-shot warning (it would render a blank, selectable picker row). An entry with no `contextWindow` leaves the window **unknown** rather than zero — `getContextWindow` treats non-positive values as absent and falls through to `contextWindowEnvVar` / `null`. The provider key is the pi-ai registry id (usually the factory name); the Codex provider is the exception, storing records under `openai-codex` and pricing under `openai`, and accepts an entry keyed either way on BOTH sides — the wire path via `aliasCatalogProviders`, the host path via the descriptor's key set (`catalogProvidersOf`) — so an override can't half-apply (right invoice, missing context gauge). `estimateRebilledCostUsd` takes the catalog as an argument instead: cache-break telemetry is computed by the host that owns the `cache:break` hook, outside any run context, so a host using a catalog must pass the same one there. The `{ get, list }` form holds functions and therefore cannot be snapshotted by a durable/replay runtime that serializes `behavior` — use the table form or install it with `setModelCatalog` at boot; and prefer `behavior.modelCatalog` over the process-wide setter in multi-tenant servers. Threaded as `StreamOptions.modelCatalog`, so per-agent catalogs reach the wire path (Anthropic's `max_tokens` default + clamp, `fillEstimatedCost` for all ten providers, Codex model resolution) without process-wide state — two agents can carry different catalogs. The chat/TUI layer (`modelsForDescriptor`, `getModelInfo`, context gauge) resolves metadata before any agent exists, so it reads the process-wide catalog only. SDK default: unset — the bundled registry is authoritative.
-
-**`dedupReads` + `requireReadBeforeEdit`** share the same per-session `WeakMap<Session, Map<canonicalAbsPath, { contentHash, offset, limit, maxBytes, mtimeMs }>>`. The key is the canonical absolute path (via `node:path.resolve(handle.cwd, modelProvidedPath)`) so all path shapes the model can write — `src/x`, `./src/x`, `/abs/cwd/src/x` — converge on one entry. Map population happens whenever **either** feature is enabled; the dedup *short-circuit* (returning the "unchanged since the previous read" stub) is what `dedupReads` actually gates. This decoupling means `dedupReads: false` no longer breaks the `requireReadBeforeEdit` guard. `edit` / `multi_edit` reject when no entry exists (the message notes that shell reads — cat/grep/sed — don't register). On-disk hash drift is **anchor-tolerant**: the hazard drift creates is a mis-anchored `old_string`, so if the edit still resolves VERBATIM against the current bytes it proceeds with a disclosure note; when resolution fails or only a fuzzy recovery (quote normalization, line-number strip) matches — drift + fuzzy being the one combination where mis-anchoring is genuinely plausible — the drift is refused with "re-read the file" — and consecutive refusals without an intervening read escalate (`staleRejections` on the entry, reset by any fresh read or successful edit) to name the likely external writer (editor auto-save, formatter, codegen watcher). Flat drift refusals are what taught models to abandon `edit` for shell one-liners that bypass every guard. Both tools update the hash on success so chained edits don't need re-reads — and set the entry's `elided` flag in the same update, so the next re-read misses dedup and serves the fresh body instead of a "still current" stub pointing at the pre-mutation output (`write_file` seeds with the flag for the same reason). Dedup resumes after that one honest read; the flag never affects the edit gate. Optional `AgentOptions.readState` (also exposed on `ToolContext.readState`) forwards an explicit map — used by `createSpawnTool({ shareReadState: true })` so a sessionless child still feeds the parent's tracking without sharing turn persistence. GC'd with the session when no explicit map is in play. The map is **never serialized**, so a host that reloads a fresh `Session` from a store on resume — or a durable/replay runtime where a journaled `read_file` never re-runs its live `rememberRead` — would start with an empty map and the gate would reject every edit whose read happened in an earlier turn. To prevent that, a `tool:gate` hook (installed when `requireReadBeforeEdit` is on) pre-hydrates the map from `session.turns` right before an `edit`/`multi_edit` runs, when its target path is missing from the map: transcript reconstruction for full reads, an `execution.readFile` re-hash fallback for partial ones, alias-aware for wire-named transcripts. It fires **inside the loop, outside any journaled tool body, on every replay**, so the verdict can never be frozen by a host that journals tool execution; it has an O(1) `Map.has` fast path so it only scans when a path is genuinely absent, and never blocks (the authoritative read/drift verdict stays in the tool body). The `restateTool` wrapper additionally hydrates once per process for `read_file` dedup; it is a complement, not what the gate depends on.
-
-**`dedupTools`** generalizes the same pattern via a consumer hasher per tool. Parallel `WeakMap<Session, Map<toolName, { hash, result, repeats }>>` keeps only the most recent hash. Two forms:
-
-- **Hasher function** (legacy / `mode: 'replay'`) — on hit, the prior result replays verbatim. Substitute path fires `tool:transform` + `tool:after` so budgets stay coherent. Makes loops cheap, doesn't break them.
-- **Config object with `mode: 'block-after'`** — `{ hasher, mode: 'block-after', threshold, reason?, scope? }`. Replays for the first `threshold − 1` identical calls; the `threshold`-th identical call (and all subsequent ones) gets refused via `tool:gate` `ctx.block = true` with `Blocked: <reason>`. Counter is sticky on the same hash — once the cap trips it stays tripped until a different input resets the counter. `threshold` defaults to `4`, clamps at `2`. `reason` accepts a string or `(input, count) => string`; default is `"Identical \`<tool>\` call repeated N times — break the loop by changing your approach or moving on to a different step."`.
-- **`scope: 'session' | 'run'`** (any mode) — keying granularity for the dedup counter. `'session'` (default) keys `(session, toolName)` — right for pure tools (`read_file`, `grep`). `'run'` keys `(session, runId, toolName)` so a parent and its subagents never share an entry; `todowrite` uses this so its identical-write block is run-local. Falls back to session-scope for hand-built contexts with no `runId`.
-
-Tools with side effects or non-deterministic outputs MUST NOT be listed (no safety net beyond the consumer hasher).
-
-**`ToolContext.state`** (`src/tool-state.ts`) is durable key/value state for tools — the supported way to keep a one-shot marker, a cursor, or a dedup flag that must outlive the process. It exists because a closure variable can't: under a durable runtime a journaled tool result skips the body on replay, so a mutation made inside `execute` silently doesn't happen the second time. Reads are synchronous against a snapshot the agent hydrates once per agent instance (before the first dispatch, memoized on the controller); writes are staged as ops and committed by the dispatch path when the call settles — in call-index order, never completion order, and a rejecting store commit drops the write rather than failing the call. `AgentOptions.toolState` supplies the durable backing (`ToolStateStore` = `load` + `commit`, runtime-agnostic; `zidane/restate` ships `restateToolStateStore`); with none configured the map is in-memory and agent-scoped, so tools behave identically locally minus durability. The three-phase split is what lets a durable adapter journal the staged delta *as data* alongside the tool result and re-issue the identical write on replay — see [Durable tool state](./RESTATE.md#durable-tool-state). A rejecting store never fails the call (the body already ran): it fires `tool-state:commit-failed` with the lost ops and otherwise logs. Values are size-checked at `set()` time against `ToolStateStore.maxValueBytes` (default 64 KiB of JSON) so an oversized write throws in the tool that caused it rather than at commit — under Restate that difference is a failed-and-retried invocation versus a clean error.
-
-**`toolBudgets`** caps per-tool calls per run. When `runToolCounts[name] >= max`, fires `onExceed`: `'block'` refuses with `Blocked: <message>`, `'steer'` enqueues a synthetic user message (one per tool per run, deduped). Function form returns `{ mode, message }` dynamically. Fires `tool-budget:exceeded` (distinct from byte-level `budget:exceeded`). Counts include dedup substitutes by design.
-
-**`thinkingDecay`** tapers `thinkingBudget` per run-relative turn (1-indexed). `applyThinkingDecay(base, decay, turn)` runs at `runTurn` start. Struct form `{ afterTurn, factor, floor }` does geometric decay; function form `(turn, base) => number` accepts arbitrary curves. Result clamped to `[0, base]` so buggy curves can't exceed the caller's opt-in. Skipped for `thinking: 'adaptive'` only on providers with `adaptiveBudgetIsEnvelope` (Anthropic), where `thinkingBudget` caps the whole response envelope (`max_tokens`) and decaying it would strangle text/tool output; providers where adaptive `thinkingBudget` is a genuine per-turn thinking budget (openai-compat `reasoning.max_tokens`) still decay. `taskBudget` (Anthropic adaptive-only whole-task cap, emitted as `output_config.task_budget`) never decays.
-
-**Reliability levers** are opt-in and live in `src/behaviors/`. `writeFileExistingPolicy` blocks full-file rewrites of existing files and points the model at `read_file` + `edit` / `multi_edit`; `readFileDefaults` sets omitted `read_file` slice defaults without overriding explicit tool-call args; `thinkingOverrunPolicy` queues a non-interrupting next-turn nudge when streamed thinking crosses a threshold; `textToolCallRescue` steers after a model writes a tool call as text; `unknownToolRecovery` queues closest currently-advertised tool-name suggestions without changing the unknown-tool error result; `progressNudges` emits bounded non-interrupting pivot nudges for broad stalls that exact repeat guards do not cover; `maxTurnsWarningMessage` customizes the existing max-turn proximity nudge.
-
-**Gate precedence**. Consumer hooks register first (agent-lifetime then per-run), framework gates install after — `allowed-tools → writeFileExistingPolicy → toolBudgets → repeatGuard → dedupTools → lazy-disclosure`. Each framework gate short-circuits on existing `ctx.block` or `ctx.result`, so the firing order is consumer → framework with the framework gates acting as an early-exit chain. The net effect: a policy gate always beats a consumer cache substitute, budgets enforce before dedup replays a cached call against an exhausted cap, repeat-guard can still escalate budget-blocked loops when configured to count blocked calls, and lazy-disclosure runs last so skill refusal wins over "load schema first" and dedup substitutes only hit on previously-recorded successful calls (which already passed lazy-disclosure once).
-
-**Tool-result persistence** (`behavior.persistThreshold` + `persistDir` + `persistExcludeTools`). When set, the loop replaces oversize `tool_result` outputs with a `<persisted-output tool="…" bytes="…" path="…">` stub carrying a 2 KiB preview. Substitution happens just after `tool:transform`; the stub flows into `session.turns` directly so the prompt-cache prefix stays stable across turns. `persistDir` is required to enable the feature — without a target dir the framework silently skips persistence. `persistExcludeTools` (default empty at the SDK; the chat layer ships `DEFAULT_PERSIST_EXCLUDE_TOOLS` — see CHAT.md) lists canonical tool names that bypass regardless of size. `persistMaxBytes` caps the directory's cumulative `*.txt` size; after each successful write the helper evicts oldest-first by mtime (LRU) until total ≤ cap. The just-written blob is never evicted in the same sweep, so a single oversize result still lands. Off by default.
-
-**Run-level budget circuit breaker** (`behavior.maxCostUsd` + `behavior.maxTotalTokens`). Soft caps the cumulative spend / token consumption of a single `agent.run()`. Checked **after** each turn (post-`turn:after` + `usage` hooks), so the breaching turn's numbers are visible before the throw lands. Trips throw `AgentBudgetExceededError` (`limit: 'cost' | 'tokens'`, `limitValue`, `actualValue`); the agent finalizes the session run as `'aborted'` so the persisted record distinguishes operator-imposed stops from runtime errors. Cost check wins when both axes would trip on the same turn (operators set ceilings against dollar accounting). Token ledger sums `input + output` only — cache reads/creates are billed at a discount and counting them at par would under-estimate affordability. `0` / negative / non-finite values disable the corresponding axis. Off by default; `maxTurns` is the count-based companion.
-
-**`maxConsecutivePauseTurns`** caps consecutive empty `pause_turn` recoveries (Anthropic 4.6+ streaming edge case where the model returns a `pause_turn` stop reason with no text and no tool calls). Each empty pause counts; any productive turn — text, thinking, OR tool calls — resets the counter. When the counter reaches the cap, the loop exits cleanly (no `agent:abort` fire — this is graceful termination, not user-driven cancel). The last `TurnUsage.finishReason` stays `'pause'` so consumers detect pause exhaustion from `stats`. Default `5`; set `0` to disable.
-
-**Retry-with-backoff** (`behavior.retry`: `{ maxAttempts, initialDelayMs, maxDelayMs }`). Wraps each `provider.stream()` call. Triggers only when `Provider.classifyError` returns `{ kind: 'provider_error', retryable: true }` (429, 5xx, Anthropic `overloaded_error` / `api_error` / `timeout_error` SSE events, OpenAI-compat stream truncation, OpenAI Codex transient messages) **and** nothing has streamed yet this turn — the partial-output guard avoids replaying content the user already saw; prefill-continuation (replaying with the partial assistant response prefilled so the model continues from there) is a separate, larger change. Fires `stream:retry` before each backoff sleep with `{ attempt, nextAttempt, delayMs, err, statusCode?, requestId? }`; `stream:error` only fires on the terminal failure. Backoff is `min(maxDelayMs, initialDelayMs * 2^(attempt-1))` with full jitter (`Math.random() * computed`); `retry-after` / `retry-after-ms` headers, when present on the error, override the schedule (still capped at `maxDelayMs`). The sleep is `signal`-aware so `agent.abort()` cancels cleanly. Defaults: `maxAttempts: 3`, `initialDelayMs: 1000`, `maxDelayMs: 30_000`. Set `maxAttempts: 1` to disable. The Anthropic SDK's own pre-stream retry (default `maxRetries: 2` for the initial HTTP request) sits below this layer; the loop-level retry covers mid-stream errors the SDK can't replay.
+`run.behavior` > `agent.behavior` > defaults, field-by-field.
+
+**Defaults:** unlimited turns, model-driven output tokens, level-based thinking, `cache: true`, `dedupReads: true`, `requireReadBeforeEdit: false`, `maxConcurrentTools: 10`, `compactStrategy: 'off'`, `compactThreshold: 128 KiB`, `compactKeepTurns: 4`, `toolDisclosure: 'eager'`, `readLineNumbers: true`, `elideStaleReads: false`, `surfaceMcpInstructions: true`, `maxConsecutivePauseTurns: 0` (unlimited), `persistTurns: true`, `providerStreamStartTimeoutMs: 300000`, `providerStreamTimeoutMs: 1800000`, `mcpConnectTimeoutMs: 120000`. All other knobs below default to `undefined`/off unless noted. The chat-layer profiles (`BUILD_AGENT`/`PLAN_AGENT`) override several — see `docs/CHAT.md` § Agents.
+
+- **`toolOutputBudget`** (off). Sums every result's `outputBytes` after `tool:transform`. On overshoot, appends a synthetic user message (`[Tool output budget exceeded: N bytes … cap: M]`) and fires `budget:exceeded` — the model self-compacts next turn instead of being cut.
+- **`compactStrategy: 'tail' | CompactFunction'`** — client-side, wire-only trim for non-Anthropic providers. `'tail'` stubs `tool_result` blocks older than `compactKeepTurns` past a byte threshold; `session.turns` is untouched. Anthropic should prefer server-side `context-management-2025-06-27` (token-accurate). A custom function must preserve `tool_use ↔ tool_result` adjacency and the trailing user message.
+- **`mediaKeepTurns`** — wire-only media age-out. Inline `image`/`document` blocks older than N messages become an `attachment://<hash>` marker on the wire; `session.turns` keeps the bytes, `read_file path="attachment://<hash>"` re-inlines. Chunk-snapped for cache stability; requires `read_file` registered to be actionable.
+- **`autoCompact`** (`boolean | AutoCompactConfig`, off). At each turn boundary, once effective input (`input + cacheRead + cacheCreation`) crosses `threshold` (default `0.85`) of the context window, summarizes older turns and continues. Window source: `autoCompact.contextWindow` → `provider.meta.contextWindow`, else inert. `minGrowthFraction` (default `0.1`) stops post-compact thrashing; `maxFailures` (default `2`) disables it after consecutive summary failures. Chat profiles enable at `{ threshold: 0.85 }`.
+- **`modelCatalog`** — override model metadata keyed `"<provider>:<modelId>"` or via `{ get, list }`. Resolution: run → agent `behavior.modelCatalog` → process-wide `setModelCatalog()` → bundled registry → local fallback tables, merged field-level. `list` returning `[]` empties a provider's picker; `get` returning `undefined` falls through. Unset by default.
+- **`dedupReads` + `requireReadBeforeEdit`** share a per-session map keyed by canonical absolute path. `dedupReads` gates the short-circuit "unchanged since last read" reply; `requireReadBeforeEdit` rejects `edit`/`multi_edit` when no entry exists (shell reads don't register). Hash drift is anchor-tolerant — a still-verbatim `old_string` proceeds with a disclosure note, a fuzzy-only match is refused with "re-read the file", and consecutive refusals escalate to name the likely external writer. A `tool:gate` hook pre-hydrates the map from `session.turns` on resume.
+- **`dedupTools`** generalizes the pattern via a per-tool hasher keeping only the most recent hash. Hasher-only form replays the prior result on hit (fires `tool:transform`+`tool:after`). `{ hasher, mode: 'block-after', threshold, reason?, scope? }` replays the first `threshold − 1` calls then blocks via `tool:gate` (`threshold` default `4`, clamps at `2`); `scope: 'run'` keeps parent/subagent counters separate. Never list tools with side effects or non-deterministic output.
+- **`ToolContext.state`** (`src/tool-state.ts`) — durable key/value state that survives a durable-runtime replay where a journaled tool body doesn't re-execute. Reads are synchronous against a per-agent snapshot; writes stage as ops committed in call-index order. `AgentOptions.toolState` supplies the backing (unset ⇒ in-memory). A rejecting commit fires `tool-state:commit-failed` rather than failing the call; values cap at `maxValueBytes` (default 64 KiB JSON). See `docs/RESTATE.md#durable-tool-state`.
+- **`toolBudgets`** caps per-tool calls per run. At `runToolCounts[name] >= max`, `onExceed: 'block'` refuses (`Blocked: <message>`), `'steer'` enqueues a deduped synthetic user message. Fires `tool-budget:exceeded` (distinct from byte-level `budget:exceeded`). Counts include dedup substitutes.
+- **`thinkingDecay`** tapers `thinkingBudget` per run-relative turn. Struct form `{ afterTurn, factor, floor }` does geometric decay; function form `(turn, base) => number` allows arbitrary curves, clamped to `[0, base]`. Skipped for Anthropic's `thinking: 'adaptive'` (the budget caps the whole response envelope there); openai-compat's per-turn adaptive budget still decays. `taskBudget` never decays.
+- **Reliability levers** (`src/behaviors/`, opt-in): `writeFileExistingPolicy` blocks full-file rewrites of existing files; `readFileDefaults` sets omitted `read_file` slice defaults; `thinkingOverrunPolicy` nudges next-turn on thinking overrun; `textToolCallRescue` steers after a model writes a tool call as text; `unknownToolRecovery` suggests closest advertised tool names; `progressNudges` nudges broad stalls repeat guards don't cover; `maxTurnsWarningMessage` customizes the max-turn proximity nudge.
+- **Gate precedence.** Consumer hooks register first (agent-lifetime then per-run); framework gates install after: `allowed-tools → writeFileExistingPolicy → toolBudgets → repeatGuard → dedupTools → lazy-disclosure`. Each short-circuits on existing `ctx.block`/`ctx.result` — a policy gate always beats a consumer cache substitute, and lazy-disclosure runs last so skill refusal wins over "load schema first".
+- **Tool-result persistence** (`persistThreshold` + `persistDir` + `persistExcludeTools`, off without `persistDir`). Oversize `tool_result` outputs become a `<persisted-output tool="…" bytes="…" path="…">` stub with a 2 KiB preview, substituted just after `tool:transform` so the stub — not the raw output — hits the cache prefix. `persistMaxBytes` caps the directory with oldest-first eviction; the just-written blob is never evicted in the same sweep.
+- **Run-level budget circuit breaker** (`maxCostUsd` + `maxTotalTokens`, off). Checked after each turn. Trips `AgentBudgetExceededError` (`limit: 'cost' | 'tokens'`); the session run finalizes as `'aborted'`. Cost wins when both axes trip together. Token ledger sums `input + output` only (cache reads/creates are discounted). `maxTurns` is the count-based companion.
+- **`maxConsecutivePauseTurns`** (default `5`, `0` disables) caps consecutive empty `pause_turn` recoveries (Anthropic 4.6+ streaming edge case). Any productive turn resets the counter; hitting the cap exits cleanly with no `agent:abort` — `finishReason` stays `'pause'`.
+- **`retry`** (`{ maxAttempts, initialDelayMs, maxDelayMs }`, defaults `3`/`1000`/`30000`). Wraps `provider.stream()`; triggers only on a retryable `provider_error` **and** nothing streamed yet this turn. Fires `stream:retry` before each backoff sleep (full-jitter, `retry-after` header overrides); `stream:error` only on terminal failure. `maxAttempts: 1` disables it. Sits above the Anthropic SDK's own pre-stream HTTP retry, which can't replay a mid-stream error.
 
 ## Related
 
 - `docs/SKILL.md` — public API surface (createAgent, providers, presets, hooks, sessions, skills, MCP).
-- `docs/CHAT.md` — renderer-agnostic chat engine (`zidane/chat`).
+- `docs/CHAT.md` — renderer-agnostic chat engine (`zidane/chat`), owns per-edit approval.
 - `docs/TUI.md` — OpenTUI terminal shell (`zidane/tui`).
+- `docs/ARTIFACTS.md` — session artifacts model, producers, storage.
+- `docs/RUN_IN_BACKGROUND.md` — background task mechanics.
+- `docs/EXECUTION_CONTEXT.md` — `process` / `docker` / `e2b` / `daytona` execution contexts.
 - `docs/INTERACTIONS.md` — interactive tools (`present_plan`, `ask_user`) protocol.
 - `docs/RESTATE.md` — optional durable-execution adapter (`zidane/restate`).