zidane 4.1.8 → 5.0.0

package/dist/{index-bgh-k8Mv.d.ts → agent-JhicgLOV.d.ts}

@@ -1,4 +1,4 @@
-import { c as ExecutionContext, l as ExecutionHandle } from "./index-BB4kuRh3.js";
+import { c as ExecutionContext, l as ExecutionHandle } from "./index-CXVvqTQj.js";
 import { Hookable } from "hookable";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 //#region src/errors.d.ts
@@ -117,2257 +117,2370 @@ declare function matchesContextExceeded(message: unknown): boolean;
  */
 declare function toTypedError(classification: ClassifiedError, provider: string, cause: unknown): AgentContextExceededError | AgentProviderError | AgentAbortedError;
 //#endregion
-//#region src/mcp/index.d.ts
-interface McpConnection {
-  tools: Record<string, ToolDef>;
-  close: () => Promise<void>;
-}
-/**
- * Normalize MCP server configs from any common shape to `McpServerConfig[]`.
- *
- * Accepts:
- * - `McpServerConfig[]` — zidane native (pass-through).
- * - `McpServerConfig` — a single config object (wrapped to a 1-element array).
- * - `Record<string, RawShape>` — name-keyed map (common in host-SDK configs), where the key is the server name.
- * - Mixed shapes with `type` vs `transport`, `httpUrl`/`sseUrl` vs `url`.
- *
- * Returns `[]` when `input` is nullish. Throws a descriptive error when the transport
- * cannot be inferred from a given entry, or when the input shape is unsupported.
- */
-declare function normalizeMcpServers(input: unknown): McpServerConfig[];
-/**
- * Lossy flattener — converts MCP `CallToolResult.content` blocks to a single
- * string. Text blocks are extracted; non-text blocks are JSON-stringified.
- *
- * Use this only at UI / log boundaries that require a string. The agent
- * loop itself routes through {@link normalizeMcpBlocks} so image blocks
- * survive into provider-native tool_result content (Anthropic blocks,
- * OpenAI companion-user-message).
- */
-declare function resultToString(content: unknown[]): string;
-/**
- * Normalize MCP `CallToolResult.content` to zidane's {@link ToolResultContent[]} shape.
- *
- * Handles the four MCP content block types:
- * - `text` → preserved as `{type:'text', text}`
- * - `image` → preserved as `{type:'image', mediaType, data}` (MCP uses `mimeType`)
- * - `resource` with embedded text → flattened to a text block
- * - `resource` with embedded blob whose `mimeType` is `image/*` → flattened to an image block
- * - Any unrecognized block → JSON-stringified fallback text block (lossy but safe)
- *
- * Returns `null` when the input is not an array — callers should fall back to an empty
- * result in that case.
- */
-declare function normalizeMcpBlocks(content: unknown): ToolResultContent[] | null;
-/**
- * Connect to MCP servers and discover their tools.
- *
- * Each tool is namespaced as `mcp_{serverName}_{toolName}` to avoid
- * collisions with agent tools or tools from other servers.
- *
- * @param configs - Array of MCP server configurations
- * @param _clientFactory - Internal: override client construction for testing
- * @param hooks - Optional agent hooks for firing mcp:connect, mcp:error, mcp:close events
- */
-declare function connectMcpServers(configs: McpServerConfig[], _clientFactory?: () => Client, hooks?: Hookable<AgentHooks>): Promise<McpConnection>;
-//#endregion
-//#region src/session/file-map.d.ts
-/**
- * Host-provided file-map adapter. Three methods exchanging `Record<string, string>`
- * payloads — the whole persistence surface the wrapper needs.
- */
-interface FileMapAdapter {
-  /** Load the current file map. Returns an empty `files` record when nothing is persisted. */
-  get: () => Promise<{
-    files: Record<string, string>;
-  }>;
-  /** Replace the persisted file map. Full-rewrite semantics. */
-  save: (files: Record<string, string>) => Promise<void>;
-  /** Delete all persisted state. */
-  delete: () => Promise<void>;
-}
-interface FileMapStoreOptions {
-  /** Filename for the JSONL turns log. Default: `turns.jsonl`. */
-  turnsFile?: string;
-  /** Filename for the metadata JSON. Default: `meta.json`. */
-  metaFile?: string;
-}
+//#region src/types.d.ts
 /**
- * Create a single-session `SessionStore` backed by a file-map adapter.
+ * Thinking / extended-reasoning configuration.
  *
- * @example
- * ```ts
- * const session = await createSession({
- *   store: createFileMapStore(hostSessionStore),
- * })
- * ```
+ * - `'off'` — no thinking.
+ * - `'minimal' | 'low' | 'medium' | 'high'` — explicit token budget. Maps to
+ *   provider-specific reasoning controls (Anthropic `thinking.type='enabled'`
+ *   with a budget; OpenAI `reasoning_effort`).
+ * - `'adaptive'` — let the model decide per-turn whether and how much to think.
+ *   Anthropic-only (`thinking.type='adaptive'`). Other providers fall back to
+ *   no reasoning when this value is supplied.
  */
-declare function createFileMapStore(adapter: FileMapAdapter, options?: FileMapStoreOptions): SessionStore;
-//#endregion
-//#region src/session/memory.d.ts
-declare function createMemoryStore(): SessionStore;
-//#endregion
-//#region src/session/messages.d.ts
-declare function fromAnthropic(msg: {
-  role: string;
-  content: unknown;
-}): SessionMessage;
-declare function fromOpenAI(msg: {
-  role: string;
-  content: unknown;
-}): SessionMessage;
-declare function toAnthropic(msg: SessionMessage): {
-  role: string;
-  content: unknown;
-};
-declare function toOpenAI(msg: SessionMessage): {
-  role: string;
-  content: unknown;
-};
-declare function autoDetectAndConvert(msg: {
-  role: string;
-  content: unknown;
-}): SessionMessage;
-//#endregion
-//#region src/session/remote.d.ts
-interface RemoteStoreOptions {
-  /** Base URL of the session API */
-  url: string;
-  /** Optional headers (e.g. for authentication) */
-  headers?: Record<string, string>;
-}
-declare function createRemoteStore(options: RemoteStoreOptions): SessionStore;
-//#endregion
-//#region src/session/index.d.ts
-interface SessionRun {
-  id: string;
-  startedAt: number;
-  endedAt?: number;
-  prompt: string;
-  status: 'running' | 'completed' | 'aborted' | 'error';
-  turns?: number;
-  tokensIn?: number;
-  tokensOut?: number;
-  error?: string;
-  /** Per-turn usage breakdown */
-  turnUsage?: TurnUsage[];
-  /** Total usage across all turns */
-  totalUsage?: TurnUsage;
-  /** Estimated cost in USD */
-  cost?: number;
+type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'adaptive';
+interface McpServerConfig {
+  /** Display name (used for tool namespacing) */
+  name: string;
+  /** Transport type */
+  transport: 'stdio' | 'sse' | 'streamable-http';
+  /** For stdio: command to run */
+  command?: string;
+  /** For stdio: command arguments */
+  args?: string[];
   /**
-   * The run that spawned this one, when the agent is a subagent sharing its
-   * parent's session. Undefined on top-level `agent.run()`. Consumers can walk
-   * `runs` by `parentRunId` to reconstruct the subagent tree.
+   * For stdio: environment variables to pass to the server process.
+   *
+   * Merged on top of the MCP SDK's default inherited environment — a safety
+   * whitelist (`PATH`, `HOME`, `LANG`, `SHELL`, `USER` on POSIX; `APPDATA`,
+   * `PATH`, ... on Win32). Setting this to `{}` no longer strips `PATH` from
+   * the child process. Set {@link McpServerConfig.strictEnv} to `true` to
+   * pass `env` verbatim with no inherited defaults.
    */
-  parentRunId?: string;
+  env?: Record<string, string>;
   /**
-   * Zero-based subagent depth. 0 = top-level run, 1 = direct child, …
-   * Recorded here so hosts can query/filter by level without walking the tree.
+   * When true, {@link McpServerConfig.env} is passed verbatim to the spawned
+   * process — the MCP SDK's default inherited environment (`PATH`, `HOME`, ...)
+   * is NOT merged in. Most consumers should leave this off; the default merge
+   * prevents `spawn ENOENT` when a stdio server declares an `env` without
+   * restating `PATH`.
    */
-  depth?: number;
-}
-interface SessionData {
-  id: string;
-  agentId?: string;
-  turns: SessionTurn[];
-  runs: SessionRun[];
-  status: 'idle' | 'running' | 'completed' | 'error';
-  metadata: Record<string, unknown>;
-  createdAt: number;
-  updatedAt: number;
-}
-interface SessionStore {
-  /** Optional: generate a session ID server-side (e.g. Supabase UUID). */
-  generateSessionId?: () => string | Promise<string>;
-  /** Optional: generate a turn ID server-side. */
-  generateTurnId?: () => string | Promise<string>;
-  /** Load a session by ID. Returns null if not found. */
-  load: (sessionId: string) => Promise<SessionData | null>;
-  /** Save a session (create or update, full document). */
-  save: (session: SessionData) => Promise<void>;
-  /** Delete a session. */
-  delete: (sessionId: string) => Promise<void>;
-  /** List session IDs, optionally filtered. */
-  list: (filter?: {
-    agentId?: string;
-    limit?: number;
-  }) => Promise<string[]>;
-  /** Append new turns to a session (incremental, avoids full re-save). */
-  appendTurns: (sessionId: string, turns: SessionTurn[]) => Promise<void>;
-  /** Return a slice of turns for a session. */
-  getTurns: (sessionId: string, from?: number, limit?: number) => Promise<SessionTurn[]>;
-  /** Persist an updated run record (called after completeRun / abortRun / errorRun). */
-  updateRun: (sessionId: string, run: SessionRun) => Promise<void>;
-  /** Update the top-level status of a session. */
-  updateStatus: (sessionId: string, status: SessionData['status']) => Promise<void>;
-}
-interface Session {
-  /** Session ID */
-  readonly id: string;
-  /** Agent ID (optional label) */
-  readonly agentId?: string;
-  /** Current turn history */
-  readonly turns: SessionTurn[];
+  strictEnv?: boolean;
+  /** For sse/streamable-http: server URL */
+  url?: string;
+  /** Optional headers for HTTP transports */
+  headers?: Record<string, string>;
   /**
-   * True when this session has no turns yet.
+   * Timeout in milliseconds for MCP server bootstrap (connect + tool discovery).
    *
-   * Use this as a first-prompt signal when setting up a run — e.g. writing initial
-   * configuration only on fresh sessions. Equivalent to `turns.length === 0`.
+   * Zidane connects MCP servers lazily on the first `run()`. Without a
+   * bootstrap timeout, a slow or hung server can delay the first provider call
+   * for an arbitrarily long time even when that MCP server is never used.
+   *
+   * Default: `10000`.
    */
-  readonly isEmpty: boolean;
-  /** Top-level session status */
-  readonly status: SessionData['status'];
-  /** All runs in this session */
-  readonly runs: SessionRun[];
-  /** Arbitrary metadata */
-  readonly metadata: Record<string, unknown>;
+  bootstrapTimeout?: number;
+  /** Timeout in milliseconds for MCP tool calls (default: 30000) */
+  toolTimeout?: number;
   /**
-   * Start tracking a new run. `extras.parentRunId` + `extras.depth` are
-   * populated by the spawn tool when a child agent shares its parent's
-   * session; regular top-level `agent.run()` calls omit them.
+   * Allow-list of tool names to expose. Names match the upstream tool name
+   * (NOT the namespaced `mcp_{server}_{tool}` form). Tools not in the list are
+   * dropped before registration — the model never sees them in its catalog and
+   * the wire cost of advertising them is avoided.
+   *
+   * Mutually exclusive with {@link McpServerConfig.disabledTools} — passing both
+   * throws at bootstrap time.
+   *
+   * Composes with {@link McpServerConfig.toolFilter}: allow-list applies first,
+   * then the predicate. Composes with the `mcp:tools:filter` hook: config-side
+   * filters apply first, then the hook can further narrow the list.
    */
-  startRun: (runId: string, prompt?: string, extras?: {
-    parentRunId?: string;
-    depth?: number;
-  }) => void;
-  /** Mark a run as completed */
-  completeRun: (runId: string, stats: {
-    turns: number;
-    tokensIn: number;
-    tokensOut: number;
-    turnUsage?: TurnUsage[];
-    cost?: number;
-  }) => void;
-  /** Mark a run as aborted */
-  abortRun: (runId: string) => void;
-  /** Mark a run as errored */
-  errorRun: (runId: string, error: string) => void;
-  /** Append turns to in-memory history AND persist via store.appendTurns (if store present) */
-  appendTurns: (turns: SessionTurn[]) => Promise<void>;
-  /** Replace all turns in-memory (does not persist — use save() for that) */
-  setTurns: (turns: SessionTurn[]) => void;
-  /** Update the session status in memory AND via store.updateStatus (if store present) */
-  updateStatus: (status: SessionData['status']) => Promise<void>;
-  /** Persist an updated run record via store.updateRun (if store present) */
-  updateRun: (run: SessionRun) => Promise<void>;
-  /** Generate a turn ID using store.generateTurnId if available, else crypto.randomUUID() */
-  generateTurnId: () => string | Promise<string>;
-  /** Set metadata key */
-  setMeta: (key: string, value: unknown) => void;
-  /** Persist the full session document to the store */
-  save: () => Promise<void>;
-  /** Serialize to SessionData */
-  toJSON: () => SessionData;
-}
-interface CreateSessionOptions {
-  /** Session ID. If omitted and store provides generateSessionId, that is used. */
-  id?: string;
-  /** Agent ID label */
-  agentId?: string;
-  /** Initial metadata */
-  metadata?: Record<string, unknown>;
-  /** Storage backend (optional, enables save/load) */
-  store?: SessionStore;
-  _data?: SessionData;
-}
-/**
- * Create a new session.
- * Async so stores that generate IDs server-side (e.g. Supabase) can be supported.
- */
-declare function createSession(options?: CreateSessionOptions): Promise<Session>;
-/**
- * Load an existing session from a store.
- */
-declare function loadSession(store: SessionStore, sessionId: string): Promise<Session | null>;
-//#endregion
-//#region src/skills/types.d.ts
-/**
- * Types for the Agent Skills system.
- *
- * Follows the Agent Skills open standard (agentskills.io/specification).
- * Zidane-specific metadata conventionally uses the `zidane.` key prefix
- * (e.g. `metadata['zidane.paths']`) to stay spec-compliant.
- */
-interface SkillResource {
-  /** Relative path from skill directory */
-  path: string;
-  /** Resource type inferred from directory */
-  type: 'script' | 'reference' | 'asset' | 'other';
-}
-/**
- * Where the skill came from. Used for collision precedence (project beats user)
- * and for host SDKs to gate project-level skills on a trust check.
- */
-type SkillSource = 'project' | 'user' | 'inline' | 'builtin';
-/** Severity + code for lenient-load warnings surfaced to host UIs. */
-interface SkillDiagnostic {
-  severity: 'warning' | 'error';
-  /** Stable machine-readable code (e.g. `name-mismatch-directory`). */
-  code: string;
-  /** Human-readable description. */
-  message: string;
-  /** Optional frontmatter field name the diagnostic relates to. */
-  field?: string;
-}
-interface SkillConfig {
-  /** Skill name: 1-64 chars, lowercase alphanumeric + hyphens */
-  name: string;
-  /** What the skill does and when to use it (1-1024 chars) */
-  description: string;
-  /** The SKILL.md body content (after YAML frontmatter) */
-  instructions: string;
+  enabledTools?: string[];
   /**
-   * Where this skill was loaded from. Drives collision precedence and the
-   * `trustProjectSkills` gate. Optional — `parseSkillFile` stamps it; raw
-   * fixtures that omit it are treated as `'project'` by downstream readers.
+   * Deny-list of tool names. Tools matching are dropped before registration.
+   * Same matching semantics as {@link McpServerConfig.enabledTools}.
    */
-  source?: SkillSource;
-  /** Absolute path to SKILL.md (undefined for inline skills) */
-  location?: string;
-  /** Skill directory path for resolving relative references */
-  baseDir?: string;
-  /** License identifier or reference */
-  license?: string;
-  /** Environment requirements */
-  compatibility?: string;
+  disabledTools?: string[];
   /**
-   * Flat key-value metadata bag per the spec. For Zidane-specific hints,
-   * use the `zidane.` key prefix (e.g. `metadata['zidane.paths']`).
+   * Custom predicate run on each upstream tool. Return `true` to keep, `false`
+   * to drop. Receives the raw `listTools()` payload — useful for filtering by
+   * description, schema shape, or other metadata that an allow/deny list can't
+   * express.
+   *
+   * Runs after the allow/deny filter but before the `mcp:tools:filter` hook.
    */
-  metadata?: Record<string, string>;
-  /** Pre-approved tool names (experimental per spec) */
-  allowedTools?: string[];
-  /** Bundled resource files discovered in the skill directory */
-  resources?: SkillResource[];
+  toolFilter?: (tool: {
+    name: string;
+    description?: string | null;
+    inputSchema?: unknown;
+  }) => boolean;
   /**
-   * Lenient-load warnings recorded during parsing. Host SDKs can surface these
-   * as inline UI hints. Absent when no issues were found.
+   * Per-server override for {@link AgentBehavior.toolDisclosure}. When set,
+   * this server's tools follow this disclosure mode regardless of the
+   * agent-wide default. Useful when one big MCP server (200+ tools) should
+   * stay lazy while smaller servers stay eager.
+   *
+   * Default: inherits from `behavior.toolDisclosure`.
    */
-  diagnostics?: SkillDiagnostic[];
+  disclosure?: 'eager' | 'lazy';
 }
-interface SkillsConfig {
+type ToolExecutionMode = 'sequential' | 'parallel';
+interface AgentBehavior {
+  /** Tool execution mode (default: 'sequential') */
+  toolExecution?: ToolExecutionMode;
   /**
-   * Control which skills are active.
-   * - `true` (default): all discovered skills are enabled
-   * - `false` or `[]`: fully disable the skills system (no resolution, no catalog, no hooks)
-   * - `string[]`: allowlist — only skills with matching names are enabled
+   * Max agent loop iterations.
+   *
+   * Default: unlimited (Infinity). The loop runs until the model signals
+   * completion (no tool calls / `end_turn`), the abort signal fires, or this
+   * cap is hit. Set a finite value as a safety net for runaway loops.
    */
-  enabled?: boolean | string[];
-  /** Directories to scan for SKILL.md files */
-  scan?: string[];
-  /** Dynamic skills written to disk at agent start, then loaded normally */
-  write?: SkillConfig[];
-  /** Skill names to exclude from the catalog */
-  exclude?: string[];
-  /** Skip default scan paths (~/.agents/skills, .zidane/skills, etc.) */
-  skipDefaultPaths?: boolean;
+  maxTurns?: number;
+  /** Max tokens per LLM response (default: 16384) */
+  maxTokens?: number;
+  /** Thinking token budget — overrides the level-based default when set */
+  thinkingBudget?: number;
+  /** JSON Schema for structured output enforcement */
+  schema?: Record<string, unknown>;
   /**
-   * Auto-inject `skills_use` / `skills_read` / `skills_run_script` tools
-   * when the catalog is non-empty. Default `true`. Set `false` to opt out
-   * (the system prompt will then instruct the model to use its file-read
-   * tool instead).
+   * Enable provider prompt caching. When on (default), the provider marks the
+   * system prompt, tools, and the last stable message with cache breakpoints so
+   * the shared prefix is served from cache across turns.
+   *
+   * - Anthropic: `cache_control: { type: 'ephemeral' }` on the last `system`
+   *   content part, the last tool, and the last message content part.
+   * - OpenAI-compatible / OpenRouter: same shape — honored by Anthropic-backed
+   *   OpenRouter routes and by Gemini; ignored (no-op) by providers that cache
+   *   automatically (OpenAI, DeepSeek, Grok, Groq, Moonshot).
+   *
+   * Usage is surfaced via `TurnUsage.cacheRead` / `TurnUsage.cacheCreation`.
+   *
+   * Default: `true`.
    */
-  tool?: boolean;
+  cache?: boolean;
   /**
-   * Cap on concurrently active skills per run. Default `undefined` (unlimited).
-   * Attempts to activate past the cap throw from `skills_use`.
+   * Soft per-turn cap on total tool-output bytes. When the sum of `outputBytes`
+   * across a turn's tool results exceeds this value, the loop injects a
+   * synthetic user message instructing the model to summarize before calling
+   * more tools, and fires the `budget:exceeded` hook.
+   *
+   * Measured **post-`tool:transform`** so consumer truncation counts toward the
+   * budget. Off by default (undefined / `0` disables the check). A reasonable
+   * starting value for OSS-model integrations is `32768`.
    */
-  maxActive?: number;
-  /** Script timeout for `skills_run_script`, in milliseconds. Default `60000`. */
-  scriptTimeoutMs?: number;
+  toolOutputBudget?: number;
   /**
-   * When `false`, skills with `source: 'project'` are skipped during
-   * resolution with a diagnostic. Default `true` (preserves existing behavior).
-   * Useful for host SDKs handling untrusted repositories.
+   * Deduplicate identical re-reads of the same file in `read_file`. When the
+   * model re-reads a file with the same slice and the bytes haven't changed
+   * since the last read in this session, the tool returns a short stub
+   * instead of re-emitting the full content. Pairs with the read-before-edit
+   * guard in `edit` / `multi_edit`.
+   *
+   * Requires a session (set via `createSession()`); without one, the flag is
+   * a no-op since per-session state has nowhere to live.
+   *
+   * Default: `true`.
    */
-  trustProjectSkills?: boolean;
-}
-//#endregion
-//#region src/skills/activation.d.ts
-/** How a skill was activated. Surfaced in `skills:activate` hook ctx. */
-type ActivationVia = 'model' | 'explicit' | 'resume';
-/** Reason a skill was deactivated. Surfaced in `skills:deactivate` hook ctx. */
-type DeactivationReason = 'run-end' | 'explicit' | 'reset';
-/** A skill currently active in the state machine. */
-interface ActiveSkill {
-  skill: SkillConfig;
-  activatedAt: number;
-  activatedVia: ActivationVia;
-}
-/**
- * Per-agent skill activation state. Public read-surface is the `active()` list
- * and `isActive(name)` predicate; writes go through `activate()` / `deactivate()`.
- */
-interface SkillActivationState {
-  /** List of currently active skills in activation order. Returns a snapshot. */
-  active: () => readonly ActiveSkill[];
-  /** Is the skill with this canonical name currently active? */
-  isActive: (name: string) => boolean;
-  /** Retrieve the `ActiveSkill` record by name, or `undefined`. */
-  get: (name: string) => ActiveSkill | undefined;
+  dedupReads?: boolean;
   /**
-   * Mark a skill as active.
-   * - Returns `'ok'` on a fresh activation (caller should fire `skills:activate`).
-   * - Returns `'already-active'` if the skill was already in the set (idempotent).
-   * - Returns `'cap-reached'` if the `maxActive` cap would be exceeded. State is unchanged.
+   * Taper the thinking budget over the course of a run. Late turns are
+   * usually checkpoint / cleanup work where reasoning rarely pays for
+   * itself; early turns benefit most. Two forms:
+   *
+   * - **Struct** — geometric decay starting after `afterTurn`, multiplying by
+   *   `factor` each subsequent turn, clamped to `floor`. Example
+   *   `{ afterTurn: 5, factor: 0.5, floor: 1024 }` with a base budget of 8192:
+   *   turns 1-5 = 8192, turn 6 = 4096, turn 7 = 2048, turn 8+ = 1024.
+   * - **Function** — `(runTurn, baseBudget) => number`. Arbitrary curves;
+   *   `runTurn` is 1-indexed, run-relative (resumed sessions reset).
+   *
+   * No-op when `thinkingBudget` is unset. Honored by every provider that
+   * respects `thinkingBudget` (anthropic explicit-budget `enabled` path,
+   * adaptive `maxTokensCap`, openai-compat `max_tokens` padding).
+   *
+   * Default: `undefined` (no decay).
    */
-  activate: (skill: SkillConfig, via: ActivationVia) => 'ok' | 'already-active' | 'cap-reached';
-  /**
-   * Mark a skill as inactive. Returns the removed `ActiveSkill` record or `undefined`
-   * if it wasn't active. Callers fire `skills:deactivate` on removal.
-   */
-  deactivate: (name: string) => ActiveSkill | undefined;
-  /** Remove every active skill. Returns the list of removed records. */
-  clear: () => readonly ActiveSkill[];
-}
-interface SkillActivationStateOptions {
-  /**
-   * Cap on concurrent activations. `undefined` (the default) disables the cap.
-   * When set, `activate()` returns `'cap-reached'` once the set is at size `maxActive`.
-   */
-  maxActive?: number;
-}
-declare function createSkillActivationState(options?: SkillActivationStateOptions): SkillActivationState;
-//#endregion
-//#region src/agent.d.ts
-interface AgentHooks {
-  'system:before': (ctx: {
-    system: string;
-  }) => void;
-  'turn:before': (ctx: {
-    turn: number;
-    turnId: string;
-    options: StreamOptions;
-  }) => void;
+  thinkingDecay?: {
+    afterTurn: number;
+    factor: number;
+    floor: number;
+  } | ((runTurn: number, baseBudget: number) => number);
   /**
-   * Fires after each assistant turn (before its tool-result follow-up
-   * dispatches; the loop iterates back to a fresh `turn:before` once the
-   * tool results are produced).
+   * Per-tool soft call budget for this run. Keyed by **canonical** tool name.
+   * On the first call after the run-cumulative dispatched count for that tool
+   * reaches `max`, the framework fires `onExceed`:
    *
-   * `toolCounts.turn` — calls **emitted** by the model in this assistant
-   * turn, keyed by canonical tool name. Reflects what the model asked for,
-   * regardless of downstream gate outcome. Most useful for spotting per-turn
-   * spikes ("the model called todowrite 4 times in one turn").
+   * - `'steer'` (default) — let the call execute, but emit a synthetic user
+   *   message after the turn that nudges the model away from re-calling the
+   *   tool. Reuses the existing post-turn steer pathway used by
+   *   `toolOutputBudget`. Fires `tool-budget:exceeded` with `mode: 'steer'`.
+   * - `'block'` — refuse the call via `tool:gate` `block`. The model sees a
+   *   `Blocked: <reason>` tool result. Fires `tool-budget:exceeded` with
+   *   `mode: 'block'`.
+   * - **Function** — `(ctx) => { mode, message }`. The consumer supplies the
+   *   steering / refusal text and chooses the mode dynamically.
    *
-   * `toolCounts.run` — cumulative running counter of **dispatched** calls
-   * scoped to this `runId`, captured at fire time. Excludes calls that were
-   * `block`ed by `tool:gate` handlers. Includes calls short-circuited via
-   * `tool:gate` `result` substitution (the model still asked, the framework
-   * just answered without the tool running). Resumed sessions start a fresh
-   * run with empty counts.
+   * Counts include both real dispatches and dedup substitutes (Z19 hits).
+   * Excludes calls already blocked by an earlier gate (skill allow-list,
+   * consumer hook). Tool dispatched by spawned subagents has its own per-run
+   * counter — child counts never charge the parent.
    *
-   * Both fields are frozen snapshots; mutate-safe.
+   * For MCP tools, key by the namespaced wire name (`mcp_<server>_<tool>`).
+   *
+   * Atomic in parallel mode: the middleware tracks its own per-tool
+   * approval counter, incremented synchronously at gate-time. A
+   * 4-call parallel batch against `max: 2` will let the first 2 through
+   * and refuse the rest, even though the loop's `runToolCounts` only
+   * propagates between calls (not within a single batch's gate fan-out).
+   *
+   * Default: `undefined` (no budget enforcement).
    */
-  'turn:after': (ctx: {
-    turn: number;
-    turnId: string;
-    usage: TurnUsage;
-    message: SessionTurn;
-    toolCounts: {
-      turn: Readonly<Record<string, number>>;
-      run: Readonly<Record<string, number>>;
-    };
-  }) => void;
-  'stream:text': (ctx: StreamHookContext & {
-    delta: string;
-    text: string;
-  }) => void;
-  'stream:end': (ctx: StreamHookContext & {
-    text: string;
-  }) => void;
-  'stream:thinking': (ctx: StreamHookContext & {
-    delta: string;
-    thinking: string;
-  }) => void;
-  'oauth:refresh': (ctx: OAuthRefreshHookContext) => void;
+  toolBudgets?: Record<string, {
+    max: number;
+    onExceed?: 'steer' | 'block' | ((ctx: {
+      tool: string;
+      count: number;
+      max: number;
+    }) => {
+      mode: 'steer' | 'block';
+      message: string;
+    });
+  }>;
   /**
-   * Fires before validation, `tool:before`, and `execute`. Two ways to
-   * intercept:
-   *
-   * - Set `block = true` (with a `reason`) to refuse the call. The model
-   *   sees a `Blocked: <reason>` tool result; `tool:before` / `tool:after`
-   *   do **not** fire.
-   * - Set `result` to substitute a successful tool_result and skip
-   *   execution. The model sees the substitute as a normal tool_result;
-   *   `tool:before` does not fire, but `tool:after` and `tool:transform`
-   *   do — so byte budgets, telemetry, and post-mutation hooks see the
-   *   substitute. Useful for cache hits, dedup, idempotency guards,
-   *   plan-mode synthetic acks.
+   * Generic per-tool argument deduplication. Keyed by the tool's **canonical**
+   * name (alias-stable). Each entry is a hasher: `(input) => string | undefined`.
    *
-   * If multiple handlers along the chain set both `block` and `result`,
-   * `block` wins — refusal beats substitution, so a policy gate
-   * (skills allow-list, custom security) can always override an upstream
-   * consumer's cache substitute. Mirrors the writable-`result` shape on
-   * `tool:unknown` and `tool:error` so consumers learn one pattern.
+   * **Hasher contract** — three return values, three meanings:
    *
-   * `runToolCounts` — frozen pre-call snapshot of per-tool dispatched
-   * counts in this run. Use it to self-throttle, drive observability, or
-   * implement budget guards. Counts every call that passed gate, including
-   * dedup substitutes (Z19); excludes `block`ed calls.
+   * | Return                  | Meaning                                                                |
+   * |-------------------------|------------------------------------------------------------------------|
+   * | a non-empty string      | Cache key for this call. Equal keys (most-recent-only, this session)   |
+   * |                         | replay the prior recorded result without re-dispatching the tool.      |
+   * | `undefined`             | **Skip dedup for this call.** The tool runs normally; nothing recorded.|
+   * | `''` / non-string       | Treated identically to `undefined` (defensive: no dedup, no error).    |
    *
-   * **Parallel mode** (`toolExecution: 'parallel'`, the default): the
-   * snapshot is taken before any dispatches in the batch, so consumer
-   * hooks reading `runToolCounts` see the pre-batch view. Built-in
-   * budget / dedup middleware uses internal per-call reservation, so
-   * `behavior.toolBudgets` enforces atomically even within a parallel
-   * batch.
-   */
-  'tool:gate': (ctx: ToolHookContext & {
-    block: boolean;
-    reason: string;
-    result?: string | ToolResultContent[];
-    runToolCounts: Readonly<Record<string, number>>;
-  }) => void;
-  'tool:before': (ctx: ToolHookContext & {
-    coercions?: readonly string[];
-    runToolCounts: Readonly<Record<string, number>>;
-  }) => void;
-  'tool:after': (ctx: ToolHookContext & {
-    result: string | ToolResultContent[];
-    outputBytes: number;
-    coercions?: readonly string[];
-    runToolCounts: Readonly<Record<string, number>>;
-  }) => void;
-  /**
-   * Fires when a tool throws during execution. Mutate `result` to substitute a
-   * tool-output payload that gets sent back to the model in place of the
-   * default `Tool error: <msg>` string — useful for OSS-model error rewriting
-   * (collapse stack traces, hide internal paths, prepend recovery hints).
+   * The `undefined` opt-out is the way to say *"this specific call is not
+   * cacheable"* (timestamps in input, randomness baked in, debug flags). It
+   * is **not** the same as `JSON.stringify(input)` — that would dedup against
+   * the verbatim input. Pick one explicitly:
    *
-   * The post-hook value flows through `tool:transform` like a normal output, so
-   * downstream byte-budgeting and image-stripping still apply.
-   */
-  'tool:error': (ctx: ToolHookContext & {
-    error: Error;
-    result?: string | ToolResultContent[];
-  }) => void;
-  'tool:transform': (ctx: ToolHookContext & {
-    result: string | ToolResultContent[];
-    isError: boolean;
-    outputBytes: number;
-    coercions?: readonly string[];
-  }) => void;
-  /**
-   * Fires before the generic "Unknown tool" error when the model invokes a tool
-   * that isn't registered (hallucinated names, dropped MCP servers, dangling
-   * aliases). Mutate `result` to substitute a friendly response or set
-   * `suppressError: true` to skip the companion `tool:error` emission.
+   * ```ts
+   * // Always cache by full input — every identical re-call dedups.
+   * dedupTools: { todowrite: input => JSON.stringify(input) }
    *
-   * Fires for any unknown tool name — including hallucinated MCP-style names
-   * (`mcp_supabase_xxx`); branch on `name.startsWith('mcp_')` to differentiate.
-   */
-  'tool:unknown': (ctx: ToolHookContext & {
-    result?: string | ToolResultContent[];
-    suppressError: boolean;
-  }) => void;
-  /**
-   * Fires when `validateToolArgs` rejects an input that could not be auto-coerced
-   * to satisfy the tool's `inputSchema`. Observational — the tool call still
-   * surfaces a `Validation error: …` string back to the model. Useful for
-   * counting validation failures separately from runtime tool errors.
-   */
-  'validation:reject': (ctx: ToolHookContext & {
-    reason: string;
-    schema: Record<string, unknown>;
-  }) => void;
-  /**
-   * Fires when `validateToolArgs` successfully auto-coerced one or more input
-   * fields to satisfy the tool's `inputSchema`. **Only fires when at least one
-   * coercion happened** — never on perfectly-shaped inputs. Useful for counting
-   * model "wrongness rate" without re-running validation downstream.
+   * // Cache by a normalized subset; non-cacheable shapes opt out.
+   * dedupTools: {
+   *   execute_sql: (input) => {
+   *     const q = typeof input.query === 'string' ? input.query.trim().toLowerCase() : undefined
+   *     if (!q || q.includes('now()') || q.includes('random()')) return undefined
+   *     return q
+   *   },
+   * }
+   * ```
    *
-   * `coercions` lists the field names that were coerced. The values landed in
-   * the input that the tool actually received; consumers wanting before/after
-   * comparison can re-run `validateToolArgs(ctx.input, ctx.schema)`.
-   */
-  'validation:coerce': (ctx: ToolHookContext & {
-    coercions: readonly string[];
-    schema: Record<string, unknown>;
-  }) => void;
-  'context:transform': (ctx: {
-    messages: SessionMessage[];
-  }) => void;
-  /**
-   * Fires per request, after `context:transform` and before the request goes
-   * out. Mutating `ctx.system` updates the system prompt the provider sends
-   * for this turn — useful for runtime-derived sections (e.g. listing files
-   * already read in the session, surfacing live tool budgets, injecting
-   * skill activation reminders).
+   * On a hit, the previously-recorded result is replayed as the tool_result
+   * without dispatching the tool. The substitution flows through `tool:gate`
+   * `result` (Z20), so `tool:after` and `tool:transform` still fire.
    *
-   * Cache breakpoints are applied inside the provider after this hook, so
-   * mutations land in the cache key naturally — repeated turns with the
-   * same derived system text still hit the cache.
+   * Requires a session (`createSession()`); without one, the map is a silent
+   * no-op since per-session state has nowhere to live. Tools with side
+   * effects or non-deterministic outputs (network, time, randomness) MUST
+   * NOT be listed — there is no safety net beyond the consumer's hasher.
    *
-   * `messages` is read-only here; use `context:transform` for message
-   * surgery. `session` is `undefined` when the run is sessionless.
-   */
-  'system:transform': (ctx: {
-    system: string;
-    messages: readonly SessionMessage[];
-    turn: number;
-    turnId: string;
-    session?: Session;
-  }) => void;
-  'steer:inject': (ctx: {
-    message: string;
-  }) => void;
-  'spawn:before': (ctx: SpawnHookContext) => void;
-  'spawn:complete': (ctx: ChildRunStats) => void;
-  'spawn:error': (ctx: SpawnHookContext & {
-    error: Error;
-  }) => void;
-  'child:stream:text': (ctx: StreamHookContext & {
-    delta: string;
-    text: string;
-    childId: string;
-    depth: number;
-  }) => void;
-  'child:stream:thinking': (ctx: StreamHookContext & {
-    delta: string;
-    thinking: string;
-    childId: string;
-    depth: number;
-  }) => void;
-  'child:stream:end': (ctx: StreamHookContext & {
-    text: string;
-    childId: string;
-    depth: number;
-  }) => void;
-  /**
-   * Gate-style child events. Unlike the other `child:*` events, the bubble
-   * passes the **same `ctx` reference** the subagent's loop is awaiting on:
-   * setting `ctx.block` / `ctx.reason` / `ctx.result` on a parent listener
-   * propagates straight back to the child, refusing or substituting the call.
+   * For MCP tools, key by the namespaced wire name (`mcp_<server>_<tool>`).
+   * Parallel mode (`toolExecution: 'parallel'`, the default) sees calls in
+   * the SAME assistant turn race against each other — none can dedup against
+   * a sibling that started in the same batch. Sequential mode honors order
+   * within a turn.
    *
-   * Use these to gate subagent tool calls (native + MCP) from the parent
-   * without registering listeners on every child agent. The parent's own
-   * `tool:gate` / `mcp:tool:gate` listeners are NOT auto-shared with
-   * children — that would also share their budgets and dedup state.
-   */
-  'child:tool:gate': (ctx: ToolHookContext & {
-    block: boolean;
-    reason: string;
-    result?: string | ToolResultContent[];
-    runToolCounts: Readonly<Record<string, number>>;
-    childId: string;
-    depth: number;
-  }) => void;
-  'child:mcp:tool:gate': (ctx: McpToolHookContext & {
-    block: boolean;
-    reason: string;
-    result?: string | ToolResultContent[];
-    childId: string;
-    depth: number;
-  }) => void;
-  'child:tool:before': (ctx: ToolHookContext & {
-    coercions?: readonly string[];
-    runToolCounts: Readonly<Record<string, number>>;
-    childId: string;
-    depth: number;
-  }) => void;
-  'child:tool:after': (ctx: ToolHookContext & {
-    result: string | ToolResultContent[];
-    outputBytes: number;
-    coercions?: readonly string[];
-    runToolCounts: Readonly<Record<string, number>>;
-    childId: string;
-    depth: number;
-  }) => void;
-  'child:tool:error': (ctx: ToolHookContext & {
-    error: Error;
-    childId: string;
-    depth: number;
-  }) => void;
-  'child:turn:after': (ctx: {
-    turn: number;
-    turnId: string;
-    usage: TurnUsage;
-    message: SessionTurn;
-    toolCounts: {
-      turn: Readonly<Record<string, number>>;
-      run: Readonly<Record<string, number>>;
-    };
-    childId: string;
-    depth: number;
-  }) => void;
-  'mcp:connect': (ctx: {
-    name: string;
-    transport: string;
-    tools: string[];
-  }) => void;
-  'mcp:error': (ctx: {
-    name: string;
-    error: Error;
-  }) => void;
-  'mcp:close': (ctx: {
-    name: string;
-  }) => void;
-  /**
-   * Fires at the start of a per-server bootstrap attempt, before any network I/O.
-   * Pairs with `mcp:bootstrap:end` and is always emitted, regardless of outcome.
-   */
-  'mcp:bootstrap:start': (ctx: {
-    name: string;
-    transport: string;
-  }) => void;
-  /**
-   * Fires at the end of a per-server bootstrap attempt. `durationMs` spans from
-   * the matching `mcp:bootstrap:start`. On `ok: false` carries the originating
-   * error so consumers can log / trace without relying on a separate `mcp:error`.
-   */
-  'mcp:bootstrap:end': (ctx: {
-    name: string;
-    transport: string;
-    durationMs: number;
-  } & ({
-    ok: true;
-    toolCount: number;
-  } | {
-    ok: false;
-    error: Error;
-  })) => void;
+   * **Cache policy**: only the most recent `(hash, result)` per tool is
+   * retained. Interleaved patterns (input A, input B, input A) miss on the
+   * second A because B overwrote it. Sufficient for the common spam-the-
+   * same-call loop; consumers needing a richer cache should hook
+   * `tool:gate` directly.
+   *
+   * Default: `undefined` (no per-tool dedup).
+   */
+  dedupTools?: Record<string, (input: Record<string, unknown>) => string | undefined>;
   /**
-   * Fires once per server after `listTools()` and after the config-side filters
-   * (`enabledTools` / `disabledTools` / `toolFilter`) have applied, but BEFORE
-   * tools are registered. Handlers may mutate `ctx.tools` in place — splicing,
-   * reordering, or replacing entries — to further narrow what the model sees.
+   * Require `read_file` before `edit` / `multi_edit` on the same path, and
+   * reject edits when the file has changed on disk since the last read in
+   * this session. Eliminates the silent-corruption failure mode where a
+   * model "remembers" stale content and applies a substring edit against
+   * bytes that have moved.
    *
-   * Composes with config-side filters: config drops tools the host's static
-   * policy excludes; this hook is the runtime escape hatch for per-user, per-
-   * environment, or capability-driven decisions that the config can't express.
+   * Requires a session. Off by default; turn it on for stricter eval-grade
+   * runs where silent edit corruption would invalidate the result.
    *
-   * Items are upstream tool descriptors (NOT yet namespaced as `mcp_<server>_<tool>`).
+   * Default: `false`.
    */
-  'mcp:tools:filter': (ctx: {
-    server: string;
-    transport: 'stdio' | 'sse' | 'streamable-http';
-    tools: Array<{
-      name: string;
-      description?: string | null;
-      inputSchema?: unknown;
-    }>;
-  }) => void;
+  requireReadBeforeEdit?: boolean;
   /**
-   * MCP-side counterpart of `tool:gate`. Same shape: set `block` to refuse,
-   * set `result` to substitute a successful payload and skip the upstream
-   * MCP `callTool`. When both are set across the handler chain, `block` wins.
+   * Client-side context compaction strategy. Use this for non-Anthropic
+   * providers (OSS via cerebras / openai-compat / openrouter) that don't
+   * have a server-side equivalent. Anthropic users should prefer the
+   * server-side `context-management-2025-06-27` beta — see
+   * `AnthropicParams.contextManagement`.
    *
-   * Fires INSIDE the MCP wrapper's `execute`, after the loop's `tool:gate`
-   * already ran. Does **not** carry `runToolCounts` — those are loop-level
-   * and already exposed on `tool:gate` for MCP tools (which are registered
-   * as agent tools under their namespaced name `mcp_<server>_<tool>`). Use
-   * `tool:gate` for budget / dedup logic; reserve `mcp:tool:gate` for
-   * MCP-specific concerns (per-server routing, transport-aware refusals).
+   * - `'off'` (default) — no client-side compaction.
+   * - `'tail'` — when total tool-output bytes in the persisted history
+   *   exceed `compactThreshold`, replace older `tool_result` outputs with a
+   *   short stub, keeping the newest `compactKeepTurns` turns intact. The
+   *   compaction is applied to the wire-level message list only; the
+   *   underlying session turns are not modified.
+   *
+   * Default: `'off'`.
    */
-  'mcp:tool:gate': (ctx: McpToolHookContext & {
-    block: boolean;
-    reason: string;
-    result?: string | ToolResultContent[];
-  }) => void;
-  'mcp:tool:before': (ctx: McpToolHookContext) => void;
-  'mcp:tool:after': (ctx: McpToolHookContext & {
-    result: string | ToolResultContent[];
-    outputBytes: number;
-  }) => void;
-  'mcp:tool:transform': (ctx: McpToolHookContext & {
-    result: string | ToolResultContent[];
-    outputBytes: number;
-  }) => void;
-  'mcp:tool:error': (ctx: McpToolHookContext & {
-    error: Error;
-  }) => void;
-  'skills:resolve': (ctx: {
-    skills: SkillConfig[];
-  }) => void;
-  'skills:catalog': (ctx: {
-    catalog: string;
-    skills: SkillConfig[];
-  }) => void;
-  'skills:activate': (ctx: {
-    skill: SkillConfig;
-    via: ActivationVia;
-  }) => void;
-  'skills:deactivate': (ctx: {
-    skill: SkillConfig;
-    reason: DeactivationReason;
-  }) => void;
-  'usage': (ctx: {
-    turn: number;
-    turnId: string;
-    usage: TurnUsage;
-    totalIn: number;
-    totalOut: number;
-  }) => void;
-  'output': (ctx: {
-    output: Record<string, unknown>;
-    schema: Record<string, unknown>;
-  }) => void;
+  compactStrategy?: 'off' | 'tail';
   /**
-   * Fires when a turn's total tool-output bytes exceed `behavior.toolOutputBudget`.
-   * Measured post-`tool:transform`. Loop injects a synthetic user message after
-   * the tool-results turn instructing the model to summarize.
+   * Soft byte threshold that triggers tail compaction when
+   * `compactStrategy === 'tail'`. Counts the post-`context:transform` bytes
+   * of `tool_result` outputs across all messages. Default: `131_072` (128
+   * KiB). Ignored when compaction is off.
    */
-  'budget:exceeded': (ctx: {
-    turn: number;
-    turnId: string;
-    bytes: number;
-    budget: number;
-  }) => void;
+  compactThreshold?: number;
   /**
-   * Fires when a per-tool budget configured via `behavior.toolBudgets` is
-   * exceeded for a specific tool. `mode` reflects how the framework reacted:
-   * `'steer'` lets the call run and queues a post-turn nudge; `'block'`
-   * refuses the call outright with `Blocked: <message>`.
-   *
-   * `count` is the run-cumulative dispatched count just before this call.
-   * Use `turnId` to correlate with `turn:after` if you need the integer turn
-   * index. Distinct from `budget:exceeded` (byte-level) so consumers can
-   * subscribe specifically; both can fire in the same turn.
+   * Number of trailing turns to leave untouched during tail compaction. The
+   * most-recent `compactKeepTurns` user/assistant messages are not eligible
+   * for elision so the model keeps the freshest tool context. Default: `4`.
    */
-  'tool-budget:exceeded': (ctx: {
-    tool: string;
-    count: number;
-    max: number;
-    turnId: string;
-    mode: 'steer' | 'block';
-  }) => void;
-  'agent:abort': (ctx: object) => void;
+  compactKeepTurns?: number;
   /**
-   * Run finished — fires on all exit paths (completion, maxTurns, abort).
+   * Prefix every line of `read_file` output with its 1-indexed line number
+   * followed by a tab (`<N>\t<content>`) — the compact `cat -n`-style
+   * format Claude Code emits. The `edit` tool strips the prefix from
+   * `old_string` / `new_string` so the model can paste back a numbered
+   * chunk verbatim without breaking the match.
    *
-   * Since 4.0 the `AgentStats` carried here is **cumulative** across the
-   * parent agent loop and every recursively-spawned sub-agent
-   * (`totalIn` / `totalOut` / `cost` / `totalCacheRead` / `totalCacheCreation`).
-   * For parent-loop-only counts use `ctx.turnUsage` (parent-only array);
-   * for tree-wide turn counts use `flattenTurns(ctx).length`.
-   */
-  'agent:done': (ctx: AgentStats) => void;
-  'session:start': (ctx: SessionHookContext & {
-    runId: string;
-    prompt: string;
-  }) => void;
-  'session:end': (ctx: SessionHookContext & {
-    runId: string;
-    status: SessionEndStatus;
-    turnRange: [number, number];
-  }) => void;
-  'session:turns': (ctx: SessionHookContext & {
-    turns: SessionTurn[];
-    count: number;
-  }) => void;
-  'session:meta': (ctx: SessionHookContext & {
-    key: string;
-    value: unknown;
-  }) => void;
-  'session:save': (ctx: SessionHookContext) => void;
-}
-interface AgentOptions {
-  provider: Provider;
-  /** Display name for the agent (used in traces/logs). */
-  name?: string;
-  /** Default system prompt injected when no system is provided at run time. */
-  system?: string;
-  /** Tool definitions available to the agent. Defaults to no tools. */
-  tools?: Record<string, ToolDef>;
-  /**
-   * Map canonical tool names to LLM-facing (aliased) names.
+   * Set `false` to opt out — useful for callers piping `read_file` into
+   * downstream parsers that don't recognize the prefix. Per-call
+   * `read_file({ lineNumbers: false })` overrides this default.
    *
-   * Aliasing is **LLM-boundary-only**: the alias is what the provider's tool spec
-   * carries and what the model calls the tool; the canonical name is what lives in
-   * `session.turns` and what the agent uses to look up the tool implementation.
+   * Default: `true`.
    */
-  toolAliases?: Record<string, string>;
-  /** Agent-level behavior defaults (overridden by run-level behavior) */
-  behavior?: AgentBehavior;
-  /** Execution context: where tools run. Defaults to in-process. */
-  execution?: ExecutionContext;
-  /** MCP servers to connect and expose as tools */
-  mcpServers?: McpServerConfig[];
-  /** Session for identity, turn persistence, and run tracking */
-  session?: Session;
-  /** Skills configuration */
-  skills?: SkillsConfig;
+  readLineNumbers?: boolean;
   /**
-   * Test seam — replaces the default MCP connector with a custom
-   * implementation. Bypasses the `mcpServers` normalization layer entirely
-   * and is **not** part of the supported public API. Subject to change or
-   * removal in any release.
+   * Replace older `read_file` `tool_result` blocks with a short stub when
+   * a successful `edit` / `multi_edit` / `write_file` later in the same
+   * run modified the same path. The replacement is applied to the
+   * wire-level message list only — persisted session turns keep the
+   * original content.
    *
-   * @internal
-   */
-  mcpConnector?: (configs: McpServerConfig[]) => Promise<McpConnection>;
-  /**
-   * Pre-connect MCP servers in the background as soon as `createAgent` returns,
-   * instead of deferring the bootstrap to the first `agent.run()`.
+   * Eliminates the common waste pattern where the model carries the
+   * pre-edit file body forward across many turns "in case it needs it".
+   * Pairs cleanly with `compactStrategy: 'tail'`: stale reads shrink
+   * first, then the byte-threshold compaction fires if anything's left.
    *
-   * Useful when MCP latency is the dominant cost of a cold start: callers that
-   * construct the agent early (e.g. at process init) can hide the bootstrap
-   * behind other setup work. If bootstrap fails, the error is stored and
-   * surfaced on the first `agent.run()` / `agent.warmup()`; the in-flight
-   * promise is `await`ed by both paths so the error is never silently lost.
+   * Detection is conservative — only triggers when the corresponding
+   * tool_result confirms success (`Edited …`, `Created …`, `Updated …`).
+   * Failed edits and `No change needed` write_file calls do NOT
+   * invalidate prior reads.
    *
-   * No-op when `mcpServers` is empty. Default: `false`.
+   * Default: `false`.
    */
-  eager?: boolean;
-}
-interface Agent {
-  hooks: Hookable<AgentHooks>;
-  run: (options: AgentRunOptions) => Promise<AgentStats>;
-  abort: () => void;
-  steer: (message: string) => void;
-  followUp: (message: string) => void;
-  waitForIdle: () => Promise<void>;
+  elideStaleReads?: boolean;
   /**
-   * Clear the agent's in-memory state (turns, queues, skill activations).
-   * Fires `skills:deactivate` with `reason: 'reset'` for each previously active
-   * skill. Awaiting lets host apps observe listener rejections.
+   * Tool disclosure strategy. Controls whether the model sees every tool's
+   * full `inputSchema` in its tool list every turn ("eager") or whether MCP
+   * tools are advertised as a name+description catalog in the system prompt
+   * and only get full schemas after being surfaced via the `tool_search`
+   * native tool ("lazy" / progressive disclosure).
+   *
+   * Native tools (those passed to `createAgent({ tools })`) and skill tools
+   * are always eager — they are core to the agent and cheap. Only MCP tools
+   * are eligible for lazy disclosure.
+   *
+   * When `'lazy'`, the agent:
+   * - Appends a `<searchable_tools>` section to the system prompt listing
+   *   every MCP tool by `name` + `description` only (no `inputSchema`).
+   * - Auto-injects a `tool_search` native tool (opt out via
+   *   {@link AgentBehavior.toolSearch}) the model uses to load schemas on
+   *   demand. Surfaced tools persist for the rest of the run.
+   * - Rebuilds the wire-level tool list each turn, appending newly-unlocked
+   *   tools at the end so the prefix-cache breakpoint advances cleanly.
+   *
+   * Trade-off: every `tool_search` invocation expands the tool list and
+   * invalidates the tool-list cache breakpoint for one turn. With many
+   * MCP servers, the savings on cold turns (fewer schemas in context) are
+   * substantial; with one tiny MCP server, the overhead may not pay back.
+   *
+   * Default: `'eager'`.
    */
-  reset: () => Promise<void>;
+  toolDisclosure?: 'eager' | 'lazy';
   /**
-   * Destroy the execution context and clean up resources.
-   * Idempotent — safe to call from both a `finally` block and a signal handler.
+   * Fine-grained config for the `tool_search` tool auto-injected when
+   * {@link AgentBehavior.toolDisclosure} is `'lazy'`. No-op in eager mode.
+   *
+   * - `tool: false` — opt out of the auto-injection entirely. Use when the
+   *   host wants to ship a custom discovery tool. Note that the catalog
+   *   text drops the call-to-action prose in this case so the model isn't
+   *   pointed at a non-existent tool.
+   * - `limit` — default cap on results returned per `tool_search` call when
+   *   the model omits the parameter. Default: `20`.
+   *
+   * Note on host-defined `tool_search`: a tool the host registers under the
+   * name `tool_search` (or under any alias whose canonical is `tool_search`)
+   * will shadow the auto-injected one — the catalog text will point at the
+   * host's wire name, but driving the unlock flow requires either using
+   * `createToolSearchTool({ catalog, unlocked })` from `tools/tool-search`
+   * (which internally mutates the unlock set) or fully opting out via
+   * `toolSearch.tool: false` and treating discovery as a host-side concern.
+   * A bare host tool that doesn't touch the unlock set will not advance the
+   * lazy disclosure state and the hard gate will keep refusing lazy calls.
+   *
+   * Default: `undefined` (auto-inject with the default limit).
    */
-  destroy: () => Promise<void>;
+  toolSearch?: {
+    tool?: false;
+    limit?: number;
+  };
+}
+/**
+ * One block of a multimodal user prompt.
+ *
+ * `agent.run({ prompt })` accepts either a plain string (treated as a single
+ * text part) or an array of these parts for multimodal inputs.
+ *
+ * `document` parts are routed per provider: PDF-style mime types are sent as
+ * native document blocks when the provider supports them; text documents are
+ * inlined as text with an attachment header. Providers that cannot handle an
+ * image or document throw early.
+ */
+type PromptPart = PromptTextPart | PromptImagePart | PromptDocumentPart;
+interface PromptTextPart {
+  type: 'text';
+  text: string;
+}
+interface PromptImagePart {
+  type: 'image';
+  /** IANA media type (e.g. `image/png`, `image/jpeg`) */
+  mediaType: string;
+  /** Base64-encoded payload */
+  data: string;
+  /** Optional display name */
+  name?: string;
+}
+interface PromptDocumentPart {
+  type: 'document';
+  /** IANA media type (e.g. `application/pdf`, `text/plain`) */
+  mediaType: string;
+  /** Either a base64-encoded payload (`encoding: 'base64'`) or raw text (`encoding: 'text'`) */
+  data: string;
+  encoding: 'base64' | 'text';
+  /** Optional display name used in attachment headers */
+  name?: string;
+}
+/**
+ * A single block of structured tool-result content.
+ *
+ * MCP servers can return a mix of text, image, resource, and audio blocks. Tools
+ * return `string` for the common text-only case or `ToolResultContent[]` when they
+ * need to preserve non-text content (e.g. screenshots from a browser MCP).
+ *
+ * Providers that support native multi-part tool results (Anthropic, OpenAI Codex via
+ * pi-ai) route image blocks into their wire format verbatim; OpenAI-compat providers
+ * route them via a companion-user-message fallback when the underlying model/endpoint
+ * does not accept images inside tool-role messages.
+ */
+type ToolResultContent = ToolResultTextContent | ToolResultImageContent;
+interface ToolResultTextContent {
+  type: 'text';
+  text: string;
+}
+interface ToolResultImageContent {
+  type: 'image';
+  /** IANA media type (e.g. `image/png`, `image/jpeg`) */
+  mediaType: string;
+  /** Base64-encoded payload */
+  data: string;
+}
+/**
+ * Lossy flattener — converts `ToolResultContent[]` (or a plain string) to a single
+ * string. Image blocks are replaced with `[image: <media> — <n> b64 bytes]` markers.
+ *
+ * Use at UI boundaries where a string is required; providers that understand
+ * structured content should route the array through without flattening.
+ */
+declare function toolResultToText(content: string | ToolResultContent[]): string;
+/**
+ * Approximate byte length of a tool output as it goes back to the model.
+ *
+ * - Plain text: UTF-8 byte length.
+ * - Structured content: text blocks contribute their UTF-8 byte length; image
+ *   blocks contribute their **base64 character length**, since that is what
+ *   the model tokenizes (the wire-encoded payload, not the decoded image).
+ *
+ * Used by the agent loop to populate `outputBytes` on `tool:after`,
+ * `tool:transform`, `mcp:tool:after`, and `mcp:tool:transform` hooks so
+ * consumers can size-budget tool output without re-counting bytes themselves.
+ */
+declare function toolOutputByteLength(content: string | ToolResultContent[]): number;
+type SessionContentBlock = {
+  type: 'text';
+  text: string;
+} | {
+  type: 'image';
+  mediaType: string;
+  data: string;
+} | {
+  type: 'tool_call';
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+} | {
+  type: 'tool_result';
+  callId: string;
   /**
-   * Explicitly activate a skill by name. Fires `skills:activate` with
-   * `via: 'explicit'`. Throws if the skill isn't in the resolved catalog or
-   * if the `maxActive` cap is reached. Idempotent — activating an already-active
-   * skill is a no-op.
+   * Tool output — either a plain string (text-only, the common case) or a structured
+   * array of content blocks (text + image for multimodal tools such as screenshots).
    */
-  activateSkill: (name: string) => Promise<void>;
+  output: string | ToolResultContent[];
+  isError?: boolean;
+} | {
+  type: 'thinking';
+  text: string;
+  signature?: string;
   /**
-   * Deactivate a skill by name. Fires `skills:deactivate` with `reason: 'explicit'`.
-   * No-op when the skill wasn't active.
+   * Provider that minted `signature`. Signatures are provider-bound (Anthropic
+   * HMAC vs. OpenAI `encrypted_content`) and are dropped on cross-provider
+   * hops to avoid 400s. Unset means legacy/unknown — forwarded as-is.
    */
-  deactivateSkill: (name: string) => Promise<void>;
+  signatureProducer?: 'anthropic' | 'openai';
+} | {
+  type: 'redacted_thinking';
+  data: string;
+} | {
   /**
-   * Pre-connect MCP servers without running a turn. Idempotent and concurrency-safe:
-   * - No MCP servers configured → resolves immediately.
-   * - Connection already established → resolves immediately.
-   * - Another `warmup()` / `run()` is bootstrapping → awaits the in-flight promise.
+   * Opaque round-trip envelope for reasoning state minted by an OpenAI-compat
+   * gateway (currently OpenRouter). The gateway expects its own
+   * `reasoning_details` array echoed back verbatim on the next turn so the
+   * upstream model can resume an extended-reasoning chain across tool calls.
    *
-   * Use from host code that wants to hide MCP bootstrap latency behind other
-   * startup work (UI init, auth, etc.). Safe to call multiple times and from
-   * multiple callers concurrently.
+   * Stored opaquely because the items are provider-bound (Anthropic HMAC
+   * signatures, OpenAI `encrypted_content`, model-specific summary formats
+   * — all flowing through the gateway's normalized envelope).
    */
-  warmup: () => Promise<void>;
-  readonly isRunning: boolean;
-  readonly turns: SessionTurn[];
-  readonly execution: ExecutionContext;
-  readonly handle: ExecutionHandle | null;
-  readonly session: Session | null;
-  /** Snapshot of currently active skills. */
-  readonly activeSkills: readonly ActiveSkill[];
+  type: 'provider_reasoning';
+  producer: 'openrouter';
+  details: unknown[];
   /**
-   * Frozen view of the underlying `provider.meta`. Read-only to prevent
-   * accidental cross-agent contamination — writes are rejected at runtime
-   * (via `Object.freeze`) and at compile time (via `Readonly`). To override
-   * model / capability defaults, construct a new provider.
+   * Model id that produced the details. Reasoning is bound to a specific
+   * upstream route — a model switch on the next turn invalidates the
+   * embedded signatures, so the sender drops the block on mismatch.
    */
-  readonly meta: Readonly<Record<string, unknown>>;
+  model?: string;
+};
+interface SessionMessage {
+  role: 'user' | 'assistant';
+  content: SessionContentBlock[];
+}
+interface SessionTurn {
+  /** UUID — generated by the store if it provides generateTurnId, else crypto.randomUUID() */
+  id: string;
+  /** Run that produced this turn (e.g. 'run_1') */
+  runId?: string;
+  role: 'user' | 'assistant' | 'system';
+  content: SessionContentBlock[];
+  /** Token usage — only present on assistant turns */
+  usage?: TurnUsage;
+  /** Unix timestamp (Date.now()) when the turn was created */
+  createdAt: number;
 }
-declare function createAgent({
-  provider,
-  name: agentName,
-  system: agentSystem,
-  tools: agentTools,
-  toolAliases,
-  behavior: agentBehavior,
-  execution,
-  mcpServers,
-  session,
-  skills: agentSkills,
-  mcpConnector,
-  eager
-}: AgentOptions): Agent;
-//#endregion
-//#region src/tools/types.d.ts
 /**
- * Runtime context passed to every tool execution.
- * Provides access to the agent's provider, abort signal, execution environment, and hooks.
- *
- * The preset-y fields (`name`, `system`, `tools`, `toolAliases`, `mcpServers`, `skills`,
- * `behavior`) mirror the agent's own options so child-spawning tools can inherit them.
+ * Per-run hook registrations. Each entry can be a single handler or an array of handlers.
+ * Keys are `AgentHooks` event names (loose-typed here to avoid a circular import; agent.ts
+ * narrows it to the strongly-typed map).
  */
-interface ToolContext {
-  /** The LLM provider for this agent run */
-  provider: Provider;
-  /** Abort signal — tools should check this for early termination */
-  signal: AbortSignal;
-  /** The execution context (shell, filesystem, etc.) */
-  execution: ExecutionContext;
-  /** The active execution handle for the current agent run */
-  handle: ExecutionHandle;
-  /** Agent hooks for emitting events (e.g. spawn:complete) */
-  hooks: Hookable<AgentHooks>;
-  /** Agent display name (preset or user-supplied) */
-  name?: string;
-  /** Agent default system prompt */
-  system?: string;
-  /** Source tool map the agent was created with (pre-MCP-merge, pre-skills-injection) */
-  tools: Record<string, ToolDef>;
+type RunHookMap = Record<string, ((ctx: any) => unknown) | ((ctx: any) => unknown)[]>;
+interface AgentRunOptions {
+  model?: string;
   /**
-   * Map canonical tool names to LLM-facing (aliased) names.
-   *
-   * Aliasing is **LLM-boundary-only**:
-   * - The alias is what the provider's tool spec carries, what the model calls it, and
-   *   what appears in `ToolHookContext.displayName` / `McpToolHookContext.displayName`.
-   * - The canonical name is what lives in `session.turns`, `ToolHookContext.name`, and
-   *   what the agent uses to look up the tool implementation. Alias changes never
-   *   desync persisted history.
+   * User prompt. Optional when resuming a session with existing turns.
+   *
+   * Accepts either a plain string (single text part) or an array of `PromptPart`s for
+   * multimodal inputs (text, images, documents). See {@link PromptPart}.
    */
-  toolAliases?: Record<string, string>;
-  /** MCP servers configured on the agent (for child inheritance) */
-  mcpServers?: McpServerConfig[];
-  /** Skills configuration (for child inheritance) */
-  skills?: SkillsConfig;
-  /** Behavior defaults (for child inheritance) */
+  prompt?: string | PromptPart[];
+  system?: string;
+  thinking?: ThinkingLevel;
+  /** Abort signal — when triggered, the agent stops after the current turn */
+  signal?: AbortSignal;
+  /** Behavior overrides for this run (overrides agent defaults) */
   behavior?: AgentBehavior;
-  /** Turn ID that requested this tool call */
-  turnId: string;
-  /** Tool call ID from the model */
-  callId: string;
+  /** Tool overrides for this run. Pass {} for no tools. Omit to use agent tools. */
+  tools?: Record<string, ToolDef>;
   /**
-   * The run id this tool call is part of. Populated by the agent loop when
-   * invoking tools. Optional on the type so host code constructing contexts
-   * by hand (tests, direct tool invocations) doesn't have to synthesize one.
+   * Per-run hook registrations. Each hook is attached before the run starts and
+   * detached in a finally block so handlers never leak across runs.
    *
-   * Spawn-style tools rely on this to tag child runs with `parentRunId` so
-   * the subagent tree can be reconstructed from a persisted session.
+   * Accepts either a single handler or an array (all handlers register).
    */
-  runId?: string;
+  hooks?: RunHookMap;
   /**
-   * The agent's session, when one was provided to `createAgent`. Tools that
-   * want to persist their own state (or, in the case of `spawn`, inherit the
-   * parent's session for child persistence) can read from here.
+   * Parent run id. Populated automatically by the `spawn` tool when the child
+   * shares the parent's session; recorded on the resulting `SessionRun` so the
+   * parent↔child run tree can be reconstructed from a persisted session.
    */
-  session?: Session;
+  parentRunId?: string;
   /**
-   * Subagent depth for the agent owning this tool call. 0 = top-level,
-   * 1 = first-level child, … Used by spawn to enforce a `maxDepth` cap.
-   * Undefined is treated as 0 by spawn.
+   * Zero-based subagent depth. 0 = top-level `agent.run()`, 1 = first-level
+   * child spawned by a parent agent, and so on. Used by the spawn tool to
+   * enforce `maxDepth` and to stamp `child:*` forwarded hook payloads.
    */
   depth?: number;
 }
-interface ToolDef {
-  spec: ToolSpec;
-  /**
-   * Execute the tool and return its output.
-   *
-   * Return a plain string for text-only tools (the common case). Return a
-   * `ToolResultContent[]` when the tool produces non-text content (images, mixed
-   * text+image) that the provider can route through natively (Anthropic
-   * `tool_result.content` arrays, OpenAI Codex pi-ai) or through the
-   * companion-user-message fallback (OpenAI Chat Completions).
-   */
-  execute: (input: Record<string, unknown>, ctx: ToolContext) => Promise<string | ToolResultContent[]>;
-}
-type ToolMap = Map<string, ToolDef>;
-//#endregion
-//#region src/types.d.ts
 /**
- * Thinking / extended-reasoning configuration.
+ * Reason the provider gave for stopping the turn.
  *
- * - `'off'` — no thinking.
- * - `'minimal' | 'low' | 'medium' | 'high'` — explicit token budget. Maps to
- *   provider-specific reasoning controls (Anthropic `thinking.type='enabled'`
- *   with a budget; OpenAI `reasoning_effort`).
- * - `'adaptive'` — let the model decide per-turn whether and how much to think.
- *   Anthropic-only (`thinking.type='adaptive'`). Other providers fall back to
- *   no reasoning when this value is supplied.
+ * - `'stop'` — natural turn end (`end_turn` / `stop_sequence`).
+ * - `'tool-calls'` — model emitted tool_use blocks.
+ * - `'length'` — `max_tokens` reached, or (Anthropic 4.6+) the response bumped
+ *   against the model's context window mid-stream
+ *   (`model_context_window_exceeded`). The partial response is preserved; the
+ *   loop emits this reason so consumers can prune/retry.
+ * - `'content-filter'` — model refused.
+ * - `'pause'` — Anthropic `pause_turn`: a server-side mid-turn pause for very
+ *   long thinking. The loop continues with a synthetic "Please continue."
+ *   user message rather than terminating; consumers see the pause via this
+ *   finish reason on the prior assistant turn.
+ * - `'error'` — provider classified the turn as failed.
+ * - `'other'` — unknown / unmapped.
  */
-type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'adaptive';
-interface McpServerConfig {
-  /** Display name (used for tool namespacing) */
-  name: string;
-  /** Transport type */
-  transport: 'stdio' | 'sse' | 'streamable-http';
-  /** For stdio: command to run */
-  command?: string;
-  /** For stdio: command arguments */
-  args?: string[];
+type TurnFinishReason = 'stop' | 'tool-calls' | 'length' | 'content-filter' | 'pause' | 'error' | 'other';
+interface TurnUsage {
+  input: number;
+  output: number;
+  /** Tokens written to cache (Anthropic) */
+  cacheCreation?: number;
+  /** Tokens read from cache (Anthropic) */
+  cacheRead?: number;
+  /** Thinking/reasoning tokens used */
+  thinking?: number;
+  /** Cost in USD as reported by the provider (OpenRouter) */
+  cost?: number;
   /**
-   * For stdio: environment variables to pass to the server process.
-   *
-   * Merged on top of the MCP SDK's default inherited environment — a safety
-   * whitelist (`PATH`, `HOME`, `LANG`, `SHELL`, `USER` on POSIX; `APPDATA`,
-   * `PATH`, ... on Win32). Setting this to `{}` no longer strips `PATH` from
-   * the child process. Set {@link McpServerConfig.strictEnv} to `true` to
-   * pass `env` verbatim with no inherited defaults.
+   * Why the model stopped this turn. Providers normalize native stop reasons to this union.
+   * Absent when the provider did not surface a reason (e.g. mock turns).
    */
-  env?: Record<string, string>;
+  finishReason?: TurnFinishReason;
   /**
-   * When true, {@link McpServerConfig.env} is passed verbatim to the spawned
-   * process — the MCP SDK's default inherited environment (`PATH`, `HOME`, ...)
-   * is NOT merged in. Most consumers should leave this off; the default merge
-   * prevents `spawn ENOENT` when a stdio server declares an `env` without
-   * restating `PATH`.
+   * The model ID the provider ultimately used. May differ from the requested model when the
+   * provider remaps aliases. Absent for providers that do not echo a model ID.
    */
-  strictEnv?: boolean;
-  /** For sse/streamable-http: server URL */
-  url?: string;
-  /** Optional headers for HTTP transports */
-  headers?: Record<string, string>;
+  modelId?: string;
+}
+interface AgentStats {
   /**
-   * Timeout in milliseconds for MCP server bootstrap (connect + tool discovery).
-   *
-   * Zidane connects MCP servers lazily on the first `run()`. Without a
-   * bootstrap timeout, a slow or hung server can delay the first provider call
-   * for an arbitrarily long time even when that MCP server is never used.
-   *
-   * Default: `10000`.
+   * Cumulative input tokens across the parent agent loop **and** every
+   * recursively-spawned sub-agent. Use this for billing / token-ledger
+   * consumption.
    */
-  bootstrapTimeout?: number;
-  /** Timeout in milliseconds for MCP tool calls (default: 30000) */
-  toolTimeout?: number;
+  totalIn: number;
+  /** Cumulative output tokens. Same semantics as {@link AgentStats.totalIn}. */
+  totalOut: number;
   /**
-   * Allow-list of tool names to expose. Names match the upstream tool name
-   * (NOT the namespaced `mcp_{server}_{tool}` form). Tools not in the list are
-   * dropped before registration — the model never sees them in its catalog and
-   * the wire cost of advertising them is avoided.
-   *
-   * Mutually exclusive with {@link McpServerConfig.disabledTools} — passing both
-   * throws at bootstrap time.
-   *
-   * Composes with {@link McpServerConfig.toolFilter}: allow-list applies first,
-   * then the predicate. Composes with the `mcp:tools:filter` hook: config-side
-   * filters apply first, then the hook can further narrow the list.
+   * Cumulative cache-read tokens across the parent agent loop and every
+   * recursively-spawned sub-agent. Surfaced at the top level (rather than
+   * only per-`TurnUsage`) because Anthropic prices cache reads at a separate
+   * line-item rate from regular input — billing-correct cost computation
+   * needs this number directly. Always `0` for providers that don't report
+   * cache usage.
    */
-  enabledTools?: string[];
+  totalCacheRead: number;
   /**
-   * Deny-list of tool names. Tools matching are dropped before registration.
-   * Same matching semantics as {@link McpServerConfig.enabledTools}.
+   * Cumulative cache-creation tokens across the parent agent loop and every
+   * recursively-spawned sub-agent. Same rationale as
+   * {@link AgentStats.totalCacheRead} — separate Anthropic billing rate.
+   * Always `0` for providers that don't report cache usage.
    */
-  disabledTools?: string[];
+  totalCacheCreation: number;
   /**
-   * Custom predicate run on each upstream tool. Return `true` to keep, `false`
-   * to drop. Receives the raw `listTools()` payload — useful for filtering by
-   * description, schema shape, or other metadata that an allow/deny list can't
-   * express.
+   * Number of parent agent-loop turns. Children's turn counts live under
+   * `children[].stats.turns` and are NOT folded in here — a single "turns"
+   * number for the whole tree would conflate two different measures
+   * (parent-loop iterations vs. tree-wide tool-call rounds).
    *
-   * Runs after the allow/deny filter but before the `mcp:tools:filter` hook.
+   * Tree-wide turn count: `flattenTurns(stats).length`.
    */
-  toolFilter?: (tool: {
-    name: string;
-    description?: string | null;
-    inputSchema?: unknown;
-  }) => boolean;
+  turns: number;
   /**
-   * Per-server override for {@link AgentBehavior.toolDisclosure}. When set,
-   * this server's tools follow this disclosure mode regardless of the
-   * agent-wide default. Useful when one big MCP server (200+ tools) should
-   * stay lazy while smaller servers stay eager.
-   *
-   * Default: inherits from `behavior.toolDisclosure`.
+   * Wall-clock duration of the top-level `agent.run()` call, in milliseconds.
+   * Children run during parent tool calls so this naturally subsumes child
+   * wall time — sequential children inflate it, parallel children compress
+   * into the parent's window.
    */
-  disclosure?: 'eager' | 'lazy';
-}
-type ToolExecutionMode = 'sequential' | 'parallel';
-interface AgentBehavior {
-  /** Tool execution mode (default: 'sequential') */
-  toolExecution?: ToolExecutionMode;
+  elapsed: number;
   /**
-   * Max agent loop iterations.
-   *
-   * Default: unlimited (Infinity). The loop runs until the model signals
-   * completion (no tool calls / `end_turn`), the abort signal fires, or this
-   * cap is hit. Set a finite value as a safety net for runaway loops.
+   * Per-turn usage breakdown for the **parent loop only**. Children's per-turn
+   * usages live under `children[].stats.turnUsage`. Use {@link flattenTurns}
+   * to walk the full tree.
    */
-  maxTurns?: number;
-  /** Max tokens per LLM response (default: 16384) */
-  maxTokens?: number;
-  /** Thinking token budget — overrides the level-based default when set */
-  thinkingBudget?: number;
-  /** JSON Schema for structured output enforcement */
-  schema?: Record<string, unknown>;
+  turnUsage?: TurnUsage[];
   /**
-   * Enable provider prompt caching. When on (default), the provider marks the
-   * system prompt, tools, and the last stable message with cache breakpoints so
-   * the shared prefix is served from cache across turns.
-   *
-   * - Anthropic: `cache_control: { type: 'ephemeral' }` on the last `system`
-   *   content part, the last tool, and the last message content part.
-   * - OpenAI-compatible / OpenRouter: same shape — honored by Anthropic-backed
-   *   OpenRouter routes and by Gemini; ignored (no-op) by providers that cache
-   *   automatically (OpenAI, DeepSeek, Grok, Groq, Moonshot).
-   *
-   * Usage is surfaced via `TurnUsage.cacheRead` / `TurnUsage.cacheCreation`.
+   * Cumulative cost in USD — parent loop plus every recursively-spawned
+   * sub-agent. Sums per-turn `TurnUsage.cost` reported by the provider.
+   * Absent when neither parent nor any descendant reported a non-zero cost.
+   */
+  cost?: number;
+  /** Stats from child agents spawned during this run, in completion order. Recursive. */
+  children?: ChildRunStats[];
+  /** Structured output from schema enforcement (only present when behavior.schema is set) */
+  output?: Record<string, unknown>;
+  /**
+   * Milliseconds from the start of `agent.run()` to the first observable signal from the
+   * provider (first `stream:text`, `stream:thinking`, or `tool:before` event).
    *
-   * Default: `true`.
+   * Absent when the run produced no observable signals (e.g. aborted before any stream event).
+   */
+  timeTillFirstTokenMs?: number;
+}
+interface ChildRunStats {
+  id: string;
+  task: string;
+  /**
+   * The child agent's full {@link AgentStats}. Cumulative for that child's
+   * own subtree (child loop + its grandchildren). Do **not** sum
+   * `ctx.stats.totalIn` across `spawn:complete` events to derive top-level
+   * totals — `agent.run()`'s return value is the canonical cumulative root.
    */
-  cache?: boolean;
+  stats: AgentStats;
   /**
-   * Soft per-turn cap on total tool-output bytes. When the sum of `outputBytes`
-   * across a turn's tool results exceeds this value, the loop injects a
-   * synthetic user message instructing the model to summarize before calling
-   * more tools, and fires the `budget:exceeded` hook.
-   *
-   * Measured **post-`tool:transform`** so consumer truncation counts toward the
-   * budget. Off by default (undefined / `0` disables the check). A reasonable
-   * starting value for OSS-model integrations is `32768`.
+   * Subagent depth when this child ran. 1 = direct child of the top-level
+   * agent, 2 = grandchild, etc. Useful for telemetry that wants to group
+   * runs by depth.
    */
-  toolOutputBudget?: number;
+  depth?: number;
   /**
-   * Deduplicate identical re-reads of the same file in `read_file`. When the
-   * model re-reads a file with the same slice and the bytes haven't changed
-   * since the last read in this session, the tool returns a short stub
-   * instead of re-emitting the full content. Pairs with the read-before-edit
-   * guard in `edit` / `multi_edit`.
-   *
-   * Requires a session (set via `createSession()`); without one, the flag is
-   * a no-op since per-session state has nowhere to live.
-   *
-   * Default: `true`.
+   * Terminal state of the child run. `'completed'` is the default. Exposed so
+   * a parent reading `stats.children` can distinguish aborted/timed-out
+   * children without re-parsing the returned string.
    */
-  dedupReads?: boolean;
+  status?: 'completed' | 'aborted' | 'timeout' | 'error';
   /**
-   * Taper the thinking budget over the course of a run. Late turns are
-   * usually checkpoint / cleanup work where reasoning rarely pays for
-   * itself; early turns benefit most. Two forms:
-   *
-   * - **Struct** — geometric decay starting after `afterTurn`, multiplying by
-   *   `factor` each subsequent turn, clamped to `floor`. Example
-   *   `{ afterTurn: 5, factor: 0.5, floor: 1024 }` with a base budget of 8192:
-   *   turns 1-5 = 8192, turn 6 = 4096, turn 7 = 2048, turn 8+ = 1024.
-   * - **Function** — `(runTurn, baseBudget) => number`. Arbitrary curves;
-   *   `runTurn` is 1-indexed, run-relative (resumed sessions reset).
-   *
-   * No-op when `thinkingBudget` is unset. Honored by every provider that
-   * respects `thinkingBudget` (anthropic explicit-budget `enabled` path,
-   * adaptive `maxTokensCap`, openai-compat `max_tokens` padding).
-   *
-   * Default: `undefined` (no decay).
+   * Final structured output when the child was run with `behavior.schema`.
+   * Mirrors `AgentStats.output` but is surfaced here so the parent can read
+   * it without peeking at the nested `stats` bag.
    */
-  thinkingDecay?: {
-    afterTurn: number;
-    factor: number;
-    floor: number;
-  } | ((runTurn: number, baseBudget: number) => number);
+  output?: Record<string, unknown>;
+}
+/**
+ * Base context for tool execution hooks.
+ *
+ * `name` is the canonical tool identity — the spec name registered on the agent (or the
+ * `mcp_{server}_{tool}` name for MCP tools). Hooks should policy-match against `name`.
+ *
+ * `displayName` is the outward-facing name — the alias surfaced to the LLM when
+ * `AgentOptions.toolAliases` maps the canonical name; otherwise equal to `name`.
+ * UI/telemetry adapters should emit `displayName`.
+ *
+ * Canonical vs. alias matters on session resume: `session.turns` persists canonical
+ * names only, so renaming an alias cannot desync history.
+ */
+interface ToolHookContext {
+  turnId: string;
+  callId: string;
+  /** Canonical tool name (spec name). Stable across alias-map changes. */
+  name: string;
+  /** Aliased (wire) name — equal to `name` when no alias is defined. */
+  displayName: string;
+  input: Record<string, unknown>;
+}
+/**
+ * Base context for MCP tool hooks.
+ *
+ * `tool` is the native tool name on the MCP server. `server` is the configured server
+ * name. The canonical zidane-namespaced identity is `mcp_{server}_{tool}`.
+ *
+ * `displayName` equals the canonical namespaced name unless the agent has aliased
+ * this MCP tool via `AgentOptions.toolAliases`; in which case `displayName` is the
+ * alias that the LLM sees.
+ */
+interface McpToolHookContext {
+  turnId: string;
+  callId: string;
+  server: string;
+  tool: string;
+  /** Aliased wire name for this MCP tool, or the canonical `mcp_{server}_{tool}` name. */
+  displayName: string;
+  input: Record<string, unknown>;
+}
+/** Base context for session hooks */
+interface SessionHookContext {
+  sessionId: string;
+}
+/** Base context for spawn hooks */
+interface SpawnHookContext {
+  id: string;
+  task: string;
   /**
-   * Per-tool soft call budget for this run. Keyed by **canonical** tool name.
-   * On the first call after the run-cumulative dispatched count for that tool
-   * reaches `max`, the framework fires `onExceed`:
-   *
-   * - `'steer'` (default) — let the call execute, but emit a synthetic user
-   *   message after the turn that nudges the model away from re-calling the
-   *   tool. Reuses the existing post-turn steer pathway used by
-   *   `toolOutputBudget`. Fires `tool-budget:exceeded` with `mode: 'steer'`.
-   * - `'block'` — refuse the call via `tool:gate` `block`. The model sees a
-   *   `Blocked: <reason>` tool result. Fires `tool-budget:exceeded` with
-   *   `mode: 'block'`.
-   * - **Function** — `(ctx) => { mode, message }`. The consumer supplies the
-   *   steering / refusal text and chooses the mode dynamically.
-   *
-   * Counts include both real dispatches and dedup substitutes (Z19 hits).
-   * Excludes calls already blocked by an earlier gate (skill allow-list,
-   * consumer hook). Tool dispatched by spawned subagents has its own per-run
-   * counter — child counts never charge the parent.
-   *
-   * For MCP tools, key by the namespaced wire name (`mcp_<server>_<tool>`).
-   *
-   * Atomic in parallel mode: the middleware tracks its own per-tool
-   * approval counter, incremented synchronously at gate-time. A
-   * 4-call parallel batch against `max: 2` will let the first 2 through
-   * and refuse the rest, even though the loop's `runToolCounts` only
-   * propagates between calls (not within a single batch's gate fan-out).
-   *
-   * Default: `undefined` (no budget enforcement).
+   * Subagent depth for the spawn. 1 = direct child of the top-level agent.
+   * Present on spawn:before/complete/error. Absent for grandchild spawns that
+   * bubble through `child:*` events (which carry their own `depth`).
    */
-  toolBudgets?: Record<string, {
-    max: number;
-    onExceed?: 'steer' | 'block' | ((ctx: {
-      tool: string;
-      count: number;
-      max: number;
-    }) => {
-      mode: 'steer' | 'block';
-      message: string;
-    });
-  }>;
+  depth?: number;
+}
+/** Context for stream hooks */
+interface StreamHookContext {
+  turnId: string;
+}
+/** Context for OAuth refresh hooks */
+interface OAuthRefreshHookContext {
+  provider: string;
+  providerId: string;
+  source: 'params' | 'file';
+  previousCredentials: Record<string, unknown> & {
+    access: string;
+    refresh: string;
+    expires: number;
+  };
+  credentials: Record<string, unknown> & {
+    access: string;
+    refresh: string;
+    expires: number;
+  };
+}
+type SessionEndStatus = 'completed' | 'aborted' | 'error';
+//#endregion
+//#region src/providers/anthropic.d.ts
+/**
+ * Server-side context-management config — the body of `context_management` on
+ * the Messages API. Typed loosely (Record-of-unknown) so we don't pin a specific
+ * SDK schema version: the v0.90 SDK does not yet type this field, but the wire
+ * format is stable behind the `context-management-2025-06-27` beta.
+ *
+ * See: https://docs.anthropic.com/en/docs/build-with-claude/context-management
+ */
+interface AnthropicContextManagement {
+  edits?: Array<Record<string, unknown>>;
+  [key: string]: unknown;
+}
+interface AnthropicParams {
+  apiKey?: string;
+  access?: string;
+  refresh?: string;
+  expires?: number;
+  defaultModel?: string;
   /**
-   * Generic per-tool argument deduplication. Keyed by the tool's **canonical**
-   * name (alias-stable). Each entry is a hasher: `(input) => string | undefined`.
-   *
-   * **Hasher contract** — three return values, three meanings:
-   *
-   * | Return                  | Meaning                                                                |
-   * |-------------------------|------------------------------------------------------------------------|
-   * | a non-empty string      | Cache key for this call. Equal keys (most-recent-only, this session)   |
-   * |                         | replay the prior recorded result without re-dispatching the tool.      |
-   * | `undefined`             | **Skip dedup for this call.** The tool runs normally; nothing recorded.|
-   * | `''` / non-string       | Treated identically to `undefined` (defensive: no dedup, no error).    |
-   *
-   * The `undefined` opt-out is the way to say *"this specific call is not
-   * cacheable"* (timestamps in input, randomness baked in, debug flags). It
-   * is **not** the same as `JSON.stringify(input)` — that would dedup against
-   * the verbatim input. Pick one explicitly:
-   *
-   * ```ts
-   * // Always cache by full input — every identical re-call dedups.
-   * dedupTools: { todowrite: input => JSON.stringify(input) }
-   *
-   * // Cache by a normalized subset; non-cacheable shapes opt out.
-   * dedupTools: {
-   *   execute_sql: (input) => {
-   *     const q = typeof input.query === 'string' ? input.query.trim().toLowerCase() : undefined
-   *     if (!q || q.includes('now()') || q.includes('random()')) return undefined
-   *     return q
-   *   },
-   * }
-   * ```
-   *
-   * On a hit, the previously-recorded result is replayed as the tool_result
-   * without dispatching the tool. The substitution flows through `tool:gate`
-   * `result` (Z20), so `tool:after` and `tool:transform` still fire.
-   *
-   * Requires a session (`createSession()`); without one, the map is a silent
-   * no-op since per-session state has nowhere to live. Tools with side
-   * effects or non-deterministic outputs (network, time, randomness) MUST
-   * NOT be listed — there is no safety net beyond the consumer's hasher.
-   *
-   * For MCP tools, key by the namespaced wire name (`mcp_<server>_<tool>`).
-   * Parallel mode (`toolExecution: 'parallel'`, the default) sees calls in
-   * the SAME assistant turn race against each other — none can dedup against
-   * a sibling that started in the same batch. Sequential mode honors order
-   * within a turn.
-   *
-   * **Cache policy**: only the most recent `(hash, result)` per tool is
-   * retained. Interleaved patterns (input A, input B, input A) miss on the
-   * second A because B overwrote it. Sufficient for the common spam-the-
-   * same-call loop; consumers needing a richer cache should hook
-   * `tool:gate` directly.
-   *
-   * Default: `undefined` (no per-tool dedup).
+   * Optional override for the Anthropic SDK base URL. Honored end-to-end — headers and
+   * routing pass through to the forwarded host. Useful for proxies (e.g. corporate
+   * gateways, internal router).
    */
-  dedupTools?: Record<string, (input: Record<string, unknown>) => string | undefined>;
+  baseURL?: string;
   /**
-   * Require `read_file` before `edit` / `multi_edit` on the same path, and
-   * reject edits when the file has changed on disk since the last read in
-   * this session. Eliminates the silent-corruption failure mode where a
-   * model "remembers" stale content and applies a substring edit against
-   * bytes that have moved.
+   * Additional `anthropic-beta` flags to opt into. Merged with the OAuth-path
+   * defaults (`claude-code-20250219`, `oauth-2025-04-20`); duplicates are
+   * de-duped. Examples:
    *
-   * Requires a session. Off by default; turn it on for stricter eval-grade
-   * runs where silent edit corruption would invalidate the result.
+   * - `'context-management-2025-06-27'` — server-side context compaction
+   *   (token-accurate; pair with {@link AnthropicParams.contextManagement}).
+   * - `'token-efficient-tools-2026-03-28'` — terser tool_use wire format.
+   * - `'interleaved-thinking-2025-05-14'` — think between tool calls within
+   *   one turn.
+   * - `'redact-thinking-2026-02-12'` — replace large thinking blocks with
+   *   stubs server-side.
+   * - `'prompt-caching-scope-2026-01-05'` — extended prompt-cache scope.
    *
-   * Default: `false`.
+   * Honored on both the OAuth and API-key paths.
    */
-  requireReadBeforeEdit?: boolean;
+  extraBetas?: readonly string[];
   /**
-   * Client-side context compaction strategy. Use this for non-Anthropic
-   * providers (OSS via cerebras / openai-compat / openrouter) that don't
-   * have a server-side equivalent. Anthropic users should prefer the
-   * server-side `context-management-2025-06-27` beta — see
-   * `AnthropicParams.contextManagement`.
+   * Server-side context-management directive. Sent on the request body as
+   * `context_management`. Requires the `context-management-2025-06-27` beta —
+   * add it to {@link AnthropicParams.extraBetas}.
    *
-   * - `'off'` (default) — no client-side compaction.
-   * - `'tail'` — when total tool-output bytes in the persisted history
-   *   exceed `compactThreshold`, replace older `tool_result` outputs with a
-   *   short stub, keeping the newest `compactKeepTurns` turns intact. The
-   *   compaction is applied to the wire-level message list only; the
-   *   underlying session turns are not modified.
+   * Typed loosely so future Anthropic schema additions land without an SDK
+   * bump. A typical compaction edit:
    *
-   * Default: `'off'`.
+   * ```ts
+   * contextManagement: {
+   *   edits: [{
+   *     type: 'clear_tool_uses_20250919',
+   *     trigger: { type: 'input_tokens', value: 180_000 },
+   *     clear_at_least: { type: 'input_tokens', value: 140_000 },
+   *     clear_tool_inputs: ['Read', 'Bash', 'Grep'],
+   *   }],
+   * }
+   * ```
    */
-  compactStrategy?: 'off' | 'tail';
+  contextManagement?: AnthropicContextManagement;
   /**
-   * Soft byte threshold that triggers tail compaction when
-   * `compactStrategy === 'tail'`. Counts the post-`context:transform` bytes
-   * of `tool_result` outputs across all messages. Default: `131_072` (128
-   * KiB). Ignored when compaction is off.
+   * Generic pass-through for fields on the Messages API request body that the
+   * SDK does not yet type. Spread into the request before the typed fields,
+   * so explicit options ({@link AnthropicParams.contextManagement} and the
+   * built-in fields like `model` / `tools` / `messages`) win on collision.
+   *
+   * Forward-compat escape hatch for new Anthropic betas — when a future flag
+   * ships before zidane has a dedicated typed knob, set it here without
+   * waiting on a release. Most fields will still need the matching beta in
+   * {@link AnthropicParams.extraBetas}.
    */
-  compactThreshold?: number;
+  extraBodyParams?: Record<string, unknown>;
+}
+declare function anthropic(anthropicParams?: AnthropicParams): Provider;
+//#endregion
+//#region src/providers/cerebras.d.ts
+interface CerebrasParams {
+  apiKey?: string;
+  defaultModel?: string;
   /**
-   * Number of trailing turns to leave untouched during tail compaction. The
-   * most-recent `compactKeepTurns` user/assistant messages are not eligible
-   * for elision so the model keeps the freshest tool context. Default: `4`.
+   * Provider capability flags. Cerebras currently serves text-only OSS models
+   * (GLM, Llama-family, Qwen-family) — default: `{ vision: false, imageInToolResult: false }`.
+   * Override when routing to a vision-capable deployment.
    */
-  compactKeepTurns?: number;
+  capabilities?: ProviderCapabilities;
+}
+/**
+ * Cerebras provider.
+ *
+ * Thin wrapper around {@link openaiCompat} with Cerebras-specific defaults
+ * (base URL, default model).
+ */
+declare function cerebras(params?: CerebrasParams): Provider;
+//#endregion
+//#region src/providers/openai.d.ts
+interface OpenAIParams {
+  /** OpenAI Codex OAuth access token. Falls back to OPENAI_CODEX_API_KEY and .credentials.json. */
+  apiKey?: string;
+  /** Alias for apiKey, matching the OAuth credential field. */
+  access?: string;
+  refresh?: string;
+  expires?: number;
+  accountId?: string;
+  defaultModel?: string;
+  transport?: 'sse' | 'websocket' | 'auto';
+}
+declare function openai(params?: OpenAIParams): Provider;
+//#endregion
+//#region src/providers/openai-compat.d.ts
+/**
+ * HTTP error thrown when an OpenAI-compatible endpoint returns a non-OK response.
+ *
+ * The body is best-effort JSON-parsed; `error.message` / `error.code` / `error.type`
+ * are extracted for clean downstream classification.
+ */
+declare class OpenAICompatHttpError extends Error {
+  readonly status: number;
+  readonly providerCode?: string;
+  readonly bodyText: string;
+  constructor(status: number, bodyText: string);
+}
+/**
+ * Classify an OpenAI-compatible error into `ClassifiedError`.
+ *
+ * Recognizes:
+ * - `AbortError` (from fetch) → `aborted`.
+ * - `OpenAICompatHttpError` with a context-exceeded code or message → `context_exceeded`.
+ * - Any other `OpenAICompatHttpError` → `provider_error`.
+ *
+ * Returns `null` for unrecognized error shapes (the loop falls back to `AgentProviderError`).
+ */
+declare function classifyOpenAICompatError(err: unknown): ClassifiedError | null;
+/**
+ * Map an OpenAI-compatible `finish_reason` string to the zidane `TurnFinishReason` union.
+ */
+declare function mapOAIFinishReason(reason: string | null | undefined): TurnFinishReason | undefined;
+/**
+ * Auth header config. `scheme` is prepended to the api key with a space, e.g.
+ * `{ name: 'Authorization', scheme: 'Bearer' }` → `Authorization: Bearer <key>`.
+ * Omit `scheme` for raw header values (e.g. `{ name: 'X-Api-Key' }` → `X-Api-Key: <key>`).
+ *
+ * Real-world examples:
+ * - Default OpenAI / OpenRouter / Cerebras: `{ name: 'Authorization', scheme: 'Bearer' }`.
+ * - Baseten: `{ name: 'Authorization', scheme: 'Api-Key' }`.
+ * - Some gateways: `{ name: 'X-Api-Key' }`.
+ */
+interface OpenAICompatAuthHeader {
+  name: string;
+  scheme?: string;
+}
+interface OpenAICompatParams {
+  /** Bearer-style API key. */
+  apiKey: string;
+  /** Base URL — `/chat/completions` is appended. */
+  baseURL: string;
+  /** Default model id when `run({ model })` is omitted. */
+  defaultModel?: string;
+  /** Provider name exposed as `Provider.name`. Defaults to `'openai-compat'`. */
+  name?: string;
+  /** Auth header shape. Defaults to `{ name: 'Authorization', scheme: 'Bearer' }`. */
+  authHeader?: OpenAICompatAuthHeader;
+  /** Extra headers sent with every request (e.g. referer, user-agent). */
+  extraHeaders?: Record<string, string>;
   /**
-   * Prefix every line of `read_file` output with its 1-indexed line number
-   * followed by a tab (`<N>\t<content>`) — the compact `cat -n`-style
-   * format Claude Code emits. The `edit` tool strips the prefix from
-   * `old_string` / `new_string` so the model can paste back a numbered
-   * chunk verbatim without breaking the match.
-   *
-   * Set `false` to opt out — useful for callers piping `read_file` into
-   * downstream parsers that don't recognize the prefix. Per-call
-   * `read_file({ lineNumbers: false })` overrides this default.
+   * Provider-level capability flags. Routed into the message shaper and the
+   * agent loop so images in tool results + user messages are handled correctly
+   * for the underlying model.
    *
-   * Default: `true`.
+   * Defaults when omitted: `vision: false`, `imageInToolResult: false` — a
+   * conservative assumption matching most OSS text-only OpenAI-compat
+   * endpoints. Override when routing to a known vision-capable endpoint
+   * (e.g. OpenRouter vision models, Baseten image-capable deployments).
    */
-  readLineNumbers?: boolean;
+  capabilities?: ProviderCapabilities;
   /**
-   * Replace older `read_file` `tool_result` blocks with a short stub when
-   * a successful `edit` / `multi_edit` / `write_file` later in the same
-   * run modified the same path. The replacement is applied to the
-   * wire-level message list only — persisted session turns keep the
-   * original content.
-   *
-   * Eliminates the common waste pattern where the model carries the
-   * pre-edit file body forward across many turns "in case it needs it".
-   * Pairs cleanly with `compactStrategy: 'tail'`: stale reads shrink
-   * first, then the byte-threshold compaction fires if anything's left.
+   * Whether this endpoint honors `cache_control: { type: 'ephemeral' }` markers
+   * on message content parts and tool definitions.
    *
-   * Detection is conservative — only triggers when the corresponding
-   * tool_result confirms success (`Edited …`, `Created …`, `Updated …`).
-   * Failed edits and `No change needed` write_file calls do NOT
-   * invalidate prior reads.
+   * - `true`  — inject markers when the caller asks for caching. OpenRouter routes
+   *             to Anthropic/Gemini forward the markers; routes to OpenAI/DeepSeek/
+   *             Grok/Groq/Moonshot ignore them (those backends cache automatically).
+   * - `false` — never inject markers. Safe default for endpoints that strictly
+   *             validate the request schema (OpenAI direct, most OSS inference
+   *             servers) and would reject unknown fields.
    *
-   * Default: `false`.
+   * Default: `false`. The `openrouter` wrapper sets this to `true`.
    */
-  elideStaleReads?: boolean;
+  cacheBreakpoints?: boolean;
   /**
-   * Tool disclosure strategy. Controls whether the model sees every tool's
-   * full `inputSchema` in its tool list every turn ("eager") or whether MCP
-   * tools are advertised as a name+description catalog in the system prompt
-   * and only get full schemas after being surfaced via the `tool_search`
-   * native tool ("lazy" / progressive disclosure).
-   *
-   * Native tools (those passed to `createAgent({ tools })`) and skill tools
-   * are always eager — they are core to the agent and cheap. Only MCP tools
-   * are eligible for lazy disclosure.
-   *
-   * When `'lazy'`, the agent:
-   * - Appends a `<searchable_tools>` section to the system prompt listing
-   *   every MCP tool by `name` + `description` only (no `inputSchema`).
-   * - Auto-injects a `tool_search` native tool (opt out via
-   *   {@link AgentBehavior.toolSearch}) the model uses to load schemas on
-   *   demand. Surfaced tools persist for the rest of the run.
-   * - Rebuilds the wire-level tool list each turn, appending newly-unlocked
-   *   tools at the end so the prefix-cache breakpoint advances cleanly.
+   * Whether this endpoint speaks OpenRouter's normalized reasoning envelope —
+   * `reasoning: { effort | max_tokens | exclude }` on requests and structured
+   * `reasoning_details[]` on assistant messages, round-tripped to preserve
+   * extended-reasoning state across turns.
    *
-   * Trade-off: every `tool_search` invocation expands the tool list and
-   * invalidates the tool-list cache breakpoint for one turn. With many
-   * MCP servers, the savings on cold turns (fewer schemas in context) are
-   * substantial; with one tiny MCP server, the overhead may not pay back.
+   * - `true`  — map zidane's `behavior.thinking` / `behavior.thinkingBudget` to
+   *             the request's `reasoning` field, capture `reasoning_details`
+   *             from streaming responses into `provider_reasoning` blocks, and
+   *             echo them back on subsequent assistant messages.
+   * - `false` — never set the field; drop any stored `provider_reasoning`
+   *             blocks before sending. Safe default for hosts that strict-
+   *             validate the request schema.
    *
-   * Default: `'eager'`.
+   * Default: `false`. The `openrouter` wrapper sets this to `true`.
    */
-  toolDisclosure?: 'eager' | 'lazy';
-  /**
-   * Fine-grained config for the `tool_search` tool auto-injected when
-   * {@link AgentBehavior.toolDisclosure} is `'lazy'`. No-op in eager mode.
-   *
-   * - `tool: false` — opt out of the auto-injection entirely. Use when the
-   *   host wants to ship a custom discovery tool. Note that the catalog
-   *   text drops the call-to-action prose in this case so the model isn't
-   *   pointed at a non-existent tool.
-   * - `limit` — default cap on results returned per `tool_search` call when
-   *   the model omits the parameter. Default: `20`.
-   *
-   * Note on host-defined `tool_search`: a tool the host registers under the
-   * name `tool_search` (or under any alias whose canonical is `tool_search`)
-   * will shadow the auto-injected one — the catalog text will point at the
-   * host's wire name, but driving the unlock flow requires either using
-   * `createToolSearchTool({ catalog, unlocked })` from `tools/tool-search`
-   * (which internally mutates the unlock set) or fully opting out via
-   * `toolSearch.tool: false` and treating discovery as a host-side concern.
-   * A bare host tool that doesn't touch the unlock set will not advance the
-   * lazy disclosure state and the hard gate will keep refusing lazy calls.
+  supportsReasoning?: boolean;
+  /**
+   * Generic pass-through for fields on the Chat Completions request body that
+   * zidane does not yet type. Spread into the request before the typed core
+   * (model / messages / tools / max_tokens / stream / tool_choice), so
+   * explicit options always win on collision.
    *
-   * Default: `undefined` (auto-inject with the default limit).
+   * Forward-compat escape hatch for endpoints that ship one-off fields ahead
+   * of zidane (e.g. OpenAI `reasoning_effort`, OpenRouter `provider` routing,
+   * vendor-specific `safety_level` knobs).
    */
-  toolSearch?: {
-    tool?: false;
-    limit?: number;
-  };
+  extraBodyParams?: Record<string, unknown>;
 }
 /**
- * One block of a multimodal user prompt.
+ * Factory for any OpenAI-compatible HTTP endpoint.
  *
- * `agent.run({ prompt })` accepts either a plain string (treated as a single
- * text part) or an array of these parts for multimodal inputs.
+ * Speaks the standard `POST /chat/completions` + `stream: true` + SSE dialect.
+ * Thin wrappers (`openrouter`, `cerebras`) call this with pinned defaults.
  *
- * `document` parts are routed per provider: PDF-style mime types are sent as
- * native document blocks when the provider supports them; text documents are
- * inlined as text with an attachment header. Providers that cannot handle an
- * image or document throw early.
+ * @example Baseten (non-standard auth scheme)
+ * ```ts
+ * openaiCompat({
+ *   name: 'baseten',
+ *   apiKey: process.env.BASETEN_API_KEY!,
+ *   baseURL: process.env.BASETEN_PROXY_URL!,
+ *   authHeader: { name: 'Authorization', scheme: 'Api-Key' },
+ * })
+ * ```
  */
-type PromptPart = PromptTextPart | PromptImagePart | PromptDocumentPart;
-interface PromptTextPart {
-  type: 'text';
-  text: string;
+declare function openaiCompat(params: OpenAICompatParams): Provider;
+//#endregion
+//#region src/providers/openrouter.d.ts
+interface OpenRouterParams {
+  apiKey?: string;
+  defaultModel?: string;
+  /**
+   * Provider capability flags. OpenRouter itself is a router — whether vision or
+   * native image-in-tool-result are supported depends on the downstream model.
+   * Default: `{ vision: true, imageInToolResult: false }` — matches the default
+   * `anthropic/claude-sonnet-4-6` model (vision-capable via companion user-message
+   * fallback since OpenRouter exposes Claude over the Chat Completions dialect).
+   *
+   * Override when routing to a known-text-only model (e.g. `meta-llama/llama-3-8b-instruct`).
+   */
+  capabilities?: ProviderCapabilities;
 }
-interface PromptImagePart {
-  type: 'image';
-  /** IANA media type (e.g. `image/png`, `image/jpeg`) */
-  mediaType: string;
-  /** Base64-encoded payload */
-  data: string;
-  /** Optional display name */
-  name?: string;
+/**
+ * OpenRouter provider.
+ *
+ * Thin wrapper around {@link openaiCompat} with OpenRouter-specific defaults
+ * (base URL, default model) and required attribution headers.
+ */
+declare function openrouter(params?: OpenRouterParams): Provider;
+//#endregion
+//#region src/providers/index.d.ts
+interface ToolSpec {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
 }
-interface PromptDocumentPart {
-  type: 'document';
-  /** IANA media type (e.g. `application/pdf`, `text/plain`) */
-  mediaType: string;
-  /** Either a base64-encoded payload (`encoding: 'base64'`) or raw text (`encoding: 'text'`) */
-  data: string;
-  encoding: 'base64' | 'text';
-  /** Optional display name used in attachment headers */
-  name?: string;
+interface ToolCall {
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+interface ToolResult {
+  id: string;
+  /**
+   * Tool output — plain string for text-only tools (the common case) or a structured
+   * array of content blocks for tools that return images or mixed content (e.g. an
+   * MCP browser server returning a screenshot).
+   *
+   * Use `toolResultToText(content)` when a downstream consumer only handles strings.
+   */
+  content: string | ToolResultContent[];
 }
 /**
- * A single block of structured tool-result content.
- *
- * MCP servers can return a mix of text, image, resource, and audio blocks. Tools
- * return `string` for the common text-only case or `ToolResultContent[]` when they
- * need to preserve non-text content (e.g. screenshots from a browser MCP).
+ * Provider-level capability flags used by the agent loop to route tool results
+ * and user messages appropriately.
  *
- * Providers that support native multi-part tool results (Anthropic, OpenAI Codex via
- * pi-ai) route image blocks into their wire format verbatim; OpenAI-compat providers
- * route them via a companion-user-message fallback when the underlying model/endpoint
- * does not accept images inside tool-role messages.
+ * When a flag is `undefined` (omitted), the loop applies the conservative
+ * text-only default — images are stripped and replaced with a text marker so
+ * non-vision models do not confabulate about content they cannot see.
  */
-type ToolResultContent = ToolResultTextContent | ToolResultImageContent;
-interface ToolResultTextContent {
-  type: 'text';
+interface ProviderCapabilities {
+  /**
+   * Model accepts image input anywhere (user messages and tool results).
+   *
+   * When `false`, the loop replaces image blocks with
+   * `"[image omitted — model does not support vision]"` before they reach the provider.
+   * Gives the model an honest marker instead of letting JSON-stringified base64 slip
+   * through and get confabulated over.
+   */
+  vision?: boolean;
+  /**
+   * Provider wire format embeds images inside tool-role messages natively
+   * (Anthropic `tool_result.content` arrays, OpenAI Codex pi-ai `toolResult` blocks).
+   *
+   * When `false`, a vision-capable provider still gets images — but via a
+   * companion `user` message emitted immediately after the flattened
+   * `tool`/`tool_result` marker. This is the Claude Desktop / Cline pattern
+   * and works on any OpenAI Chat Completions endpoint that accepts image
+   * URLs in user messages.
+   */
+  imageInToolResult?: boolean;
+}
+interface StreamCallbacks {
+  onText: (delta: string) => void;
+  onThinking?: (delta: string) => void;
+  onOAuthRefresh?: (ctx: OAuthRefreshHookContext) => void | Promise<void>;
+}
+interface TurnResult {
+  /** Full assistant turn as a SessionMessage */
+  assistantMessage: SessionMessage;
+  /** Text content blocks concatenated */
   text: string;
+  /** Tool calls requested by the model */
+  toolCalls: ToolCall[];
+  /** Whether the model wants to stop */
+  done: boolean;
+  usage: TurnUsage;
 }
-interface ToolResultImageContent {
-  type: 'image';
-  /** IANA media type (e.g. `image/png`, `image/jpeg`) */
-  mediaType: string;
-  /** Base64-encoded payload */
-  data: string;
+interface StreamOptions {
+  model: string;
+  system: string;
+  tools: unknown[];
+  messages: SessionMessage[];
+  maxTokens: number;
+  /** Thinking/reasoning level (optional, default: off) */
+  thinking?: ThinkingLevel;
+  /** Exact thinking token budget — overrides the level-based default when set */
+  thinkingBudget?: number;
+  /** Force tool selection behavior */
+  toolChoice?: {
+    type: 'auto' | 'required' | 'tool';
+    name?: string;
+  };
+  /**
+   * Enable prompt caching on this call. When `true`, providers that support it
+   * insert `cache_control` breakpoints on the system prompt, last tool, and
+   * last stable message so the shared prefix is cached across turns.
+   *
+   * Default: `false` (providers opt callers in — the agent loop passes `true`).
+   */
+  cache?: boolean;
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+}
+interface Provider {
+  readonly name: string;
+  readonly meta: {
+    defaultModel: string; /** Provider-level capability flags. See {@link ProviderCapabilities}. */
+    capabilities?: ProviderCapabilities;
+  } & Record<string, unknown>;
+  /** Format tool specs for this provider */
+  formatTools: (tools: ToolSpec[]) => unknown[];
+  /** Create a text-only user message. Multimodal content goes through `promptMessage`. */
+  userMessage: (content: string) => SessionMessage;
+  /** Create an assistant message (for priming) */
+  assistantMessage: (content: string) => SessionMessage;
+  /** Create a tool results message to send back */
+  toolResultsMessage: (results: ToolResult[]) => SessionMessage;
+  /** Stream a turn, calling onText for each text delta */
+  stream: (options: StreamOptions, callbacks: StreamCallbacks) => Promise<TurnResult>;
+  /**
+   * Build a user `SessionMessage` from multimodal prompt parts.
+   *
+   * Providers that cannot handle a particular part type (e.g. document) should throw.
+   * The agent loop always canonicalizes the run-level prompt into parts before calling
+   * this method; providers may fall back to `userMessage` for the text-only path if
+   * they do not implement this.
+   */
+  promptMessage?: (parts: PromptPart[]) => SessionMessage;
+  /**
+   * Classify a native provider error for downstream typed-error wrapping.
+   *
+   * Return `null` when the error is not recognized — the loop will wrap it in
+   * `AgentProviderError` with the provider's name. Return a `ClassifiedError` to
+   * route it to one of the typed error classes.
+   */
+  classifyError?: (err: unknown) => ClassifiedError | null;
 }
+//#endregion
+//#region src/session/file-map.d.ts
 /**
- * Lossy flattener — converts `ToolResultContent[]` (or a plain string) to a single
- * string. Image blocks are replaced with `[image: <media> — <n> b64 bytes]` markers.
- *
- * Use at UI boundaries where a string is required; providers that understand
- * structured content should route the array through without flattening.
+ * Host-provided file-map adapter. Three methods exchanging `Record<string, string>`
+ * payloads — the whole persistence surface the wrapper needs.
  */
-declare function toolResultToText(content: string | ToolResultContent[]): string;
+interface FileMapAdapter {
+  /** Load the current file map. Returns an empty `files` record when nothing is persisted. */
+  get: () => Promise<{
+    files: Record<string, string>;
+  }>;
+  /** Replace the persisted file map. Full-rewrite semantics. */
+  save: (files: Record<string, string>) => Promise<void>;
+  /** Delete all persisted state. */
+  delete: () => Promise<void>;
+}
+interface FileMapStoreOptions {
+  /** Filename for the JSONL turns log. Default: `turns.jsonl`. */
+  turnsFile?: string;
+  /** Filename for the metadata JSON. Default: `meta.json`. */
+  metaFile?: string;
+}
 /**
- * Approximate byte length of a tool output as it goes back to the model.
- *
- * - Plain text: UTF-8 byte length.
- * - Structured content: text blocks contribute their UTF-8 byte length; image
- *   blocks contribute their **base64 character length**, since that is what
- *   the model tokenizes (the wire-encoded payload, not the decoded image).
+ * Create a single-session `SessionStore` backed by a file-map adapter.
  *
- * Used by the agent loop to populate `outputBytes` on `tool:after`,
- * `tool:transform`, `mcp:tool:after`, and `mcp:tool:transform` hooks so
- * consumers can size-budget tool output without re-counting bytes themselves.
+ * @example
+ * ```ts
+ * const session = await createSession({
+ *   store: createFileMapStore(hostSessionStore),
+ * })
+ * ```
  */
-declare function toolOutputByteLength(content: string | ToolResultContent[]): number;
-type SessionContentBlock = {
-  type: 'text';
-  text: string;
-} | {
-  type: 'image';
-  mediaType: string;
-  data: string;
-} | {
-  type: 'tool_call';
+declare function createFileMapStore(adapter: FileMapAdapter, options?: FileMapStoreOptions): SessionStore;
+//#endregion
+//#region src/session/memory.d.ts
+declare function createMemoryStore(): SessionStore;
+//#endregion
+//#region src/session/messages.d.ts
+declare function fromAnthropic(msg: {
+  role: string;
+  content: unknown;
+}): SessionMessage;
+declare function fromOpenAI(msg: {
+  role: string;
+  content: unknown;
+}): SessionMessage;
+declare function toAnthropic(msg: SessionMessage): {
+  role: string;
+  content: unknown;
+};
+declare function toOpenAI(msg: SessionMessage): {
+  role: string;
+  content: unknown;
+};
+declare function autoDetectAndConvert(msg: {
+  role: string;
+  content: unknown;
+}): SessionMessage;
+//#endregion
+//#region src/session/remote.d.ts
+interface RemoteStoreOptions {
+  /** Base URL of the session API */
+  url: string;
+  /** Optional headers (e.g. for authentication) */
+  headers?: Record<string, string>;
+}
+declare function createRemoteStore(options: RemoteStoreOptions): SessionStore;
+//#endregion
+//#region src/session/index.d.ts
+interface SessionRun {
   id: string;
-  name: string;
-  input: Record<string, unknown>;
-} | {
-  type: 'tool_result';
-  callId: string;
+  startedAt: number;
+  endedAt?: number;
+  prompt: string;
+  status: 'running' | 'completed' | 'aborted' | 'error';
+  turns?: number;
+  tokensIn?: number;
+  tokensOut?: number;
+  error?: string;
+  /** Per-turn usage breakdown */
+  turnUsage?: TurnUsage[];
+  /** Total usage across all turns */
+  totalUsage?: TurnUsage;
+  /** Estimated cost in USD */
+  cost?: number;
   /**
-   * Tool output — either a plain string (text-only, the common case) or a structured
-   * array of content blocks (text + image for multimodal tools such as screenshots).
+   * The run that spawned this one, when the agent is a subagent sharing its
+   * parent's session. Undefined on top-level `agent.run()`. Consumers can walk
+   * `runs` by `parentRunId` to reconstruct the subagent tree.
    */
-  output: string | ToolResultContent[];
-  isError?: boolean;
-} | {
-  type: 'thinking';
-  text: string;
-  signature?: string;
+  parentRunId?: string;
   /**
-   * Provider that minted `signature`. Signatures are provider-bound (Anthropic
-   * HMAC vs. OpenAI `encrypted_content`) and are dropped on cross-provider
-   * hops to avoid 400s. Unset means legacy/unknown — forwarded as-is.
+   * Zero-based subagent depth. 0 = top-level run, 1 = direct child, …
+   * Recorded here so hosts can query/filter by level without walking the tree.
    */
-  signatureProducer?: 'anthropic' | 'openai';
-} | {
-  type: 'redacted_thinking';
-  data: string;
-} | {
+  depth?: number;
+}
+interface SessionData {
+  id: string;
+  agentId?: string;
   /**
-   * Opaque round-trip envelope for reasoning state minted by an OpenAI-compat
-   * gateway (currently OpenRouter). The gateway expects its own
-   * `reasoning_details` array echoed back verbatim on the next turn so the
-   * upstream model can resume an extended-reasoning chain across tool calls.
+   * Absolute path of the project this session belongs to — typically
+   * the git root resolved from `cwd` at creation time, falling back to
+   * `cwd` itself when not in a git repo. Set ONCE on creation and never
+   * mutated thereafter (the session "belongs" to that project forever).
    *
-   * Stored opaquely because the items are provider-bound (Anthropic HMAC
-   * signatures, OpenAI `encrypted_content`, model-specific summary formats
-   * — all flowing through the gateway's normalized envelope).
+   * Used by the TUI's sessions list to filter rows by current project,
+   * so the user only sees conversations relevant to where they are
+   * working — without needing one `.{prefix}/` directory per project.
+   *
+   * `undefined` on pre-tagging legacy sessions; the chat layer treats
+   * those as "untagged" and hides them unless `Settings.showAllProjects`
+   * is on.
    */
-  type: 'provider_reasoning';
-  producer: 'openrouter';
-  details: unknown[];
+  projectRoot?: string;
+  turns: SessionTurn[];
+  runs: SessionRun[];
+  status: 'idle' | 'running' | 'completed' | 'error';
+  metadata: Record<string, unknown>;
+  createdAt: number;
+  updatedAt: number;
+}
+interface SessionStore {
+  /** Optional: generate a session ID server-side (e.g. Supabase UUID). */
+  generateSessionId?: () => string | Promise<string>;
+  /** Optional: generate a turn ID server-side. */
+  generateTurnId?: () => string | Promise<string>;
+  /** Load a session by ID. Returns null if not found. */
+  load: (sessionId: string) => Promise<SessionData | null>;
+  /** Save a session (create or update, full document). */
+  save: (session: SessionData) => Promise<void>;
+  /** Delete a session. */
+  delete: (sessionId: string) => Promise<void>;
   /**
-   * Model id that produced the details. Reasoning is bound to a specific
-   * upstream route — a model switch on the next turn invalidates the
-   * embedded signatures, so the sender drops the block on mismatch.
+   * List session IDs, optionally filtered. `projectRoot` restricts to
+   * sessions whose `SessionData.projectRoot` matches exactly — untagged
+   * (legacy) sessions are NOT returned under that filter; pass `null`
+   * explicitly to ask for untagged ones, or omit the field to ignore
+   * the axis entirely. `agentId` filters by recorded agent; the two
+   * conditions AND together when both are set.
    */
-  model?: string;
-};
-interface SessionMessage {
-  role: 'user' | 'assistant';
-  content: SessionContentBlock[];
-}
-interface SessionTurn {
-  /** UUID — generated by the store if it provides generateTurnId, else crypto.randomUUID() */
-  id: string;
-  /** Run that produced this turn (e.g. 'run_1') */
-  runId?: string;
-  role: 'user' | 'assistant' | 'system';
-  content: SessionContentBlock[];
-  /** Token usage — only present on assistant turns */
-  usage?: TurnUsage;
-  /** Unix timestamp (Date.now()) when the turn was created */
-  createdAt: number;
+  list: (filter?: {
+    agentId?: string;
+    limit?: number;
+    projectRoot?: string | null;
+  }) => Promise<string[]>;
+  /** Append new turns to a session (incremental, avoids full re-save). */
+  appendTurns: (sessionId: string, turns: SessionTurn[]) => Promise<void>;
+  /** Return a slice of turns for a session. */
+  getTurns: (sessionId: string, from?: number, limit?: number) => Promise<SessionTurn[]>;
+  /** Persist an updated run record (called after completeRun / abortRun / errorRun). */
+  updateRun: (sessionId: string, run: SessionRun) => Promise<void>;
+  /** Update the top-level status of a session. */
+  updateStatus: (sessionId: string, status: SessionData['status']) => Promise<void>;
 }
-/**
- * Per-run hook registrations. Each entry can be a single handler or an array of handlers.
- * Keys are `AgentHooks` event names (loose-typed here to avoid a circular import; agent.ts
- * narrows it to the strongly-typed map).
- */
-type RunHookMap = Record<string, ((ctx: any) => unknown) | ((ctx: any) => unknown)[]>;
-interface AgentRunOptions {
-  model?: string;
+interface Session {
+  /** Session ID */
+  readonly id: string;
+  /** Agent ID (optional label) */
+  readonly agentId?: string;
   /**
-   * User prompt. Optional when resuming a session with existing turns.
-   *
-   * Accepts either a plain string (single text part) or an array of `PromptPart`s for
-   * multimodal inputs (text, images, documents). See {@link PromptPart}.
+   * Project this session was created under — see {@link SessionData.projectRoot}.
+   * Set once on creation; surfaces here for read-only inspection.
    */
-  prompt?: string | PromptPart[];
-  system?: string;
-  thinking?: ThinkingLevel;
-  /** Abort signal — when triggered, the agent stops after the current turn */
-  signal?: AbortSignal;
-  /** Behavior overrides for this run (overrides agent defaults) */
-  behavior?: AgentBehavior;
-  /** Tool overrides for this run. Pass {} for no tools. Omit to use agent tools. */
-  tools?: Record<string, ToolDef>;
+  readonly projectRoot?: string;
+  /** Current turn history */
+  readonly turns: SessionTurn[];
   /**
-   * Per-run hook registrations. Each hook is attached before the run starts and
-   * detached in a finally block so handlers never leak across runs.
+   * True when this session has no turns yet.
    *
-   * Accepts either a single handler or an array (all handlers register).
+   * Use this as a first-prompt signal when setting up a run — e.g. writing initial
+   * configuration only on fresh sessions. Equivalent to `turns.length === 0`.
    */
-  hooks?: RunHookMap;
+  readonly isEmpty: boolean;
+  /** Top-level session status */
+  readonly status: SessionData['status'];
+  /** All runs in this session */
+  readonly runs: SessionRun[];
+  /** Arbitrary metadata */
+  readonly metadata: Record<string, unknown>;
   /**
-   * Parent run id. Populated automatically by the `spawn` tool when the child
-   * shares the parent's session; recorded on the resulting `SessionRun` so the
-   * parent↔child run tree can be reconstructed from a persisted session.
+   * Start tracking a new run. `extras.parentRunId` + `extras.depth` are
+   * populated by the spawn tool when a child agent shares its parent's
+   * session; regular top-level `agent.run()` calls omit them.
    */
-  parentRunId?: string;
+  startRun: (runId: string, prompt?: string, extras?: {
+    parentRunId?: string;
+    depth?: number;
+  }) => void;
+  /** Mark a run as completed */
+  completeRun: (runId: string, stats: {
+    turns: number;
+    tokensIn: number;
+    tokensOut: number;
+    turnUsage?: TurnUsage[];
+    cost?: number;
+  }) => void;
+  /** Mark a run as aborted */
+  /**
+   * Optional `stats` lets the agent backfill the run's token totals when
+   * the abort happened *after* the loop accumulated meaningful usage —
+   * common when the user presses esc mid-streaming. Without it, the run
+   * record reads `0 in / 0 out` on reload regardless of how much was
+   * spent before the abort. Same shape as `completeRun`'s stats so the
+   * persisted `totalUsage` aggregate stays consistent across paths.
+   */
+  abortRun: (runId: string, stats?: {
+    turns: number;
+    tokensIn: number;
+    tokensOut: number;
+    turnUsage?: TurnUsage[];
+    cost?: number;
+  }) => void;
+  /** Mark a run as errored */
+  /** Optional `stats` — same rationale as `abortRun.stats`. */
+  errorRun: (runId: string, error: string, stats?: {
+    turns: number;
+    tokensIn: number;
+    tokensOut: number;
+    turnUsage?: TurnUsage[];
+    cost?: number;
+  }) => void;
+  /** Append turns to in-memory history AND persist via store.appendTurns (if store present) */
+  appendTurns: (turns: SessionTurn[]) => Promise<void>;
+  /** Replace all turns in-memory (does not persist — use save() for that) */
+  setTurns: (turns: SessionTurn[]) => void;
+  /**
+   * Replace all runs in-memory (does not persist — use save() for that).
+   * Mirrors {@link setTurns} for the fork / restore case: callers that
+   * bootstrap a session from an externally-derived snapshot (e.g.
+   * `onForkTurn` copying parent runs into a child session) need this so
+   * the cloned runs land in `data.runs` before the first `save()`.
+   * Production agent runs continue to mutate runs via `startRun` /
+   * `completeRun` / `updateRun`; this is the bulk-replace escape hatch.
+   */
+  setRuns: (runs: SessionRun[]) => void;
+  /** Update the session status in memory AND via store.updateStatus (if store present) */
+  updateStatus: (status: SessionData['status']) => Promise<void>;
+  /** Persist an updated run record via store.updateRun (if store present) */
+  updateRun: (run: SessionRun) => Promise<void>;
+  /** Generate a turn ID using store.generateTurnId if available, else crypto.randomUUID() */
+  generateTurnId: () => string | Promise<string>;
+  /** Set metadata key */
+  setMeta: (key: string, value: unknown) => void;
+  /** Persist the full session document to the store */
+  save: () => Promise<void>;
+  /** Serialize to SessionData */
+  toJSON: () => SessionData;
+}
+interface CreateSessionOptions {
+  /** Session ID. If omitted and store provides generateSessionId, that is used. */
+  id?: string;
+  /** Agent ID label */
+  agentId?: string;
   /**
-   * Zero-based subagent depth. 0 = top-level `agent.run()`, 1 = first-level
-   * child spawned by a parent agent, and so on. Used by the spawn tool to
-   * enforce `maxDepth` and to stamp `child:*` forwarded hook payloads.
+   * Project tag — see {@link SessionData.projectRoot}. Stamped once on
+   * creation; ignored when `_data` is set (restoring an existing
+   * session preserves whatever was already persisted there). The TUI
+   * resolves this from `findGitRoot(cwd) ?? cwd` so sessions started
+   * from the same repo (no matter which subdir) share one tag.
    */
-  depth?: number;
+  projectRoot?: string;
+  /** Initial metadata */
+  metadata?: Record<string, unknown>;
+  /** Storage backend (optional, enables save/load) */
+  store?: SessionStore;
+  _data?: SessionData;
 }
 /**
- * Reason the provider gave for stopping the turn.
+ * Create a new session.
+ * Async so stores that generate IDs server-side (e.g. Supabase) can be supported.
+ */
+declare function createSession(options?: CreateSessionOptions): Promise<Session>;
+/**
+ * Load an existing session from a store.
+ */
+declare function loadSession(store: SessionStore, sessionId: string): Promise<Session | null>;
+//#endregion
+//#region src/skills/types.d.ts
+/**
+ * Types for the Agent Skills system.
  *
- * - `'stop'` — natural turn end (`end_turn` / `stop_sequence`).
- * - `'tool-calls'` — model emitted tool_use blocks.
- * - `'length'` — `max_tokens` reached, or (Anthropic 4.6+) the response bumped
- *   against the model's context window mid-stream
- *   (`model_context_window_exceeded`). The partial response is preserved; the
- *   loop emits this reason so consumers can prune/retry.
- * - `'content-filter'` — model refused.
- * - `'pause'` — Anthropic `pause_turn`: a server-side mid-turn pause for very
- *   long thinking. The loop continues with a synthetic "Please continue."
- *   user message rather than terminating; consumers see the pause via this
- *   finish reason on the prior assistant turn.
- * - `'error'` — provider classified the turn as failed.
- * - `'other'` — unknown / unmapped.
+ * Follows the Agent Skills open standard (agentskills.io/specification).
+ * Zidane-specific metadata conventionally uses the `zidane.` key prefix
+ * (e.g. `metadata['zidane.paths']`) to stay spec-compliant.
  */
-type TurnFinishReason = 'stop' | 'tool-calls' | 'length' | 'content-filter' | 'pause' | 'error' | 'other';
-interface TurnUsage {
-  input: number;
-  output: number;
-  /** Tokens written to cache (Anthropic) */
-  cacheCreation?: number;
-  /** Tokens read from cache (Anthropic) */
-  cacheRead?: number;
-  /** Thinking/reasoning tokens used */
-  thinking?: number;
-  /** Cost in USD as reported by the provider (OpenRouter) */
-  cost?: number;
-  /**
-   * Why the model stopped this turn. Providers normalize native stop reasons to this union.
-   * Absent when the provider did not surface a reason (e.g. mock turns).
-   */
-  finishReason?: TurnFinishReason;
-  /**
-   * The model ID the provider ultimately used. May differ from the requested model when the
-   * provider remaps aliases. Absent for providers that do not echo a model ID.
-   */
-  modelId?: string;
+interface SkillResource {
+  /** Relative path from skill directory */
+  path: string;
+  /** Resource type inferred from directory */
+  type: 'script' | 'reference' | 'asset' | 'other';
 }
-interface AgentStats {
+/**
+ * Where the skill came from. Used for collision precedence (project beats user)
+ * and for host SDKs to gate project-level skills on a trust check.
+ */
+type SkillSource = 'project' | 'user' | 'inline' | 'builtin';
+/** Severity + code for lenient-load warnings surfaced to host UIs. */
+interface SkillDiagnostic {
+  severity: 'warning' | 'error';
+  /** Stable machine-readable code (e.g. `name-mismatch-directory`). */
+  code: string;
+  /** Human-readable description. */
+  message: string;
+  /** Optional frontmatter field name the diagnostic relates to. */
+  field?: string;
+}
+interface SkillConfig {
+  /** Skill name: 1-64 chars, lowercase alphanumeric + hyphens */
+  name: string;
+  /** What the skill does and when to use it (1-1024 chars) */
+  description: string;
+  /** The SKILL.md body content (after YAML frontmatter) */
+  instructions: string;
   /**
-   * Cumulative input tokens across the parent agent loop **and** every
-   * recursively-spawned sub-agent. Use this for billing / token-ledger
-   * consumption.
+   * Where this skill was loaded from. Drives collision precedence and the
+   * `trustProjectSkills` gate. Optional — `parseSkillFile` stamps it; raw
+   * fixtures that omit it are treated as `'project'` by downstream readers.
    */
-  totalIn: number;
-  /** Cumulative output tokens. Same semantics as {@link AgentStats.totalIn}. */
-  totalOut: number;
+  source?: SkillSource;
+  /** Absolute path to SKILL.md (undefined for inline skills) */
+  location?: string;
+  /** Skill directory path for resolving relative references */
+  baseDir?: string;
+  /** License identifier or reference */
+  license?: string;
+  /** Environment requirements */
+  compatibility?: string;
   /**
-   * Cumulative cache-read tokens across the parent agent loop and every
-   * recursively-spawned sub-agent. Surfaced at the top level (rather than
-   * only per-`TurnUsage`) because Anthropic prices cache reads at a separate
-   * line-item rate from regular input — billing-correct cost computation
-   * needs this number directly. Always `0` for providers that don't report
-   * cache usage.
+   * Flat key-value metadata bag per the spec. For Zidane-specific hints,
+   * use the `zidane.` key prefix (e.g. `metadata['zidane.paths']`).
    */
-  totalCacheRead: number;
+  metadata?: Record<string, string>;
+  /** Pre-approved tool names (experimental per spec) */
+  allowedTools?: string[];
+  /** Bundled resource files discovered in the skill directory */
+  resources?: SkillResource[];
   /**
-   * Cumulative cache-creation tokens across the parent agent loop and every
-   * recursively-spawned sub-agent. Same rationale as
-   * {@link AgentStats.totalCacheRead} — separate Anthropic billing rate.
-   * Always `0` for providers that don't report cache usage.
+   * Lenient-load warnings recorded during parsing. Host SDKs can surface these
+   * as inline UI hints. Absent when no issues were found.
    */
-  totalCacheCreation: number;
+  diagnostics?: SkillDiagnostic[];
+}
+interface SkillsConfig {
   /**
-   * Number of parent agent-loop turns. Children's turn counts live under
-   * `children[].stats.turns` and are NOT folded in here — a single "turns"
-   * number for the whole tree would conflate two different measures
-   * (parent-loop iterations vs. tree-wide tool-call rounds).
-   *
-   * Tree-wide turn count: `flattenTurns(stats).length`.
+   * Control which skills are active.
+   * - `true` (default): all discovered skills are enabled
+   * - `false` or `[]`: fully disable the skills system (no resolution, no catalog, no hooks)
+   * - `string[]`: allowlist — only skills with matching names are enabled
    */
-  turns: number;
+  enabled?: boolean | string[];
+  /** Directories to scan for SKILL.md files */
+  scan?: string[];
+  /** Dynamic skills written to disk at agent start, then loaded normally */
+  write?: SkillConfig[];
+  /** Skill names to exclude from the catalog */
+  exclude?: string[];
+  /** Skip default scan paths (~/.agents/skills, .zidane/skills, etc.) */
+  skipDefaultPaths?: boolean;
   /**
-   * Wall-clock duration of the top-level `agent.run()` call, in milliseconds.
-   * Children run during parent tool calls so this naturally subsumes child
-   * wall time — sequential children inflate it, parallel children compress
-   * into the parent's window.
+   * Auto-inject `skills_use` / `skills_read` / `skills_run_script` tools
+   * when the catalog is non-empty. Default `true`. Set `false` to opt out
+   * (the system prompt will then instruct the model to use its file-read
+   * tool instead).
    */
-  elapsed: number;
+  tool?: boolean;
   /**
-   * Per-turn usage breakdown for the **parent loop only**. Children's per-turn
-   * usages live under `children[].stats.turnUsage`. Use {@link flattenTurns}
-   * to walk the full tree.
+   * Cap on concurrently active skills per run. Default `undefined` (unlimited).
+   * Attempts to activate past the cap throw from `skills_use`.
    */
-  turnUsage?: TurnUsage[];
+  maxActive?: number;
+  /** Script timeout for `skills_run_script`, in milliseconds. Default `60000`. */
+  scriptTimeoutMs?: number;
   /**
-   * Cumulative cost in USD — parent loop plus every recursively-spawned
-   * sub-agent. Sums per-turn `TurnUsage.cost` reported by the provider.
-   * Absent when neither parent nor any descendant reported a non-zero cost.
+   * When `false`, skills with `source: 'project'` are skipped during
+   * resolution with a diagnostic. Default `true` (preserves existing behavior).
+   * Useful for host SDKs handling untrusted repositories.
    */
-  cost?: number;
-  /** Stats from child agents spawned during this run, in completion order. Recursive. */
-  children?: ChildRunStats[];
-  /** Structured output from schema enforcement (only present when behavior.schema is set) */
-  output?: Record<string, unknown>;
+  trustProjectSkills?: boolean;
+}
+//#endregion
+//#region src/tools/types.d.ts
+/**
+ * Runtime context passed to every tool execution.
+ * Provides access to the agent's provider, abort signal, execution environment, and hooks.
+ *
+ * The preset-y fields (`name`, `system`, `tools`, `toolAliases`, `mcpServers`, `skills`,
+ * `behavior`) mirror the agent's own options so child-spawning tools can inherit them.
+ */
+interface ToolContext {
+  /** The LLM provider for this agent run */
+  provider: Provider;
+  /** Abort signal — tools should check this for early termination */
+  signal: AbortSignal;
+  /** The execution context (shell, filesystem, etc.) */
+  execution: ExecutionContext;
+  /** The active execution handle for the current agent run */
+  handle: ExecutionHandle;
+  /** Agent hooks for emitting events (e.g. spawn:complete) */
+  hooks: Hookable<AgentHooks>;
+  /** Agent display name (preset or user-supplied) */
+  name?: string;
+  /** Agent default system prompt */
+  system?: string;
+  /** Source tool map the agent was created with (pre-MCP-merge, pre-skills-injection) */
+  tools: Record<string, ToolDef>;
   /**
-   * Milliseconds from the start of `agent.run()` to the first observable signal from the
-   * provider (first `stream:text`, `stream:thinking`, or `tool:before` event).
+   * Map canonical tool names to LLM-facing (aliased) names.
    *
-   * Absent when the run produced no observable signals (e.g. aborted before any stream event).
+   * Aliasing is **LLM-boundary-only**:
+   * - The alias is what the provider's tool spec carries, what the model calls it, and
+   *   what appears in `ToolHookContext.displayName` / `McpToolHookContext.displayName`.
+   * - The canonical name is what lives in `session.turns`, `ToolHookContext.name`, and
+   *   what the agent uses to look up the tool implementation. Alias changes never
+   *   desync persisted history.
    */
-  timeTillFirstTokenMs?: number;
-}
-interface ChildRunStats {
-  id: string;
-  task: string;
+  toolAliases?: Record<string, string>;
+  /** MCP servers configured on the agent (for child inheritance) */
+  mcpServers?: McpServerConfig[];
+  /** Skills configuration (for child inheritance) */
+  skills?: SkillsConfig;
+  /** Behavior defaults (for child inheritance) */
+  behavior?: AgentBehavior;
+  /** Turn ID that requested this tool call */
+  turnId: string;
+  /** Tool call ID from the model */
+  callId: string;
   /**
-   * The child agent's full {@link AgentStats}. Cumulative for that child's
-   * own subtree (child loop + its grandchildren). Do **not** sum
-   * `ctx.stats.totalIn` across `spawn:complete` events to derive top-level
-   * totals — `agent.run()`'s return value is the canonical cumulative root.
+   * The run id this tool call is part of. Populated by the agent loop when
+   * invoking tools. Optional on the type so host code constructing contexts
+   * by hand (tests, direct tool invocations) doesn't have to synthesize one.
+   *
+   * Spawn-style tools rely on this to tag child runs with `parentRunId` so
+   * the subagent tree can be reconstructed from a persisted session.
    */
-  stats: AgentStats;
+  runId?: string;
   /**
-   * Subagent depth when this child ran. 1 = direct child of the top-level
-   * agent, 2 = grandchild, etc. Useful for telemetry that wants to group
-   * runs by depth.
+   * The agent's session, when one was provided to `createAgent`. Tools that
+   * want to persist their own state (or, in the case of `spawn`, inherit the
+   * parent's session for child persistence) can read from here.
    */
-  depth?: number;
+  session?: Session;
   /**
-   * Terminal state of the child run. `'completed'` is the default. Exposed so
-   * a parent reading `stats.children` can distinguish aborted/timed-out
-   * children without re-parsing the returned string.
+   * Subagent depth for the agent owning this tool call. 0 = top-level,
+   * 1 = first-level child, … Used by spawn to enforce a `maxDepth` cap.
+   * Undefined is treated as 0 by spawn.
    */
-  status?: 'completed' | 'aborted' | 'timeout' | 'error';
+  depth?: number;
+}
+interface ToolDef {
+  spec: ToolSpec;
   /**
-   * Final structured output when the child was run with `behavior.schema`.
-   * Mirrors `AgentStats.output` but is surfaced here so the parent can read
-   * it without peeking at the nested `stats` bag.
+   * Execute the tool and return its output.
+   *
+   * Return a plain string for text-only tools (the common case). Return a
+   * `ToolResultContent[]` when the tool produces non-text content (images, mixed
+   * text+image) that the provider can route through natively (Anthropic
+   * `tool_result.content` arrays, OpenAI Codex pi-ai) or through the
+   * companion-user-message fallback (OpenAI Chat Completions).
    */
-  output?: Record<string, unknown>;
+  execute: (input: Record<string, unknown>, ctx: ToolContext) => Promise<string | ToolResultContent[]>;
+}
+type ToolMap = Map<string, ToolDef>;
+//#endregion
+//#region src/mcp/index.d.ts
+interface McpConnection {
+  tools: Record<string, ToolDef>;
+  close: () => Promise<void>;
 }
 /**
- * Base context for tool execution hooks.
+ * Normalize MCP server configs from any common shape to `McpServerConfig[]`.
  *
- * `name` is the canonical tool identity — the spec name registered on the agent (or the
- * `mcp_{server}_{tool}` name for MCP tools). Hooks should policy-match against `name`.
+ * Accepts:
+ * - `McpServerConfig[]` — zidane native (pass-through).
+ * - `McpServerConfig` — a single config object (wrapped to a 1-element array).
+ * - `Record<string, RawShape>` — name-keyed map (common in host-SDK configs), where the key is the server name.
+ * - Mixed shapes with `type` vs `transport`, `httpUrl`/`sseUrl` vs `url`.
  *
- * `displayName` is the outward-facing name — the alias surfaced to the LLM when
- * `AgentOptions.toolAliases` maps the canonical name; otherwise equal to `name`.
- * UI/telemetry adapters should emit `displayName`.
+ * Returns `[]` when `input` is nullish. Throws a descriptive error when the transport
+ * cannot be inferred from a given entry, or when the input shape is unsupported.
+ */
+declare function normalizeMcpServers(input: unknown): McpServerConfig[];
+/**
+ * Lossy flattener — converts MCP `CallToolResult.content` blocks to a single
+ * string. Text blocks are extracted; non-text blocks are JSON-stringified.
  *
- * Canonical vs. alias matters on session resume: `session.turns` persists canonical
- * names only, so renaming an alias cannot desync history.
+ * Use this only at UI / log boundaries that require a string. The agent
+ * loop itself routes through {@link normalizeMcpBlocks} so image blocks
+ * survive into provider-native tool_result content (Anthropic blocks,
+ * OpenAI companion-user-message).
  */
-interface ToolHookContext {
-  turnId: string;
-  callId: string;
-  /** Canonical tool name (spec name). Stable across alias-map changes. */
-  name: string;
-  /** Aliased (wire) name — equal to `name` when no alias is defined. */
-  displayName: string;
-  input: Record<string, unknown>;
-}
+declare function resultToString(content: unknown[]): string;
 /**
- * Base context for MCP tool hooks.
+ * Normalize MCP `CallToolResult.content` to zidane's {@link ToolResultContent[]} shape.
  *
- * `tool` is the native tool name on the MCP server. `server` is the configured server
- * name. The canonical zidane-namespaced identity is `mcp_{server}_{tool}`.
+ * Handles the four MCP content block types:
+ * - `text` → preserved as `{type:'text', text}`
+ * - `image` → preserved as `{type:'image', mediaType, data}` (MCP uses `mimeType`)
+ * - `resource` with embedded text → flattened to a text block
+ * - `resource` with embedded blob whose `mimeType` is `image/*` → flattened to an image block
+ * - Any unrecognized block → JSON-stringified fallback text block (lossy but safe)
  *
- * `displayName` equals the canonical namespaced name unless the agent has aliased
- * this MCP tool via `AgentOptions.toolAliases`; in which case `displayName` is the
- * alias that the LLM sees.
+ * Returns `null` when the input is not an array — callers should fall back to an empty
+ * result in that case.
  */
-interface McpToolHookContext {
-  turnId: string;
-  callId: string;
-  server: string;
-  tool: string;
-  /** Aliased wire name for this MCP tool, or the canonical `mcp_{server}_{tool}` name. */
-  displayName: string;
-  input: Record<string, unknown>;
+declare function normalizeMcpBlocks(content: unknown): ToolResultContent[] | null;
+/**
+ * Connect to MCP servers and discover their tools.
+ *
+ * Each tool is namespaced as `mcp_{serverName}_{toolName}` to avoid
+ * collisions with agent tools or tools from other servers.
+ *
+ * @param configs - Array of MCP server configurations
+ * @param _clientFactory - Internal: override client construction for testing
+ * @param hooks - Optional agent hooks for firing mcp:connect, mcp:error, mcp:close events
+ */
+declare function connectMcpServers(configs: McpServerConfig[], _clientFactory?: () => Client, hooks?: Hookable<AgentHooks>): Promise<McpConnection>;
+//#endregion
+//#region src/skills/activation.d.ts
+/** How a skill was activated. Surfaced in `skills:activate` hook ctx. */
+type ActivationVia = 'model' | 'explicit' | 'resume';
+/** Reason a skill was deactivated. Surfaced in `skills:deactivate` hook ctx. */
+type DeactivationReason = 'run-end' | 'explicit' | 'reset';
+/** A skill currently active in the state machine. */
+interface ActiveSkill {
+  skill: SkillConfig;
+  activatedAt: number;
+  activatedVia: ActivationVia;
 }
-/** Base context for session hooks */
-interface SessionHookContext {
-  sessionId: string;
+/**
+ * Per-agent skill activation state. Public read-surface is the `active()` list
+ * and `isActive(name)` predicate; writes go through `activate()` / `deactivate()`.
+ */
+interface SkillActivationState {
+  /** List of currently active skills in activation order. Returns a snapshot. */
+  active: () => readonly ActiveSkill[];
+  /** Is the skill with this canonical name currently active? */
+  isActive: (name: string) => boolean;
+  /** Retrieve the `ActiveSkill` record by name, or `undefined`. */
+  get: (name: string) => ActiveSkill | undefined;
+  /**
+   * Mark a skill as active.
+   * - Returns `'ok'` on a fresh activation (caller should fire `skills:activate`).
+   * - Returns `'already-active'` if the skill was already in the set (idempotent).
+   * - Returns `'cap-reached'` if the `maxActive` cap would be exceeded. State is unchanged.
+   */
+  activate: (skill: SkillConfig, via: ActivationVia) => 'ok' | 'already-active' | 'cap-reached';
+  /**
+   * Mark a skill as inactive. Returns the removed `ActiveSkill` record or `undefined`
+   * if it wasn't active. Callers fire `skills:deactivate` on removal.
+   */
+  deactivate: (name: string) => ActiveSkill | undefined;
+  /** Remove every active skill. Returns the list of removed records. */
+  clear: () => readonly ActiveSkill[];
 }
-/** Base context for spawn hooks */
-interface SpawnHookContext {
-  id: string;
-  task: string;
+interface SkillActivationStateOptions {
+  /**
+   * Cap on concurrent activations. `undefined` (the default) disables the cap.
+   * When set, `activate()` returns `'cap-reached'` once the set is at size `maxActive`.
+   */
+  maxActive?: number;
+}
+declare function createSkillActivationState(options?: SkillActivationStateOptions): SkillActivationState;
+//#endregion
+//#region src/agent.d.ts
+interface AgentHooks {
+  'system:before': (ctx: {
+    system: string;
+  }) => void;
+  'turn:before': (ctx: {
+    turn: number;
+    turnId: string;
+    options: StreamOptions;
+  }) => void;
+  /**
+   * Fires after each assistant turn (before its tool-result follow-up
+   * dispatches; the loop iterates back to a fresh `turn:before` once the
+   * tool results are produced).
+   *
+   * `toolCounts.turn` — calls **emitted** by the model in this assistant
+   * turn, keyed by canonical tool name. Reflects what the model asked for,
+   * regardless of downstream gate outcome. Most useful for spotting per-turn
+   * spikes ("the model called todowrite 4 times in one turn").
+   *
+   * `toolCounts.run` — cumulative running counter of **dispatched** calls
+   * scoped to this `runId`, captured at fire time. Excludes calls that were
+   * `block`ed by `tool:gate` handlers. Includes calls short-circuited via
+   * `tool:gate` `result` substitution (the model still asked, the framework
+   * just answered without the tool running). Resumed sessions start a fresh
+   * run with empty counts.
+   *
+   * Both fields are frozen snapshots; mutate-safe.
+   */
+  'turn:after': (ctx: {
+    turn: number;
+    turnId: string;
+    usage: TurnUsage;
+    message: SessionTurn;
+    toolCounts: {
+      turn: Readonly<Record<string, number>>;
+      run: Readonly<Record<string, number>>;
+    };
+  }) => void;
+  /**
+   * Fires after a tool-results user turn is pushed onto the conversation,
+   * before* any byte-budget enforcement or follow-up steering. Symmetric
+   * with `turn:after` but for the user-role tool_result turn that closes the
+   * round-trip.
+   *
+   * Why it exists: persistence layers must write tool_use/tool_result turn
+   * pairs together — if only the assistant turn (carrying tool_use blocks)
+   * is durable, a process death between turns leaves the DB with an orphan
+   * tool_use that Anthropic rejects on resume. Subscribe here to persist
+   * the tool-results turn before the loop continues.
+   */
+  'tool-results:after': (ctx: {
+    turn: number;
+    turnId: string;
+    message: SessionTurn; /** Frozen list of tool results that were packed into `message`. */
+    results: readonly ToolResult[];
+  }) => void;
+  'stream:text': (ctx: StreamHookContext & {
+    delta: string;
+    text: string;
+  }) => void;
+  'stream:end': (ctx: StreamHookContext & {
+    text: string;
+  }) => void;
+  'stream:thinking': (ctx: StreamHookContext & {
+    delta: string;
+    thinking: string;
+  }) => void;
+  'oauth:refresh': (ctx: OAuthRefreshHookContext) => void;
+  /**
+   * Fires before validation, `tool:before`, and `execute`. Two ways to
+   * intercept:
+   *
+   * - Set `block = true` (with a `reason`) to refuse the call. The model
+   *   sees a `Blocked: <reason>` tool result; `tool:before` / `tool:after`
+   *   do **not** fire.
+   * - Set `result` to substitute a successful tool_result and skip
+   *   execution. The model sees the substitute as a normal tool_result;
+   *   `tool:before` does not fire, but `tool:after` and `tool:transform`
+   *   do — so byte budgets, telemetry, and post-mutation hooks see the
+   *   substitute. Useful for cache hits, dedup, idempotency guards,
+   *   plan-mode synthetic acks.
+   *
+   * If multiple handlers along the chain set both `block` and `result`,
+   * `block` wins — refusal beats substitution, so a policy gate
+   * (skills allow-list, custom security) can always override an upstream
+   * consumer's cache substitute. Mirrors the writable-`result` shape on
+   * `tool:unknown` and `tool:error` so consumers learn one pattern.
+   *
+   * `runToolCounts` — frozen pre-call snapshot of per-tool dispatched
+   * counts in this run. Use it to self-throttle, drive observability, or
+   * implement budget guards. Counts every call that passed gate, including
+   * dedup substitutes (Z19); excludes `block`ed calls.
+   *
+   * **Parallel mode** (`toolExecution: 'parallel'`, the default): the
+   * snapshot is taken before any dispatches in the batch, so consumer
+   * hooks reading `runToolCounts` see the pre-batch view. Built-in
+   * budget / dedup middleware uses internal per-call reservation, so
+   * `behavior.toolBudgets` enforces atomically even within a parallel
+   * batch.
+   */
+  'tool:gate': (ctx: ToolHookContext & {
+    block: boolean;
+    reason: string;
+    result?: string | ToolResultContent[];
+    runToolCounts: Readonly<Record<string, number>>;
+  }) => void;
+  'tool:before': (ctx: ToolHookContext & {
+    coercions?: readonly string[];
+    runToolCounts: Readonly<Record<string, number>>;
+  }) => void;
+  'tool:after': (ctx: ToolHookContext & {
+    result: string | ToolResultContent[];
+    outputBytes: number;
+    coercions?: readonly string[];
+    runToolCounts: Readonly<Record<string, number>>;
+  }) => void;
   /**
-   * Subagent depth for the spawn. 1 = direct child of the top-level agent.
-   * Present on spawn:before/complete/error. Absent for grandchild spawns that
-   * bubble through `child:*` events (which carry their own `depth`).
+   * Fires when a tool throws during execution. Mutate `result` to substitute a
+   * tool-output payload that gets sent back to the model in place of the
+   * default `Tool error: <msg>` string — useful for OSS-model error rewriting
+   * (collapse stack traces, hide internal paths, prepend recovery hints).
+   *
+   * The post-hook value flows through `tool:transform` like a normal output, so
+   * downstream byte-budgeting and image-stripping still apply.
    */
-  depth?: number;
-}
-/** Context for stream hooks */
-interface StreamHookContext {
-  turnId: string;
-}
-/** Context for OAuth refresh hooks */
-interface OAuthRefreshHookContext {
-  provider: string;
-  providerId: string;
-  source: 'params' | 'file';
-  previousCredentials: Record<string, unknown> & {
-    access: string;
-    refresh: string;
-    expires: number;
-  };
-  credentials: Record<string, unknown> & {
-    access: string;
-    refresh: string;
-    expires: number;
-  };
-}
-type SessionEndStatus = 'completed' | 'aborted' | 'error';
-//#endregion
-//#region src/providers/anthropic.d.ts
-/**
- * Server-side context-management config — the body of `context_management` on
- * the Messages API. Typed loosely (Record-of-unknown) so we don't pin a specific
- * SDK schema version: the v0.90 SDK does not yet type this field, but the wire
- * format is stable behind the `context-management-2025-06-27` beta.
- *
- * See: https://docs.anthropic.com/en/docs/build-with-claude/context-management
- */
-interface AnthropicContextManagement {
-  edits?: Array<Record<string, unknown>>;
-  [key: string]: unknown;
-}
-interface AnthropicParams {
-  apiKey?: string;
-  access?: string;
-  refresh?: string;
-  expires?: number;
-  defaultModel?: string;
+  'tool:error': (ctx: ToolHookContext & {
+    error: Error;
+    result?: string | ToolResultContent[];
+  }) => void;
+  'tool:transform': (ctx: ToolHookContext & {
+    result: string | ToolResultContent[];
+    isError: boolean;
+    outputBytes: number;
+    coercions?: readonly string[];
+  }) => void;
   /**
-   * Optional override for the Anthropic SDK base URL. Honored end-to-end — headers and
-   * routing pass through to the forwarded host. Useful for proxies (e.g. corporate
-   * gateways, internal router).
+   * Fires before the generic "Unknown tool" error when the model invokes a tool
+   * that isn't registered (hallucinated names, dropped MCP servers, dangling
+   * aliases). Mutate `result` to substitute a friendly response or set
+   * `suppressError: true` to skip the companion `tool:error` emission.
+   *
+   * Fires for any unknown tool name — including hallucinated MCP-style names
+   * (`mcp_supabase_xxx`); branch on `name.startsWith('mcp_')` to differentiate.
    */
-  baseURL?: string;
+  'tool:unknown': (ctx: ToolHookContext & {
+    result?: string | ToolResultContent[];
+    suppressError: boolean;
+  }) => void;
   /**
-   * Additional `anthropic-beta` flags to opt into. Merged with the OAuth-path
-   * defaults (`claude-code-20250219`, `oauth-2025-04-20`); duplicates are
-   * de-duped. Examples:
-   *
-   * - `'context-management-2025-06-27'` — server-side context compaction
-   *   (token-accurate; pair with {@link AnthropicParams.contextManagement}).
-   * - `'token-efficient-tools-2026-03-28'` — terser tool_use wire format.
-   * - `'interleaved-thinking-2025-05-14'` — think between tool calls within
-   *   one turn.
-   * - `'redact-thinking-2026-02-12'` — replace large thinking blocks with
-   *   stubs server-side.
-   * - `'prompt-caching-scope-2026-01-05'` — extended prompt-cache scope.
+   * Fires when `validateToolArgs` rejects an input that could not be auto-coerced
+   * to satisfy the tool's `inputSchema`. Observational — the tool call still
+   * surfaces a `Validation error: …` string back to the model. Useful for
+   * counting validation failures separately from runtime tool errors.
+   */
+  'validation:reject': (ctx: ToolHookContext & {
+    reason: string;
+    schema: Record<string, unknown>;
+  }) => void;
+  /**
+   * Fires when `validateToolArgs` successfully auto-coerced one or more input
+   * fields to satisfy the tool's `inputSchema`. **Only fires when at least one
+   * coercion happened** — never on perfectly-shaped inputs. Useful for counting
+   * model "wrongness rate" without re-running validation downstream.
    *
-   * Honored on both the OAuth and API-key paths.
+   * `coercions` lists the field names that were coerced. The values landed in
+   * the input that the tool actually received; consumers wanting before/after
+   * comparison can re-run `validateToolArgs(ctx.input, ctx.schema)`.
    */
-  extraBetas?: readonly string[];
+  'validation:coerce': (ctx: ToolHookContext & {
+    coercions: readonly string[];
+    schema: Record<string, unknown>;
+  }) => void;
+  'context:transform': (ctx: {
+    messages: SessionMessage[];
+  }) => void;
   /**
-   * Server-side context-management directive. Sent on the request body as
-   * `context_management`. Requires the `context-management-2025-06-27` beta —
-   * add it to {@link AnthropicParams.extraBetas}.
+   * Fires per request, after `context:transform` and before the request goes
+   * out. Mutating `ctx.system` updates the system prompt the provider sends
+   * for this turn — useful for runtime-derived sections (e.g. listing files
+   * already read in the session, surfacing live tool budgets, injecting
+   * skill activation reminders).
    *
-   * Typed loosely so future Anthropic schema additions land without an SDK
-   * bump. A typical compaction edit:
+   * Cache breakpoints are applied inside the provider after this hook, so
+   * mutations land in the cache key naturally — repeated turns with the
+   * same derived system text still hit the cache.
    *
-   * ```ts
-   * contextManagement: {
-   *   edits: [{
-   *     type: 'clear_tool_uses_20250919',
-   *     trigger: { type: 'input_tokens', value: 180_000 },
-   *     clear_at_least: { type: 'input_tokens', value: 140_000 },
-   *     clear_tool_inputs: ['Read', 'Bash', 'Grep'],
-   *   }],
-   * }
-   * ```
+   * `messages` is read-only here; use `context:transform` for message
+   * surgery. `session` is `undefined` when the run is sessionless.
    */
-  contextManagement?: AnthropicContextManagement;
+  'system:transform': (ctx: {
+    system: string;
+    messages: readonly SessionMessage[];
+    turn: number;
+    turnId: string;
+    session?: Session;
+  }) => void;
+  'steer:inject': (ctx: {
+    message: string;
+  }) => void;
+  'spawn:before': (ctx: SpawnHookContext) => void;
+  'spawn:complete': (ctx: ChildRunStats) => void;
+  'spawn:error': (ctx: SpawnHookContext & {
+    error: Error;
+  }) => void;
+  'child:stream:text': (ctx: StreamHookContext & {
+    delta: string;
+    text: string;
+    childId: string;
+    depth: number;
+  }) => void;
+  'child:stream:thinking': (ctx: StreamHookContext & {
+    delta: string;
+    thinking: string;
+    childId: string;
+    depth: number;
+  }) => void;
+  'child:stream:end': (ctx: StreamHookContext & {
+    text: string;
+    childId: string;
+    depth: number;
+  }) => void;
   /**
-   * Generic pass-through for fields on the Messages API request body that the
-   * SDK does not yet type. Spread into the request before the typed fields,
-   * so explicit options ({@link AnthropicParams.contextManagement} and the
-   * built-in fields like `model` / `tools` / `messages`) win on collision.
+   * Gate-style child events. Unlike the other `child:*` events, the bubble
+   * passes the **same `ctx` reference** the subagent's loop is awaiting on:
+   * setting `ctx.block` / `ctx.reason` / `ctx.result` on a parent listener
+   * propagates straight back to the child, refusing or substituting the call.
    *
-   * Forward-compat escape hatch for new Anthropic betas — when a future flag
-   * ships before zidane has a dedicated typed knob, set it here without
-   * waiting on a release. Most fields will still need the matching beta in
-   * {@link AnthropicParams.extraBetas}.
+   * Use these to gate subagent tool calls (native + MCP) from the parent
+   * without registering listeners on every child agent. The parent's own
+   * `tool:gate` / `mcp:tool:gate` listeners are NOT auto-shared with
+   * children — that would also share their budgets and dedup state.
    */
-  extraBodyParams?: Record<string, unknown>;
-}
-declare function anthropic(anthropicParams?: AnthropicParams): Provider;
-//#endregion
-//#region src/providers/cerebras.d.ts
-interface CerebrasParams {
-  apiKey?: string;
-  defaultModel?: string;
+  'child:tool:gate': (ctx: ToolHookContext & {
+    block: boolean;
+    reason: string;
+    result?: string | ToolResultContent[];
+    runToolCounts: Readonly<Record<string, number>>;
+    childId: string;
+    depth: number;
+  }) => void;
+  'child:mcp:tool:gate': (ctx: McpToolHookContext & {
+    block: boolean;
+    reason: string;
+    result?: string | ToolResultContent[];
+    childId: string;
+    depth: number;
+  }) => void;
+  'child:tool:before': (ctx: ToolHookContext & {
+    coercions?: readonly string[];
+    runToolCounts: Readonly<Record<string, number>>;
+    childId: string;
+    depth: number;
+  }) => void;
+  'child:tool:after': (ctx: ToolHookContext & {
+    result: string | ToolResultContent[];
+    outputBytes: number;
+    coercions?: readonly string[];
+    runToolCounts: Readonly<Record<string, number>>;
+    childId: string;
+    depth: number;
+  }) => void;
+  'child:tool:error': (ctx: ToolHookContext & {
+    error: Error;
+    childId: string;
+    depth: number;
+  }) => void;
+  'child:turn:after': (ctx: {
+    turn: number;
+    turnId: string;
+    usage: TurnUsage;
+    message: SessionTurn;
+    toolCounts: {
+      turn: Readonly<Record<string, number>>;
+      run: Readonly<Record<string, number>>;
+    };
+    childId: string;
+    depth: number;
+  }) => void;
+  'mcp:connect': (ctx: {
+    name: string;
+    transport: string;
+    tools: string[];
+  }) => void;
+  'mcp:error': (ctx: {
+    name: string;
+    error: Error;
+  }) => void;
+  'mcp:close': (ctx: {
+    name: string;
+  }) => void;
   /**
-   * Provider capability flags. Cerebras currently serves text-only OSS models
-   * (GLM, Llama-family, Qwen-family) — default: `{ vision: false, imageInToolResult: false }`.
-   * Override when routing to a vision-capable deployment.
+   * Fires at the start of a per-server bootstrap attempt, before any network I/O.
+   * Pairs with `mcp:bootstrap:end` and is always emitted, regardless of outcome.
    */
-  capabilities?: ProviderCapabilities;
-}
-/**
- * Cerebras provider.
- *
- * Thin wrapper around {@link openaiCompat} with Cerebras-specific defaults
- * (base URL, default model).
- */
-declare function cerebras(params?: CerebrasParams): Provider;
-//#endregion
-//#region src/providers/openai.d.ts
-interface OpenAIParams {
-  /** OpenAI Codex OAuth access token. Falls back to OPENAI_CODEX_API_KEY and .credentials.json. */
-  apiKey?: string;
-  /** Alias for apiKey, matching the OAuth credential field. */
-  access?: string;
-  refresh?: string;
-  expires?: number;
-  accountId?: string;
-  defaultModel?: string;
-  transport?: 'sse' | 'websocket' | 'auto';
-}
-declare function openai(params?: OpenAIParams): Provider;
-//#endregion
-//#region src/providers/openai-compat.d.ts
-/**
- * HTTP error thrown when an OpenAI-compatible endpoint returns a non-OK response.
- *
- * The body is best-effort JSON-parsed; `error.message` / `error.code` / `error.type`
- * are extracted for clean downstream classification.
- */
-declare class OpenAICompatHttpError extends Error {
-  readonly status: number;
-  readonly providerCode?: string;
-  readonly bodyText: string;
-  constructor(status: number, bodyText: string);
-}
-/**
- * Classify an OpenAI-compatible error into `ClassifiedError`.
- *
- * Recognizes:
- * - `AbortError` (from fetch) → `aborted`.
- * - `OpenAICompatHttpError` with a context-exceeded code or message → `context_exceeded`.
- * - Any other `OpenAICompatHttpError` → `provider_error`.
- *
- * Returns `null` for unrecognized error shapes (the loop falls back to `AgentProviderError`).
- */
-declare function classifyOpenAICompatError(err: unknown): ClassifiedError | null;
-/**
- * Map an OpenAI-compatible `finish_reason` string to the zidane `TurnFinishReason` union.
- */
-declare function mapOAIFinishReason(reason: string | null | undefined): TurnFinishReason | undefined;
-/**
- * Auth header config. `scheme` is prepended to the api key with a space, e.g.
- * `{ name: 'Authorization', scheme: 'Bearer' }` → `Authorization: Bearer <key>`.
- * Omit `scheme` for raw header values (e.g. `{ name: 'X-Api-Key' }` → `X-Api-Key: <key>`).
- *
- * Real-world examples:
- * - Default OpenAI / OpenRouter / Cerebras: `{ name: 'Authorization', scheme: 'Bearer' }`.
- * - Baseten: `{ name: 'Authorization', scheme: 'Api-Key' }`.
- * - Some gateways: `{ name: 'X-Api-Key' }`.
- */
-interface OpenAICompatAuthHeader {
-  name: string;
-  scheme?: string;
-}
-interface OpenAICompatParams {
-  /** Bearer-style API key. */
-  apiKey: string;
-  /** Base URL — `/chat/completions` is appended. */
-  baseURL: string;
-  /** Default model id when `run({ model })` is omitted. */
-  defaultModel?: string;
-  /** Provider name exposed as `Provider.name`. Defaults to `'openai-compat'`. */
-  name?: string;
-  /** Auth header shape. Defaults to `{ name: 'Authorization', scheme: 'Bearer' }`. */
-  authHeader?: OpenAICompatAuthHeader;
-  /** Extra headers sent with every request (e.g. referer, user-agent). */
-  extraHeaders?: Record<string, string>;
+  'mcp:bootstrap:start': (ctx: {
+    name: string;
+    transport: string;
+  }) => void;
   /**
-   * Provider-level capability flags. Routed into the message shaper and the
-   * agent loop so images in tool results + user messages are handled correctly
-   * for the underlying model.
-   *
-   * Defaults when omitted: `vision: false`, `imageInToolResult: false` — a
-   * conservative assumption matching most OSS text-only OpenAI-compat
-   * endpoints. Override when routing to a known vision-capable endpoint
-   * (e.g. OpenRouter vision models, Baseten image-capable deployments).
+   * Fires at the end of a per-server bootstrap attempt. `durationMs` spans from
+   * the matching `mcp:bootstrap:start`. On `ok: false` carries the originating
+   * error so consumers can log / trace without relying on a separate `mcp:error`.
    */
-  capabilities?: ProviderCapabilities;
+  'mcp:bootstrap:end': (ctx: {
+    name: string;
+    transport: string;
+    durationMs: number;
+  } & ({
+    ok: true;
+    toolCount: number;
+  } | {
+    ok: false;
+    error: Error;
+  })) => void;
   /**
-   * Whether this endpoint honors `cache_control: { type: 'ephemeral' }` markers
-   * on message content parts and tool definitions.
+   * Fires once per server after `listTools()` and after the config-side filters
+   * (`enabledTools` / `disabledTools` / `toolFilter`) have applied, but BEFORE
+   * tools are registered. Handlers may mutate `ctx.tools` in place — splicing,
+   * reordering, or replacing entries — to further narrow what the model sees.
    *
-   * - `true`  — inject markers when the caller asks for caching. OpenRouter routes
-   *             to Anthropic/Gemini forward the markers; routes to OpenAI/DeepSeek/
-   *             Grok/Groq/Moonshot ignore them (those backends cache automatically).
-   * - `false` — never inject markers. Safe default for endpoints that strictly
-   *             validate the request schema (OpenAI direct, most OSS inference
-   *             servers) and would reject unknown fields.
+   * Composes with config-side filters: config drops tools the host's static
+   * policy excludes; this hook is the runtime escape hatch for per-user, per-
+   * environment, or capability-driven decisions that the config can't express.
    *
-   * Default: `false`. The `openrouter` wrapper sets this to `true`.
+   * Items are upstream tool descriptors (NOT yet namespaced as `mcp_<server>_<tool>`).
    */
-  cacheBreakpoints?: boolean;
+  'mcp:tools:filter': (ctx: {
+    server: string;
+    transport: 'stdio' | 'sse' | 'streamable-http';
+    tools: Array<{
+      name: string;
+      description?: string | null;
+      inputSchema?: unknown;
+    }>;
+  }) => void;
   /**
-   * Whether this endpoint speaks OpenRouter's normalized reasoning envelope —
-   * `reasoning: { effort | max_tokens | exclude }` on requests and structured
-   * `reasoning_details[]` on assistant messages, round-tripped to preserve
-   * extended-reasoning state across turns.
-   *
-   * - `true`  — map zidane's `behavior.thinking` / `behavior.thinkingBudget` to
-   *             the request's `reasoning` field, capture `reasoning_details`
-   *             from streaming responses into `provider_reasoning` blocks, and
-   *             echo them back on subsequent assistant messages.
-   * - `false` — never set the field; drop any stored `provider_reasoning`
-   *             blocks before sending. Safe default for hosts that strict-
-   *             validate the request schema.
+   * MCP-side counterpart of `tool:gate`. Same shape: set `block` to refuse,
+   * set `result` to substitute a successful payload and skip the upstream
+   * MCP `callTool`. When both are set across the handler chain, `block` wins.
    *
-   * Default: `false`. The `openrouter` wrapper sets this to `true`.
+   * Fires INSIDE the MCP wrapper's `execute`, after the loop's `tool:gate`
+   * already ran. Does **not** carry `runToolCounts` — those are loop-level
+   * and already exposed on `tool:gate` for MCP tools (which are registered
+   * as agent tools under their namespaced name `mcp_<server>_<tool>`). Use
+   * `tool:gate` for budget / dedup logic; reserve `mcp:tool:gate` for
+   * MCP-specific concerns (per-server routing, transport-aware refusals).
    */
-  supportsReasoning?: boolean;
+  'mcp:tool:gate': (ctx: McpToolHookContext & {
+    block: boolean;
+    reason: string;
+    result?: string | ToolResultContent[];
+  }) => void;
+  'mcp:tool:before': (ctx: McpToolHookContext) => void;
+  'mcp:tool:after': (ctx: McpToolHookContext & {
+    result: string | ToolResultContent[];
+    outputBytes: number;
+  }) => void;
+  'mcp:tool:transform': (ctx: McpToolHookContext & {
+    result: string | ToolResultContent[];
+    outputBytes: number;
+  }) => void;
+  'mcp:tool:error': (ctx: McpToolHookContext & {
+    error: Error;
+  }) => void;
+  'skills:resolve': (ctx: {
+    skills: SkillConfig[];
+  }) => void;
+  'skills:catalog': (ctx: {
+    catalog: string;
+    skills: SkillConfig[];
+  }) => void;
+  'skills:activate': (ctx: {
+    skill: SkillConfig;
+    via: ActivationVia;
+  }) => void;
+  'skills:deactivate': (ctx: {
+    skill: SkillConfig;
+    reason: DeactivationReason;
+  }) => void;
+  'usage': (ctx: {
+    turn: number;
+    turnId: string;
+    usage: TurnUsage;
+    totalIn: number;
+    totalOut: number;
+  }) => void;
+  'output': (ctx: {
+    output: Record<string, unknown>;
+    schema: Record<string, unknown>;
+  }) => void;
   /**
-   * Generic pass-through for fields on the Chat Completions request body that
-   * zidane does not yet type. Spread into the request before the typed core
-   * (model / messages / tools / max_tokens / stream / tool_choice), so
-   * explicit options always win on collision.
+   * Fires when a turn's total tool-output bytes exceed `behavior.toolOutputBudget`.
+   * Measured post-`tool:transform`. Loop injects a synthetic user message after
+   * the tool-results turn instructing the model to summarize.
+   */
+  'budget:exceeded': (ctx: {
+    turn: number;
+    turnId: string;
+    bytes: number;
+    budget: number;
+  }) => void;
+  /**
+   * Fires when a per-tool budget configured via `behavior.toolBudgets` is
+   * exceeded for a specific tool. `mode` reflects how the framework reacted:
+   * `'steer'` lets the call run and queues a post-turn nudge; `'block'`
+   * refuses the call outright with `Blocked: <message>`.
    *
-   * Forward-compat escape hatch for endpoints that ship one-off fields ahead
-   * of zidane (e.g. OpenAI `reasoning_effort`, OpenRouter `provider` routing,
-   * vendor-specific `safety_level` knobs).
+   * `count` is the run-cumulative dispatched count just before this call.
+   * Use `turnId` to correlate with `turn:after` if you need the integer turn
+   * index. Distinct from `budget:exceeded` (byte-level) so consumers can
+   * subscribe specifically; both can fire in the same turn.
    */
-  extraBodyParams?: Record<string, unknown>;
-}
-/**
- * Factory for any OpenAI-compatible HTTP endpoint.
- *
- * Speaks the standard `POST /chat/completions` + `stream: true` + SSE dialect.
- * Thin wrappers (`openrouter`, `cerebras`) call this with pinned defaults.
- *
- * @example Baseten (non-standard auth scheme)
- * ```ts
- * openaiCompat({
- *   name: 'baseten',
- *   apiKey: process.env.BASETEN_API_KEY!,
- *   baseURL: process.env.BASETEN_PROXY_URL!,
- *   authHeader: { name: 'Authorization', scheme: 'Api-Key' },
- * })
- * ```
- */
-declare function openaiCompat(params: OpenAICompatParams): Provider;
-//#endregion
-//#region src/providers/openrouter.d.ts
-interface OpenRouterParams {
-  apiKey?: string;
-  defaultModel?: string;
+  'tool-budget:exceeded': (ctx: {
+    tool: string;
+    count: number;
+    max: number;
+    turnId: string;
+    mode: 'steer' | 'block';
+  }) => void;
+  'agent:abort': (ctx: object) => void;
   /**
-   * Provider capability flags. OpenRouter itself is a router — whether vision or
-   * native image-in-tool-result are supported depends on the downstream model.
-   * Default: `{ vision: true, imageInToolResult: false }` — matches the default
-   * `anthropic/claude-sonnet-4-6` model (vision-capable via companion user-message
-   * fallback since OpenRouter exposes Claude over the Chat Completions dialect).
+   * Run finished — fires on all exit paths (completion, maxTurns, abort).
    *
-   * Override when routing to a known-text-only model (e.g. `meta-llama/llama-3-8b-instruct`).
+   * Since 4.0 the `AgentStats` carried here is **cumulative** across the
+   * parent agent loop and every recursively-spawned sub-agent
+   * (`totalIn` / `totalOut` / `cost` / `totalCacheRead` / `totalCacheCreation`).
+   * For parent-loop-only counts use `ctx.turnUsage` (parent-only array);
+   * for tree-wide turn counts use `flattenTurns(ctx).length`.
    */
-  capabilities?: ProviderCapabilities;
+  'agent:done': (ctx: AgentStats) => void;
+  'session:start': (ctx: SessionHookContext & {
+    runId: string;
+    prompt: string;
+  }) => void;
+  'session:end': (ctx: SessionHookContext & {
+    runId: string;
+    status: SessionEndStatus;
+    turnRange: [number, number];
+  }) => void;
+  'session:turns': (ctx: SessionHookContext & {
+    turns: SessionTurn[];
+    count: number;
+  }) => void;
+  'session:meta': (ctx: SessionHookContext & {
+    key: string;
+    value: unknown;
+  }) => void;
+  'session:save': (ctx: SessionHookContext) => void;
 }
 /**
- * OpenRouter provider.
+ * Strongly-typed hook registration map accepted on {@link AgentOptions.hooks}
+ * (and therefore on any {@link Preset}). Each entry is a single handler or an
+ * array of handlers — arrays are what {@link composePresets} produces when
+ * multiple presets register handlers for the same event.
  *
- * Thin wrapper around {@link openaiCompat} with OpenRouter-specific defaults
- * (base URL, default model) and required attribution headers.
+ * Handlers registered here live for the **lifetime of the agent**. They fire
+ * across every `run()`, mirroring a manual `agent.hooks.hook(event, fn)` call
+ * made right after `createAgent` returns. For per-run handlers (auto-detached
+ * at run end) use {@link AgentRunOptions.hooks} instead.
  */
-declare function openrouter(params?: OpenRouterParams): Provider;
-//#endregion
-//#region src/providers/index.d.ts
-interface ToolSpec {
-  name: string;
-  description: string;
-  inputSchema: Record<string, unknown>;
-}
-interface ToolCall {
-  id: string;
-  name: string;
-  input: Record<string, unknown>;
-}
-interface ToolResult {
-  id: string;
+type AgentHookMap = Partial<{ [K in keyof AgentHooks]: AgentHooks[K] | AgentHooks[K][] }>;
+interface AgentOptions {
+  provider: Provider;
+  /** Display name for the agent (used in traces/logs). */
+  name?: string;
+  /** Default system prompt injected when no system is provided at run time. */
+  system?: string;
+  /** Tool definitions available to the agent. Defaults to no tools. */
+  tools?: Record<string, ToolDef>;
   /**
-   * Tool output — plain string for text-only tools (the common case) or a structured
-   * array of content blocks for tools that return images or mixed content (e.g. an
-   * MCP browser server returning a screenshot).
+   * Map canonical tool names to LLM-facing (aliased) names.
    *
-   * Use `toolResultToText(content)` when a downstream consumer only handles strings.
+   * Aliasing is **LLM-boundary-only**: the alias is what the provider's tool spec
+   * carries and what the model calls the tool; the canonical name is what lives in
+   * `session.turns` and what the agent uses to look up the tool implementation.
    */
-  content: string | ToolResultContent[];
-}
-/**
- * Provider-level capability flags used by the agent loop to route tool results
- * and user messages appropriately.
- *
- * When a flag is `undefined` (omitted), the loop applies the conservative
- * text-only default — images are stripped and replaced with a text marker so
- * non-vision models do not confabulate about content they cannot see.
- */
-interface ProviderCapabilities {
+  toolAliases?: Record<string, string>;
+  /** Agent-level behavior defaults (overridden by run-level behavior) */
+  behavior?: AgentBehavior;
+  /** Execution context: where tools run. Defaults to in-process. */
+  execution?: ExecutionContext;
+  /** MCP servers to connect and expose as tools */
+  mcpServers?: McpServerConfig[];
+  /** Session for identity, turn persistence, and run tracking */
+  session?: Session;
+  /** Skills configuration */
+  skills?: SkillsConfig;
   /**
-   * Model accepts image input anywhere (user messages and tool results).
+   * Agent-lifetime hook registrations. Registered once when `createAgent`
+   * returns; identical in effect to calling `agent.hooks.hook(event, fn)` for
+   * each entry. Use this to bake observability / policy hooks into a
+   * {@link Preset} so consumers get them automatically via `...spread`.
    *
-   * When `false`, the loop replaces image blocks with
-   * `"[image omitted — model does not support vision]"` before they reach the provider.
-   * Gives the model an honest marker instead of letting JSON-stringified base64 slip
-   * through and get confabulated over.
+   * Handlers may be a single function or an array — the array form is what
+   * `composePresets()` produces when multiple presets register handlers for
+   * the same event. Unknown event names throw at agent construction so typos
+   * never silently no-op.
+   *
+   * For per-run handlers (auto-detached at run end) use
+   * {@link AgentRunOptions.hooks}.
    */
-  vision?: boolean;
+  hooks?: AgentHookMap;
   /**
-   * Provider wire format embeds images inside tool-role messages natively
-   * (Anthropic `tool_result.content` arrays, OpenAI Codex pi-ai `toolResult` blocks).
+   * Test seam — replaces the default MCP connector with a custom
+   * implementation. Bypasses the `mcpServers` normalization layer entirely
+   * and is **not** part of the supported public API. Subject to change or
+   * removal in any release.
    *
-   * When `false`, a vision-capable provider still gets images — but via a
-   * companion `user` message emitted immediately after the flattened
-   * `tool`/`tool_result` marker. This is the Claude Desktop / Cline pattern
-   * and works on any OpenAI Chat Completions endpoint that accepts image
-   * URLs in user messages.
+   * @internal
    */
-  imageInToolResult?: boolean;
-}
-interface StreamCallbacks {
-  onText: (delta: string) => void;
-  onThinking?: (delta: string) => void;
-  onOAuthRefresh?: (ctx: OAuthRefreshHookContext) => void | Promise<void>;
-}
-interface TurnResult {
-  /** Full assistant turn as a SessionMessage */
-  assistantMessage: SessionMessage;
-  /** Text content blocks concatenated */
-  text: string;
-  /** Tool calls requested by the model */
-  toolCalls: ToolCall[];
-  /** Whether the model wants to stop */
-  done: boolean;
-  usage: TurnUsage;
-}
-interface StreamOptions {
-  model: string;
-  system: string;
-  tools: unknown[];
-  messages: SessionMessage[];
-  maxTokens: number;
-  /** Thinking/reasoning level (optional, default: off) */
-  thinking?: ThinkingLevel;
-  /** Exact thinking token budget — overrides the level-based default when set */
-  thinkingBudget?: number;
-  /** Force tool selection behavior */
-  toolChoice?: {
-    type: 'auto' | 'required' | 'tool';
-    name?: string;
-  };
+  mcpConnector?: (configs: McpServerConfig[]) => Promise<McpConnection>;
   /**
-   * Enable prompt caching on this call. When `true`, providers that support it
-   * insert `cache_control` breakpoints on the system prompt, last tool, and
-   * last stable message so the shared prefix is cached across turns.
+   * Pre-connect MCP servers in the background as soon as `createAgent` returns,
+   * instead of deferring the bootstrap to the first `agent.run()`.
    *
-   * Default: `false` (providers opt callers in — the agent loop passes `true`).
+   * Useful when MCP latency is the dominant cost of a cold start: callers that
+   * construct the agent early (e.g. at process init) can hide the bootstrap
+   * behind other setup work. If bootstrap fails, the error is stored and
+   * surfaced on the first `agent.run()` / `agent.warmup()`; the in-flight
+   * promise is `await`ed by both paths so the error is never silently lost.
+   *
+   * No-op when `mcpServers` is empty. Default: `false`.
    */
-  cache?: boolean;
-  /** Abort signal for cancellation */
-  signal?: AbortSignal;
+  eager?: boolean;
 }
-interface Provider {
-  readonly name: string;
-  readonly meta: {
-    defaultModel: string; /** Provider-level capability flags. See {@link ProviderCapabilities}. */
-    capabilities?: ProviderCapabilities;
-  } & Record<string, unknown>;
-  /** Format tool specs for this provider */
-  formatTools: (tools: ToolSpec[]) => unknown[];
-  /** Create a text-only user message. Multimodal content goes through `promptMessage`. */
-  userMessage: (content: string) => SessionMessage;
-  /** Create an assistant message (for priming) */
-  assistantMessage: (content: string) => SessionMessage;
-  /** Create a tool results message to send back */
-  toolResultsMessage: (results: ToolResult[]) => SessionMessage;
-  /** Stream a turn, calling onText for each text delta */
-  stream: (options: StreamOptions, callbacks: StreamCallbacks) => Promise<TurnResult>;
+interface Agent {
+  hooks: Hookable<AgentHooks>;
+  run: (options: AgentRunOptions) => Promise<AgentStats>;
+  abort: () => void;
+  steer: (message: string) => void;
+  followUp: (message: string) => void;
+  waitForIdle: () => Promise<void>;
   /**
-   * Build a user `SessionMessage` from multimodal prompt parts.
-   *
-   * Providers that cannot handle a particular part type (e.g. document) should throw.
-   * The agent loop always canonicalizes the run-level prompt into parts before calling
-   * this method; providers may fall back to `userMessage` for the text-only path if
-   * they do not implement this.
+   * Clear the agent's in-memory state (turns, queues, skill activations).
+   * Fires `skills:deactivate` with `reason: 'reset'` for each previously active
+   * skill. Awaiting lets host apps observe listener rejections.
    */
-  promptMessage?: (parts: PromptPart[]) => SessionMessage;
+  reset: () => Promise<void>;
   /**
-   * Classify a native provider error for downstream typed-error wrapping.
+   * Destroy the execution context and clean up resources.
+   * Idempotent — safe to call from both a `finally` block and a signal handler.
+   */
+  destroy: () => Promise<void>;
+  /**
+   * Explicitly activate a skill by name. Fires `skills:activate` with
+   * `via: 'explicit'`. Throws if the skill isn't in the resolved catalog or
+   * if the `maxActive` cap is reached. Idempotent — activating an already-active
+   * skill is a no-op.
+   */
+  activateSkill: (name: string) => Promise<void>;
+  /**
+   * Deactivate a skill by name. Fires `skills:deactivate` with `reason: 'explicit'`.
+   * No-op when the skill wasn't active.
+   */
+  deactivateSkill: (name: string) => Promise<void>;
+  /**
+   * Pre-connect MCP servers without running a turn. Idempotent and concurrency-safe:
+   * - No MCP servers configured → resolves immediately.
+   * - Connection already established → resolves immediately.
+   * - Another `warmup()` / `run()` is bootstrapping → awaits the in-flight promise.
    *
-   * Return `null` when the error is not recognized — the loop will wrap it in
-   * `AgentProviderError` with the provider's name. Return a `ClassifiedError` to
-   * route it to one of the typed error classes.
+   * Use from host code that wants to hide MCP bootstrap latency behind other
+   * startup work (UI init, auth, etc.). Safe to call multiple times and from
+   * multiple callers concurrently.
    */
-  classifyError?: (err: unknown) => ClassifiedError | null;
+  warmup: () => Promise<void>;
+  readonly isRunning: boolean;
+  readonly turns: SessionTurn[];
+  readonly execution: ExecutionContext;
+  readonly handle: ExecutionHandle | null;
+  readonly session: Session | null;
+  /** Snapshot of currently active skills. */
+  readonly activeSkills: readonly ActiveSkill[];
+  /**
+   * Frozen view of the underlying `provider.meta`. Read-only to prevent
+   * accidental cross-agent contamination — writes are rejected at runtime
+   * (via `Object.freeze`) and at compile time (via `Readonly`). To override
+   * model / capability defaults, construct a new provider.
+   */
+  readonly meta: Readonly<Record<string, unknown>>;
 }
+declare function createAgent({
+  provider,
+  name: agentName,
+  system: agentSystem,
+  tools: agentTools,
+  toolAliases,
+  behavior: agentBehavior,
+  execution,
+  mcpServers,
+  session,
+  skills: agentSkills,
+  mcpConnector,
+  eager,
+  hooks: initialHooks
+}: AgentOptions): Agent;
 //#endregion
-export { ToolDef as $, PromptDocumentPart as A, createMemoryStore as At, SpawnHookContext as B, AgentContextExceededError as Bt, AgentBehavior as C, RemoteStoreOptions as Ct, McpServerConfig as D, fromOpenAI as Dt, ChildRunStats as E, fromAnthropic as Et, SessionContentBlock as F, connectMcpServers as Ft, ToolResultContent as G, ClassifiedErrorKind as Gt, ThinkingLevel as H, AgentToolNotAllowedError as Ht, SessionEndStatus as I, normalizeMcpBlocks as It, TurnFinishReason as J, ToolResultImageContent as K, matchesContextExceeded as Kt, SessionHookContext as L, normalizeMcpServers as Lt, PromptPart as M, FileMapStoreOptions as Mt, PromptTextPart as N, createFileMapStore as Nt, McpToolHookContext as O, toAnthropic as Ot, RunHookMap as P, McpConnection as Pt, ToolContext as Q, SessionMessage as R, resultToString as Rt, anthropic as S, loadSession as St, AgentStats as T, autoDetectAndConvert as Tt, ToolExecutionMode as U, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as Ut, StreamHookContext as V, AgentProviderError as Vt, ToolHookContext as W, ClassifiedError as Wt, toolOutputByteLength as X, TurnUsage as Y, toolResultToText as Z, OpenAIParams as _, Session as _t, ToolCall as a, ActivationVia as at, cerebras as b, SessionStore as bt, TurnResult as c, SkillActivationState as ct, OpenAICompatAuthHeader as d, SkillConfig as dt, ToolMap as et, OpenAICompatHttpError as f, SkillDiagnostic as ft, openaiCompat as g, CreateSessionOptions as gt, mapOAIFinishReason as h, SkillsConfig as ht, StreamOptions as i, createAgent as it, PromptImagePart as j, FileMapAdapter as jt, OAuthRefreshHookContext as k, toOpenAI as kt, OpenRouterParams as l, SkillActivationStateOptions as lt, classifyOpenAICompatError as m, SkillSource as mt, ProviderCapabilities as n, AgentHooks as nt, ToolResult as o, ActiveSkill as ot, OpenAICompatParams as p, SkillResource as pt, ToolResultTextContent as q, toTypedError as qt, StreamCallbacks as r, AgentOptions as rt, ToolSpec as s, DeactivationReason as st, Provider as t, Agent as tt, openrouter as u, createSkillActivationState as ut, openai as v, SessionData as vt, AgentRunOptions as w, createRemoteStore as wt, AnthropicParams as x, createSession as xt, CerebrasParams as y, SessionRun as yt, SessionTurn as z, AgentAbortedError as zt };
-//# sourceMappingURL=index-bgh-k8Mv.d.ts.map
+export { OpenAICompatAuthHeader as $, createSession as A, ThinkingLevel as At, FileMapAdapter as B, AgentAbortedError as Bt, SkillSource as C, SessionContentBlock as Ct, SessionData as D, SessionTurn as Dt, Session as E, SessionMessage as Et, fromAnthropic as F, ToolResultTextContent as Ft, StreamCallbacks as G, ClassifiedError as Gt, createFileMapStore as H, AgentProviderError as Ht, fromOpenAI as I, TurnFinishReason as It, ToolResult as J, toTypedError as Jt, StreamOptions as K, ClassifiedErrorKind as Kt, toAnthropic as L, TurnUsage as Lt, RemoteStoreOptions as M, ToolHookContext as Mt, createRemoteStore as N, ToolResultContent as Nt, SessionRun as O, SpawnHookContext as Ot, autoDetectAndConvert as P, ToolResultImageContent as Pt, openrouter as Q, toOpenAI as R, toolOutputByteLength as Rt, SkillResource as S, RunHookMap as St, CreateSessionOptions as T, SessionHookContext as Tt, Provider as U, AgentToolNotAllowedError as Ut, FileMapStoreOptions as V, AgentContextExceededError as Vt, ProviderCapabilities as W, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as Wt, TurnResult as X, ToolSpec as Y, OpenRouterParams as Z, ToolContext as _, OAuthRefreshHookContext as _t, createAgent as a, OpenAIParams as at, SkillConfig as b, PromptPart as bt, DeactivationReason as c, cerebras as ct, createSkillActivationState as d, AgentBehavior as dt, OpenAICompatHttpError as et, McpConnection as f, AgentRunOptions as ft, resultToString as g, McpToolHookContext as gt, normalizeMcpServers as h, McpServerConfig as ht, AgentOptions as i, openaiCompat as it, loadSession as j, ToolExecutionMode as jt, SessionStore as k, StreamHookContext as kt, SkillActivationState as l, AnthropicParams as lt, normalizeMcpBlocks as m, ChildRunStats as mt, AgentHookMap as n, classifyOpenAICompatError as nt, ActivationVia as o, openai as ot, connectMcpServers as p, AgentStats as pt, ToolCall as q, matchesContextExceeded as qt, AgentHooks as r, mapOAIFinishReason as rt, ActiveSkill as s, CerebrasParams as st, Agent as t, OpenAICompatParams as tt, SkillActivationStateOptions as u, anthropic as ut, ToolDef as v, PromptDocumentPart as vt, SkillsConfig as w, SessionEndStatus as wt, SkillDiagnostic as x, PromptTextPart as xt, ToolMap as y, PromptImagePart as yt, createMemoryStore as z, toolResultToText as zt };
+//# sourceMappingURL=agent-JhicgLOV.d.ts.map