zidane 5.1.17 → 5.1.18

package/docs/ARCHITECTURE.md

@@ -0,0 +1,581 @@
+# Zidane Architecture
+
+## Agent Lifecycle
+
+```mermaid
+flowchart TB
+    subgraph Creation ["createAgent()"]
+        C1[Create hooks] --> C2[Merge config]
+        C2 --> C3["Provider + Tools + Options"]
+        C3 --> C4["eager: true?"]
+        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()"]
+    end
+
+    subgraph PostRun ["Post-loop"]
+        P1{"Aborted?"} -->|yes| P2["session.abortRun()"]
+        P1 -->|no| P3["session.completeRun()"]
+        P2 --> P4["agent:done hook"]
+        P3 --> P4
+        P4 --> P5["Return AgentStats"]
+    end
+
+    Creation --> FirstRun
+    FirstRun --> 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 PostRun fill:#16213e,stroke:#0f3460,color:#fff
+```
+
+## Turn Loop
+
+```mermaid
+flowchart TB
+    START((runLoop)) --> ABORT1{Aborted?}
+    ABORT1 -->|yes| DONE["agent:done hook\nReturn stats"]
+    ABORT1 -->|no| TURN["executeTurn()"]
+
+    TURN --> STATS["Accumulate usage"]
+    STATS --> ABORT2{Aborted?}
+    ABORT2 -->|yes| DONE
+
+    ABORT2 -->|no| STEER{Steering\nqueued?}
+    STEER -->|yes| INJECT_STEER["Inject steering\nas user turn"] --> CONTINUE
+    STEER -->|no| ENDED{LLM said\ndone?}
+
+    ENDED -->|no| CONTINUE((Next turn))
+    CONTINUE --> ABORT1
+
+    ENDED -->|yes| FOLLOWUP{Follow-up\nqueued?}
+    FOLLOWUP -->|yes| INJECT_FU["Inject follow-up\nas user turn"] --> CONTINUE
+    FOLLOWUP -->|no| DONE
+
+    style DONE fill:#0f3460,stroke:#e94560,color:#fff
+    style TURN fill:#1a1a2e,stroke:#533483,color:#fff
+```
+
+## Single Turn
+
+```mermaid
+flowchart TB
+    T1["Generate turnId"] --> T2["turnsToMessages()"]
+    T2 --> T2B["sanitizeStoredToolResults()\n(flatten images for non-vision providers)"]
+    T2B --> T3["context:transform hook"]
+    T3 --> T3B["system:transform hook\n(per-request system mutation)"]
+    T3B --> T3C["applyThinkingDecay()\n(per-turn budget taper)"]
+    T3C --> T4["turn:before hook"]
+    T4 --> STREAM
+
+    subgraph STREAM ["provider.stream()"]
+        S1["Send system + messages + tools to LLM"] --> S2["Stream text chunks"]
+        S2 --> S3["stream:text hook (per chunk)"]
+    end
+
+    STREAM -->|error| CATCH["turn:after hook (zero usage)\nRethrow"]
+    STREAM -->|ok| S4{"Has text?"}
+    S4 -->|yes| S5["stream:end hook"]
+    S4 -->|no| AFTER
+    S5 --> AFTER["turn:after hook (with usage)"]
+
+    AFTER --> DONE_CHECK{LLM done?\nNo tool calls}
+
+    DONE_CHECK -->|yes| SCHEMA{"behavior\n.schema?"}
+    SCHEMA -->|yes| ENFORCE["Force __output__ tool call\nExtract structured output\nFire output hook"]
+    SCHEMA -->|no| PUSH_FINAL["Return ended: true"]
+    ENFORCE --> PUSH_FINAL
+    DONE_CHECK -->|no| TOOLS
+
+    subgraph TOOLS ["Tool Execution"]
+        direction TB
+        TE1["Push assistant turn\n(with tool calls)"] --> TE2{Parallel\nmode?}
+        TE2 -->|sequential| SEQ["For each tool:\n1. Check abort + steering queue\n   (on hit: synthesize Aborted/Skipped\n    tool_results for remaining calls)\n2. executeSingleTool()"]
+        TE2 -->|parallel| PAR["Promise.allSettled(\nexecuteSingleTool)"]
+        SEQ --> TE3["Push tool results turn\n+ fire tool-results:after"]
+        PAR --> TE3
+    end
+
+    TOOLS --> RET["Return ended: false"]
+
+    style STREAM fill:#16213e,stroke:#0f3460,color:#fff
+    style TOOLS fill:#1a1a2e,stroke:#533483,color:#fff
+```
+
+## Tool Execution
+
+```mermaid
+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)"]
+    RES1 --> RES2["Return substitute"]
+    RES -->|no| INC["increment runToolCounts"]
+    INC --> T3{Tool\nexists?}
+    T3 -->|no| TU["tool:unknown hook\n(can substitute result\nor suppress error)"]
+    TU --> TUE{suppressError?}
+    TUE -->|no| T4["tool:error hook\n(can substitute result)"]
+    TUE -->|yes| T4B["(skip tool:error)"]
+    T4 --> TUR["Return ctx.result\n(or default 'Unknown tool: …')"]
+    T4B --> TUR
+    T3 -->|yes| T5["validateToolArgs()\n(auto-coerce types)"]
+    T5 --> VALID{Valid?}
+    VALID -->|no| VR["validation:reject hook\n(observational)"]
+    VR --> T6["Return 'Validation error: …'"]
+    VALID -->|yes| VC{"coercions\n.length > 0?"}
+    VC -->|yes| VCH["validation:coerce hook\n(observational)"]
+    VC -->|no| T7
+    VCH --> T7["tool:before hook\n(ctx.coercions when present, runToolCounts)"]
+    T7 --> T8["toolDef.execute(coercedInput, ctx)"]
+    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)"]
+    T10B --> T11["tool:after hook\n(ctx.outputBytes post-mutation, runToolCounts)"]
+    T11 --> T12["Return { id, content: string | ToolResultContent[] }"]
+
+    style T8 fill:#1a1a2e,stroke:#e94560,color:#fff
+    style TU fill:#1a1a2e,stroke:#0f3460,color:#fff
+    style VR fill:#1a1a2e,stroke:#0f3460,color:#fff
+    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.
+
+**`runToolCounts`** is a frozen pre-call snapshot, scoped to `runId`. Includes dedup + gate-`result` substitutes; excludes blocked calls. Resumed sessions reset the counter. In parallel mode, consumer hooks see the pre-batch snapshot — built-in budget/dedup middleware uses its own gate-time reservation counter so `behavior.toolBudgets` stays atomic mid-batch.
+
+**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 ergonomics defaults
+
+Built-in tools are opinionated about output sizes — drop your v2 `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. **Ungated** (no `_outcomes` in input — the SDK default): atomic, first failure aborts. **Gated** (chat layer injects `_outcomes` per-hunk via `injectOutcomesIntoInput`): each hunk reported independently into a structured `Edited <path>: N/M applied · K denied · …` body — `parseEditOutcomesFromResult` re-parses for transcript replay. See CHAT.md → Per-edit approval. |
+| `grep` | Wraps `rg` when present (with explicit `.` path to avoid stdin hangs). Bun.Glob fallback otherwise. `head_limit=250`, `offset` paginates. |
+
+## 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`).
+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.
+
+## Data Flow
+
+```mermaid
+flowchart LR
+    subgraph Input
+        USER[User prompt] --> TURNS[SessionTurn array]
+        SESSION[(Session store)] -.->|resume| TURNS
+    end
+
+    subgraph Agent
+        TURNS --> MSG["turnsToMessages()"]
+        MSG --> PROVIDER["provider.stream()"]
+        PROVIDER --> RESULT{Tool calls?}
+        RESULT -->|text only| DONE[Push final turn]
+        RESULT -->|tool calls| EXEC["Execute tools"]
+        EXEC --> PUSH["Push tool results"]
+        PUSH --> MSG
+    end
+
+    subgraph Output
+        DONE --> STATS["AgentStats"]
+        DONE -.->|incremental| SESSION
+        PUSH -.->|incremental| SESSION
+    end
+
+    style Input fill:#16213e,stroke:#0f3460,color:#fff
+    style Agent fill:#1a1a2e,stroke:#533483,color:#fff
+    style Output fill:#16213e,stroke:#0f3460,color:#fff
+```
+
+## Typed errors
+
+Provider failures are wrapped before leaving `agent.run()`:
+
+```
+native error
+  → provider.classifyError(err)   returns ClassifiedError | null
+     kind: 'context_exceeded'  → AgentContextExceededError
+     kind: 'provider_error'    → AgentProviderError
+     kind: 'aborted'           → AgentAbortedError
+     null                      → AgentProviderError (fallback)
+```
+
+`agent.abort()` and 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** — last text block.
+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:
+
+| Provider | Behavior |
+|---|---|
+| `anthropic` | Breakpoints honored natively. |
+| `openrouter` | Breakpoints forwarded; Anthropic + Gemini routes honor them, others ignore. |
+| `openaiCompat` | Factory-gated via `cacheBreakpoints: boolean` (default **off**). `openrouter` flips it on; bare `openaiCompat` stays off so OpenAI-direct doesn't reject unknown fields. |
+| `cerebras` | Off (factory doesn't enable breakpoints). |
+| `openai` (Codex) | Not affected — separate wire format (pi-ai). |
+
+Cache-read + cache-write counts surface on `TurnUsage.cacheRead` / `TurnUsage.cacheCreation`,
+populated from Anthropic's native fields and from OpenRouter's `prompt_tokens_details`.
+
+## Tool aliasing (wire vs. canonical)
+
+Aliasing lives at the LLM boundary only:
+
+```
+AgentOptions.tools keyed by canonical name ← agent dispatch
+                 │
+                 ▼
+Loop.aliasMaps (canonical ↔ wire)
+                 │
+outbound: canonical → wire     inbound: wire → canonical
+  │                              │
+  ▼                              ▼
+ToolSpec sent to provider      result.toolCalls / assistantMessage.content[tool_call]
+(model calls by wire name)     (immediately rewritten to canonical)
+                 │
+                 ▼
+session.turns persists canonical names
+ToolHookContext.name = canonical, .displayName = wire
+```
+
+`session.turns` can't desync on alias-map changes; hooks match on canonical names; UI adapters read `displayName` for labels.
+
+## Skills activation lifecycle
+
+Zidane implements the [Agent Skills spec](https://agentskills.io/specification) via dedicated-tool activation. Three tools auto-inject when the catalog is non-empty: `skills_use` / `skills_read` / `skills_run_script`.
+
+```
+createAgent({ skills })                    → skillActivationState({ maxActive })
+
+ensureSkillsResolved() [idempotent, shared promise across callers]:
+  resolveSkills(config)                    → skills:resolve
+  buildCatalog(skills, …)                  → skills:catalog
+
+triggered by (first-caller-wins):
+  agent.warmup()                           ← explicit pre-warm (or eager: true)
+  agent.run()                              ← lazy bootstrap on first run
+  agent.activateSkill(name)                ← host-driven activation (e.g. TUI slash-cmd)
+
+first run():
+  rehydrate from session turns             → skills:activate (via: 'resume')
+
+per run():
+  installAllowedToolsGate, installToolBudgetsGate, installDedupToolsGate
+  auto-inject skills_use / skills_read / skills_run_script
+  runLoop():
+    skills_use({ name })                   → state.activate(skill, 'model')
+                                             → skills:activate (via: 'model')
+                                             → <skill_content> wrapper
+    skills_read / skills_run_script        → gated on state.isActive + path sandbox
+  run end: deactivateAllSkills()           → skills:deactivate (reason: 'run-end')
+
+agent.activateSkill(name)                  → skills:activate (via: 'explicit')
+agent.deactivateSkill(name)                → skills:deactivate (reason: 'explicit')
+agent.reset()                              → skills:deactivate (reason: 'reset')
+```
+
+**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).
+
+**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.
+
+## 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.
+
+```
+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
+
+unlocked = new Set(eagerCanonicalNames)
+if (lazyEntries && toolSearch.tool !== false && !host-defined tool_search):
+  tools.tool_search = createToolSearchTool({ catalog: lazyEntries, unlocked, defaultLimit })
+  unlocked.add('tool_search')
+
+system += buildSearchableCatalog(lazyEntries)   // wire names, XML-escaped, no inputSchema
+installLazyDisclosureGate                       // tool:gate refuses lazy ∉ unlocked
+
+per turn:
+  buildFormattedTools()  → filter ctx.tools by unlocked, alias through aliasMaps
+
+tool_search({ names | query | server, limit? }):
+  match wire-keyed byName/byServer indexes
+  unlocked.add(canonicalName) per match
+  return <tool_search_results>…<input_schema>{json}</input_schema>…
+    (inputSchema JSON inlined with `<` → `\u003c` so a hostile schema can't break the envelope)
+
+run end: uninstallLazyDisclosureGate; unlocked 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 cost.** Each `tool_search` advances the tool-list cache breakpoint — one miss per discovery wave; subsequent same-unlocked turns hit cache. Still beats eager (every schema, every turn) when lazy tools are many and discovery waves few. 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 })` to drive the unlock flow — bare implementations leave the gate refusing every lazy call. For custom flows, prefer `toolSearch.tool: false`.
+
+## Hook Firing Order
+
+### Skills
+
+```
+skills:resolve                               ← once per agent, after discovery (warmup / run / activateSkill — first wins)
+skills:catalog    [mutable: catalog]         ← once per agent, after system-prompt catalog built (same trigger)
+skills:activate                              ← per activation; { skill, via: 'model' | 'explicit' | 'resume' }
+skills:deactivate                            ← per deactivation; { skill, reason: 'run-end' | 'explicit' | 'reset' }
+```
+
+Every run ends with an implicit deactivate-all pass (`reason: 'run-end'`); activation state never leaks across runs unless re-asserted via `agent.activateSkill()`.
+
+### 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.
+
+> **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`.
+
+```
+context:transform     [mutable: messages]       ← edit messages before LLM call
+system:transform      [mutable: system]         ← per-request system mutation
+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)
+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)
+    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
+  tool:after                                     ← + outputBytes post-mutation
+  tool:error          [mutable: result?]         ← on execute throw; ctx.result substitutes
+tool-results:after                               ← after the tool-results user turn is pushed (persistence seam)
+usage                                            ← running totals
+output                                           ← when behavior.schema set
+budget:exceeded / tool-budget:exceeded           ← byte / per-tool caps tripped
+```
+
+**`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 loop also synthesizes `Aborted: …` / `Skipped: …` tool_results for any remaining calls when abort / steering interrupts a sequential batch (`synthesizeMissingToolResults` in `src/agent.ts`), so the assistant turn's `tool_use` ids always stay matched.
+
+`tool:unknown` replaces `tool:before` when no `toolDef` exists; `validation:reject` fires after coercion attempts fail. The model receives a result string in both cases (substituted or `Validation error: …`) so it can recover.
+
+### 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.
+  [turn hooks above, repeated]
+  session:turns                      ← after turns persisted (includes 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)
+                                       includes turnRange [start, end] for cleanup
+```
+
+### Once (lazy on first `warmup()` / `run()` / `activateSkill()` — or eager when `eager: true`)
+
+```
+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
+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.
+
+### 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.
+
+```
+spawn:before          ← child agent created, before run
+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:
+
+```
+child:stream:text / child:stream:thinking / child:stream:end
+child:tool:gate / child:mcp:tool:gate          ← share the child's ctx — parent mutations propagate
+child:tool:before / child:tool:after / child:tool:error
+child:turn:after
+```
+
+The two `child:*:gate` events are special: the bubbled ctx is the same reference the child loop awaits on, so a parent listener can refuse / substitute a subagent's tool call without registering on the child agent.
+
+## Dependency Graph
+
+```mermaid
+flowchart TB
+    AGENT[agent.ts] --> LOOP[loop.ts]
+    AGENT --> TOOLS[tools/]
+    AGENT --> PROVIDER[providers/]
+    AGENT --> SESSION[session/]
+    AGENT --> SKILLS[skills/]
+    AGENT --> MCP[mcp/]
+    AGENT --> CONTEXTS[contexts/]
+    AGENT --> PROMPT[prompt.ts]
+    AGENT --> ALIASING[aliasing.ts]
+
+    LOOP --> PROVIDER
+    LOOP --> TOOLS
+    LOOP --> ALIASING
+    LOOP --> ERRORS[errors.ts]
+
+    PRESETS[presets/] --> TOOLS
+    TOOLS --> CONTEXTS
+    TOOLS -->|spawn| AGENT
+
+    PROVIDER --> TYPES[types.ts]
+    PROVIDER --> ERRORS
+    LOOP --> TYPES
+    SESSION --> TYPES
+    AGENT --> TYPES
+
+    TRACING[tracing.ts] -.->|installs on| AGENT
+
+    style AGENT fill:#e94560,stroke:#fff,color:#fff
+    style LOOP fill:#533483,stroke:#fff,color:#fff
+    style TYPES fill:#0f3460,stroke:#fff,color:#fff
+    style ERRORS fill:#16213e,stroke:#e94560,color:#fff
+    style ALIASING fill:#16213e,stroke:#e94560,color:#fff
+    style PROMPT fill:#16213e,stroke:#e94560,color:#fff
+    style TRACING fill:#1a1a2e,stroke:#533483,color:#fff
+```
+
+## Presets
+
+A `Preset` is `Omit<Partial<AgentOptions>, 'provider' | 'execution' | 'session' | 'mcpConnector'>` — a reusable slice of agent config that consumers spread into `createAgent`:
+
+```ts
+createAgent({ ...basic, provider })
+```
+
+Excluded fields are either ambient runtime (`provider`, `session`, `execution`) or test seams (`mcpConnector`). Everything else — `name`, `system`, `tools`, `toolAliases`, `behavior`, `mcpServers`, `skills`, `eager`, **`hooks`** — is preset-shareable.
+
+### `hooks` field
+
+`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.
+
+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:
+
+```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
+
+- **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.
+
+## Option Precedence
+
+`run.behavior` > `agent.behavior` > defaults (field-by-field merge).
+
+Defaults: unlimited turns (set `maxTurns` as a safety net), `maxTokens: 16384`, level-based thinking; `cache: true`, `dedupReads: true`, `requireReadBeforeEdit: false`, `compactStrategy: 'off'`, `compactThreshold: 128 KiB`, `compactKeepTurns: 4`, `toolDisclosure: 'eager'`, `readLineNumbers: true`, `elideStaleReads: false`. All other knobs (`toolOutputBudget`, `dedupTools`, `toolBudgets`, `thinkingDecay`, `toolSearch`, `persistThreshold`, `persistDir`, `persistExcludeTools`) are `undefined`. The chat-layer profiles (`BUILD_AGENT` / `PLAN_AGENT`) override several of these — 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'`** — client-side companion for non-Anthropic providers. After `sanitizeStoredToolResults` and before `context:transform`, the loop sums tool-result bytes; 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 })`.
+
+**`dedupReads` + `requireReadBeforeEdit`** share a per-session `WeakMap<Session, Map<path, { contentHash, offset, limit, maxBytes, mtimeMs }>>` (keyed `${handle.cwd}::${path}`). `read_file` returns a stub on identical (hash + slice) re-reads. `edit` / `multi_edit` reject when no entry exists or the on-disk hash drifted. Edits update the hash on success so chained edits don't need re-reads. GC'd with the session.
+
+**`dedupTools`** generalizes the same pattern via a consumer hasher per tool. Parallel `WeakMap<Session, Map<toolName, { hash, result }>>` keeps only the most recent hash. On hit, the prior result replays verbatim — substitute path fires `tool:transform` + `tool:after` so budgets stay coherent. Tools with side effects or non-deterministic outputs MUST NOT be listed.
+
+**`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. `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.
+
+**Gate precedence**. Consumer hooks register first (agent-lifetime then per-run), framework gates install after — `allowed-tools → tool-budgets → dedup → 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, 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.
+
+## Related
+
+- `docs/SKILL.md` — public API surface (createAgent, providers, presets, hooks, sessions, skills, MCP).
+- `docs/CHAT.md` — renderer-agnostic chat engine (`zidane/chat`).
+- `docs/TUI.md` — OpenTUI terminal shell (`zidane/tui`).
+- `docs/INTERACTIONS.md` — interactive tools (`present_plan`, `ask_user`) protocol.