zidane 4.1.8 → 4.1.9

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

@@ -1,4 +1,4 @@
-import { c as ExecutionContext, l as ExecutionHandle } from "./index-BB4kuRh3.js";
+import { c as ExecutionContext, l as ExecutionHandle } from "./index-CXVvqTQj.js";
 import { Hookable } from "hookable";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 //#region src/errors.d.ts
@@ -117,2257 +117,2296 @@ declare function matchesContextExceeded(message: unknown): boolean;
  */
 declare function toTypedError(classification: ClassifiedError, provider: string, cause: unknown): AgentContextExceededError | AgentProviderError | AgentAbortedError;
 //#endregion
-//#region src/mcp/index.d.ts
-interface McpConnection {
-  tools: Record<string, ToolDef>;
-  close: () => Promise<void>;
-}
-/**
- * Normalize MCP server configs from any common shape to `McpServerConfig[]`.
- *
- * Accepts:
- * - `McpServerConfig[]` — zidane native (pass-through).
- * - `McpServerConfig` — a single config object (wrapped to a 1-element array).
- * - `Record<string, RawShape>` — name-keyed map (common in host-SDK configs), where the key is the server name.
- * - Mixed shapes with `type` vs `transport`, `httpUrl`/`sseUrl` vs `url`.
- *
- * Returns `[]` when `input` is nullish. Throws a descriptive error when the transport
- * cannot be inferred from a given entry, or when the input shape is unsupported.
- */
-declare function normalizeMcpServers(input: unknown): McpServerConfig[];
-/**
- * Lossy flattener — converts MCP `CallToolResult.content` blocks to a single
- * string. Text blocks are extracted; non-text blocks are JSON-stringified.
- *
- * Use this only at UI / log boundaries that require a string. The agent
- * loop itself routes through {@link normalizeMcpBlocks} so image blocks
- * survive into provider-native tool_result content (Anthropic blocks,
- * OpenAI companion-user-message).
- */
-declare function resultToString(content: unknown[]): string;
-/**
- * Normalize MCP `CallToolResult.content` to zidane's {@link ToolResultContent[]} shape.
- *
- * Handles the four MCP content block types:
- * - `text` → preserved as `{type:'text', text}`
- * - `image` → preserved as `{type:'image', mediaType, data}` (MCP uses `mimeType`)
- * - `resource` with embedded text → flattened to a text block
- * - `resource` with embedded blob whose `mimeType` is `image/*` → flattened to an image block
- * - Any unrecognized block → JSON-stringified fallback text block (lossy but safe)
- *
- * Returns `null` when the input is not an array — callers should fall back to an empty
- * result in that case.
- */
-declare function normalizeMcpBlocks(content: unknown): ToolResultContent[] | null;
-/**
- * Connect to MCP servers and discover their tools.
- *
- * Each tool is namespaced as `mcp_{serverName}_{toolName}` to avoid
- * collisions with agent tools or tools from other servers.
- *
- * @param configs - Array of MCP server configurations
- * @param _clientFactory - Internal: override client construction for testing
- * @param hooks - Optional agent hooks for firing mcp:connect, mcp:error, mcp:close events
- */
-declare function connectMcpServers(configs: McpServerConfig[], _clientFactory?: () => Client, hooks?: Hookable<AgentHooks>): Promise<McpConnection>;
-//#endregion
-//#region src/session/file-map.d.ts
-/**
- * Host-provided file-map adapter. Three methods exchanging `Record<string, string>`
- * payloads — the whole persistence surface the wrapper needs.
- */
-interface FileMapAdapter {
-  /** Load the current file map. Returns an empty `files` record when nothing is persisted. */
-  get: () => Promise<{
-    files: Record<string, string>;
-  }>;
-  /** Replace the persisted file map. Full-rewrite semantics. */
-  save: (files: Record<string, string>) => Promise<void>;
-  /** Delete all persisted state. */
-  delete: () => Promise<void>;
-}
-interface FileMapStoreOptions {
-  /** Filename for the JSONL turns log. Default: `turns.jsonl`. */
-  turnsFile?: string;
-  /** Filename for the metadata JSON. Default: `meta.json`. */
-  metaFile?: string;
-}
+//#region src/types.d.ts
 /**
- * Create a single-session `SessionStore` backed by a file-map adapter.
+ * Thinking / extended-reasoning configuration.
  *
- * @example
- * ```ts
- * const session = await createSession({
- *   store: createFileMapStore(hostSessionStore),
- * })
- * ```
+ * - `'off'` — no thinking.
+ * - `'minimal' | 'low' | 'medium' | 'high'` — explicit token budget. Maps to
+ *   provider-specific reasoning controls (Anthropic `thinking.type='enabled'`
+ *   with a budget; OpenAI `reasoning_effort`).
+ * - `'adaptive'` — let the model decide per-turn whether and how much to think.
+ *   Anthropic-only (`thinking.type='adaptive'`). Other providers fall back to
+ *   no reasoning when this value is supplied.
  */
-declare function createFileMapStore(adapter: FileMapAdapter, options?: FileMapStoreOptions): SessionStore;
-//#endregion
-//#region src/session/memory.d.ts
-declare function createMemoryStore(): SessionStore;
-//#endregion
-//#region src/session/messages.d.ts
-declare function fromAnthropic(msg: {
-  role: string;
-  content: unknown;
-}): SessionMessage;
-declare function fromOpenAI(msg: {
-  role: string;
-  content: unknown;
-}): SessionMessage;
-declare function toAnthropic(msg: SessionMessage): {
-  role: string;
-  content: unknown;
-};
-declare function toOpenAI(msg: SessionMessage): {
-  role: string;
-  content: unknown;
-};
-declare function autoDetectAndConvert(msg: {
-  role: string;
-  content: unknown;
-}): SessionMessage;
-//#endregion
-//#region src/session/remote.d.ts
-interface RemoteStoreOptions {
-  /** Base URL of the session API */
-  url: string;
-  /** Optional headers (e.g. for authentication) */
-  headers?: Record<string, string>;
-}
-declare function createRemoteStore(options: RemoteStoreOptions): SessionStore;
-//#endregion
-//#region src/session/index.d.ts
-interface SessionRun {
-  id: string;
-  startedAt: number;
-  endedAt?: number;
-  prompt: string;
-  status: 'running' | 'completed' | 'aborted' | 'error';
-  turns?: number;
-  tokensIn?: number;
-  tokensOut?: number;
-  error?: string;
-  /** Per-turn usage breakdown */
-  turnUsage?: TurnUsage[];
-  /** Total usage across all turns */
-  totalUsage?: TurnUsage;
-  /** Estimated cost in USD */
-  cost?: number;
+type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'adaptive';
+interface McpServerConfig {
+  /** Display name (used for tool namespacing) */
+  name: string;
+  /** Transport type */
+  transport: 'stdio' | 'sse' | 'streamable-http';
+  /** For stdio: command to run */
+  command?: string;
+  /** For stdio: command arguments */
+  args?: string[];
   /**
-   * The run that spawned this one, when the agent is a subagent sharing its
-   * parent's session. Undefined on top-level `agent.run()`. Consumers can walk
-   * `runs` by `parentRunId` to reconstruct the subagent tree.
+   * For stdio: environment variables to pass to the server process.
+   *
+   * Merged on top of the MCP SDK's default inherited environment — a safety
+   * whitelist (`PATH`, `HOME`, `LANG`, `SHELL`, `USER` on POSIX; `APPDATA`,
+   * `PATH`, ... on Win32). Setting this to `{}` no longer strips `PATH` from
+   * the child process. Set {@link McpServerConfig.strictEnv} to `true` to
+   * pass `env` verbatim with no inherited defaults.
    */
-  parentRunId?: string;
+  env?: Record<string, string>;
   /**
-   * Zero-based subagent depth. 0 = top-level run, 1 = direct child, …
-   * Recorded here so hosts can query/filter by level without walking the tree.
+   * When true, {@link McpServerConfig.env} is passed verbatim to the spawned
+   * process — the MCP SDK's default inherited environment (`PATH`, `HOME`, ...)
+   * is NOT merged in. Most consumers should leave this off; the default merge
+   * prevents `spawn ENOENT` when a stdio server declares an `env` without
+   * restating `PATH`.
    */
-  depth?: number;
-}
-interface SessionData {
-  id: string;
-  agentId?: string;
-  turns: SessionTurn[];
-  runs: SessionRun[];
-  status: 'idle' | 'running' | 'completed' | 'error';
-  metadata: Record<string, unknown>;
-  createdAt: number;
-  updatedAt: number;
-}
-interface SessionStore {
-  /** Optional: generate a session ID server-side (e.g. Supabase UUID). */
-  generateSessionId?: () => string | Promise<string>;
-  /** Optional: generate a turn ID server-side. */
-  generateTurnId?: () => string | Promise<string>;
-  /** Load a session by ID. Returns null if not found. */
-  load: (sessionId: string) => Promise<SessionData | null>;
-  /** Save a session (create or update, full document). */
-  save: (session: SessionData) => Promise<void>;
-  /** Delete a session. */
-  delete: (sessionId: string) => Promise<void>;
-  /** List session IDs, optionally filtered. */
-  list: (filter?: {
-    agentId?: string;
-    limit?: number;
-  }) => Promise<string[]>;
-  /** Append new turns to a session (incremental, avoids full re-save). */
-  appendTurns: (sessionId: string, turns: SessionTurn[]) => Promise<void>;
-  /** Return a slice of turns for a session. */
-  getTurns: (sessionId: string, from?: number, limit?: number) => Promise<SessionTurn[]>;
-  /** Persist an updated run record (called after completeRun / abortRun / errorRun). */
-  updateRun: (sessionId: string, run: SessionRun) => Promise<void>;
-  /** Update the top-level status of a session. */
-  updateStatus: (sessionId: string, status: SessionData['status']) => Promise<void>;
-}
-interface Session {
-  /** Session ID */
-  readonly id: string;
-  /** Agent ID (optional label) */
-  readonly agentId?: string;
-  /** Current turn history */
-  readonly turns: SessionTurn[];
+  strictEnv?: boolean;
+  /** For sse/streamable-http: server URL */
+  url?: string;
+  /** Optional headers for HTTP transports */
+  headers?: Record<string, string>;
   /**
-   * True when this session has no turns yet.
+   * Timeout in milliseconds for MCP server bootstrap (connect + tool discovery).
    *
-   * Use this as a first-prompt signal when setting up a run — e.g. writing initial
-   * configuration only on fresh sessions. Equivalent to `turns.length === 0`.
+   * Zidane connects MCP servers lazily on the first `run()`. Without a
+   * bootstrap timeout, a slow or hung server can delay the first provider call
+   * for an arbitrarily long time even when that MCP server is never used.
+   *
+   * Default: `10000`.
    */
-  readonly isEmpty: boolean;
-  /** Top-level session status */
-  readonly status: SessionData['status'];
-  /** All runs in this session */
-  readonly runs: SessionRun[];
-  /** Arbitrary metadata */
-  readonly metadata: Record<string, unknown>;
+  bootstrapTimeout?: number;
+  /** Timeout in milliseconds for MCP tool calls (default: 30000) */
+  toolTimeout?: number;
   /**
-   * Start tracking a new run. `extras.parentRunId` + `extras.depth` are
-   * populated by the spawn tool when a child agent shares its parent's
-   * session; regular top-level `agent.run()` calls omit them.
+   * Allow-list of tool names to expose. Names match the upstream tool name
+   * (NOT the namespaced `mcp_{server}_{tool}` form). Tools not in the list are
+   * dropped before registration — the model never sees them in its catalog and
+   * the wire cost of advertising them is avoided.
+   *
+   * Mutually exclusive with {@link McpServerConfig.disabledTools} — passing both
+   * throws at bootstrap time.
+   *
+   * Composes with {@link McpServerConfig.toolFilter}: allow-list applies first,
+   * then the predicate. Composes with the `mcp:tools:filter` hook: config-side
+   * filters apply first, then the hook can further narrow the list.
    */
-  startRun: (runId: string, prompt?: string, extras?: {
-    parentRunId?: string;
-    depth?: number;
-  }) => void;
-  /** Mark a run as completed */
-  completeRun: (runId: string, stats: {
-    turns: number;
-    tokensIn: number;
-    tokensOut: number;
-    turnUsage?: TurnUsage[];
-    cost?: number;
-  }) => void;
-  /** Mark a run as aborted */
-  abortRun: (runId: string) => void;
-  /** Mark a run as errored */
-  errorRun: (runId: string, error: string) => void;
-  /** Append turns to in-memory history AND persist via store.appendTurns (if store present) */
-  appendTurns: (turns: SessionTurn[]) => Promise<void>;
-  /** Replace all turns in-memory (does not persist — use save() for that) */
-  setTurns: (turns: SessionTurn[]) => void;
-  /** Update the session status in memory AND via store.updateStatus (if store present) */
-  updateStatus: (status: SessionData['status']) => Promise<void>;
-  /** Persist an updated run record via store.updateRun (if store present) */
-  updateRun: (run: SessionRun) => Promise<void>;
-  /** Generate a turn ID using store.generateTurnId if available, else crypto.randomUUID() */
-  generateTurnId: () => string | Promise<string>;
-  /** Set metadata key */
-  setMeta: (key: string, value: unknown) => void;
-  /** Persist the full session document to the store */
-  save: () => Promise<void>;
-  /** Serialize to SessionData */
-  toJSON: () => SessionData;
-}
-interface CreateSessionOptions {
-  /** Session ID. If omitted and store provides generateSessionId, that is used. */
-  id?: string;
-  /** Agent ID label */
-  agentId?: string;
-  /** Initial metadata */
-  metadata?: Record<string, unknown>;
-  /** Storage backend (optional, enables save/load) */
-  store?: SessionStore;
-  _data?: SessionData;
-}
-/**
- * Create a new session.
- * Async so stores that generate IDs server-side (e.g. Supabase) can be supported.
- */
-declare function createSession(options?: CreateSessionOptions): Promise<Session>;
-/**
- * Load an existing session from a store.
- */
-declare function loadSession(store: SessionStore, sessionId: string): Promise<Session | null>;
-//#endregion
-//#region src/skills/types.d.ts
-/**
- * Types for the Agent Skills system.
- *
- * Follows the Agent Skills open standard (agentskills.io/specification).
- * Zidane-specific metadata conventionally uses the `zidane.` key prefix
- * (e.g. `metadata['zidane.paths']`) to stay spec-compliant.
- */
-interface SkillResource {
-  /** Relative path from skill directory */
-  path: string;
-  /** Resource type inferred from directory */
-  type: 'script' | 'reference' | 'asset' | 'other';
-}
-/**
- * Where the skill came from. Used for collision precedence (project beats user)
- * and for host SDKs to gate project-level skills on a trust check.
- */
-type SkillSource = 'project' | 'user' | 'inline' | 'builtin';
-/** Severity + code for lenient-load warnings surfaced to host UIs. */
-interface SkillDiagnostic {
-  severity: 'warning' | 'error';
-  /** Stable machine-readable code (e.g. `name-mismatch-directory`). */
-  code: string;
-  /** Human-readable description. */
-  message: string;
-  /** Optional frontmatter field name the diagnostic relates to. */
-  field?: string;
-}
-interface SkillConfig {
-  /** Skill name: 1-64 chars, lowercase alphanumeric + hyphens */
-  name: string;
-  /** What the skill does and when to use it (1-1024 chars) */
-  description: string;
-  /** The SKILL.md body content (after YAML frontmatter) */
-  instructions: string;
+  enabledTools?: string[];
   /**
-   * Where this skill was loaded from. Drives collision precedence and the
-   * `trustProjectSkills` gate. Optional — `parseSkillFile` stamps it; raw
-   * fixtures that omit it are treated as `'project'` by downstream readers.
+   * Deny-list of tool names. Tools matching are dropped before registration.
+   * Same matching semantics as {@link McpServerConfig.enabledTools}.
    */
-  source?: SkillSource;
-  /** Absolute path to SKILL.md (undefined for inline skills) */
-  location?: string;
-  /** Skill directory path for resolving relative references */
-  baseDir?: string;
-  /** License identifier or reference */
-  license?: string;
-  /** Environment requirements */
-  compatibility?: string;
+  disabledTools?: string[];
   /**
-   * Flat key-value metadata bag per the spec. For Zidane-specific hints,
-   * use the `zidane.` key prefix (e.g. `metadata['zidane.paths']`).
+   * Custom predicate run on each upstream tool. Return `true` to keep, `false`
+   * to drop. Receives the raw `listTools()` payload — useful for filtering by
+   * description, schema shape, or other metadata that an allow/deny list can't
+   * express.
+   *
+   * Runs after the allow/deny filter but before the `mcp:tools:filter` hook.
    */
-  metadata?: Record<string, string>;
-  /** Pre-approved tool names (experimental per spec) */
-  allowedTools?: string[];
-  /** Bundled resource files discovered in the skill directory */
-  resources?: SkillResource[];
+  toolFilter?: (tool: {
+    name: string;
+    description?: string | null;
+    inputSchema?: unknown;
+  }) => boolean;
   /**
-   * Lenient-load warnings recorded during parsing. Host SDKs can surface these
-   * as inline UI hints. Absent when no issues were found.
+   * Per-server override for {@link AgentBehavior.toolDisclosure}. When set,
+   * this server's tools follow this disclosure mode regardless of the
+   * agent-wide default. Useful when one big MCP server (200+ tools) should
+   * stay lazy while smaller servers stay eager.
+   *
+   * Default: inherits from `behavior.toolDisclosure`.
    */
-  diagnostics?: SkillDiagnostic[];
+  disclosure?: 'eager' | 'lazy';
 }
-interface SkillsConfig {
+type ToolExecutionMode = 'sequential' | 'parallel';
+interface AgentBehavior {
+  /** Tool execution mode (default: 'sequential') */
+  toolExecution?: ToolExecutionMode;
   /**
-   * Control which skills are active.
-   * - `true` (default): all discovered skills are enabled
-   * - `false` or `[]`: fully disable the skills system (no resolution, no catalog, no hooks)
-   * - `string[]`: allowlist — only skills with matching names are enabled
+   * Max agent loop iterations.
+   *
+   * Default: unlimited (Infinity). The loop runs until the model signals
+   * completion (no tool calls / `end_turn`), the abort signal fires, or this
+   * cap is hit. Set a finite value as a safety net for runaway loops.
    */
-  enabled?: boolean | string[];
-  /** Directories to scan for SKILL.md files */
-  scan?: string[];
-  /** Dynamic skills written to disk at agent start, then loaded normally */
-  write?: SkillConfig[];
-  /** Skill names to exclude from the catalog */
-  exclude?: string[];
-  /** Skip default scan paths (~/.agents/skills, .zidane/skills, etc.) */
-  skipDefaultPaths?: boolean;
+  maxTurns?: number;
+  /** Max tokens per LLM response (default: 16384) */
+  maxTokens?: number;
+  /** Thinking token budget — overrides the level-based default when set */
+  thinkingBudget?: number;
+  /** JSON Schema for structured output enforcement */
+  schema?: Record<string, unknown>;
   /**
-   * Auto-inject `skills_use` / `skills_read` / `skills_run_script` tools
-   * when the catalog is non-empty. Default `true`. Set `false` to opt out
-   * (the system prompt will then instruct the model to use its file-read
-   * tool instead).
+   * Enable provider prompt caching. When on (default), the provider marks the
+   * system prompt, tools, and the last stable message with cache breakpoints so
+   * the shared prefix is served from cache across turns.
+   *
+   * - Anthropic: `cache_control: { type: 'ephemeral' }` on the last `system`
+   *   content part, the last tool, and the last message content part.
+   * - OpenAI-compatible / OpenRouter: same shape — honored by Anthropic-backed
+   *   OpenRouter routes and by Gemini; ignored (no-op) by providers that cache
+   *   automatically (OpenAI, DeepSeek, Grok, Groq, Moonshot).
+   *
+   * Usage is surfaced via `TurnUsage.cacheRead` / `TurnUsage.cacheCreation`.
+   *
+   * Default: `true`.
    */
-  tool?: boolean;
+  cache?: boolean;
   /**
-   * Cap on concurrently active skills per run. Default `undefined` (unlimited).
-   * Attempts to activate past the cap throw from `skills_use`.
+   * Soft per-turn cap on total tool-output bytes. When the sum of `outputBytes`
+   * across a turn's tool results exceeds this value, the loop injects a
+   * synthetic user message instructing the model to summarize before calling
+   * more tools, and fires the `budget:exceeded` hook.
+   *
+   * Measured **post-`tool:transform`** so consumer truncation counts toward the
+   * budget. Off by default (undefined / `0` disables the check). A reasonable
+   * starting value for OSS-model integrations is `32768`.
    */
-  maxActive?: number;
-  /** Script timeout for `skills_run_script`, in milliseconds. Default `60000`. */
-  scriptTimeoutMs?: number;
+  toolOutputBudget?: number;
   /**
-   * When `false`, skills with `source: 'project'` are skipped during
-   * resolution with a diagnostic. Default `true` (preserves existing behavior).
-   * Useful for host SDKs handling untrusted repositories.
+   * Deduplicate identical re-reads of the same file in `read_file`. When the
+   * model re-reads a file with the same slice and the bytes haven't changed
+   * since the last read in this session, the tool returns a short stub
+   * instead of re-emitting the full content. Pairs with the read-before-edit
+   * guard in `edit` / `multi_edit`.
+   *
+   * Requires a session (set via `createSession()`); without one, the flag is
+   * a no-op since per-session state has nowhere to live.
+   *
+   * Default: `true`.
    */
-  trustProjectSkills?: boolean;
-}
-//#endregion
-//#region src/skills/activation.d.ts
-/** How a skill was activated. Surfaced in `skills:activate` hook ctx. */
-type ActivationVia = 'model' | 'explicit' | 'resume';
-/** Reason a skill was deactivated. Surfaced in `skills:deactivate` hook ctx. */
-type DeactivationReason = 'run-end' | 'explicit' | 'reset';
-/** A skill currently active in the state machine. */
-interface ActiveSkill {
-  skill: SkillConfig;
-  activatedAt: number;
-  activatedVia: ActivationVia;
-}
-/**
- * Per-agent skill activation state. Public read-surface is the `active()` list
- * and `isActive(name)` predicate; writes go through `activate()` / `deactivate()`.
- */
-interface SkillActivationState {
-  /** List of currently active skills in activation order. Returns a snapshot. */
-  active: () => readonly ActiveSkill[];
-  /** Is the skill with this canonical name currently active? */
-  isActive: (name: string) => boolean;
-  /** Retrieve the `ActiveSkill` record by name, or `undefined`. */
-  get: (name: string) => ActiveSkill | undefined;
+  dedupReads?: boolean;
   /**
-   * Mark a skill as active.
-   * - Returns `'ok'` on a fresh activation (caller should fire `skills:activate`).
-   * - Returns `'already-active'` if the skill was already in the set (idempotent).
-   * - Returns `'cap-reached'` if the `maxActive` cap would be exceeded. State is unchanged.
+   * Taper the thinking budget over the course of a run. Late turns are
+   * usually checkpoint / cleanup work where reasoning rarely pays for
+   * itself; early turns benefit most. Two forms:
+   *
+   * - **Struct** — geometric decay starting after `afterTurn`, multiplying by
+   *   `factor` each subsequent turn, clamped to `floor`. Example
+   *   `{ afterTurn: 5, factor: 0.5, floor: 1024 }` with a base budget of 8192:
+   *   turns 1-5 = 8192, turn 6 = 4096, turn 7 = 2048, turn 8+ = 1024.
+   * - **Function** — `(runTurn, baseBudget) => number`. Arbitrary curves;
+   *   `runTurn` is 1-indexed, run-relative (resumed sessions reset).
+   *
+   * No-op when `thinkingBudget` is unset. Honored by every provider that
+   * respects `thinkingBudget` (anthropic explicit-budget `enabled` path,
+   * adaptive `maxTokensCap`, openai-compat `max_tokens` padding).
+   *
+   * Default: `undefined` (no decay).
    */
-  activate: (skill: SkillConfig, via: ActivationVia) => 'ok' | 'already-active' | 'cap-reached';
-  /**
-   * Mark a skill as inactive. Returns the removed `ActiveSkill` record or `undefined`
-   * if it wasn't active. Callers fire `skills:deactivate` on removal.
-   */
-  deactivate: (name: string) => ActiveSkill | undefined;
-  /** Remove every active skill. Returns the list of removed records. */
-  clear: () => readonly ActiveSkill[];
-}
-interface SkillActivationStateOptions {
-  /**
-   * Cap on concurrent activations. `undefined` (the default) disables the cap.
-   * When set, `activate()` returns `'cap-reached'` once the set is at size `maxActive`.
-   */
-  maxActive?: number;
-}
-declare function createSkillActivationState(options?: SkillActivationStateOptions): SkillActivationState;
-//#endregion
-//#region src/agent.d.ts
-interface AgentHooks {
-  'system:before': (ctx: {
-    system: string;
-  }) => void;
-  'turn:before': (ctx: {
-    turn: number;
-    turnId: string;
-    options: StreamOptions;
-  }) => void;
+  thinkingDecay?: {
+    afterTurn: number;
+    factor: number;
+    floor: number;
+  } | ((runTurn: number, baseBudget: number) => number);
   /**
-   * Fires after each assistant turn (before its tool-result follow-up
-   * dispatches; the loop iterates back to a fresh `turn:before` once the
-   * tool results are produced).
+   * Per-tool soft call budget for this run. Keyed by **canonical** tool name.
+   * On the first call after the run-cumulative dispatched count for that tool
+   * reaches `max`, the framework fires `onExceed`:
    *
-   * `toolCounts.turn` — calls **emitted** by the model in this assistant
-   * turn, keyed by canonical tool name. Reflects what the model asked for,
-   * regardless of downstream gate outcome. Most useful for spotting per-turn
-   * spikes ("the model called todowrite 4 times in one turn").
+   * - `'steer'` (default) — let the call execute, but emit a synthetic user
+   *   message after the turn that nudges the model away from re-calling the
+   *   tool. Reuses the existing post-turn steer pathway used by
+   *   `toolOutputBudget`. Fires `tool-budget:exceeded` with `mode: 'steer'`.
+   * - `'block'` — refuse the call via `tool:gate` `block`. The model sees a
+   *   `Blocked: <reason>` tool result. Fires `tool-budget:exceeded` with
+   *   `mode: 'block'`.
+   * - **Function** — `(ctx) => { mode, message }`. The consumer supplies the
+   *   steering / refusal text and chooses the mode dynamically.
    *
-   * `toolCounts.run` — cumulative running counter of **dispatched** calls
-   * scoped to this `runId`, captured at fire time. Excludes calls that were
-   * `block`ed by `tool:gate` handlers. Includes calls short-circuited via
-   * `tool:gate` `result` substitution (the model still asked, the framework
-   * just answered without the tool running). Resumed sessions start a fresh
-   * run with empty counts.
+   * Counts include both real dispatches and dedup substitutes (Z19 hits).
+   * Excludes calls already blocked by an earlier gate (skill allow-list,
+   * consumer hook). Tool dispatched by spawned subagents has its own per-run
+   * counter — child counts never charge the parent.
    *
-   * Both fields are frozen snapshots; mutate-safe.
+   * For MCP tools, key by the namespaced wire name (`mcp_<server>_<tool>`).
+   *
+   * Atomic in parallel mode: the middleware tracks its own per-tool
+   * approval counter, incremented synchronously at gate-time. A
+   * 4-call parallel batch against `max: 2` will let the first 2 through
+   * and refuse the rest, even though the loop's `runToolCounts` only
+   * propagates between calls (not within a single batch's gate fan-out).
+   *
+   * Default: `undefined` (no budget enforcement).
    */
-  'turn:after': (ctx: {
-    turn: number;
-    turnId: string;
-    usage: TurnUsage;
-    message: SessionTurn;
-    toolCounts: {
-      turn: Readonly<Record<string, number>>;
-      run: Readonly<Record<string, number>>;
-    };
-  }) => void;
-  'stream:text': (ctx: StreamHookContext & {
-    delta: string;
-    text: string;
-  }) => void;
-  'stream:end': (ctx: StreamHookContext & {
-    text: string;
-  }) => void;
-  'stream:thinking': (ctx: StreamHookContext & {
-    delta: string;
-    thinking: string;
-  }) => void;
-  'oauth:refresh': (ctx: OAuthRefreshHookContext) => void;
+  toolBudgets?: Record<string, {
+    max: number;
+    onExceed?: 'steer' | 'block' | ((ctx: {
+      tool: string;
+      count: number;
+      max: number;
+    }) => {
+      mode: 'steer' | 'block';
+      message: string;
+    });
+  }>;
   /**
-   * Fires before validation, `tool:before`, and `execute`. Two ways to
-   * intercept:
+   * Generic per-tool argument deduplication. Keyed by the tool's **canonical**
+   * name (alias-stable). Each entry is a hasher: `(input) => string | undefined`.
    *
-   * - 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.
+   * **Hasher contract** — three return values, three meanings:
    *
-   * 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.
+   * | 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).    |
    *
-   * `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.
+   * 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:
    *
-   * **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.
+   * ```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).
    */
-  '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;
+  dedupTools?: Record<string, (input: Record<string, unknown>) => string | undefined>;
   /**
-   * 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).
+   * 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.
    *
-   * The post-hook value flows through `tool:transform` like a normal output, so
-   * downstream byte-budgeting and image-stripping still apply.
+   * Requires a session. Off by default; turn it on for stricter eval-grade
+   * runs where silent edit corruption would invalidate the result.
+   *
+   * Default: `false`.
    */
-  '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;
+  requireReadBeforeEdit?: boolean;
   /**
-   * 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.
+   * Client-side context compaction strategy. Use this for non-Anthropic
+   * providers (OSS via cerebras / openai-compat / openrouter) that don't
+   * have a server-side equivalent. Anthropic users should prefer the
+   * server-side `context-management-2025-06-27` beta — see
+   * `AnthropicParams.contextManagement`.
    *
-   * Fires for any unknown tool name — including hallucinated MCP-style names
-   * (`mcp_supabase_xxx`); branch on `name.startsWith('mcp_')` to differentiate.
+   * - `'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'`.
    */
-  'tool:unknown': (ctx: ToolHookContext & {
-    result?: string | ToolResultContent[];
-    suppressError: boolean;
-  }) => void;
+  compactStrategy?: 'off' | 'tail';
   /**
-   * 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.
+   * 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.
    */
-  'validation:reject': (ctx: ToolHookContext & {
-    reason: string;
-    schema: Record<string, unknown>;
-  }) => void;
+  compactThreshold?: number;
   /**
-   * 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)`.
+   * 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`.
    */
-  'validation:coerce': (ctx: ToolHookContext & {
-    coercions: readonly string[];
-    schema: Record<string, unknown>;
-  }) => void;
-  'context:transform': (ctx: {
-    messages: SessionMessage[];
-  }) => void;
+  compactKeepTurns?: number;
   /**
-   * 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).
+   * 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.
    *
-   * 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.
+   * 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.
    *
-   * `messages` is read-only here; use `context:transform` for message
-   * surgery. `session` is `undefined` when the run is sessionless.
+   * Default: `true`.
    */
-  '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;
+  readLineNumbers?: boolean;
   /**
-   * 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.
+   * 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.
    *
-   * Use these to gate subagent tool calls (native + MCP) from the parent
-   * without registering listeners on every child agent. The parent's own
-   * `tool:gate` / `mcp:tool:gate` listeners are NOT auto-shared with
-   * children — that would also share their budgets and dedup state.
-   */
-  'child:tool:gate': (ctx: ToolHookContext & {
-    block: boolean;
-    reason: string;
-    result?: string | ToolResultContent[];
-    runToolCounts: Readonly<Record<string, number>>;
-    childId: string;
-    depth: number;
-  }) => void;
-  'child:mcp:tool:gate': (ctx: McpToolHookContext & {
-    block: boolean;
-    reason: string;
-    result?: string | ToolResultContent[];
-    childId: string;
-    depth: number;
-  }) => void;
-  'child:tool:before': (ctx: ToolHookContext & {
-    coercions?: readonly string[];
-    runToolCounts: Readonly<Record<string, number>>;
-    childId: string;
-    depth: number;
-  }) => void;
-  'child:tool:after': (ctx: ToolHookContext & {
-    result: string | ToolResultContent[];
-    outputBytes: number;
-    coercions?: readonly string[];
-    runToolCounts: Readonly<Record<string, number>>;
-    childId: string;
-    depth: number;
-  }) => void;
-  'child:tool:error': (ctx: ToolHookContext & {
-    error: Error;
-    childId: string;
-    depth: number;
-  }) => void;
-  'child:turn:after': (ctx: {
-    turn: number;
-    turnId: string;
-    usage: TurnUsage;
-    message: SessionTurn;
-    toolCounts: {
-      turn: Readonly<Record<string, number>>;
-      run: Readonly<Record<string, number>>;
-    };
-    childId: string;
-    depth: number;
-  }) => void;
-  'mcp:connect': (ctx: {
-    name: string;
-    transport: string;
-    tools: string[];
-  }) => void;
-  'mcp:error': (ctx: {
-    name: string;
-    error: Error;
-  }) => void;
-  'mcp:close': (ctx: {
-    name: string;
-  }) => void;
-  /**
-   * Fires at the start of a per-server bootstrap attempt, before any network I/O.
-   * Pairs with `mcp:bootstrap:end` and is always emitted, regardless of outcome.
-   */
-  'mcp:bootstrap:start': (ctx: {
-    name: string;
-    transport: string;
-  }) => void;
-  /**
-   * Fires at the end of a per-server bootstrap attempt. `durationMs` spans from
-   * the matching `mcp:bootstrap:start`. On `ok: false` carries the originating
-   * error so consumers can log / trace without relying on a separate `mcp:error`.
+   * 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`.
    */
-  'mcp:bootstrap:end': (ctx: {
-    name: string;
-    transport: string;
-    durationMs: number;
-  } & ({
-    ok: true;
-    toolCount: number;
-  } | {
-    ok: false;
-    error: Error;
-  })) => void;
+  elideStaleReads?: boolean;
   /**
-   * 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 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).
    *
-   * 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.
+   * 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.
    *
-   * Items are upstream tool descriptors (NOT yet namespaced as `mcp_<server>_<tool>`).
+   * 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'`.
    */
-  'mcp:tools:filter': (ctx: {
-    server: string;
-    transport: 'stdio' | 'sse' | 'streamable-http';
-    tools: Array<{
-      name: string;
-      description?: string | null;
-      inputSchema?: unknown;
-    }>;
-  }) => void;
+  toolDisclosure?: 'eager' | 'lazy';
   /**
-   * 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.
+   * Fine-grained config for the `tool_search` tool auto-injected when
+   * {@link AgentBehavior.toolDisclosure} is `'lazy'`. No-op in eager mode.
    *
-   * 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).
+   * - `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).
    */
-  '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;
-  /**
-   * Fires when a turn's total tool-output bytes exceed `behavior.toolOutputBudget`.
-   * Measured post-`tool:transform`. Loop injects a synthetic user message after
-   * the tool-results turn instructing the model to summarize.
-   */
-  'budget:exceeded': (ctx: {
-    turn: number;
-    turnId: string;
-    bytes: number;
-    budget: number;
-  }) => void;
-  /**
-   * Fires when a per-tool budget configured via `behavior.toolBudgets` is
-   * exceeded for a specific tool. `mode` reflects how the framework reacted:
-   * `'steer'` lets the call run and queues a post-turn nudge; `'block'`
-   * refuses the call outright with `Blocked: <message>`.
-   *
-   * `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.
-   */
-  'tool-budget:exceeded': (ctx: {
-    tool: string;
-    count: number;
-    max: number;
-    turnId: string;
-    mode: 'steer' | 'block';
-  }) => void;
-  'agent:abort': (ctx: object) => void;
-  /**
-   * Run finished — fires on all exit paths (completion, maxTurns, abort).
-   *
-   * Since 4.0 the `AgentStats` carried here is **cumulative** across the
-   * parent agent loop and every recursively-spawned sub-agent
-   * (`totalIn` / `totalOut` / `cost` / `totalCacheRead` / `totalCacheCreation`).
-   * For parent-loop-only counts use `ctx.turnUsage` (parent-only array);
-   * for tree-wide turn counts use `flattenTurns(ctx).length`.
-   */
-  'agent:done': (ctx: AgentStats) => void;
-  'session:start': (ctx: SessionHookContext & {
-    runId: string;
-    prompt: string;
-  }) => void;
-  'session:end': (ctx: SessionHookContext & {
-    runId: string;
-    status: SessionEndStatus;
-    turnRange: [number, number];
-  }) => void;
-  'session:turns': (ctx: SessionHookContext & {
-    turns: SessionTurn[];
-    count: number;
-  }) => void;
-  'session:meta': (ctx: SessionHookContext & {
-    key: string;
-    value: unknown;
-  }) => void;
-  'session:save': (ctx: SessionHookContext) => void;
+  toolSearch?: {
+    tool?: false;
+    limit?: number;
+  };
 }
-interface AgentOptions {
-  provider: Provider;
-  /** Display name for the agent (used in traces/logs). */
+/**
+ * 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;
-  /** 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>;
+}
+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;
   /**
-   * Map canonical tool names to LLM-facing (aliased) names.
-   *
-   * 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.
+   * 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).
    */
-  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;
+  output: string | ToolResultContent[];
+  isError?: boolean;
+} | {
+  type: 'thinking';
+  text: string;
+  signature?: string;
   /**
-   * 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.
-   *
-   * @internal
+   * 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.
    */
-  mcpConnector?: (configs: McpServerConfig[]) => Promise<McpConnection>;
+  signatureProducer?: 'anthropic' | 'openai';
+} | {
+  type: 'redacted_thinking';
+  data: 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.
+   * 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.
    *
-   * No-op when `mcpServers` is empty. Default: `false`.
-   */
-  eager?: boolean;
-}
-interface Agent {
-  hooks: Hookable<AgentHooks>;
-  run: (options: AgentRunOptions) => Promise<AgentStats>;
-  abort: () => void;
-  steer: (message: string) => void;
-  followUp: (message: string) => void;
-  waitForIdle: () => Promise<void>;
-  /**
-   * 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.
+   * 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).
    */
-  reset: () => Promise<void>;
+  type: 'provider_reasoning';
+  producer: 'openrouter';
+  details: unknown[];
   /**
-   * Destroy the execution context and clean up resources.
-   * Idempotent — safe to call from both a `finally` block and a signal handler.
+   * 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.
    */
-  destroy: () => Promise<void>;
+  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;
   /**
-   * 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.
+   * User prompt. Optional when resuming a session with existing turns.
+   *
+   * Accepts either a plain string (single text part) or an array of `PromptPart`s for
+   * multimodal inputs (text, images, documents). See {@link PromptPart}.
    */
-  activateSkill: (name: string) => Promise<void>;
+  prompt?: string | PromptPart[];
+  system?: string;
+  thinking?: ThinkingLevel;
+  /** Abort signal — when triggered, the agent stops after the current turn */
+  signal?: AbortSignal;
+  /** Behavior overrides for this run (overrides agent defaults) */
+  behavior?: AgentBehavior;
+  /** Tool overrides for this run. Pass {} for no tools. Omit to use agent tools. */
+  tools?: Record<string, ToolDef>;
   /**
-   * Deactivate a skill by name. Fires `skills:deactivate` with `reason: 'explicit'`.
-   * No-op when the skill wasn't active.
+   * Per-run hook registrations. Each hook is attached before the run starts and
+   * detached in a finally block so handlers never leak across runs.
+   *
+   * Accepts either a single handler or an array (all handlers register).
    */
-  deactivateSkill: (name: string) => Promise<void>;
+  hooks?: RunHookMap;
   /**
-   * 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.
+   * 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.
    */
-  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[];
+  parentRunId?: string;
   /**
-   * 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.
+   * 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.
    */
-  readonly meta: Readonly<Record<string, unknown>>;
+  depth?: number;
 }
-declare function createAgent({
-  provider,
-  name: agentName,
-  system: agentSystem,
-  tools: agentTools,
-  toolAliases,
-  behavior: agentBehavior,
-  execution,
-  mcpServers,
-  session,
-  skills: agentSkills,
-  mcpConnector,
-  eager
-}: AgentOptions): Agent;
-//#endregion
-//#region src/tools/types.d.ts
 /**
- * Runtime context passed to every tool execution.
- * Provides access to the agent's provider, abort signal, execution environment, and hooks.
+ * Reason the provider gave for stopping the turn.
  *
- * The preset-y fields (`name`, `system`, `tools`, `toolAliases`, `mcpServers`, `skills`,
- * `behavior`) mirror the agent's own options so child-spawning tools can inherit them.
+ * - `'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 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 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;
   /**
-   * 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.
+   * 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).
    */
-  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;
+  finishReason?: TurnFinishReason;
   /**
-   * 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.
+   * 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.
    */
-  runId?: string;
+  modelId?: string;
+}
+interface AgentStats {
   /**
-   * 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.
+   * Cumulative input tokens across the parent agent loop **and** every
+   * recursively-spawned sub-agent. Use this for billing / token-ledger
+   * consumption.
    */
-  session?: Session;
+  totalIn: number;
+  /** Cumulative output tokens. Same semantics as {@link AgentStats.totalIn}. */
+  totalOut: number;
   /**
-   * 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.
+   * 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.
    */
-  depth?: number;
-}
-interface ToolDef {
-  spec: ToolSpec;
+  totalCacheRead: number;
   /**
-   * 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).
+   * 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.
    */
-  execute: (input: Record<string, unknown>, ctx: ToolContext) => Promise<string | ToolResultContent[]>;
-}
-type ToolMap = Map<string, ToolDef>;
-//#endregion
-//#region src/types.d.ts
-/**
- * Thinking / extended-reasoning configuration.
- *
- * - `'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.
- */
-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[];
+  totalCacheCreation: number;
   /**
-   * For stdio: environment variables to pass to the server process.
+   * 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).
    *
-   * 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.
+   * Tree-wide turn count: `flattenTurns(stats).length`.
    */
-  env?: Record<string, string>;
+  turns: number;
   /**
-   * 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`.
+   * 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.
    */
-  strictEnv?: boolean;
-  /** For sse/streamable-http: server URL */
-  url?: string;
-  /** Optional headers for HTTP transports */
-  headers?: Record<string, string>;
+  elapsed: number;
   /**
-   * Timeout in milliseconds for MCP server bootstrap (connect + tool discovery).
-   *
-   * Zidane connects MCP servers lazily on the first `run()`. Without a
-   * bootstrap timeout, a slow or hung server can delay the first provider call
-   * for an arbitrarily long time even when that MCP server is never used.
-   *
-   * Default: `10000`.
+   * 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.
    */
-  bootstrapTimeout?: number;
-  /** Timeout in milliseconds for MCP tool calls (default: 30000) */
-  toolTimeout?: number;
+  turnUsage?: TurnUsage[];
   /**
-   * 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.
+   * 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).
    *
-   * 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.
+   * Absent when the run produced no observable signals (e.g. aborted before any stream event).
    */
-  enabledTools?: string[];
+  timeTillFirstTokenMs?: number;
+}
+interface ChildRunStats {
+  id: string;
+  task: string;
   /**
-   * Deny-list of tool names. Tools matching are dropped before registration.
-   * Same matching semantics as {@link McpServerConfig.enabledTools}.
+   * 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.
    */
-  disabledTools?: string[];
+  stats: AgentStats;
   /**
-   * 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.
+   * 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.
    */
-  toolFilter?: (tool: {
-    name: string;
-    description?: string | null;
-    inputSchema?: unknown;
-  }) => boolean;
+  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.
+   */
+  status?: 'completed' | 'aborted' | 'timeout' | 'error';
+  /**
+   * 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.
+   */
+  output?: Record<string, unknown>;
+}
+/**
+ * Base context for tool execution hooks.
+ *
+ * `name` is the canonical tool identity — the spec name registered on the agent (or the
+ * `mcp_{server}_{tool}` name for MCP tools). Hooks should policy-match against `name`.
+ *
+ * `displayName` is the outward-facing name — the alias surfaced to the LLM when
+ * `AgentOptions.toolAliases` maps the canonical name; otherwise equal to `name`.
+ * UI/telemetry adapters should emit `displayName`.
+ *
+ * Canonical vs. alias matters on session resume: `session.turns` persists canonical
+ * names only, so renaming an alias cannot desync history.
+ */
+interface ToolHookContext {
+  turnId: string;
+  callId: string;
+  /** Canonical tool name (spec name). Stable across alias-map changes. */
+  name: string;
+  /** Aliased (wire) name — equal to `name` when no alias is defined. */
+  displayName: string;
+  input: Record<string, unknown>;
+}
+/**
+ * Base context for MCP tool hooks.
+ *
+ * `tool` is the native tool name on the MCP server. `server` is the configured server
+ * name. The canonical zidane-namespaced identity is `mcp_{server}_{tool}`.
+ *
+ * `displayName` equals the canonical namespaced name unless the agent has aliased
+ * this MCP tool via `AgentOptions.toolAliases`; in which case `displayName` is the
+ * alias that the LLM sees.
+ */
+interface McpToolHookContext {
+  turnId: string;
+  callId: string;
+  server: string;
+  tool: string;
+  /** Aliased wire name for this MCP tool, or the canonical `mcp_{server}_{tool}` name. */
+  displayName: string;
+  input: Record<string, unknown>;
+}
+/** Base context for session hooks */
+interface SessionHookContext {
+  sessionId: string;
+}
+/** Base context for spawn hooks */
+interface SpawnHookContext {
+  id: string;
+  task: string;
   /**
-   * Per-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`.
+   * 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`).
    */
-  disclosure?: 'eager' | 'lazy';
+  depth?: number;
 }
-type ToolExecutionMode = 'sequential' | 'parallel';
-interface AgentBehavior {
-  /** Tool execution mode (default: 'sequential') */
-  toolExecution?: ToolExecutionMode;
+/** 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;
   /**
-   * 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.
+   * 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).
    */
-  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>;
+  baseURL?: string;
   /**
-   * 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).
+   * 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:
    *
-   * Usage is surfaced via `TurnUsage.cacheRead` / `TurnUsage.cacheCreation`.
+   * - `'context-management-2025-06-27'` — server-side context compaction
+   *   (token-accurate; pair with {@link AnthropicParams.contextManagement}).
+   * - `'token-efficient-tools-2026-03-28'` — terser tool_use wire format.
+   * - `'interleaved-thinking-2025-05-14'` — think between tool calls within
+   *   one turn.
+   * - `'redact-thinking-2026-02-12'` — replace large thinking blocks with
+   *   stubs server-side.
+   * - `'prompt-caching-scope-2026-01-05'` — extended prompt-cache scope.
    *
-   * Default: `true`.
+   * Honored on both the OAuth and API-key paths.
    */
-  cache?: boolean;
+  extraBetas?: readonly string[];
   /**
-   * 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.
+   * 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}.
    *
-   * 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`.
+   * Typed loosely so future Anthropic schema additions land without an SDK
+   * bump. A typical compaction edit:
+   *
+   * ```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'],
+   *   }],
+   * }
+   * ```
    */
-  toolOutputBudget?: number;
+  contextManagement?: AnthropicContextManagement;
   /**
-   * 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.
+   * 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.
    *
-   * Default: `true`.
+   * 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}.
    */
-  dedupReads?: boolean;
+  extraBodyParams?: Record<string, unknown>;
+}
+declare function anthropic(anthropicParams?: AnthropicParams): Provider;
+//#endregion
+//#region src/providers/cerebras.d.ts
+interface CerebrasParams {
+  apiKey?: string;
+  defaultModel?: string;
   /**
-   * 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).
+   * 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.
    */
-  thinkingDecay?: {
-    afterTurn: number;
-    factor: number;
-    floor: number;
-  } | ((runTurn: number, baseBudget: number) => number);
+  capabilities?: ProviderCapabilities;
+}
+/**
+ * Cerebras provider.
+ *
+ * Thin wrapper around {@link openaiCompat} with Cerebras-specific defaults
+ * (base URL, default model).
+ */
+declare function cerebras(params?: CerebrasParams): Provider;
+//#endregion
+//#region src/providers/openai.d.ts
+interface OpenAIParams {
+  /** OpenAI Codex OAuth access token. Falls back to OPENAI_CODEX_API_KEY and .credentials.json. */
+  apiKey?: string;
+  /** Alias for apiKey, matching the OAuth credential field. */
+  access?: string;
+  refresh?: string;
+  expires?: number;
+  accountId?: string;
+  defaultModel?: string;
+  transport?: 'sse' | 'websocket' | 'auto';
+}
+declare function openai(params?: OpenAIParams): Provider;
+//#endregion
+//#region src/providers/openai-compat.d.ts
+/**
+ * HTTP error thrown when an OpenAI-compatible endpoint returns a non-OK response.
+ *
+ * The body is best-effort JSON-parsed; `error.message` / `error.code` / `error.type`
+ * are extracted for clean downstream classification.
+ */
+declare class OpenAICompatHttpError extends Error {
+  readonly status: number;
+  readonly providerCode?: string;
+  readonly bodyText: string;
+  constructor(status: number, bodyText: string);
+}
+/**
+ * Classify an OpenAI-compatible error into `ClassifiedError`.
+ *
+ * Recognizes:
+ * - `AbortError` (from fetch) → `aborted`.
+ * - `OpenAICompatHttpError` with a context-exceeded code or message → `context_exceeded`.
+ * - Any other `OpenAICompatHttpError` → `provider_error`.
+ *
+ * Returns `null` for unrecognized error shapes (the loop falls back to `AgentProviderError`).
+ */
+declare function classifyOpenAICompatError(err: unknown): ClassifiedError | null;
+/**
+ * Map an OpenAI-compatible `finish_reason` string to the zidane `TurnFinishReason` union.
+ */
+declare function mapOAIFinishReason(reason: string | null | undefined): TurnFinishReason | undefined;
+/**
+ * Auth header config. `scheme` is prepended to the api key with a space, e.g.
+ * `{ name: 'Authorization', scheme: 'Bearer' }` → `Authorization: Bearer <key>`.
+ * Omit `scheme` for raw header values (e.g. `{ name: 'X-Api-Key' }` → `X-Api-Key: <key>`).
+ *
+ * Real-world examples:
+ * - Default OpenAI / OpenRouter / Cerebras: `{ name: 'Authorization', scheme: 'Bearer' }`.
+ * - Baseten: `{ name: 'Authorization', scheme: 'Api-Key' }`.
+ * - Some gateways: `{ name: 'X-Api-Key' }`.
+ */
+interface OpenAICompatAuthHeader {
+  name: string;
+  scheme?: string;
+}
+interface OpenAICompatParams {
+  /** Bearer-style API key. */
+  apiKey: string;
+  /** Base URL — `/chat/completions` is appended. */
+  baseURL: string;
+  /** Default model id when `run({ model })` is omitted. */
+  defaultModel?: string;
+  /** Provider name exposed as `Provider.name`. Defaults to `'openai-compat'`. */
+  name?: string;
+  /** Auth header shape. Defaults to `{ name: 'Authorization', scheme: 'Bearer' }`. */
+  authHeader?: OpenAICompatAuthHeader;
+  /** Extra headers sent with every request (e.g. referer, user-agent). */
+  extraHeaders?: Record<string, string>;
   /**
-   * 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).
+   * Provider-level capability flags. Routed into the message shaper and the
+   * agent loop so images in tool results + user messages are handled correctly
+   * for the underlying model.
    *
-   * Default: `undefined` (no budget enforcement).
+   * 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).
    */
-  toolBudgets?: Record<string, {
-    max: number;
-    onExceed?: 'steer' | 'block' | ((ctx: {
-      tool: string;
-      count: number;
-      max: number;
-    }) => {
-      mode: 'steer' | 'block';
-      message: string;
-    });
-  }>;
+  capabilities?: ProviderCapabilities;
   /**
-   * 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).    |
+   * Whether this endpoint honors `cache_control: { type: 'ephemeral' }` markers
+   * on message content parts and tool definitions.
    *
-   * 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:
+   * - `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.
    *
-   * ```ts
-   * // Always cache by full input — every identical re-call dedups.
-   * dedupTools: { todowrite: input => JSON.stringify(input) }
+   * Default: `false`. The `openrouter` wrapper sets this to `true`.
+   */
+  cacheBreakpoints?: boolean;
+  /**
+   * 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.
    *
-   * // 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
-   *   },
-   * }
-   * ```
+   * - `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.
    *
-   * 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.
+   * Default: `false`. The `openrouter` wrapper sets this to `true`.
+   */
+  supportsReasoning?: boolean;
+  /**
+   * Generic pass-through for fields on the Chat Completions request body that
+   * zidane does not yet type. Spread into the request before the typed core
+   * (model / messages / tools / max_tokens / stream / tool_choice), so
+   * explicit options always win on collision.
    *
-   * 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.
+   * 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).
+   */
+  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;
+  /**
+   * 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).
    *
-   * 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.
+   * Override when routing to a known-text-only model (e.g. `meta-llama/llama-3-8b-instruct`).
+   */
+  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;
+  /**
+   * 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).
    *
-   * **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.
+   * Use `toolResultToText(content)` when a downstream consumer only handles strings.
+   */
+  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 {
+  /**
+   * Model accepts image input anywhere (user messages and tool results).
    *
-   * Default: `undefined` (no per-tool dedup).
+   * 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.
    */
-  dedupTools?: Record<string, (input: Record<string, unknown>) => string | undefined>;
+  vision?: boolean;
   /**
-   * 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.
+   * Provider wire format embeds images inside tool-role messages natively
+   * (Anthropic `tool_result.content` arrays, OpenAI Codex pi-ai `toolResult` blocks).
    *
-   * Requires a session. Off by default; turn it on for stricter eval-grade
-   * runs where silent edit corruption would invalidate the result.
+   * When `false`, a vision-capable provider still gets images — but via a
+   * companion `user` message emitted immediately after the flattened
+   * `tool`/`tool_result` marker. This is the Claude Desktop / Cline pattern
+   * and works on any OpenAI Chat Completions endpoint that accepts image
+   * URLs in user messages.
+   */
+  imageInToolResult?: boolean;
+}
+interface StreamCallbacks {
+  onText: (delta: string) => void;
+  onThinking?: (delta: string) => void;
+  onOAuthRefresh?: (ctx: OAuthRefreshHookContext) => void | Promise<void>;
+}
+interface TurnResult {
+  /** Full assistant turn as a SessionMessage */
+  assistantMessage: SessionMessage;
+  /** Text content blocks concatenated */
+  text: string;
+  /** Tool calls requested by the model */
+  toolCalls: ToolCall[];
+  /** Whether the model wants to stop */
+  done: boolean;
+  usage: TurnUsage;
+}
+interface StreamOptions {
+  model: string;
+  system: string;
+  tools: unknown[];
+  messages: SessionMessage[];
+  maxTokens: number;
+  /** Thinking/reasoning level (optional, default: off) */
+  thinking?: ThinkingLevel;
+  /** Exact thinking token budget — overrides the level-based default when set */
+  thinkingBudget?: number;
+  /** Force tool selection behavior */
+  toolChoice?: {
+    type: 'auto' | 'required' | 'tool';
+    name?: string;
+  };
+  /**
+   * Enable prompt caching on this call. When `true`, providers that support it
+   * insert `cache_control` breakpoints on the system prompt, last tool, and
+   * last stable message so the shared prefix is cached across turns.
    *
-   * Default: `false`.
+   * Default: `false` (providers opt callers in — the agent loop passes `true`).
    */
-  requireReadBeforeEdit?: boolean;
+  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>;
   /**
-   * 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.
+   * Build a user `SessionMessage` from multimodal prompt parts.
    *
-   * Default: `'off'`.
+   * 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.
    */
-  compactStrategy?: 'off' | 'tail';
+  promptMessage?: (parts: PromptPart[]) => SessionMessage;
   /**
-   * 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.
+   * 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.
    */
-  compactThreshold?: number;
+  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;
   /**
-   * 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`.
+   * 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.
    */
-  compactKeepTurns?: number;
+  parentRunId?: string;
   /**
-   * Prefix every line of `read_file` output with its 1-indexed line number
-   * followed by a tab (`<N>\t<content>`) — the compact `cat -n`-style
-   * format Claude Code emits. The `edit` tool strips the prefix from
-   * `old_string` / `new_string` so the model can paste back a numbered
-   * chunk verbatim without breaking the match.
-   *
-   * Set `false` to opt out — useful for callers piping `read_file` into
-   * downstream parsers that don't recognize the prefix. Per-call
-   * `read_file({ lineNumbers: false })` overrides this default.
-   *
-   * Default: `true`.
+   * Zero-based subagent depth. 0 = top-level run, 1 = direct child, …
+   * Recorded here so hosts can query/filter by level without walking the tree.
    */
-  readLineNumbers?: boolean;
+  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[];
   /**
-   * 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.
+   * True when this session has no turns yet.
    *
-   * Default: `false`.
+   * 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`.
    */
-  elideStaleReads?: boolean;
-  /**
-   * Tool disclosure strategy. Controls whether the model sees every tool's
-   * full `inputSchema` in its tool list every turn ("eager") or whether MCP
-   * tools are advertised as a name+description catalog in the system prompt
-   * and only get full schemas after being surfaced via the `tool_search`
-   * native tool ("lazy" / progressive disclosure).
-   *
-   * Native tools (those passed to `createAgent({ tools })`) and skill tools
-   * are always eager — they are core to the agent and cheap. Only MCP tools
-   * are eligible for lazy disclosure.
-   *
-   * When `'lazy'`, the agent:
-   * - Appends a `<searchable_tools>` section to the system prompt listing
-   *   every MCP tool by `name` + `description` only (no `inputSchema`).
-   * - Auto-injects a `tool_search` native tool (opt out via
-   *   {@link AgentBehavior.toolSearch}) the model uses to load schemas on
-   *   demand. Surfaced tools persist for the rest of the run.
-   * - Rebuilds the wire-level tool list each turn, appending newly-unlocked
-   *   tools at the end so the prefix-cache breakpoint advances cleanly.
-   *
-   * 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>;
+  /**
+   * 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.
    */
-  toolDisclosure?: 'eager' | 'lazy';
+  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 */
   /**
-   * 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).
+   * Optional `stats` lets the agent backfill the run's token totals when
+   * the abort happened *after* the loop accumulated meaningful usage —
+   * common when the user presses esc mid-streaming. Without it, the run
+   * record reads `0 in / 0 out` on reload regardless of how much was
+   * spent before the abort. Same shape as `completeRun`'s stats so the
+   * persisted `totalUsage` aggregate stays consistent across paths.
    */
-  toolSearch?: {
-    tool?: false;
-    limit?: number;
-  };
+  abortRun: (runId: string, stats?: {
+    turns: number;
+    tokensIn: number;
+    tokensOut: number;
+    turnUsage?: TurnUsage[];
+    cost?: number;
+  }) => void;
+  /** Mark a run as errored */
+  /** Optional `stats` — same rationale as `abortRun.stats`. */
+  errorRun: (runId: string, error: string, stats?: {
+    turns: number;
+    tokensIn: number;
+    tokensOut: number;
+    turnUsage?: TurnUsage[];
+    cost?: number;
+  }) => void;
+  /** Append turns to in-memory history AND persist via store.appendTurns (if store present) */
+  appendTurns: (turns: SessionTurn[]) => Promise<void>;
+  /** Replace all turns in-memory (does not persist — use save() for that) */
+  setTurns: (turns: SessionTurn[]) => void;
+  /** 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;
 }
 /**
- * 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.
+ * Create a new session.
+ * Async so stores that generate IDs server-side (e.g. Supabase) can be supported.
  */
-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;
-}
+declare function createSession(options?: CreateSessionOptions): Promise<Session>;
 /**
- * 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.
+ * Load an existing session from a store.
  */
-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;
-}
+declare function loadSession(store: SessionStore, sessionId: string): Promise<Session | null>;
+//#endregion
+//#region src/skills/types.d.ts
 /**
- * Lossy flattener — converts `ToolResultContent[]` (or a plain string) to a single
- * string. Image blocks are replaced with `[image: <media> — <n> b64 bytes]` markers.
+ * Types for the Agent Skills system.
  *
- * Use at UI boundaries where a string is required; providers that understand
- * structured content should route the array through without flattening.
+ * 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.
  */
-declare function toolResultToText(content: string | ToolResultContent[]): string;
+interface SkillResource {
+  /** Relative path from skill directory */
+  path: string;
+  /** Resource type inferred from directory */
+  type: 'script' | 'reference' | 'asset' | 'other';
+}
 /**
- * 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.
+ * 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.
  */
-declare function toolOutputByteLength(content: string | ToolResultContent[]): number;
-type SessionContentBlock = {
-  type: 'text';
-  text: string;
-} | {
-  type: 'image';
-  mediaType: string;
-  data: string;
-} | {
-  type: 'tool_call';
-  id: string;
+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;
-  input: Record<string, unknown>;
-} | {
-  type: 'tool_result';
-  callId: 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;
   /**
-   * 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).
+   * 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.
    */
-  output: string | ToolResultContent[];
-  isError?: boolean;
-} | {
-  type: 'thinking';
-  text: string;
-  signature?: 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;
+  /**
+   * 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 SkillsConfig {
+  /**
+   * 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
+   */
+  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;
   /**
-   * 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.
+   * 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).
    */
-  signatureProducer?: 'anthropic' | 'openai';
-} | {
-  type: 'redacted_thinking';
-  data: string;
-} | {
+  tool?: boolean;
   /**
-   * 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).
+   * Cap on concurrently active skills per run. Default `undefined` (unlimited).
+   * Attempts to activate past the cap throw from `skills_use`.
    */
-  type: 'provider_reasoning';
-  producer: 'openrouter';
-  details: unknown[];
+  maxActive?: number;
+  /** Script timeout for `skills_run_script`, in milliseconds. Default `60000`. */
+  scriptTimeoutMs?: number;
   /**
-   * 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.
+   * 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?: 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;
+  trustProjectSkills?: boolean;
 }
+//#endregion
+//#region src/tools/types.d.ts
 /**
- * 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).
+ * 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.
  */
-type RunHookMap = Record<string, ((ctx: any) => unknown) | ((ctx: any) => unknown)[]>;
-interface AgentRunOptions {
-  model?: string;
+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>;
   /**
-   * User prompt. Optional when resuming a session with existing turns.
+   * Map canonical tool names to LLM-facing (aliased) names.
    *
-   * Accepts either a plain string (single text part) or an array of `PromptPart`s for
-   * multimodal inputs (text, images, documents). See {@link PromptPart}.
+   * 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.
    */
-  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) */
+  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;
-  /** Tool overrides for this run. Pass {} for no tools. Omit to use agent tools. */
-  tools?: Record<string, ToolDef>;
+  /** Turn ID that requested this tool call */
+  turnId: string;
+  /** Tool call ID from the model */
+  callId: string;
   /**
-   * Per-run hook registrations. Each hook is attached before the run starts and
-   * detached in a finally block so handlers never leak across runs.
+   * 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.
    *
-   * Accepts either a single handler or an array (all handlers register).
+   * Spawn-style tools rely on this to tag child runs with `parentRunId` so
+   * the subagent tree can be reconstructed from a persisted session.
    */
-  hooks?: RunHookMap;
+  runId?: string;
   /**
-   * 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.
+   * 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.
    */
-  parentRunId?: string;
+  session?: Session;
   /**
-   * 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.
+   * 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;
 }
+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>;
+}
 /**
- * Reason the provider gave for stopping the turn.
+ * Normalize MCP server configs from any common shape to `McpServerConfig[]`.
  *
- * - `'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.
+ * 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 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;
+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;
 }
-interface AgentStats {
+/**
+ * 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;
   /**
-   * Cumulative input tokens across the parent agent loop **and** every
-   * recursively-spawned sub-agent. Use this for billing / token-ledger
-   * consumption.
+   * 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.
    */
-  totalIn: number;
-  /** Cumulative output tokens. Same semantics as {@link AgentStats.totalIn}. */
-  totalOut: number;
+  activate: (skill: SkillConfig, via: ActivationVia) => 'ok' | 'already-active' | 'cap-reached';
   /**
-   * 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.
+   * Mark a skill as inactive. Returns the removed `ActiveSkill` record or `undefined`
+   * if it wasn't active. Callers fire `skills:deactivate` on removal.
    */
-  totalCacheRead: number;
+  deactivate: (name: string) => ActiveSkill | undefined;
+  /** Remove every active skill. Returns the list of removed records. */
+  clear: () => readonly ActiveSkill[];
+}
+interface SkillActivationStateOptions {
   /**
-   * 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.
+   * Cap on concurrent activations. `undefined` (the default) disables the cap.
+   * When set, `activate()` returns `'cap-reached'` once the set is at size `maxActive`.
    */
-  totalCacheCreation: number;
+  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;
   /**
-   * 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).
+   * 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).
    *
-   * 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.
-   */
-  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).
+   * `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").
    *
-   * Absent when the run produced no observable signals (e.g. aborted before any stream event).
-   */
-  timeTillFirstTokenMs?: number;
-}
-interface ChildRunStats {
-  id: string;
-  task: string;
-  /**
-   * The child agent's full {@link AgentStats}. Cumulative for that child's
-   * own subtree (child loop + its grandchildren). Do **not** sum
-   * `ctx.stats.totalIn` across `spawn:complete` events to derive top-level
-   * totals — `agent.run()`'s return value is the canonical cumulative root.
+   * `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.
    */
-  stats: AgentStats;
+  'turn:after': (ctx: {
+    turn: number;
+    turnId: string;
+    usage: TurnUsage;
+    message: SessionTurn;
+    toolCounts: {
+      turn: Readonly<Record<string, number>>;
+      run: Readonly<Record<string, number>>;
+    };
+  }) => 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.
+   * Fires after a tool-results user turn is pushed onto the conversation,
+   * before* any byte-budget enforcement or follow-up steering. Symmetric
+   * with `turn:after` but for the user-role tool_result turn that closes the
+   * round-trip.
+   *
+   * Why it exists: persistence layers must write tool_use/tool_result turn
+   * pairs together — if only the assistant turn (carrying tool_use blocks)
+   * is durable, a process death between turns leaves the DB with an orphan
+   * tool_use that Anthropic rejects on resume. Subscribe here to persist
+   * the tool-results turn before the loop continues.
    */
-  depth?: number;
+  'tool-results:after': (ctx: {
+    turn: number;
+    turnId: string;
+    message: SessionTurn; /** Frozen list of tool results that were packed into `message`. */
+    results: readonly ToolResult[];
+  }) => void;
+  'stream:text': (ctx: StreamHookContext & {
+    delta: string;
+    text: string;
+  }) => void;
+  'stream:end': (ctx: StreamHookContext & {
+    text: string;
+  }) => void;
+  'stream:thinking': (ctx: StreamHookContext & {
+    delta: string;
+    thinking: string;
+  }) => void;
+  'oauth:refresh': (ctx: OAuthRefreshHookContext) => void;
   /**
-   * 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.
+   * 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.
    */
-  status?: 'completed' | 'aborted' | 'timeout' | 'error';
+  '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;
   /**
-   * 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.
+   * Fires when a tool throws during execution. Mutate `result` to substitute a
+   * tool-output payload that gets sent back to the model in place of the
+   * default `Tool error: <msg>` string — useful for OSS-model error rewriting
+   * (collapse stack traces, hide internal paths, prepend recovery hints).
+   *
+   * The post-hook value flows through `tool:transform` like a normal output, so
+   * downstream byte-budgeting and image-stripping still apply.
    */
-  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;
+  '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;
   /**
-   * Subagent depth for the spawn. 1 = direct child of the top-level agent.
-   * Present on spawn:before/complete/error. Absent for grandchild spawns that
-   * bubble through `child:*` events (which carry their own `depth`).
+   * Fires before the generic "Unknown tool" error when the model invokes a tool
+   * that isn't registered (hallucinated names, dropped MCP servers, dangling
+   * aliases). Mutate `result` to substitute a friendly response or set
+   * `suppressError: true` to skip the companion `tool:error` emission.
+   *
+   * Fires for any unknown tool name — including hallucinated MCP-style names
+   * (`mcp_supabase_xxx`); branch on `name.startsWith('mcp_')` to differentiate.
    */
-  depth?: number;
-}
-/** Context for stream hooks */
-interface StreamHookContext {
-  turnId: string;
-}
-/** Context for OAuth refresh hooks */
-interface OAuthRefreshHookContext {
-  provider: string;
-  providerId: string;
-  source: 'params' | 'file';
-  previousCredentials: Record<string, unknown> & {
-    access: string;
-    refresh: string;
-    expires: number;
-  };
-  credentials: Record<string, unknown> & {
-    access: string;
-    refresh: string;
-    expires: number;
-  };
-}
-type SessionEndStatus = 'completed' | 'aborted' | 'error';
-//#endregion
-//#region src/providers/anthropic.d.ts
-/**
- * Server-side context-management config — the body of `context_management` on
- * the Messages API. Typed loosely (Record-of-unknown) so we don't pin a specific
- * SDK schema version: the v0.90 SDK does not yet type this field, but the wire
- * format is stable behind the `context-management-2025-06-27` beta.
- *
- * See: https://docs.anthropic.com/en/docs/build-with-claude/context-management
- */
-interface AnthropicContextManagement {
-  edits?: Array<Record<string, unknown>>;
-  [key: string]: unknown;
-}
-interface AnthropicParams {
-  apiKey?: string;
-  access?: string;
-  refresh?: string;
-  expires?: number;
-  defaultModel?: string;
+  'tool:unknown': (ctx: ToolHookContext & {
+    result?: string | ToolResultContent[];
+    suppressError: boolean;
+  }) => void;
   /**
-   * Optional override for the Anthropic SDK base URL. Honored end-to-end — headers and
-   * routing pass through to the forwarded host. Useful for proxies (e.g. corporate
-   * gateways, internal router).
+   * Fires 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.
    */
-  baseURL?: string;
+  'validation:reject': (ctx: ToolHookContext & {
+    reason: string;
+    schema: Record<string, unknown>;
+  }) => void;
   /**
-   * Additional `anthropic-beta` flags to opt into. Merged with the OAuth-path
-   * defaults (`claude-code-20250219`, `oauth-2025-04-20`); duplicates are
-   * de-duped. Examples:
+   * 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.
    *
-   * - `'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.
+   * `coercions` lists the field names that were coerced. The values landed in
+   * the input that the tool actually received; consumers wanting before/after
+   * comparison can re-run `validateToolArgs(ctx.input, ctx.schema)`.
+   */
+  'validation:coerce': (ctx: ToolHookContext & {
+    coercions: readonly string[];
+    schema: Record<string, unknown>;
+  }) => void;
+  'context:transform': (ctx: {
+    messages: SessionMessage[];
+  }) => void;
+  /**
+   * Fires per request, after `context:transform` and before the request goes
+   * out. Mutating `ctx.system` updates the system prompt the provider sends
+   * for this turn — useful for runtime-derived sections (e.g. listing files
+   * already read in the session, surfacing live tool budgets, injecting
+   * skill activation reminders).
    *
-   * Honored on both the OAuth and API-key paths.
+   * 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.
    */
-  extraBetas?: readonly string[];
+  '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;
   /**
-   * 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}.
+   * 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.
    *
-   * Typed loosely so future Anthropic schema additions land without an SDK
-   * bump. A typical compaction edit:
+   * Use these to gate subagent tool calls (native + MCP) from the parent
+   * without registering listeners on every child agent. The parent's own
+   * `tool:gate` / `mcp:tool:gate` listeners are NOT auto-shared with
+   * children — that would also share their budgets and dedup state.
+   */
+  'child:tool:gate': (ctx: ToolHookContext & {
+    block: boolean;
+    reason: string;
+    result?: string | ToolResultContent[];
+    runToolCounts: Readonly<Record<string, number>>;
+    childId: string;
+    depth: number;
+  }) => void;
+  'child:mcp:tool:gate': (ctx: McpToolHookContext & {
+    block: boolean;
+    reason: string;
+    result?: string | ToolResultContent[];
+    childId: string;
+    depth: number;
+  }) => void;
+  'child:tool:before': (ctx: ToolHookContext & {
+    coercions?: readonly string[];
+    runToolCounts: Readonly<Record<string, number>>;
+    childId: string;
+    depth: number;
+  }) => void;
+  'child:tool:after': (ctx: ToolHookContext & {
+    result: string | ToolResultContent[];
+    outputBytes: number;
+    coercions?: readonly string[];
+    runToolCounts: Readonly<Record<string, number>>;
+    childId: string;
+    depth: number;
+  }) => void;
+  'child:tool:error': (ctx: ToolHookContext & {
+    error: Error;
+    childId: string;
+    depth: number;
+  }) => void;
+  'child:turn:after': (ctx: {
+    turn: number;
+    turnId: string;
+    usage: TurnUsage;
+    message: SessionTurn;
+    toolCounts: {
+      turn: Readonly<Record<string, number>>;
+      run: Readonly<Record<string, number>>;
+    };
+    childId: string;
+    depth: number;
+  }) => void;
+  'mcp:connect': (ctx: {
+    name: string;
+    transport: string;
+    tools: string[];
+  }) => void;
+  'mcp:error': (ctx: {
+    name: string;
+    error: Error;
+  }) => void;
+  'mcp:close': (ctx: {
+    name: string;
+  }) => void;
+  /**
+   * Fires at the start of a per-server bootstrap attempt, before any network I/O.
+   * Pairs with `mcp:bootstrap:end` and is always emitted, regardless of outcome.
+   */
+  'mcp:bootstrap:start': (ctx: {
+    name: string;
+    transport: string;
+  }) => void;
+  /**
+   * Fires at the end of a per-server bootstrap attempt. `durationMs` spans from
+   * the matching `mcp:bootstrap:start`. On `ok: false` carries the originating
+   * error so consumers can log / trace without relying on a separate `mcp:error`.
+   */
+  'mcp:bootstrap:end': (ctx: {
+    name: string;
+    transport: string;
+    durationMs: number;
+  } & ({
+    ok: true;
+    toolCount: number;
+  } | {
+    ok: false;
+    error: Error;
+  })) => void;
+  /**
+   * 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.
+   *
+   * 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.
    *
-   * ```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'],
-   *   }],
-   * }
-   * ```
+   * Items are upstream tool descriptors (NOT yet namespaced as `mcp_<server>_<tool>`).
    */
-  contextManagement?: AnthropicContextManagement;
+  'mcp:tools:filter': (ctx: {
+    server: string;
+    transport: 'stdio' | 'sse' | 'streamable-http';
+    tools: Array<{
+      name: string;
+      description?: string | null;
+      inputSchema?: unknown;
+    }>;
+  }) => void;
   /**
-   * Generic pass-through for fields on the Messages API request body that the
-   * SDK does not yet type. Spread into the request before the typed fields,
-   * so explicit options ({@link AnthropicParams.contextManagement} and the
-   * built-in fields like `model` / `tools` / `messages`) win on collision.
+   * 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.
    *
-   * 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}.
+   * 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).
    */
-  extraBodyParams?: Record<string, unknown>;
-}
-declare function anthropic(anthropicParams?: AnthropicParams): Provider;
-//#endregion
-//#region src/providers/cerebras.d.ts
-interface CerebrasParams {
-  apiKey?: string;
-  defaultModel?: 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 capability flags. Cerebras currently serves text-only OSS models
-   * (GLM, Llama-family, Qwen-family) — default: `{ vision: false, imageInToolResult: false }`.
-   * Override when routing to a vision-capable deployment.
+   * Fires 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.
    */
-  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>;
+  'budget:exceeded': (ctx: {
+    turn: number;
+    turnId: string;
+    bytes: number;
+    budget: number;
+  }) => void;
   /**
-   * Provider-level capability flags. Routed into the message shaper and the
-   * agent loop so images in tool results + user messages are handled correctly
-   * for the underlying model.
+   * 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>`.
    *
-   * 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).
+   * `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.
    */
-  capabilities?: ProviderCapabilities;
+  'tool-budget:exceeded': (ctx: {
+    tool: string;
+    count: number;
+    max: number;
+    turnId: string;
+    mode: 'steer' | 'block';
+  }) => void;
+  'agent:abort': (ctx: object) => void;
   /**
-   * Whether this endpoint honors `cache_control: { type: 'ephemeral' }` markers
-   * on message content parts and tool definitions.
-   *
-   * - `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.
+   * Run finished — fires on all exit paths (completion, maxTurns, abort).
    *
-   * Default: `false`. The `openrouter` wrapper sets this to `true`.
+   * 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`.
    */
-  cacheBreakpoints?: boolean;
-  /**
-   * Whether this endpoint speaks OpenRouter's normalized reasoning envelope —
-   * `reasoning: { effort | max_tokens | exclude }` on requests and structured
-   * `reasoning_details[]` on assistant messages, round-tripped to preserve
-   * extended-reasoning state across turns.
-   *
-   * - `true`  — map zidane's `behavior.thinking` / `behavior.thinkingBudget` to
-   *             the request's `reasoning` field, capture `reasoning_details`
-   *             from streaming responses into `provider_reasoning` blocks, and
-   *             echo them back on subsequent assistant messages.
-   * - `false` — never set the field; drop any stored `provider_reasoning`
-   *             blocks before sending. Safe default for hosts that strict-
-   *             validate the request schema.
+  'agent:done': (ctx: AgentStats) => void;
+  'session:start': (ctx: SessionHookContext & {
+    runId: string;
+    prompt: string;
+  }) => void;
+  'session:end': (ctx: SessionHookContext & {
+    runId: string;
+    status: SessionEndStatus;
+    turnRange: [number, number];
+  }) => void;
+  'session:turns': (ctx: SessionHookContext & {
+    turns: SessionTurn[];
+    count: number;
+  }) => void;
+  'session:meta': (ctx: SessionHookContext & {
+    key: string;
+    value: unknown;
+  }) => void;
+  'session:save': (ctx: SessionHookContext) => void;
+}
+interface AgentOptions {
+  provider: Provider;
+  /** Display name for the agent (used in traces/logs). */
+  name?: string;
+  /** Default system prompt injected when no system is provided at run time. */
+  system?: string;
+  /** Tool definitions available to the agent. Defaults to no tools. */
+  tools?: Record<string, ToolDef>;
+  /**
+   * Map canonical tool names to LLM-facing (aliased) names.
    *
-   * Default: `false`. The `openrouter` wrapper sets this to `true`.
+   * 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.
    */
-  supportsReasoning?: boolean;
+  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;
   /**
-   * 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.
+   * 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.
    *
-   * 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).
+   * @internal
    */
-  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;
+  mcpConnector?: (configs: McpServerConfig[]) => Promise<McpConnection>;
   /**
-   * 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).
+   * Pre-connect MCP servers in the background as soon as `createAgent` returns,
+   * instead of deferring the bootstrap to the first `agent.run()`.
    *
-   * Override when routing to a known-text-only model (e.g. `meta-llama/llama-3-8b-instruct`).
+   * 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`.
    */
-  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>;
+  eager?: boolean;
 }
-interface ToolResult {
-  id: string;
+interface Agent {
+  hooks: Hookable<AgentHooks>;
+  run: (options: AgentRunOptions) => Promise<AgentStats>;
+  abort: () => void;
+  steer: (message: string) => void;
+  followUp: (message: string) => void;
+  waitForIdle: () => Promise<void>;
   /**
-   * 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.
+   * 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.
    */
-  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 {
+  reset: () => Promise<void>;
   /**
-   * 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 the execution context and clean up resources.
+   * Idempotent — safe to call from both a `finally` block and a signal handler.
    */
-  vision?: boolean;
+  destroy: () => Promise<void>;
   /**
-   * 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.
+   * 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.
    */
-  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;
-  };
+  activateSkill: (name: string) => Promise<void>;
   /**
-   * 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`).
+   * Deactivate a skill by name. Fires `skills:deactivate` with `reason: 'explicit'`.
+   * No-op when the skill wasn't active.
    */
-  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>;
+  deactivateSkill: (name: string) => Promise<void>;
   /**
-   * Build a user `SessionMessage` from multimodal prompt parts.
+   * 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.
    *
-   * 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.
+   * 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.
    */
-  promptMessage?: (parts: PromptPart[]) => SessionMessage;
+  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[];
   /**
-   * 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.
+   * 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.
    */
-  classifyError?: (err: unknown) => ClassifiedError | null;
+  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
-export { ToolDef as $, PromptDocumentPart as A, createMemoryStore as At, SpawnHookContext as B, AgentContextExceededError as Bt, AgentBehavior as C, RemoteStoreOptions as Ct, McpServerConfig as D, fromOpenAI as Dt, ChildRunStats as E, fromAnthropic as Et, SessionContentBlock as F, connectMcpServers as Ft, ToolResultContent as G, ClassifiedErrorKind as Gt, ThinkingLevel as H, AgentToolNotAllowedError as Ht, SessionEndStatus as I, normalizeMcpBlocks as It, TurnFinishReason as J, ToolResultImageContent as K, matchesContextExceeded as Kt, SessionHookContext as L, normalizeMcpServers as Lt, PromptPart as M, FileMapStoreOptions as Mt, PromptTextPart as N, createFileMapStore as Nt, McpToolHookContext as O, toAnthropic as Ot, RunHookMap as P, McpConnection as Pt, ToolContext as Q, SessionMessage as R, resultToString as Rt, anthropic as S, loadSession as St, AgentStats as T, autoDetectAndConvert as Tt, ToolExecutionMode as U, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as Ut, StreamHookContext as V, AgentProviderError as Vt, ToolHookContext as W, ClassifiedError as Wt, toolOutputByteLength as X, TurnUsage as Y, toolResultToText as Z, OpenAIParams as _, Session as _t, ToolCall as a, ActivationVia as at, cerebras as b, SessionStore as bt, TurnResult as c, SkillActivationState as ct, OpenAICompatAuthHeader as d, SkillConfig as dt, ToolMap as et, OpenAICompatHttpError as f, SkillDiagnostic as ft, openaiCompat as g, CreateSessionOptions as gt, mapOAIFinishReason as h, SkillsConfig as ht, StreamOptions as i, createAgent as it, PromptImagePart as j, FileMapAdapter as jt, OAuthRefreshHookContext as k, toOpenAI as kt, OpenRouterParams as l, SkillActivationStateOptions as lt, classifyOpenAICompatError as m, SkillSource as mt, ProviderCapabilities as n, AgentHooks as nt, ToolResult as o, ActiveSkill as ot, OpenAICompatParams as p, SkillResource as pt, ToolResultTextContent as q, toTypedError as qt, StreamCallbacks as r, AgentOptions as rt, ToolSpec as s, DeactivationReason as st, Provider as t, Agent as tt, openrouter as u, createSkillActivationState as ut, openai as v, SessionData as vt, AgentRunOptions as w, createRemoteStore as wt, AnthropicParams as x, createSession as xt, CerebrasParams as y, SessionRun as yt, SessionTurn as z, AgentAbortedError as zt };
-//# sourceMappingURL=index-bgh-k8Mv.d.ts.map
+export { 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-CMIhYhDz.d.ts.map