zidane 4.1.5 → 4.1.7

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

@@ -1,4 +1,4 @@
-import { c as ExecutionContext, l as ExecutionHandle } from "./index-BfSdALzk.js";
+import { c as ExecutionContext, l as ExecutionHandle } from "./index-BB4kuRh3.js";
 import { Hookable } from "hookable";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 //#region src/errors.d.ts
@@ -117,2231 +117,2257 @@ declare function matchesContextExceeded(message: unknown): boolean;
  */
 declare function toTypedError(classification: ClassifiedError, provider: string, cause: unknown): AgentContextExceededError | AgentProviderError | AgentAbortedError;
 //#endregion
-//#region src/types.d.ts
+//#region src/mcp/index.d.ts
+interface McpConnection {
+  tools: Record<string, ToolDef>;
+  close: () => Promise<void>;
+}
 /**
- * Thinking / extended-reasoning configuration.
+ * Normalize MCP server configs from any common shape to `McpServerConfig[]`.
  *
- * - `'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.
+ * 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.
  */
-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[];
+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;
+}
+/**
+ * Create a single-session `SessionStore` backed by a file-map adapter.
+ *
+ * @example
+ * ```ts
+ * const session = await createSession({
+ *   store: createFileMapStore(hostSessionStore),
+ * })
+ * ```
+ */
+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;
   /**
-   * 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.
+   * 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.
    */
-  env?: Record<string, string>;
+  parentRunId?: string;
   /**
-   * 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`.
+   * Zero-based subagent depth. 0 = top-level run, 1 = direct child, …
+   * Recorded here so hosts can query/filter by level without walking the tree.
    */
-  strictEnv?: boolean;
-  /** For sse/streamable-http: server URL */
-  url?: string;
-  /** Optional headers for HTTP transports */
-  headers?: Record<string, string>;
+  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[];
   /**
-   * 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.
+   * True when this session has no turns yet.
    *
-   * Default: `10000`.
+   * 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`.
    */
-  bootstrapTimeout?: number;
-  /** Timeout in milliseconds for MCP tool calls (default: 30000) */
-  toolTimeout?: number;
+  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>;
   /**
-   * 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.
+   * 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.
    */
-  enabledTools?: 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 */
+  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;
   /**
-   * Deny-list of tool names. Tools matching are dropped before registration.
-   * Same matching semantics as {@link McpServerConfig.enabledTools}.
+   * 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.
    */
-  disabledTools?: string[];
+  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;
   /**
-   * 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.
+   * Flat key-value metadata bag per the spec. For Zidane-specific hints,
+   * use the `zidane.` key prefix (e.g. `metadata['zidane.paths']`).
    */
-  toolFilter?: (tool: {
-    name: string;
-    description?: string | null;
-    inputSchema?: unknown;
-  }) => boolean;
+  metadata?: Record<string, string>;
+  /** Pre-approved tool names (experimental per spec) */
+  allowedTools?: string[];
+  /** Bundled resource files discovered in the skill directory */
+  resources?: SkillResource[];
   /**
-   * 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`.
+   * Lenient-load warnings recorded during parsing. Host SDKs can surface these
+   * as inline UI hints. Absent when no issues were found.
    */
-  disclosure?: 'eager' | 'lazy';
+  diagnostics?: SkillDiagnostic[];
 }
-type ToolExecutionMode = 'sequential' | 'parallel';
-interface AgentBehavior {
-  /** Tool execution mode (default: 'sequential') */
-  toolExecution?: ToolExecutionMode;
+interface SkillsConfig {
   /**
-   * 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.
+   * 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
    */
-  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>;
+  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;
   /**
-   * 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`.
+   * 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).
    */
-  cache?: boolean;
+  tool?: boolean;
   /**
-   * 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`.
+   * Cap on concurrently active skills per run. Default `undefined` (unlimited).
+   * Attempts to activate past the cap throw from `skills_use`.
    */
-  toolOutputBudget?: number;
+  maxActive?: number;
+  /** Script timeout for `skills_run_script`, in milliseconds. Default `60000`. */
+  scriptTimeoutMs?: 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`.
+   * 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.
    */
-  dedupReads?: boolean;
+  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;
   /**
-   * 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).
+   * 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.
    */
-  thinkingDecay?: {
-    afterTurn: number;
-    factor: number;
-    floor: number;
-  } | ((runTurn: number, baseBudget: number) => number);
+  activate: (skill: SkillConfig, via: ActivationVia) => 'ok' | 'already-active' | 'cap-reached';
   /**
-   * 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).
+   * Mark a skill as inactive. Returns the removed `ActiveSkill` record or `undefined`
+   * if it wasn't active. Callers fire `skills:deactivate` on removal.
    */
-  toolBudgets?: Record<string, {
-    max: number;
-    onExceed?: 'steer' | 'block' | ((ctx: {
-      tool: string;
-      count: number;
-      max: number;
-    }) => {
-      mode: 'steer' | 'block';
-      message: string;
-    });
-  }>;
+  deactivate: (name: string) => ActiveSkill | undefined;
+  /** Remove every active skill. Returns the list of removed records. */
+  clear: () => readonly ActiveSkill[];
+}
+interface SkillActivationStateOptions {
   /**
-   * 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:
+   * 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).
    *
-   * ```ts
-   * // Always cache by full input — every identical re-call dedups.
-   * dedupTools: { todowrite: input => JSON.stringify(input) }
+   * `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").
    *
-   * // 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
-   *   },
-   * }
-   * ```
+   * `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.
    *
-   * 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.
+   * 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;
+  '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:
    *
-   * 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.
+   * - 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.
    *
-   * 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.
+   * 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.
    *
-   * **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.
+   * `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.
    *
-   * Default: `undefined` (no per-tool dedup).
+   * **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.
    */
-  dedupTools?: Record<string, (input: Record<string, unknown>) => string | undefined>;
+  '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;
   /**
-   * 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.
-   *
-   * Requires a session. Off by default; turn it on for stricter eval-grade
-   * runs where silent edit corruption would invalidate the result.
+   * 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).
    *
-   * Default: `false`.
+   * The post-hook value flows through `tool:transform` like a normal output, so
+   * downstream byte-budgeting and image-stripping still apply.
    */
-  requireReadBeforeEdit?: boolean;
+  '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;
   /**
-   * 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`.
-   *
-   * - `'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.
+   * 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.
    *
-   * Default: `'off'`.
+   * Fires for any unknown tool name — including hallucinated MCP-style names
+   * (`mcp_supabase_xxx`); branch on `name.startsWith('mcp_')` to differentiate.
    */
-  compactStrategy?: 'off' | 'tail';
+  'tool:unknown': (ctx: ToolHookContext & {
+    result?: string | ToolResultContent[];
+    suppressError: boolean;
+  }) => void;
   /**
-   * 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.
+   * 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.
    */
-  compactThreshold?: number;
-  /**
-   * 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`.
-   */
-  compactKeepTurns?: number;
+  'validation:reject': (ctx: ToolHookContext & {
+    reason: string;
+    schema: Record<string, unknown>;
+  }) => void;
   /**
-   * 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.
+   * 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.
    *
-   * Default: `true`.
+   * `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)`.
    */
-  readLineNumbers?: boolean;
+  'validation:coerce': (ctx: ToolHookContext & {
+    coercions: readonly string[];
+    schema: Record<string, unknown>;
+  }) => void;
+  'context:transform': (ctx: {
+    messages: SessionMessage[];
+  }) => void;
   /**
-   * 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.
+   * 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).
    *
-   * 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.
+   * 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.
    *
-   * Default: `false`.
+   * `messages` is read-only here; use `context:transform` for message
+   * surgery. `session` is `undefined` when the run is sessionless.
    */
-  elideStaleReads?: boolean;
+  '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;
   /**
-   * 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.
+   * 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.
    *
-   * Default: `'eager'`.
+   * 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.
    */
-  toolDisclosure?: 'eager' | 'lazy';
+  '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;
   /**
-   * Fine-grained config for the `tool_search` tool auto-injected when
-   * {@link AgentBehavior.toolDisclosure} is `'lazy'`. No-op in eager mode.
+   * 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;
+  /**
+   * 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.
    *
-   * - `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`.
+   * 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.
    *
-   * 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.
+   * Items are upstream tool descriptors (NOT yet namespaced as `mcp_<server>_<tool>`).
+   */
+  'mcp:tools:filter': (ctx: {
+    server: string;
+    transport: 'stdio' | 'sse' | 'streamable-http';
+    tools: Array<{
+      name: string;
+      description?: string | null;
+      inputSchema?: unknown;
+    }>;
+  }) => void;
+  /**
+   * 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: `undefined` (auto-inject with the default limit).
+   * 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).
    */
-  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;
-  /**
-   * 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).
-   */
-  output: string | ToolResultContent[];
-  isError?: boolean;
-} | {
-  type: 'thinking';
-  text: string;
-  signature?: string;
+  '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;
   /**
-   * 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.
+   * 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.
    */
-  signatureProducer?: 'anthropic' | 'openai';
-} | {
-  type: 'redacted_thinking';
-  data: string;
-} | {
+  'budget:exceeded': (ctx: {
+    turn: number;
+    turnId: string;
+    bytes: number;
+    budget: number;
+  }) => void;
   /**
-   * 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.
+   * 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>`.
    *
-   * 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).
-   */
-  type: 'provider_reasoning';
-  producer: 'openrouter';
-  details: unknown[];
-  /**
-   * 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.
+   * `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.
    */
-  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;
-}
-/**
- * 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;
+  'tool-budget:exceeded': (ctx: {
+    tool: string;
+    count: number;
+    max: number;
+    turnId: string;
+    mode: 'steer' | 'block';
+  }) => void;
+  'agent:abort': (ctx: object) => void;
   /**
-   * User prompt. Optional when resuming a session with existing turns.
+   * Run finished — fires on all exit paths (completion, maxTurns, abort).
    *
-   * Accepts either a plain string (single text part) or an array of `PromptPart`s for
-   * multimodal inputs (text, images, documents). See {@link PromptPart}.
+   * 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`.
    */
-  prompt?: string | PromptPart[];
+  '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;
-  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. */
+  /** Tool definitions available to the agent. Defaults to no tools. */
   tools?: Record<string, ToolDef>;
   /**
-   * Per-run hook registrations. Each hook is attached before the run starts and
-   * detached in a finally block so handlers never leak across runs.
+   * Map canonical tool names to LLM-facing (aliased) names.
    *
-   * Accepts either a single handler or an array (all handlers register).
-   */
-  hooks?: RunHookMap;
-  /**
-   * 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.
-   */
-  parentRunId?: 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.
-   */
-  depth?: number;
-}
-/**
- * Reason the provider gave for stopping the turn.
- *
- * - `'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 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 AgentStats {
-  /**
-   * Cumulative input tokens across the parent agent loop **and** every
-   * recursively-spawned sub-agent. Use this for billing / token-ledger
-   * consumption.
-   */
-  totalIn: number;
-  /** Cumulative output tokens. Same semantics as {@link AgentStats.totalIn}. */
-  totalOut: number;
-  /**
-   * 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.
-   */
-  totalCacheRead: number;
-  /**
-   * 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.
+   * 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.
    */
-  totalCacheCreation: number;
+  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;
   /**
-   * 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).
+   * 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.
    *
-   * Tree-wide turn count: `flattenTurns(stats).length`.
-   */
-  turns: number;
-  /**
-   * 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.
+   * @internal
    */
-  elapsed: number;
+  mcpConnector?: (configs: McpServerConfig[]) => Promise<McpConnection>;
   /**
-   * 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.
+   * Pre-connect MCP servers in the background as soon as `createAgent` returns,
+   * instead of deferring the bootstrap to the first `agent.run()`.
+   *
+   * 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`.
    */
-  turnUsage?: TurnUsage[];
+  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>;
   /**
-   * 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.
+   * 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.
    */
-  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>;
+  reset: () => Promise<void>;
   /**
-   * Milliseconds from the start of `agent.run()` to the first observable signal from the
-   * provider (first `stream:text`, `stream:thinking`, or `tool:before` event).
-   *
-   * Absent when the run produced no observable signals (e.g. aborted before any stream event).
+   * Destroy the execution context and clean up resources.
+   * Idempotent — safe to call from both a `finally` block and a signal handler.
    */
-  timeTillFirstTokenMs?: number;
-}
-interface ChildRunStats {
-  id: string;
-  task: string;
+  destroy: () => Promise<void>;
   /**
-   * 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.
+   * 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.
    */
-  stats: AgentStats;
+  activateSkill: (name: string) => Promise<void>;
   /**
-   * 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.
+   * Deactivate a skill by name. Fires `skills:deactivate` with `reason: 'explicit'`.
+   * No-op when the skill wasn't active.
    */
-  depth?: number;
+  deactivateSkill: (name: string) => Promise<void>;
   /**
-   * 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.
+   * 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.
+   *
+   * 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.
    */
-  status?: 'completed' | 'aborted' | 'timeout' | 'error';
+  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[];
   /**
-   * 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.
+   * 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.
    */
-  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>;
+  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
+}: AgentOptions): Agent;
+//#endregion
+//#region src/tools/types.d.ts
 /**
- * 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}`.
+ * Runtime context passed to every tool execution.
+ * Provides access to the agent's provider, abort signal, execution environment, and hooks.
  *
- * `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.
+ * 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 McpToolHookContext {
+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>;
+  /**
+   * 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.
+   */
+  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;
-  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;
   /**
-   * 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`).
+   * 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.
+   */
+  runId?: string;
+  /**
+   * 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.
+   */
+  session?: Session;
+  /**
+   * 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.
    */
   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;
-  };
+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 SessionEndStatus = 'completed' | 'aborted' | 'error';
+type ToolMap = Map<string, ToolDef>;
 //#endregion
-//#region src/providers/anthropic.d.ts
+//#region src/types.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.
+ * Thinking / extended-reasoning configuration.
  *
- * See: https://docs.anthropic.com/en/docs/build-with-claude/context-management
+ * - `'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.
  */
-interface AnthropicContextManagement {
-  edits?: Array<Record<string, unknown>>;
-  [key: string]: unknown;
-}
-interface AnthropicParams {
-  apiKey?: string;
-  access?: string;
-  refresh?: string;
-  expires?: number;
-  defaultModel?: string;
+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[];
   /**
-   * 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).
+   * 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.
    */
-  baseURL?: string;
+  env?: Record<string, string>;
   /**
-   * 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.
-   *
-   * Honored on both the OAuth and API-key paths.
+   * 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`.
    */
-  extraBetas?: readonly string[];
+  strictEnv?: boolean;
+  /** For sse/streamable-http: server URL */
+  url?: string;
+  /** Optional headers for HTTP transports */
+  headers?: Record<string, string>;
   /**
-   * 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}.
+   * Timeout in milliseconds for MCP server bootstrap (connect + tool discovery).
    *
-   * Typed loosely so future Anthropic schema additions land without an SDK
-   * bump. A typical compaction edit:
+   * 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.
    *
-   * ```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'],
-   *   }],
-   * }
-   * ```
+   * Default: `10000`.
    */
-  contextManagement?: AnthropicContextManagement;
+  bootstrapTimeout?: number;
+  /** Timeout in milliseconds for MCP tool calls (default: 30000) */
+  toolTimeout?: number;
   /**
-   * 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.
+   * 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.
    *
-   * 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}.
+   * 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.
    */
-  extraBodyParams?: Record<string, unknown>;
-}
-declare function anthropic(anthropicParams?: AnthropicParams): Provider;
-//#endregion
-//#region src/providers/cerebras.d.ts
-interface CerebrasParams {
-  apiKey?: string;
-  defaultModel?: string;
+  enabledTools?: string[];
   /**
-   * 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.
+   * Deny-list of tool names. Tools matching are dropped before registration.
+   * Same matching semantics as {@link McpServerConfig.enabledTools}.
    */
-  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>;
+  disabledTools?: string[];
   /**
-   * 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.
+   * 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.
    *
-   * 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).
+   * Runs after the allow/deny filter but before the `mcp:tools:filter` hook.
    */
-  capabilities?: ProviderCapabilities;
+  toolFilter?: (tool: {
+    name: string;
+    description?: string | null;
+    inputSchema?: unknown;
+  }) => boolean;
   /**
-   * Whether this endpoint honors `cache_control: { type: 'ephemeral' }` markers
-   * on message content parts and tool definitions.
+   * 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.
    *
-   * - `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: inherits from `behavior.toolDisclosure`.
+   */
+  disclosure?: 'eager' | 'lazy';
+}
+type ToolExecutionMode = 'sequential' | 'parallel';
+interface AgentBehavior {
+  /** Tool execution mode (default: 'sequential') */
+  toolExecution?: ToolExecutionMode;
+  /**
+   * Max agent loop iterations.
    *
-   * Default: `false`. The `openrouter` wrapper sets this to `true`.
+   * 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.
    */
-  cacheBreakpoints?: 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>;
   /**
-   * 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.
+   * 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.
    *
-   * - `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.
+   * - 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).
    *
-   * Default: `false`. The `openrouter` wrapper sets this to `true`.
+   * Usage is surfaced via `TurnUsage.cacheRead` / `TurnUsage.cacheCreation`.
+   *
+   * Default: `true`.
    */
-  supportsReasoning?: boolean;
+  cache?: 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.
+   * 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.
    *
-   * 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).
+   * 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`.
    */
-  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;
+  toolOutputBudget?: number;
   /**
-   * 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).
+   * 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`.
    *
-   * Override when routing to a known-text-only model (e.g. `meta-llama/llama-3-8b-instruct`).
+   * Requires a session (set via `createSession()`); without one, the flag is
+   * a no-op since per-session state has nowhere to live.
+   *
+   * Default: `true`.
    */
-  capabilities?: ProviderCapabilities;
-}
-/**
- * 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 ToolCall {
-  id: string;
-  name: string;
-  input: Record<string, unknown>;
-}
-interface ToolResult {
-  id: string;
+  dedupReads?: boolean;
   /**
-   * 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).
+   * 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:
    *
-   * Use `toolResultToText(content)` when a downstream consumer only handles strings.
+   * - **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).
    */
-  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 {
+  thinkingDecay?: {
+    afterTurn: number;
+    factor: number;
+    floor: number;
+  } | ((runTurn: number, baseBudget: number) => number);
   /**
-   * Model accepts image input anywhere (user messages and tool results).
+   * 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`:
    *
-   * 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.
+   * - `'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).
    */
-  vision?: boolean;
+  toolBudgets?: Record<string, {
+    max: number;
+    onExceed?: 'steer' | 'block' | ((ctx: {
+      tool: string;
+      count: number;
+      max: number;
+    }) => {
+      mode: 'steer' | 'block';
+      message: string;
+    });
+  }>;
   /**
-   * Provider wire format embeds images inside tool-role messages natively
-   * (Anthropic `tool_result.content` arrays, OpenAI Codex pi-ai `toolResult` blocks).
+   * Generic per-tool argument deduplication. Keyed by the tool's **canonical**
+   * name (alias-stable). Each entry is a hasher: `(input) => string | undefined`.
    *
-   * 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.
+   * **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).
    */
-  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;
-  };
+  dedupTools?: Record<string, (input: Record<string, unknown>) => string | undefined>;
   /**
-   * 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.
+   * 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.
    *
-   * Default: `false` (providers opt callers in — the agent loop passes `true`).
+   * Requires a session. Off by default; turn it on for stricter eval-grade
+   * runs where silent edit corruption would invalidate the result.
+   *
+   * Default: `false`.
    */
-  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>;
+  requireReadBeforeEdit?: boolean;
   /**
-   * Build a user `SessionMessage` from multimodal prompt parts.
+   * 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`.
    *
-   * 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.
+   * - `'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'`.
    */
-  promptMessage?: (parts: PromptPart[]) => SessionMessage;
+  compactStrategy?: 'off' | 'tail';
   /**
-   * 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.
+   * 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.
    */
-  classifyError?: (err: unknown) => ClassifiedError | null;
-}
-//#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;
-}
-/**
- * Create a single-session `SessionStore` backed by a file-map adapter.
- *
- * @example
- * ```ts
- * const session = await createSession({
- *   store: createFileMapStore(hostSessionStore),
- * })
- * ```
- */
-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;
+  compactThreshold?: number;
   /**
-   * 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.
+   * 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`.
    */
-  parentRunId?: string;
+  compactKeepTurns?: number;
   /**
-   * Zero-based subagent depth. 0 = top-level run, 1 = direct child, …
-   * Recorded here so hosts can query/filter by level without walking the tree.
+   * 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.
+   *
+   * Default: `true`.
    */
-  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[];
+  readLineNumbers?: boolean;
+  /**
+   * 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.
+   *
+   * 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.
+   *
+   * Default: `false`.
+   */
+  elideStaleReads?: boolean;
   /**
-   * True when this session has no turns yet.
+   * 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).
    *
-   * 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`.
+   * 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'`.
    */
-  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>;
+  toolDisclosure?: 'eager' | 'lazy';
   /**
-   * 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.
+   * 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).
    */
-  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;
+  toolSearch?: {
+    tool?: false;
+    limit?: number;
+  };
 }
 /**
- * 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.
+ * One block of a multimodal user prompt.
  *
- * 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.
+ * `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.
  */
-interface SkillResource {
-  /** Relative path from skill directory */
-  path: string;
-  /** Resource type inferred from directory */
-  type: 'script' | 'reference' | 'asset' | 'other';
+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;
 }
 /**
- * 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.
+ * 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 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;
+type ToolResultContent = ToolResultTextContent | ToolResultImageContent;
+interface ToolResultTextContent {
+  type: 'text';
+  text: 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;
-  /**
-   * 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.
-   */
-  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;
-  /**
-   * Flat key-value metadata bag per the spec. For Zidane-specific hints,
-   * use the `zidane.` key prefix (e.g. `metadata['zidane.paths']`).
-   */
-  metadata?: Record<string, string>;
-  /** Pre-approved tool names (experimental per spec) */
-  allowedTools?: string[];
-  /** Bundled resource files discovered in the skill directory */
-  resources?: SkillResource[];
-  /**
-   * Lenient-load warnings recorded during parsing. Host SDKs can surface these
-   * as inline UI hints. Absent when no issues were found.
-   */
-  diagnostics?: SkillDiagnostic[];
+interface ToolResultImageContent {
+  type: 'image';
+  /** IANA media type (e.g. `image/png`, `image/jpeg`) */
+  mediaType: string;
+  /** Base64-encoded payload */
+  data: string;
 }
-interface SkillsConfig {
+/**
+ * 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;
   /**
-   * 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
+   * 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).
    */
-  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;
+  output: string | ToolResultContent[];
+  isError?: boolean;
+} | {
+  type: 'thinking';
+  text: string;
+  signature?: string;
   /**
-   * 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).
+   * 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.
    */
-  tool?: boolean;
+  signatureProducer?: 'anthropic' | 'openai';
+} | {
+  type: 'redacted_thinking';
+  data: string;
+} | {
   /**
-   * Cap on concurrently active skills per run. Default `undefined` (unlimited).
-   * Attempts to activate past the cap throw from `skills_use`.
+   * 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.
+   *
+   * 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).
    */
-  maxActive?: number;
-  /** Script timeout for `skills_run_script`, in milliseconds. Default `60000`. */
-  scriptTimeoutMs?: number;
+  type: 'provider_reasoning';
+  producer: 'openrouter';
+  details: unknown[];
   /**
-   * 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.
+   * 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.
    */
-  trustProjectSkills?: boolean;
+  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;
 }
-//#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.
+   * User prompt. Optional when resuming a session with existing turns.
    *
-   * 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.
+   * 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/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/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()`.
+ * Reason the provider gave for stopping the turn.
+ *
+ * - `'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.
  */
-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;
+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;
   /**
-   * 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.
+   * 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).
    */
-  activate: (skill: SkillConfig, via: ActivationVia) => 'ok' | 'already-active' | 'cap-reached';
+  finishReason?: TurnFinishReason;
   /**
-   * Mark a skill as inactive. Returns the removed `ActiveSkill` record or `undefined`
-   * if it wasn't active. Callers fire `skills:deactivate` on removal.
+   * 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.
    */
-  deactivate: (name: string) => ActiveSkill | undefined;
-  /** Remove every active skill. Returns the list of removed records. */
-  clear: () => readonly ActiveSkill[];
+  modelId?: string;
 }
-interface SkillActivationStateOptions {
+interface AgentStats {
   /**
-   * Cap on concurrent activations. `undefined` (the default) disables the cap.
-   * When set, `activate()` returns `'cap-reached'` once the set is at size `maxActive`.
+   * Cumulative input tokens across the parent agent loop **and** every
+   * recursively-spawned sub-agent. Use this for billing / token-ledger
+   * consumption.
    */
-  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;
+  totalIn: number;
+  /** Cumulative output tokens. Same semantics as {@link AgentStats.totalIn}. */
+  totalOut: 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).
-   *
-   * `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.
+   * 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.
    */
-  '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;
+  totalCacheRead: number;
   /**
-   * 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.
+   * 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.
    */
-  '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;
+  totalCacheCreation: number;
   /**
-   * 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).
+   * 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).
    *
-   * The post-hook value flows through `tool:transform` like a normal output, so
-   * downstream byte-budgeting and image-stripping still apply.
+   * Tree-wide turn count: `flattenTurns(stats).length`.
    */
-  '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;
+  turns: number;
   /**
-   * 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.
+   * 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.
+   */
+  elapsed: number;
+  /**
+   * 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.
+   */
+  turnUsage?: TurnUsage[];
+  /**
+   * 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).
    *
-   * Fires for any unknown tool name — including hallucinated MCP-style names
-   * (`mcp_supabase_xxx`); branch on `name.startsWith('mcp_')` to differentiate.
+   * Absent when the run produced no observable signals (e.g. aborted before any stream event).
    */
-  'tool:unknown': (ctx: ToolHookContext & {
-    result?: string | ToolResultContent[];
-    suppressError: boolean;
-  }) => void;
+  timeTillFirstTokenMs?: number;
+}
+interface ChildRunStats {
+  id: string;
+  task: string;
   /**
-   * 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.
+   * 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.
+   */
+  stats: AgentStats;
+  /**
+   * 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.
+   */
+  depth?: number;
+  /**
+   * 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.
    */
-  'validation:reject': (ctx: ToolHookContext & {
-    reason: string;
-    schema: Record<string, unknown>;
-  }) => void;
+  status?: 'completed' | 'aborted' | 'timeout' | 'error';
   /**
-   * 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.
-   *
-   * `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)`.
+   * 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.
    */
-  'validation:coerce': (ctx: ToolHookContext & {
-    coercions: readonly string[];
-    schema: Record<string, unknown>;
-  }) => void;
-  'context:transform': (ctx: {
-    messages: SessionMessage[];
-  }) => void;
+  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;
   /**
-   * 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).
-   *
-   * 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.
-   *
-   * `messages` is read-only here; use `context:transform` for message
-   * surgery. `session` is `undefined` when the run is sessionless.
+   * 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`).
    */
-  '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;
-  '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;
+  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;
   /**
-   * 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.
+   * 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).
    */
-  'mcp:bootstrap:start': (ctx: {
-    name: string;
-    transport: string;
-  }) => void;
+  baseURL?: string;
   /**
-   * 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`.
+   * 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.
+   *
+   * Honored on both the OAuth and API-key paths.
    */
-  'mcp:bootstrap:end': (ctx: {
-    name: string;
-    transport: string;
-    durationMs: number;
-  } & ({
-    ok: true;
-    toolCount: number;
-  } | {
-    ok: false;
-    error: Error;
-  })) => void;
+  extraBetas?: readonly string[];
   /**
-   * 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.
+   * 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}.
    *
-   * 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.
+   * Typed loosely so future Anthropic schema additions land without an SDK
+   * bump. A typical compaction edit:
    *
-   * Items are upstream tool descriptors (NOT yet namespaced as `mcp_<server>_<tool>`).
+   * ```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'],
+   *   }],
+   * }
+   * ```
    */
-  'mcp:tools:filter': (ctx: {
-    server: string;
-    transport: 'stdio' | 'sse' | 'streamable-http';
-    tools: Array<{
-      name: string;
-      description?: string | null;
-      inputSchema?: unknown;
-    }>;
-  }) => void;
+  contextManagement?: AnthropicContextManagement;
   /**
-   * 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.
+   * 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.
    *
-   * 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).
+   * 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}.
    */
-  '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;
+  extraBodyParams?: Record<string, unknown>;
+}
+declare function anthropic(anthropicParams?: AnthropicParams): Provider;
+//#endregion
+//#region src/providers/cerebras.d.ts
+interface CerebrasParams {
+  apiKey?: string;
+  defaultModel?: string;
   /**
-   * 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.
+   * 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.
    */
-  'budget:exceeded': (ctx: {
-    turn: number;
-    turnId: string;
-    bytes: number;
-    budget: number;
-  }) => void;
+  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>;
   /**
-   * 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>`.
+   * 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.
    *
-   * `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.
+   * 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).
    */
-  'tool-budget:exceeded': (ctx: {
-    tool: string;
-    count: number;
-    max: number;
-    turnId: string;
-    mode: 'steer' | 'block';
-  }) => void;
-  'agent:abort': (ctx: object) => void;
+  capabilities?: ProviderCapabilities;
   /**
-   * Run finished — fires on all exit paths (completion, maxTurns, abort).
+   * Whether this endpoint honors `cache_control: { type: 'ephemeral' }` markers
+   * on message content parts and tool definitions.
    *
-   * 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`.
+   * - `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`. The `openrouter` wrapper sets this to `true`.
    */
-  '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>;
+  cacheBreakpoints?: boolean;
   /**
-   * Map canonical tool names to LLM-facing (aliased) names.
+   * 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.
    *
-   * 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.
+   * - `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: `false`. The `openrouter` wrapper sets this to `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;
+  supportsReasoning?: 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.
+   * 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.
    *
-   * @internal
+   * 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).
    */
-  mcpConnector?: (configs: McpServerConfig[]) => Promise<McpConnection>;
+  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;
   /**
-   * Pre-connect MCP servers in the background as soon as `createAgent` returns,
-   * instead of deferring the bootstrap to the first `agent.run()`.
-   *
-   * 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.
+   * 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).
    *
-   * No-op when `mcpServers` is empty. Default: `false`.
+   * Override when routing to a known-text-only model (e.g. `meta-llama/llama-3-8b-instruct`).
    */
-  eager?: boolean;
+  capabilities?: ProviderCapabilities;
 }
-interface Agent {
-  hooks: Hookable<AgentHooks>;
-  run: (options: AgentRunOptions) => Promise<AgentStats>;
-  abort: () => void;
-  steer: (message: string) => void;
-  followUp: (message: string) => void;
-  waitForIdle: () => Promise<void>;
+/**
+ * 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 ToolCall {
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+interface ToolResult {
+  id: string;
   /**
-   * 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 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.
    */
-  reset: () => Promise<void>;
+  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 {
   /**
-   * Destroy the execution context and clean up resources.
-   * Idempotent — safe to call from both a `finally` block and a signal handler.
+   * 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.
    */
-  destroy: () => Promise<void>;
+  vision?: boolean;
   /**
-   * 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.
+   * 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.
    */
-  activateSkill: (name: string) => Promise<void>;
+  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;
+  };
   /**
-   * Deactivate a skill by name. Fires `skills:deactivate` with `reason: 'explicit'`.
-   * No-op when the skill wasn't active.
+   * 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`).
    */
-  deactivateSkill: (name: string) => Promise<void>;
+  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>;
   /**
-   * 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.
+   * Build a user `SessionMessage` from multimodal prompt parts.
    *
-   * 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.
+   * 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.
    */
-  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[];
+  promptMessage?: (parts: PromptPart[]) => SessionMessage;
   /**
-   * 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.
+   * 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.
    */
-  readonly meta: Readonly<Record<string, unknown>>;
+  classifyError?: (err: unknown) => ClassifiedError | null;
 }
-declare function createAgent({
-  provider,
-  name: agentName,
-  system: agentSystem,
-  tools: agentTools,
-  toolAliases,
-  behavior: agentBehavior,
-  execution,
-  mcpServers,
-  session,
-  skills: agentSkills,
-  mcpConnector,
-  eager
-}: AgentOptions): Agent;
 //#endregion
-export { OpenAICompatHttpError as $, loadSession as A, ToolExecutionMode as At, FileMapStoreOptions as B, AgentContextExceededError as Bt, SkillsConfig as C, SessionEndStatus as Ct, SessionRun as D, SpawnHookContext as Dt, SessionData as E, SessionTurn as Et, fromOpenAI as F, TurnFinishReason as Ft, StreamOptions as G, ClassifiedErrorKind as Gt, Provider as H, AgentToolNotAllowedError as Ht, toAnthropic as I, TurnUsage as It, ToolSpec as J, ToolCall as K, matchesContextExceeded as Kt, toOpenAI as L, toolOutputByteLength as Lt, createRemoteStore as M, ToolResultContent as Mt, autoDetectAndConvert as N, ToolResultImageContent as Nt, SessionStore as O, StreamHookContext as Ot, fromAnthropic as P, ToolResultTextContent as Pt, OpenAICompatAuthHeader as Q, createMemoryStore as R, toolResultToText as Rt, SkillSource as S, SessionContentBlock as St, Session as T, SessionMessage as Tt, ProviderCapabilities as U, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as Ut, createFileMapStore as V, AgentProviderError as Vt, StreamCallbacks as W, ClassifiedError as Wt, OpenRouterParams as X, TurnResult as Y, openrouter as Z, ToolDef as _, PromptDocumentPart as _t, ActivationVia as a, openai as at, SkillDiagnostic as b, PromptTextPart as bt, SkillActivationState as c, AnthropicParams as ct, McpConnection as d, AgentRunOptions as dt, OpenAICompatParams as et, connectMcpServers as f, AgentStats as ft, ToolContext as g, OAuthRefreshHookContext as gt, resultToString as h, McpToolHookContext as ht, createAgent as i, OpenAIParams as it, RemoteStoreOptions as j, ToolHookContext as jt, createSession as k, ThinkingLevel as kt, SkillActivationStateOptions as l, anthropic as lt, normalizeMcpServers as m, McpServerConfig as mt, AgentHooks as n, mapOAIFinishReason as nt, ActiveSkill as o, CerebrasParams as ot, normalizeMcpBlocks as p, ChildRunStats as pt, ToolResult as q, toTypedError as qt, AgentOptions as r, openaiCompat as rt, DeactivationReason as s, cerebras as st, Agent as t, classifyOpenAICompatError as tt, createSkillActivationState as u, AgentBehavior as ut, ToolMap as v, PromptImagePart as vt, CreateSessionOptions as w, SessionHookContext as wt, SkillResource as x, RunHookMap as xt, SkillConfig as y, PromptPart as yt, FileMapAdapter as z, AgentAbortedError as zt };
-//# sourceMappingURL=agent-BoV5Twdl.d.ts.map
+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