zidane 5.7.7 → 5.7.8

package/dist/{index-B6h9C_JE.d.ts → index-DEqGfnZr.d.ts}

@@ -1,4 +1,4 @@
-import { D as SkillConfig, Gt as AgentStats, Kt as ChildRunStats, N as Session, Zt as McpServerConfig, bn as TurnUsage, dn as SessionTurn, ft as StreamOptions, gn as ToolResultContent, i as AgentOptions, l as SkillActivationState, lt as Provider, mn as ThinkingLevel, r as AgentHooks, s as ActiveSkill, v as ToolContext, y as ToolDef } from "./agent-BSPhByzT.js";
+import { D as SkillConfig, Gt as AgentStats, I as SessionStore, Kt as ChildRunStats, N as Session, Zt as McpServerConfig, bn as TurnUsage, dn as SessionTurn, ft as StreamOptions, gn as ToolResultContent, i as AgentOptions, l as SkillActivationState, lt as Provider, mn as ThinkingLevel, r as AgentHooks, rn as PromptPart, s as ActiveSkill, v as ToolContext, y as ToolDef, yn as TurnFinishReason } from "./agent-BSPhByzT.js";
 import { a as ExecutionContext, o as ExecutionHandle } from "./types-CEAMIUXw.js";
 import { Hookable } from "hookable";
 import { OAuthClientProvider, OAuthDiscoveryState } from "@modelcontextprotocol/sdk/client/auth.js";
@@ -618,1348 +618,1495 @@ declare const BYTES_PER_TOKEN = 4;
  */
 declare function estimateTokens(text: string): number;
 //#endregion
-//#region src/logger.d.ts
-type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-interface LogRecord {
-  level: LogLevel;
-  /** Unix ms — set by `Logger` at emit time. */
-  timestamp: number;
-  /** Free-form message. Sinks render this as the human-facing line. */
+//#region src/run-summary.d.ts
+interface RunSummaryTokens {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheCreation: number;
+  cost?: number;
+  /** First observable byte from the provider, ms from run start. */
+  ttftMs?: number;
+}
+interface RunSummaryByModel {
+  modelId: string;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheCreation: number;
+  cost: number;
+  turns: number;
+}
+interface RunSummaryError {
+  kind: 'stream' | 'tool' | 'mcp-tool' | 'mcp' | 'spawn';
   message: string;
-  /** Structured fields. Correlation ids land here automatically. */
-  attrs: Record<string, unknown>;
+  errorType?: string;
+  turnId?: string;
+  callId?: string;
+  server?: string;
+  toolName?: string;
+  childId?: string;
+  statusCode?: number;
+  requestId?: string;
 }
-interface LogSink {
-  emit: (record: LogRecord) => void;
+interface RunSummaryBlock {
+  callId: string;
+  toolName: string;
+  outcome: 'gate-block' | 'unknown' | 'invalid-input';
+  reason?: string;
 }
-interface Logger {
-  debug: (message: string, attrs?: Record<string, unknown>) => void;
-  info: (message: string, attrs?: Record<string, unknown>) => void;
-  warn: (message: string, attrs?: Record<string, unknown>) => void;
-  error: (message: string, attrs?: Record<string, unknown>) => void;
-  /**
-   * Returns a child logger that prepends the given attributes onto every
-   * subsequent emit. Equivalent to `pino.child` / `winston.child`. The
-   * parent and child share the same sink — children are zero-cost.
-   */
-  with: (extra: Record<string, unknown>) => Logger;
-  /**
-   * Inspectable baseline attributes — handy for tests and for hook
-   * handlers that want to clone-with-extra without recursing.
-   */
-  readonly baseAttributes: Readonly<Record<string, unknown>>;
+interface RunSummaryValidation {
+  callId: string;
+  toolName: string;
+  reason: string;
 }
-/**
- * Build a Logger from a sink. Stateless and cheap; create one per agent
- * (or per app) and use `.with()` to attach correlation ids per-call.
- */
-declare function createLogger(sink: LogSink, baseAttributes?: Readonly<Record<string, unknown>>): Logger;
-interface ConsoleSinkOptions {
-  /**
-   * Minimum level to emit. Defaults to `'info'` — `debug` is dropped so
-   * the harness's lifecycle logging is not noisy by default. Set to
-   * `'debug'` to see every event.
-   */
-  minLevel?: LogLevel;
-  /** Custom output stream. Defaults to `process.stderr` so logs don't pollute stdout. */
-  stream?: {
-    write: (chunk: string) => void;
-  };
+interface RunSummaryBudget {
+  kind: 'bytes' | 'tool-count';
+  /** Tool name (for `'tool-count'`); absent for byte budgets. */
+  toolName?: string;
+  /** `mode` for `'tool-count'`; absent for byte budgets. */
+  mode?: 'steer' | 'block';
+  observed: number;
+  limit: number;
+  turnId?: string;
 }
 /**
- * Human-readable terminal sink. Renders each record as
- * `<ISO timestamp> <LEVEL> <message> <attrs as kv pairs>`.
- *
- * Honors `process.stderr` by default so log lines don't interleave with
- * the agent's stdout-bound output (chat responses, JSON results).
- */
-declare function consoleSink(options?: ConsoleSinkOptions): LogSink;
-/**
- * One-JSON-object-per-line sink. Suitable for piping into log aggregators
- * (Datadog Agent, Fluent Bit, Loki, Vector) that expect JSONL.
+ * Postmortem snapshot of one `agent.run()`. Strictly serializable — every
+ * field round-trips through `JSON.stringify` / `JSON.parse` without loss
+ * so a log aggregator can ingest it as-is.
  */
-declare function jsonSink(options?: ConsoleSinkOptions): LogSink;
-interface LoggingHooksOptions {
-  logger: Logger;
+interface RunSummary {
+  runId?: string;
+  parentRunId?: string;
+  depth: number;
+  agentName?: string;
+  startedAt: number;
+  endedAt: number;
+  durationMs: number;
+  status: 'completed' | 'aborted';
+  turns: number;
+  totals: RunSummaryTokens;
+  byModel: RunSummaryByModel[];
+  errors: RunSummaryError[];
+  blocks: RunSummaryBlock[];
+  validationRejects: RunSummaryValidation[];
+  budgetEvents: RunSummaryBudget[];
+  /** Counts of pairing repairs, keyed by repair mode. */
+  pairingRepairs: Record<string, number>;
   /**
-   * Minimum interesting level for harness-emitted lines. Default `'info'`.
-   * Set to `'debug'` to see every tool dispatch / stream event. Set to
-   * `'warn'` to mute the chatty ones and only see failures + budgets.
+   * Postmortem snapshots of child runs that bubbled their stats up via
+   * `spawn:complete`. Only present when the run actually spawned.
    */
-  level?: LogLevel;
+  children?: RunSummary[];
+}
+interface RunSummaryCollectorOptions {
   /**
-   * When true (default), lifecycle events (`agent:start`, `turn:before`,
-   * `tool:before`, `mcp:bootstrap:start`) emit at `debug` level so they
-   * stay quiet by default. Set false to mute them entirely regardless of
-   * the configured minimum level — useful when piping into a tracer
-   * that already captures lifecycle.
+   * Called with the assembled {@link RunSummary} on every `agent:done`.
+   * Synchronous — heavy I/O should be deferred (e.g. via `setImmediate`).
    */
-  includeLifecycle?: boolean;
+  onSummary?: (summary: RunSummary) => void;
 }
-interface LoggingHookSet {
+interface RunSummaryCollector {
+  /** Install the collector's hook handlers. Returns an uninstall fn. */
   install: (hooks: Hookable<AgentHooks>) => () => void;
+  /** Most-recent summary; `undefined` until the first `agent:done` fires. */
+  latest: () => RunSummary | undefined;
 }
 /**
- * Install a bundle of hook handlers that emit a structured line per
- * relevant lifecycle event, automatically attaching correlation ids
- * (`runId`, `turnId`, `callId`, `childId`, `depth`, `agentName`).
+ * Build a run-summary collector. State is created fresh inside each
+ * `install()` call, so a single collector instance can be installed
+ * across multiple agents without attribution cross-talk. `latest()`
+ * returns the most-recent summary across **any** install — install
+ * per-agent collectors if you need separate post-run snapshots.
  *
  * @example
  * ```ts
- * const logger = createLogger(consoleSink({ minLevel: 'debug' }), { service: 'tui' })
- * const lh = createLoggingHooks({ logger })
- * const uninstall = lh.install(agent.hooks)
+ * const collector = createRunSummaryCollector({
+ *   onSummary: s => console.log(JSON.stringify(s)),
+ * })
+ * const uninstall = collector.install(agent.hooks)
  * try { await agent.run({ prompt }) }
  * finally { uninstall() }
  * ```
  */
-declare function createLoggingHooks(options: LoggingHooksOptions): LoggingHookSet;
+declare function createRunSummaryCollector(options?: RunSummaryCollectorOptions): RunSummaryCollector;
 //#endregion
-//#region src/loop.d.ts
-/**
- * Canonical tool_result text emitted when a tool call is interrupted by the
- * user mid-flight (Esc / Ctrl-C / external `AbortSignal`). Mirrors Claude
- * Code's `INTERRUPT_MESSAGE_FOR_TOOL_USE` so downstream consumers can pattern
- * match a single string across both harnesses. Always paired with
- * `isError: true` on the wire — the model treats it as a failed call rather
- * than a successful tool response.
- */
-declare const INTERRUPT_MESSAGE_FOR_TOOL_USE = "[Request interrupted by user for tool use]";
-/**
- * Canonical tool_result text emitted when a tool call is skipped because a
- * steering message arrived between dispatches inside
- * {@link executeToolBatch}. Distinguished from
- * {@link INTERRUPT_MESSAGE_FOR_TOOL_USE} so consumers can split "user
- * cancelled" from "framework superseded".
- */
-declare const TOOL_USE_SKIPPED_MESSAGE = "[Tool use skipped \u2014 superseded by user message]";
+//#region src/tools/edit.d.ts
 /**
- * Canonical tool_result text emitted when a single tool call is cancelled
- * mid-flight via `agent.cancelTool(callId)` (typically the TUI's
- * "cancel this tool" affordance). Distinguished from
- * {@link INTERRUPT_MESSAGE_FOR_TOOL_USE} (run-wide user abort) and
- * {@link TOOL_USE_SKIPPED_MESSAGE} (steered) so the model — and downstream
- * consumers — can tell the three apart by string match.
+ * Surgical edit — replace `old_string` with `new_string` in a single file.
  *
- * Always paired with `isError: true` on the wire so the model treats the
- * call as failed rather than as a successful response. The remaining tool
- * calls in the batch continue running, in contrast with a full-run abort.
- */
-declare const TOOL_USE_CANCELLED_MESSAGE = "[Tool call cancelled by user]";
-/**
- * Canonical `tool_result.content` text emitted to siblings that were
- * cancelled by a `shell` error in the same batch. Distinct from
- * {@link INTERRUPT_MESSAGE_FOR_TOOL_USE} (user-issued abort) and
- * {@link TOOL_USE_SKIPPED_MESSAGE} (steered) so consumers can split
- * the three causes by string-match.
+ * Mirrors Claude Code's `Edit` semantics so models post-trained on Anthropic's
+ * tool surface need no relearning. Fails clearly when `old_string` isn't unique
+ * (unless `replace_all: true`) and when not found, with a nearest-match preview
+ * so the model can recover without a separate `read_file` round-trip.
  */
-declare const SHELL_CASCADE_CANCEL_MESSAGE = "Cancelled: a sibling `shell` call in the same batch errored; re-run independently if still needed.";
+declare const edit: ToolDef;
 //#endregion
-//#region src/loop-persistence.d.ts
-/**
- * Bytes of head content included in the inline preview block. 2 KiB matches
- * Claude Code's `PREVIEW_SIZE_BYTES` — enough for the model to identify the
- * content class (error output / structured data / log shape) and decide
- * whether to call `read_file` on the persisted path for the full payload.
- *
- * Tail-priority preview (matching `shell`'s truncation strategy) was
- * considered but rejected: most "what is this?" decisions get made from
- * the head, and the path is in the stub for the rare case where the tail
- * matters.
- */
-declare const PERSISTENCE_PREVIEW_BYTES: number;
+//#region src/tools/glob.d.ts
+declare const glob: ToolDef;
+//#endregion
+//#region src/tools/grep.d.ts
+declare const grep: ToolDef;
+//#endregion
+//#region src/tools/interaction.d.ts
+interface InteractionToolOptions {
+  /** JSON Schema for the request payload the model sends */
+  schema: Record<string, unknown>;
+  /** Tool name (default: 'interaction') */
+  name?: string;
+  /** Tool description shown to the model */
+  description?: string;
+  /** Called when the model invokes this tool. Receives the validated payload and tool context, returns data for the model. */
+  onRequest: (payload: Record<string, unknown>, ctx: ToolContext) => Promise<Record<string, unknown> | string>;
+}
 /**
- * Byte-stable prefix every {@link buildPersistedStub} output starts with.
- * Exported so wire-level passes (tail compaction, future stale-output
- * elision) can recognize a persisted stub and preserve its path attribute
- * rather than replacing the stub with their own — losing the pointer to
- * the on-disk blob.
+ * Create an interaction tool that lets the agent request structured input.
  *
- * Bound to the literal opening of the XML tag; changing the stub format
- * requires updating this constant in lockstep (and shipping a migration
- * for in-flight sessions).
+ * The model calls this tool with a payload matching the schema.
+ * `onRequest` is called with the payload and should return the response
+ * (string or object) that gets sent back to the model as the tool result.
  */
-declare const PERSISTED_STUB_PREFIX = "<persisted-output tool=\"";
-/**
- * Resolve the per-session persistence directory under `<userDir>/tool-results/<sessionId>/`.
- *
- * The chat layer calls this at session activation and forwards the result
- * via `behavior.persistDir`. Exposed as a public helper so SDK consumers
- * pick the same layout — single source of truth for "where do blobs live".
- */
-declare function resolvePersistDir(opts: {
-  userDir: string;
-  sessionId: string;
-}): string;
-/**
- * Resolve the per-session background-tasks directory under
- * `<userDir>/<sessionId>/tasks/`.
- *
- * The chat layer calls this at session activation and forwards the result
- * via `behavior.tasksDir`. Same shape as {@link resolvePersistDir}: hosts
- * get a single source of truth for "where do task log files live".
- * Created on first write; cleanup is the session-delete path's job.
- */
-declare function resolveTasksDir(opts: {
-  userDir: string;
-  sessionId: string;
-}): string;
-/**
- * Inputs to {@link maybePersistToolResult}. Kept as a struct so the loop's
- * call site stays readable and additional optional knobs (compression,
- * mime detection, …) land without re-threading every call site.
- */
-interface PersistInput {
-  /** Canonical tool name — checked against `excludeTools`. */
-  toolName: string;
-  /** `tool_use` id from the assistant turn. Used as the filename. */
-  callId: string;
-  /** Result returned by the tool (post-`tool:transform`). */
-  output: string | ToolResultContent[];
-  /** Byte threshold; outputs at or below stay inline. */
-  threshold: number;
-  /** Canonical tool names that bypass persistence. */
-  excludeTools?: readonly string[];
-  /** Persistence root directory. Created on first write. */
-  persistDir: string;
+declare function createInteractionTool(options: InteractionToolOptions): ToolDef;
+//#endregion
+//#region src/tools/list-files.d.ts
+declare const listFiles: ToolDef;
+//#endregion
+//#region src/tools/multi-edit.d.ts
+declare const multiEdit: ToolDef;
+//#endregion
+//#region src/tools/read-file.d.ts
+declare const readFile: ToolDef;
+//#endregion
+//#region src/tools/shell.d.ts
+interface CreateShellToolOptions {
   /**
-   * Optional cap on the total bytes of persisted blobs under `persistDir`.
-   * When set (and > 0), after a successful write the helper sweeps the
-   * directory and removes the oldest `*.txt` blobs (by mtime) until the
-   * sum of remaining sizes is at or below the cap.
+   * Whether to expose the `run_in_background` flag in the input schema +
+   * the background-mode paragraphs in the description. When `false`, the
+   * model never sees the flag and won't try to use it. The execute path
+   * still has a defensive fallback: an explicit `run_in_background: true`
+   * call (e.g. from a hand-crafted message) returns a clean error rather
+   * than silently running foreground.
    *
-   * Bound to the **current session** because `persistDir` is per-session
-   * (see {@link resolvePersistDir}); eviction never crosses session
-   * boundaries. The new blob is always preserved — its mtime is the
-   * latest, so the LRU sort guarantees older blobs go first.
+   * Default: `true`.
+   */
+  allowBackground?: boolean;
+  /**
+   * Canonical names of tools registered alongside `shell` on the same
+   * agent. When non-empty, the description gains a "prefer the dedicated
+   * tool" block for each known sibling (`read_file`, `glob`, `grep`,
+   * `list_files`, `edit`, `write_file`) — useful against the
+   * `ls`/`cat`-to-re-verify loop some models fall into when both a
+   * dedicated tool AND `shell` are visible. Unknown / unrecognized names
+   * are ignored.
    *
-   * Skipped when the value isn't a positive finite number. Eviction
-   * failures (permissions, races) are surfaced through `ZIDANE_DEBUG`
-   * but never block the calling tool result; an over-cap dir is a
-   * housekeeping concern, not a correctness one.
+   * Set by `createAgent` per-run from the tool registry; hosts that
+   * construct a `shell` directly can pass it explicitly. Omit to suppress
+   * the block entirely (no nudge for shell-only agents, no nudge for
+   * hosts that prefer to author their own anti-loop prose).
    */
-  maxBytes?: number;
-}
-type PersistOutcome = {
-  kind: 'skip';
-  reason: 'disabled' | 'excluded' | 'under-threshold' | 'unsupported-shape' | 'unsafe-call-id' | 'invalid-persist-dir';
-} | {
-  kind: 'persisted';
-  output: string;
-  originalBytes: number;
-  persistedPath: string;
-  evicted?: {
-    files: number;
-    bytes: number;
-  };
-} | {
-  kind: 'error';
-  reason: 'write-failed';
-  error: Error;
-};
-/**
- * Decide-and-persist for a single tool result. Pure decision + filesystem
- * side-effect; returns the new wire-level `output` string when substitution
- * happened, otherwise tells the caller to leave the result alone.
- *
- * Atomicity: writes go through `<path>.tmp` + `rename` so a concurrent
- * read (or a crash mid-write) never sees a half-written blob.
- *
- * `ToolResultContent[]` results (images, structured blocks) currently bypass
- * persistence — the inline image bytes are the point of the call, and a
- * mixed text/image array isn't representable as a single `.txt` file. We
- * may revisit if a tool starts returning very large text-only arrays.
- */
-declare function maybePersistToolResult(input: PersistInput): Promise<PersistOutcome>;
-interface BuildStubInput {
-  toolName: string;
-  originalBytes: number;
-  persistedPath: string;
-  output: string;
+  registeredCanonicals?: ReadonlySet<string>;
+  /**
+   * The agent's `toolAliases` map, used to render the wire-level name of
+   * each sibling in the swap block. Without this, the block always prints
+   * canonical names — fine for the default preset, wrong for hosts that
+   * alias-rename (the model would be told to call a name it doesn't see
+   * in the tool spec).
+   */
+  toolAliases?: Record<string, string>;
 }
 /**
- * Render the byte-stable `<persisted-output>` stub the model sees in place
- * of the original `tool_result`.
- *
- * Format choices:
- *  - XML wrapper because models reliably parse it as structural.
- *  - Byte count + path in attributes so the model can decide whether to
- *    `read_file` the persisted blob without scanning the preview.
- *  - Preview always shows the head — `shell`'s tail-priority truncation is
- *    irrelevant here because the model has the full path if it needs the
- *    tail.
- *  - No timestamps, no random UUIDs inside the stub: every byte must be
- *    reproducible from the inputs, otherwise re-emission on subsequent
- *    turns would bust the prompt cache.
+ * Factory for the `shell` tool. The default exported `shell` is
+ * equivalent to `createShellTool({ allowBackground: true })`. The
+ * factory is the entry point hosts use when they want to override the
+ * default — e.g. to ship a preset that always disables background mode
+ * regardless of `behavior.tasksDir`.
  *
- * Exported for tests (asserting the byte-stable contract) and for SDK
- * consumers wiring their own persistence middleware against the same
- * surface.
+ * Hosts that use the framework's `createAgent` typically don't need to
+ * call this directly: when `behavior.tasksDir` is unset or
+ * `behavior.disableBackgroundTasks: true` is set, the agent
+ * automatically rewrites the registered `shell` (if it's the
+ * framework's built-in) using this factory.
  */
-declare function buildPersistedStub(input: BuildStubInput): string;
+declare function createShellTool(opts?: CreateShellToolOptions): ToolDef;
 /**
- * Remove every persisted blob belonging to a session. Called by the chat
- * layer from its session-delete path so closing a session frees the disk
- * footprint alongside the SQLite row.
+ * Default `shell` tool with background mode enabled.
  *
- * Idempotent — missing directory (session never persisted anything) is a
- * no-op, not an error. Wraps the `rm -rf` so a permissions blip on one
- * blob doesn't propagate to the caller; the chat layer can't usefully
- * recover from "couldn't unlink a result file" mid-delete.
+ * Most hosts use this directly via `basicTools`. When the agent's
+ * `behavior.tasksDir` is unset OR `behavior.disableBackgroundTasks:
+ * true` is set, `createAgent` auto-rewrites this identity to a
+ * `createShellTool({ allowBackground: false })` variant so the model
+ * never sees a flag it can't use. Hosts who want to bypass that
+ * auto-rewrite can register a `createShellTool({ allowBackground })`
+ * directly — the rewrite only fires on identity-equal references to
+ * this constant.
  */
-declare function cleanupPersistedSession(persistRoot: string): Promise<void>;
+declare const shell: ToolDef;
 //#endregion
-//#region src/mcp/oauth-provider.d.ts
-/**
- * Per-server persisted state. Subfields are optional so a partial save
- * (e.g. `saveCodeVerifier` arriving before `saveTokens`) doesn't blow away
- * earlier subfields — the provider always patches, never replaces.
- */
-interface McpCredentialEntry {
-  tokens?: OAuthTokens;
-  clientInformation?: OAuthClientInformationMixed;
-  discoveryState?: OAuthDiscoveryState;
+//#region src/tools/shell-kill.d.ts
+declare const shellKill: ToolDef;
+//#endregion
+//#region src/tools/skills-read.d.ts
+interface SkillsReadToolOptions {
+  catalog: readonly SkillConfig[];
+  state: SkillActivationState;
 }
-interface McpCredentialStore {
-  load: (name: string) => McpCredentialEntry | undefined;
-  save: (name: string, entry: McpCredentialEntry) => void;
-  delete: (name: string) => void;
+declare function createSkillsReadTool(options: SkillsReadToolOptions): ToolDef;
+//#endregion
+//#region src/tools/skills-run-script.d.ts
+interface SkillsRunScriptToolOptions {
+  catalog: readonly SkillConfig[];
+  state: SkillActivationState;
+  /** Script timeout in milliseconds. Default 60000. */
+  scriptTimeoutMs?: number;
+}
+declare function createSkillsRunScriptTool(options: SkillsRunScriptToolOptions): ToolDef;
+//#endregion
+//#region src/tools/skills-use.d.ts
+interface SkillsUseToolOptions {
+  /** Resolved skills catalog for this run. */
+  catalog: readonly SkillConfig[];
+  /** Per-agent activation state the tool mutates. */
+  state: SkillActivationState;
+  /** Agent hooks — used to fire `skills:activate` on first activation. */
+  hooks: Hookable<AgentHooks>;
 }
 /**
- * In-memory store — primarily for tests, but valid as a no-persistence option
- * (tokens evaporate on process exit, the user re-auths every cold start).
+ * Factory for `skills_use`. Auto-injected into the agent's tool set by the
+ * agent runtime when a non-empty skills catalog is available (unless
+ * `SkillsConfig.tool === false`).
+ *
+ * The tool schema's `name` property is `enum`-constrained to the resolved
+ * catalog so the LLM cannot hallucinate a skill that doesn't exist.
  */
-declare function createMemoryMcpCredentialStore(seed?: Record<string, McpCredentialEntry>): McpCredentialStore;
-interface McpOAuthProviderOptions {
-  /** Server name — used as the storage key. */
-  name: string;
-  /** Persistence backend. */
-  store: McpCredentialStore;
+declare function createSkillsUseTool(options: SkillsUseToolOptions): ToolDef;
+//#endregion
+//#region src/tools/spawn.d.ts
+interface ChildAgent {
+  id: string;
+  task: string;
+  startedAt: number;
+  /** Subagent depth — 1 for a direct child of a top-level agent. */
+  depth: number;
+}
+interface SpawnToolState {
+  /** Currently running children. */
+  readonly children: ReadonlyMap<string, ChildAgent>;
   /**
-   * Loopback callback URI. Pass `undefined` for bootstrap (non-interactive
-   * mode — stored tokens + refresh only, never opens a browser).
+   * Cumulative stats across every completed direct child of this spawn-tool
+   * instance (returns a copy). Each child's contribution is the cumulative
+   * `AgentStats` returned by its `agent.run()` — so
+   * `totalIn`/`totalOut`/`totalCacheRead`/`totalCacheCreation` cover the
+   * entire subtree (children + grandchildren + …), while `turns` and
+   * `elapsed` stay parent-loop-only per child and are summed across direct
+   * children. `elapsed` over-counts when children ran in parallel.
+   *
+   * Lives across multiple parent runs that share this instance.
    */
-  redirectUri?: string;
-  /**
-   * Invoked when the SDK wants the user agent to navigate to the authorization
-   * URL. Typically the host opens the browser AND emits a hook so the TUI can
-   * render the URL in a status row. No-op in non-interactive mode (the SDK
-   * still calls this before throwing `UnauthorizedError` from connect).
+  readonly totalChildStats: Readonly<AgentStats>;
+}
+interface SpawnToolOptions {
+  /** Maximum concurrent sub-agents (default: 3). */
+  maxConcurrent?: number;
+  /**
+   * Maximum subagent depth. 0 disables spawning entirely; 1 allows top-level
+   * spawns but forbids grandchildren; 3 (default) allows three levels of
+   * recursion — enough for most orchestration patterns, a sharp ceiling
+   * against runaway loops.
    */
-  onAuthorizationUrl?: (url: URL) => void | Promise<void>;
+  maxDepth?: number;
+  /** Child model override. */
+  model?: string;
+  /** Child system prompt override. Per-spawn `input.system` takes precedence. */
+  system?: string;
+  /** Child thinking level. */
+  thinking?: 'off' | 'minimal' | 'low' | 'medium' | 'high';
+  /** Preset override for children. Shallow-merged over the parent's preset (parent fields still win for anything left unset). */
+  preset?: Preset;
   /**
-   * `client_name` used in dynamic client registration. Defaults to `'zidane'`.
-   * Some servers display this string to the user on the consent screen.
+   * Per-child timeout, in milliseconds. When the child exceeds it the spawn
+   * tool returns a timeout marker, fires `spawn:error`, and destroys the
+   * child agent. Default: none.
    */
-  clientName?: string;
+  timeoutMs?: number;
   /**
-   * Override the requested OAuth scope. Default: unset (the SDK negotiates
-   * via the server's metadata).
+   * When `true` and the parent has a session, the child reuses the parent's
+   * session — child turns are appended with the child's own `runId`, and the
+   * resulting `SessionRun` carries `parentRunId` so the tree is
+   * reconstructible. Default: `false` (child is in-memory only).
+   *
+   * **Read-state isolation.** Sharing the session also shares the
+   * `read_file` / `requireReadBeforeEdit` tracking map (it's keyed
+   * by `Session`). With `persist: false` the child gets no session,
+   * so reads inside the subagent populate nothing the parent can see —
+   * a follow-up `edit` / `multi_edit` in the parent will trip the
+   * gate with `"has not been read"` even though the model just
+   * read the file in the child. Use {@link shareReadState} when
+   * you want the parent's gate to honor the child's reads WITHOUT
+   * also persisting child turns to the parent's session.
    */
-  scope?: string;
-}
-declare class McpOAuthProvider implements OAuthClientProvider {
-  private readonly name;
-  private readonly store;
-  private readonly _redirectUri?;
-  private readonly onAuthorizationUrl?;
-  private readonly clientName;
-  private readonly _scope?;
-  private codeVerifierValue;
-  constructor(opts: McpOAuthProviderOptions);
-  get redirectUrl(): string | URL | undefined;
-  get clientMetadata(): OAuthClientMetadata;
-  tokens(): OAuthTokens | undefined;
-  saveTokens(tokens: OAuthTokens): void;
-  clientInformation(): OAuthClientInformationMixed | undefined;
-  saveClientInformation(info: OAuthClientInformationMixed): void;
-  discoveryState(): OAuthDiscoveryState | undefined;
-  saveDiscoveryState(state: OAuthDiscoveryState): void;
-  saveCodeVerifier(verifier: string): void;
-  codeVerifier(): string;
-  redirectToAuthorization(url: URL): Promise<void>;
+  persist?: boolean;
   /**
-   * Wipe stored credentials when the server reports the cached state is no
-   * longer valid. The SDK calls this with a scope hint:
-   *   - `'tokens'`  → access/refresh revoked, keep client registration
-   *   - `'client'`  → client registration invalidated, reset everything
-   *   - `'verifier'`→ PKCE state stale (e.g. mismatched state param)
-   *   - `'discovery'` → discovery metadata stale (servers re-keyed)
-   *   - `'all'`     → full reset
+   * Forward the parent's read-state map to the child agent so the
+   * `requireReadBeforeEdit` gate and `dedupReads` cache see reads
+   * across the parent/child boundary. Orthogonal to {@link persist} —
+   * use this when you want shared read tracking without sharing the
+   * session's turn history. Default: `false`.
+   *
+   * Has no effect when the parent has no read-state to share (no
+   * session and no explicit `readState` on the parent agent's
+   * options). Implementation: passes the parent's resolved
+   * `ReadStateMap` to the child via `AgentOptions.readState`, which
+   * tools resolve via `ctx.readState ?? getReadState(ctx.session)`.
    */
-  invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void>;
-  private patch;
+  shareReadState?: boolean;
+  /**
+   * Forward a curated subset of child hook events (`stream:*`, `tool:*`,
+   * `turn:after`) onto the parent's hook bus as `child:*` events. Default:
+   * `true`. Grandchildren bubble through their child transparently.
+   */
+  forwardHooks?: boolean;
+  /** Called when a child agent starts. */
+  onSpawn?: (child: ChildAgent) => void;
+  /** Called when a child agent completes (success, abort, timeout, or error). */
+  onComplete?: (child: ChildAgent, stats: AgentStats, status: NonNullable<ChildRunStats['status']>) => void;
+  /**
+   * Named subagent presets the model can select via the `subagent_type`
+   * input field. Mirrors the Claude Code SDK's surface — models trained
+   * on it routinely emit `subagent_type: 'Explore' | 'Plan' |
+   * 'Verification' | 'general-purpose'`, and without a registry the
+   * field is silently dropped, so hosts wanting type-specialized
+   * subagents have to invent their own dispatch layer.
+   *
+   * Each entry overlays the base spawn config for that particular
+   * dispatch. Per-call `input.system` still wins over `subagents[type].system`
+   * so the model can always specialize further.
+   *
+   * When the registry is non-empty:
+   *   - `subagent_type` appears in the spawn input schema as a `string`
+   *     enum of the registered keys (plus the always-available
+   *     `'general-purpose'` fallback).
+   *   - Models that pass an unregistered type are routed to
+   *     `'general-purpose'` (no error — degrade gracefully so trained
+   *     models keep working even on hosts that haven't wired every
+   *     type Claude Code uses).
+   *
+   * When the registry is empty / unset, the field is omitted entirely
+   * (preserves the historical schema for hosts that never use this).
+   *
+   * Default: `undefined` (no subagent types; `subagent_type` schema
+   * field hidden).
+   */
+  subagents?: SubagentRegistry;
 }
 /**
- * True when an HTTP transport's auth headers already include an explicit
- * Authorization. Used by the bootstrap escape-hatch: a user who provided
- * their own bearer token shouldn't be auto-promoted to OAuth on a 401.
- *
- * Case-insensitive — Node normalizes outgoing headers to lowercase but
- * users hand-write `Authorization` in configs.
+ * Per-type subagent override applied when the model calls
+ * `spawn({ subagent_type: '…' })`. All fields are optional; absent
+ * fields fall back to the parent's resolved configuration (see
+ * {@link SpawnToolOptions} comments for the merge order).
  */
-declare function hasAuthorizationHeader(headers: Record<string, string> | undefined): boolean;
-//#endregion
-//#region src/mcp/login.d.ts
-interface LoginMcpServerOptions {
-  /** Persistence — same store the bootstrap path reads from. */
-  store: McpCredentialStore;
+interface SubagentDef {
   /**
-   * Invoked with the authorization URL once it's ready. Hosts typically
-   * (a) emit `mcp:auth:url` for the TUI, and (b) call `tryOpenBrowser`.
-   * The URL is identical to the one passed to the `mcp:auth:url` hook
-   * fired automatically — this callback is a synchronous hook for callers
-   * that don't want to wire the agent hook machinery.
+   * System prompt override for this subagent type. Per-call
+   * `input.system` still wins — model-supplied specialization beats
+   * preset defaults.
    */
-  onAuthorizationUrl?: (url: URL) => void | Promise<void>;
-  /** Cancels the flow (esc / close modal / SIGINT). */
-  signal?: AbortSignal;
-  /** Agent hooks. The flow emits `mcp:auth:url`/`success`/`error` when wired. */
-  hooks?: Hookable<AgentHooks>;
-  /** Override `client_name` shown on consent screens. Default: 'zidane'. */
-  clientName?: string;
-  /** Override the requested OAuth scope. */
-  scope?: string;
+  system?: string;
   /**
-   * Override the loopback callback path. Default: `/callback`. Useful only
-   * for servers that pinned a different path during registration.
+   * Restrict the child agent's tool registry to this list of canonical
+   * tool names. Operates as a filter over the parent's tools (the
+   * parent's selection is the upper bound — a subagent can never gain
+   * tools the parent doesn't have). When unset, the child inherits the
+   * parent's full tool list.
+   *
+   * Tool names are canonical (registry-key) not wire/alias names — the
+   * filter runs before aliases are applied. Names that don't match a
+   * parent tool are silently dropped (matches the lenient behaviour of
+   * `enabledTools` on MCP configs).
    */
-  callbackPath?: string;
+  tools?: readonly string[];
   /**
-   * Maximum time to wait for the user to complete the browser flow, in ms.
-   * The user can also cancel via `signal`. Default: 5 minutes.
+   * Mark this subagent as read-only — equivalent to listing only
+   * obviously-non-mutating tools (`read_file`, `grep`, `glob`,
+   * `list_files`) in {@link SubagentDef.tools}. Convenience for the
+   * common "Plan" / "Explore" subagent shape Claude Code ships.
+   *
+   * When both `readonly: true` and `tools` are set, `tools` wins
+   * (explicit beats implicit).
    */
-  timeoutMs?: number;
-}
-interface LoginMcpServerResult {
-  /** Stored OAuth tokens after a successful exchange. */
-  tokens: NonNullable<ReturnType<McpOAuthProvider['tokens']>>;
+  readonly?: boolean;
   /**
-   * Upstream tool descriptors discovered after re-connecting with the new
-   * tokens. Already filtered by the server's `enabledTools` / `disabledTools`
-   * is NOT applied here — that's a bootstrap concern. Hosts that want filtering
-   * should pass the result through `connectMcpServers` rebuild on the next
-   * session activation rather than reusing this list verbatim.
+   * Short description rendered into the spawn tool's schema (the
+   * `subagent_type` field's description) so the model can pick a type
+   * that matches the task without round-tripping through docs.
    */
-  tools: Array<{
-    name: string;
-    description?: string | null;
-    inputSchema?: unknown;
-  }>;
+  description?: string;
 }
 /**
- * Run the full interactive OAuth flow for `config`. Only supports `sse` and
- * `streamable-http` transports — `stdio` MCP servers don't speak OAuth.
- *
- * Throws on:
- *   - Wrong transport.
- *   - Abort signal.
- *   - Browser-side error (user denied, server rejected, etc.).
- *   - Code exchange failure.
- *   - Post-exchange connect failure.
- *
- * Always closes the loopback callback server before returning, success or
- * failure.
+ * Map of subagent-type key → preset. Keys are case-sensitive and
+ * appear verbatim in the spawn input schema's enum so the model emits
+ * them with the same casing. Common conventions: `'Explore'`,
+ * `'Plan'`, `'Verification'`, `'general-purpose'` (Claude Code SDK's
+ * built-in set).
  */
-declare function loginMcpServer(config: McpServerConfig, options: LoginMcpServerOptions): Promise<LoginMcpServerResult>;
-//#endregion
-//#region src/mcp/oauth-callback.d.ts
+type SubagentRegistry = Record<string, SubagentDef>;
 /**
- * Local loopback HTTP callback for OAuth 2.0 authorization code flows.
- *
- * Stands up a one-shot server on `127.0.0.1:<random>` that captures the
- * `?code=...` redirect from a browser-driven OAuth flow and resolves a
- * promise with the code. Used as the `redirectUrl` half of the MCP SDK's
- * `OAuthClientProvider` (the persistence half lives separately).
+ * Create a configured spawn tool.
  *
- * Design:
- *   - Loopback-only (`127.0.0.1`) — the OAuth spec treats `http://127.0.0.1:<port>`
- *     as a public-client redirect URI per RFC 8252 §7.3. Browsers do NOT block it,
- *     and Anthropic / OpenAI / Linear / GitHub all accept it.
- *   - Random port (`port = 0`) — the OS picks an unused one. We read the actual
- *     port back from `server.address()` after `listen()`.
- *   - Single-shot — the first GET to `path` with a `code` (or `error`) wins;
- *     subsequent requests get 404. The server keeps listening (in case the user
- *     hits "back" and re-authorizes), so callers must `close()` once they have
- *     the code or have given up.
- *   - Abort-aware — wiring an external `AbortSignal` rejects the promise and
- *     closes the server immediately. Required for the TUI's "esc cancels login"
- *     UX.
- *   - No HTML framework — a single inline `<html>` string keeps this isolated
- *     from any UI dependency.
+ * State (`children`, `totalChildStats`, counters, active count) is scoped to
+ * the returned instance. Multiple parent agents using the same instance will
+ * share counters + stats + concurrency slots — call `createSpawnTool()` per
+ * agent (or use the stateless default `spawn`) to keep them isolated.
  */
-/**
- * Result of a successful callback. `state` is forwarded verbatim from the
- * query string — callers verify it against their pre-flight value to defend
- * against CSRF (the MCP SDK does this internally when it controls `state`).
- */
-interface OAuthCallbackResult {
-  code: string;
-  state?: string;
-}
-interface OAuthCallbackHandle {
-  /**
-   * Full URI to register with the authorization server, e.g.
-   * `http://127.0.0.1:51823/callback`. Stable for the lifetime of the
-   * handle.
-   */
-  redirectUri: string;
+declare function createSpawnTool(options?: SpawnToolOptions): ToolDef & SpawnToolState;
+//#endregion
+//#region src/tools/tool-search.d.ts
+interface LazyToolEntry {
   /**
-   * Resolves with `{ code, state }` on a successful callback. Rejects with:
-   *   - The OAuth-spec `error` field (`access_denied`, `server_error`, ...)
-   *     when the authorization server redirects with `?error=...`.
-   *   - `'OAuth callback aborted'` when the external `AbortSignal` fires.
-   *   - `'OAuth callback server closed'` when `close()` is called before any
-   *     callback arrives.
-   *
-   * Single-shot — only the first matching request resolves the promise.
+   * Wire name (after `toolAliases` rewrite). What the model sees in the
+   * catalog, what `tool_search` matches against, and what the provider's
+   * tool list will carry once the entry is unlocked.
    */
-  promise: Promise<OAuthCallbackResult>;
+  name: string;
   /**
-   * Idempotent shutdown. Safe to call from a `finally` block whether the
-   * flow succeeded, failed, or was aborted. Resolves once the server stops
-   * accepting connections.
+   * Canonical (registry-key) name used for unlock-set membership and for the
+   * loop's `ctx.tools[name]` dispatch lookup. Equal to `name` when no alias
+   * is configured for this tool.
    */
-  close: () => Promise<void>;
+  canonicalName: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  /** Source MCP server, when applicable. Used for `server`-bulk unlock. */
+  server?: string;
 }
-interface OAuthCallbackOptions {
-  /** Cancels the flow — rejects `promise` and closes the server. */
-  signal?: AbortSignal;
+interface ToolSearchToolOptions {
   /**
-   * Path component the authorization server should redirect to. Defaults
-   * to `/callback`. Useful when matching a pre-registered URI that uses a
-   * different path.
+   * Snapshot of every lazy tool the model can discover. Built once per run by
+   * the agent — the tool closes over this array and never mutates it.
    */
-  path?: string;
+  catalog: readonly LazyToolEntry[];
   /**
-   * Override the loopback host. Defaults to `127.0.0.1`. Don't bind to
-   * `0.0.0.0` here — the OAuth code is a one-time secret and the server
-   * would otherwise accept it from any host on the LAN.
+   * Mutable per-run set of unlocked **canonical** tool names. The tool adds
+   * matches in place; the loop reads the set when rebuilding the wire-level
+   * tool list. Keyed by canonical (not wire) so dispatch lookups stay
+   * alias-stable.
+   *
+   * Prefer `addUnlock` for cache-stable wire-tool ordering: writes through a
+   * Set lose unlock order, so the wire-level rebuild that filters by `unlocked`
+   * has to fall back to registry iteration order — which moves entries every
+   * time a lazy tool earlier in the registry is unlocked, breaking provider
+   * prompt-cache breakpoints. The agent passes both when it owns the unlock
+   * tracker, with `addUnlock` mirroring writes into an ordered log.
    */
-  host?: string;
+  unlocked: Set<string>;
   /**
-   * Override the port. Defaults to `0` (OS-assigned). Pin to a fixed port
-   * only when the authorization server requires a pre-registered redirect
-   * URI; the random-port path is preferred so concurrent flows don't clash.
+   * Optional callback fired for every canonical name the tool unlocks. When
+   * set, the agent uses this to maintain an append-only `dynamicUnlockOrder`
+   * so the wire-level tool list emits new unlocks at the tail and keeps the
+   * provider prefix cache warm. Idempotent on repeat unlocks of the same
+   * name — callers may dedupe internally.
+   *
+   * Invoked **in addition to** the `unlocked.add` (which still happens for
+   * back-compat with callers that only watch the Set).
    */
-  port?: number;
+  addUnlock?: (canonical: string) => void;
+  /** Default cap on returned matches when the model omits `limit`. */
+  defaultLimit?: number;
 }
 /**
- * Start a one-shot OAuth callback server. The returned handle's `redirectUri`
- * should be passed to the authorization server as the `redirect_uri` query
- * parameter; `promise` resolves once the user finishes the browser flow.
- *
- * Always `await handle.close()` in a `finally` block — even on success, the
- * server stays open until told to shut down (so it can serve the
- * "you can close this tab" page).
+ * Factory for `tool_search`. Auto-injected by the agent when
+ * `behavior.toolDisclosure === 'lazy'` and at least one MCP tool is in the
+ * registry. Opt out via `behavior.toolSearch.tool === false`.
  */
-declare function startOAuthCallback(opts?: OAuthCallbackOptions): Promise<OAuthCallbackHandle>;
+declare function createToolSearchTool(options: ToolSearchToolOptions): ToolDef;
 //#endregion
-//#region src/metrics.d.ts
-type MetricAttributes = Record<string, string | number | boolean | undefined>;
-interface Counter {
-  add: (value: number, attributes?: MetricAttributes) => void;
-}
-interface Histogram {
-  record: (value: number, attributes?: MetricAttributes) => void;
-}
-interface UpDownCounter {
-  add: (value: number, attributes?: MetricAttributes) => void;
-}
-interface InstrumentOptions {
-  description?: string;
-  unit?: string;
-}
+//#region src/tools/validation.d.ts
 /**
- * Minimal Meter interface — structurally identical to OTel's `Meter`.
- * Hosts passing `metrics.getMeter(name)` (from `@opentelemetry/api`)
- * satisfy this without adaptation.
+ * Tool argument validation against JSON Schema-style inputSchema.
+ *
+ * Two passes:
+ *   1. Required-field presence. Missing or null/undefined required fields fail.
+ *   2. Per-property type checks with **best-effort coercion**. Small/OSS models
+ *      routinely send `"true"` for a `boolean` field or `"42"` for a `number`,
+ *      and rejecting outright forces a confusing retry. Instead, we auto-heal
+ *      coerce when the conversion is unambiguous, fail only when the value
+ *      cannot be reasonably normalized to any of the declared types.
+ *
+ * Recursion: when a property declares `type: 'array'` with an `items` schema,
+ * each item is validated against `items`. Object items are walked one level
+ * deep (their declared `properties` get the same coercion + enum checks the
+ * top level does). Items that can't be coerced are dropped rather than
+ * rejecting the whole call — the model rarely benefits from an
+ * all-or-nothing failure on a 20-item list because one entry was malformed.
+ * Dropped items are reported back via `droppedItems` so the tool's `execute`
+ * can surface a hint to the model if it wants to.
  */
-interface Meter {
-  createCounter: (name: string, options?: InstrumentOptions) => Counter;
-  createHistogram: (name: string, options?: InstrumentOptions) => Histogram;
-  createUpDownCounter: (name: string, options?: InstrumentOptions) => UpDownCounter;
-}
-interface MetricsHooksOptions {
-  meter: Meter;
+interface ValidationResult {
+  valid: boolean;
+  /** Human-readable reason. Present on failure only. */
+  error?: string;
   /**
-   * Optional prefix prepended to every instrument name. Default: no prefix
-   * (instrument names follow OTel Gen AI semantic conventions verbatim,
-   * which is the most-portable shape). Set to e.g. `'zidane.'` to
-   * namespace inside a shared meter registry.
+   * Possibly-coerced input. Present iff `valid: true`. Tools should call
+   * `execute(coercedInput, ctx)` so auto-healed values reach the tool body.
+   * When no coercion was applied, this is reference-equal to the input.
    */
-  namespace?: string;
+  coercedInput?: Record<string, unknown>;
   /**
-   * Optional baseline attributes applied to every measurement. Typical
-   * use: `{ service: 'tui', env: 'prod' }`. Per-event attributes win on
-   * key collision.
+   * Names of fields whose values were coerced. Empty when nothing changed.
+   * Useful for telemetry (`validation:reject` on failure already carries the
+   * reason; this is the success-path equivalent).
    */
-  baseAttributes?: MetricAttributes;
+  coercions?: readonly string[];
   /**
-   * Error sink for meter failures. The helper still swallows the throw
-   * so a broken backend can't crash a run; this callback surfaces the
-   * failure for ops dashboards.
+   * Indexes of array items dropped during recursive validation, keyed by
+   * the property name. Empty / absent when nothing was dropped. Tools that
+   * care about the discrepancy (e.g. `todowrite` wanting to surface
+   * "ignored 2 malformed items") can inspect this.
    */
-  onError?: (kind: string, err: unknown) => void;
-}
-interface MetricsHookSet {
-  install: (hooks: Hookable<AgentHooks>) => () => void;
+  droppedItems?: Readonly<Record<string, readonly number[]>>;
 }
+declare function validateToolArgs(input: Record<string, unknown>, schema: Record<string, unknown>): ValidationResult;
+//#endregion
+//#region src/tools/write-file.d.ts
 /**
- * Build a set of metrics hook handlers that can be installed on an agent.
+ * Write a file, with an idempotency signal when the content is unchanged.
  *
- * @example OpenTelemetry
- * ```ts
- * import { metrics } from '@opentelemetry/api'
- * const meter = metrics.getMeter('zidane')
- * const m = createMetricsHooks({ meter, baseAttributes: { service: 'tui' } })
- * const uninstall = m.install(agent.hooks)
- * try { await agent.run({ prompt }) }
- * finally { uninstall() }
- * ```
+ * Three return shapes — chosen so the model can recognize a no-op without a
+ * separate read:
+ *   - `Created path (N bytes)` — file did not exist
+ *   - `Updated path (N bytes)` — content differed from on-disk
+ *   - `No change needed: path already at target state (N bytes)` — equal
+ *
+ * Race window: in non-process execution contexts (docker, sandbox) shared by
+ * multiple agents, another writer can mutate the file between our read and
+ * our write. Local process context is single-writer per agent so the race is
+ * a non-issue there. Documented rather than locked because the cost of
+ * cross-context locking outweighs the cost of a stale "No change" message.
  */
-declare function createMetricsHooks(options: MetricsHooksOptions): MetricsHookSet;
+declare const writeFile: ToolDef;
 //#endregion
-//#region src/run-summary.d.ts
-interface RunSummaryTokens {
+//#region src/headless.d.ts
+type HeadlessStatus = 'completed' | 'aborted' | 'error' | 'timeout';
+interface HeadlessUsage {
   input: number;
   output: number;
   cacheRead: number;
   cacheCreation: number;
+  /** Cumulative USD cost when the provider/registry could price the run. */
   cost?: number;
-  /** First observable byte from the provider, ms from run start. */
-  ttftMs?: number;
-}
-interface RunSummaryByModel {
-  modelId: string;
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheCreation: number;
-  cost: number;
-  turns: number;
 }
-interface RunSummaryError {
-  kind: 'stream' | 'tool' | 'mcp-tool' | 'mcp' | 'spawn';
+interface HeadlessErrorInfo {
   message: string;
-  errorType?: string;
-  turnId?: string;
-  callId?: string;
-  server?: string;
-  toolName?: string;
-  childId?: string;
-  statusCode?: number;
-  requestId?: string;
-}
-interface RunSummaryBlock {
-  callId: string;
-  toolName: string;
-  outcome: 'gate-block' | 'unknown' | 'invalid-input';
-  reason?: string;
-}
-interface RunSummaryValidation {
-  callId: string;
-  toolName: string;
-  reason: string;
+  /** Typed-error class name (`AgentAbortedError`, `AgentContextExceededError`, …). */
+  type: string;
 }
-interface RunSummaryBudget {
-  kind: 'bytes' | 'tool-count';
-  /** Tool name (for `'tool-count'`); absent for byte budgets. */
-  toolName?: string;
-  /** `mode` for `'tool-count'`; absent for byte budgets. */
-  mode?: 'steer' | 'block';
-  observed: number;
-  limit: number;
-  turnId?: string;
+/**
+ * Strictly JSON-serializable postmortem of one headless run. Everything an RL
+ * reward function needs: the final answer (`finalText`), the verifiable
+ * structured output (`output`, present iff a `schema` was set), usage/turns,
+ * and the lossless `transcript` (the SFT training data).
+ */
+interface HeadlessResult {
+  status: HeadlessStatus;
+  /** Concatenated text of the last assistant turn that produced any text. */
+  finalText: string;
+  /** Schema-enforced structured output (only when `opts.schema` is set). */
+  output?: Record<string, unknown>;
+  usage: HeadlessUsage;
+  turns: number;
+  durationMs: number;
+  /** Total `tool_call` blocks across the whole transcript. */
+  numToolCalls: number;
+  /** Finish reason of the final turn that reported one. */
+  finishReason?: TurnFinishReason;
+  error?: HeadlessErrorInfo;
+  sessionId: string;
+  /** Incident postmortem (errors, gate blocks, budget events) via run-summary. */
+  summary?: RunSummary;
+  /** Lossless transcript — raw `session.turns`. Thinking stripped when `includeThinking: false`. */
+  transcript: SessionTurn[];
 }
 /**
- * Postmortem snapshot of one `agent.run()`. Strictly serializable — every
- * field round-trips through `JSON.stringify` / `JSON.parse` without loss
- * so a log aggregator can ingest it as-is.
+ * Live event union — the in-process equivalent of a `stream-json` line. Every
+ * member is JSON-serializable; render to JSONL with {@link headlessEventToJsonl}.
  */
-interface RunSummary {
-  runId?: string;
-  parentRunId?: string;
-  depth: number;
-  agentName?: string;
-  startedAt: number;
-  endedAt: number;
-  durationMs: number;
-  status: 'completed' | 'aborted';
-  turns: number;
-  totals: RunSummaryTokens;
-  byModel: RunSummaryByModel[];
-  errors: RunSummaryError[];
-  blocks: RunSummaryBlock[];
-  validationRejects: RunSummaryValidation[];
-  budgetEvents: RunSummaryBudget[];
-  /** Counts of pairing repairs, keyed by repair mode. */
-  pairingRepairs: Record<string, number>;
+type HeadlessEvent = {
+  type: 'start';
+  runId: string;
+  provider?: string;
+} | {
+  type: 'text';
+  delta: string;
+} | {
+  type: 'thinking';
+  delta: string;
+} | {
+  type: 'tool_call';
+  callId: string;
+  name: string;
+  input: Record<string, unknown>;
+} | {
+  type: 'tool_result';
+  callId: string;
+  name: string;
+  output: string;
+  isError: boolean;
+} | {
+  type: 'turn';
+  index: number;
+  usage: TurnUsage;
+} | {
+  type: 'spawn';
+  event: 'before' | 'complete' | 'error';
+  id: string;
+  info?: Record<string, unknown>;
+} | {
+  type: 'error';
+  message: string;
+  errorType?: string;
+} | {
+  type: 'result';
+  result: HeadlessResult;
+};
+/** Serialize one event as a newline-terminated JSON line (stream-json). */
+declare function headlessEventToJsonl(event: HeadlessEvent): string;
+interface HeadlessOptions {
+  /** User prompt — plain string or multimodal `PromptPart[]`. */
+  prompt: string | PromptPart[];
+  /** Built provider (e.g. `local()`, `openaiCompat(...)`, `anthropic(...)`). */
+  provider: Provider;
+  model?: string;
+  /** Override the preset system prompt for this run. */
+  system?: string;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  maxTokens?: number;
+  /** Wall-clock cap; on expiry the run is aborted and `status` becomes `'timeout'`. */
+  timeoutMs?: number;
+  /** External abort signal — chained with the internal timeout controller. */
+  signal?: AbortSignal;
+  /** JSON Schema for structured-output enforcement → populates `result.output`. */
+  schema?: Record<string, unknown>;
+  /** Tool overrides. Omit to use the basic preset's tools. */
+  tools?: Record<string, ToolDef>;
+  mcpServers?: McpServerConfig[];
+  skills?: AgentOptions['skills'];
+  /** Execution context. Defaults to a process context rooted at `cwd`. */
+  execution?: ExecutionContext;
+  /** Working directory for the default process context (ignored if `execution` is set). */
+  cwd?: string;
+  /** Reuse / resume an existing session. */
+  session?: Session;
+  /** Session store for a fresh session (defaults to an in-memory store). */
+  store?: SessionStore;
+  /** Keep `thinking` blocks in `result.transcript` (default true). */
+  includeThinking?: boolean;
+  /** Live event callback — the in-process stream-json equivalent. */
+  onEvent?: (event: HeadlessEvent) => void;
+}
+/**
+ * Run a prompt to completion, headless, and return a single serializable
+ * {@link HeadlessResult}. Safe to call concurrently for parallel rollouts —
+ * each call builds its own agent + session and tears them down in `finally`.
+ */
+declare function runHeadless(opts: HeadlessOptions): Promise<HeadlessResult>;
+interface OpenAIChatMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string | null;
+  tool_calls?: Array<{
+    id: string;
+    type: 'function';
+    function: {
+      name: string;
+      arguments: string;
+    };
+  }>;
+  tool_call_id?: string;
+}
+/**
+ * Convert raw `session.turns` into standard OpenAI chat-completion messages:
+ * assistant turns carry `tool_calls`, and each `tool_result` becomes its own
+ * `role: 'tool'` message. This is the drop-in shape for an SFT renderer —
+ * unlike `toOpenAI` (session/messages.ts), which emits an internal `_tag`
+ * envelope meant for re-sending to a provider, not for training data.
+ */
+declare function transcriptToOpenAIMessages(turns: SessionTurn[]): OpenAIChatMessage[];
+//#endregion
+//#region src/logger.d.ts
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface LogRecord {
+  level: LogLevel;
+  /** Unix ms — set by `Logger` at emit time. */
+  timestamp: number;
+  /** Free-form message. Sinks render this as the human-facing line. */
+  message: string;
+  /** Structured fields. Correlation ids land here automatically. */
+  attrs: Record<string, unknown>;
+}
+interface LogSink {
+  emit: (record: LogRecord) => void;
+}
+interface Logger {
+  debug: (message: string, attrs?: Record<string, unknown>) => void;
+  info: (message: string, attrs?: Record<string, unknown>) => void;
+  warn: (message: string, attrs?: Record<string, unknown>) => void;
+  error: (message: string, attrs?: Record<string, unknown>) => void;
   /**
-   * Postmortem snapshots of child runs that bubbled their stats up via
-   * `spawn:complete`. Only present when the run actually spawned.
+   * Returns a child logger that prepends the given attributes onto every
+   * subsequent emit. Equivalent to `pino.child` / `winston.child`. The
+   * parent and child share the same sink — children are zero-cost.
    */
-  children?: RunSummary[];
+  with: (extra: Record<string, unknown>) => Logger;
+  /**
+   * Inspectable baseline attributes — handy for tests and for hook
+   * handlers that want to clone-with-extra without recursing.
+   */
+  readonly baseAttributes: Readonly<Record<string, unknown>>;
 }
-interface RunSummaryCollectorOptions {
+/**
+ * Build a Logger from a sink. Stateless and cheap; create one per agent
+ * (or per app) and use `.with()` to attach correlation ids per-call.
+ */
+declare function createLogger(sink: LogSink, baseAttributes?: Readonly<Record<string, unknown>>): Logger;
+interface ConsoleSinkOptions {
   /**
-   * Called with the assembled {@link RunSummary} on every `agent:done`.
-   * Synchronous — heavy I/O should be deferred (e.g. via `setImmediate`).
+   * Minimum level to emit. Defaults to `'info'` — `debug` is dropped so
+   * the harness's lifecycle logging is not noisy by default. Set to
+   * `'debug'` to see every event.
    */
-  onSummary?: (summary: RunSummary) => void;
+  minLevel?: LogLevel;
+  /** Custom output stream. Defaults to `process.stderr` so logs don't pollute stdout. */
+  stream?: {
+    write: (chunk: string) => void;
+  };
 }
-interface RunSummaryCollector {
-  /** Install the collector's hook handlers. Returns an uninstall fn. */
+/**
+ * Human-readable terminal sink. Renders each record as
+ * `<ISO timestamp> <LEVEL> <message> <attrs as kv pairs>`.
+ *
+ * Honors `process.stderr` by default so log lines don't interleave with
+ * the agent's stdout-bound output (chat responses, JSON results).
+ */
+declare function consoleSink(options?: ConsoleSinkOptions): LogSink;
+/**
+ * One-JSON-object-per-line sink. Suitable for piping into log aggregators
+ * (Datadog Agent, Fluent Bit, Loki, Vector) that expect JSONL.
+ */
+declare function jsonSink(options?: ConsoleSinkOptions): LogSink;
+interface LoggingHooksOptions {
+  logger: Logger;
+  /**
+   * Minimum interesting level for harness-emitted lines. Default `'info'`.
+   * Set to `'debug'` to see every tool dispatch / stream event. Set to
+   * `'warn'` to mute the chatty ones and only see failures + budgets.
+   */
+  level?: LogLevel;
+  /**
+   * When true (default), lifecycle events (`agent:start`, `turn:before`,
+   * `tool:before`, `mcp:bootstrap:start`) emit at `debug` level so they
+   * stay quiet by default. Set false to mute them entirely regardless of
+   * the configured minimum level — useful when piping into a tracer
+   * that already captures lifecycle.
+   */
+  includeLifecycle?: boolean;
+}
+interface LoggingHookSet {
   install: (hooks: Hookable<AgentHooks>) => () => void;
-  /** Most-recent summary; `undefined` until the first `agent:done` fires. */
-  latest: () => RunSummary | undefined;
 }
 /**
- * Build a run-summary collector. State is created fresh inside each
- * `install()` call, so a single collector instance can be installed
- * across multiple agents without attribution cross-talk. `latest()`
- * returns the most-recent summary across **any** install — install
- * per-agent collectors if you need separate post-run snapshots.
+ * Install a bundle of hook handlers that emit a structured line per
+ * relevant lifecycle event, automatically attaching correlation ids
+ * (`runId`, `turnId`, `callId`, `childId`, `depth`, `agentName`).
  *
  * @example
  * ```ts
- * const collector = createRunSummaryCollector({
- *   onSummary: s => console.log(JSON.stringify(s)),
- * })
- * const uninstall = collector.install(agent.hooks)
+ * const logger = createLogger(consoleSink({ minLevel: 'debug' }), { service: 'tui' })
+ * const lh = createLoggingHooks({ logger })
+ * const uninstall = lh.install(agent.hooks)
  * try { await agent.run({ prompt }) }
  * finally { uninstall() }
  * ```
  */
-declare function createRunSummaryCollector(options?: RunSummaryCollectorOptions): RunSummaryCollector;
+declare function createLoggingHooks(options: LoggingHooksOptions): LoggingHookSet;
 //#endregion
-//#region src/stats.d.ts
+//#region src/loop.d.ts
 /**
- * Per-model usage rollup produced by {@link statsByModel}.
- *
- * `turns` counts the number of `TurnUsage` entries attributed to the model
- * across the whole tree (parent loop + every recursively-spawned child).
- * Cache and cost numbers are summed from the same set of turns.
+ * Canonical tool_result text emitted when a tool call is interrupted by the
+ * user mid-flight (Esc / Ctrl-C / external `AbortSignal`). Mirrors Claude
+ * Code's `INTERRUPT_MESSAGE_FOR_TOOL_USE` so downstream consumers can pattern
+ * match a single string across both harnesses. Always paired with
+ * `isError: true` on the wire — the model treats it as a failed call rather
+ * than a successful tool response.
  */
-interface ModelUsage {
-  input: number;
-  output: number;
-  cost: number;
-  cacheRead: number;
-  cacheCreation: number;
-  turns: number;
-}
+declare const INTERRUPT_MESSAGE_FOR_TOOL_USE = "[Request interrupted by user for tool use]";
 /**
- * Depth-first walk over the stats tree, returning every `TurnUsage` entry
- * — parent loop first, then each child subtree in completion order.
- *
- * Closes the cache-token aggregation gap: `TurnUsage.cacheRead` /
- * `cacheCreation` live only on per-turn entries, and the top-level
- * `AgentStats` deliberately doesn't carry cumulative forms (one source of
- * truth, no risk of drift). Anything that needs a tree-wide sum walks
- * through this.
+ * Canonical tool_result text emitted when a tool call is skipped because a
+ * steering message arrived between dispatches inside
+ * {@link executeToolBatch}. Distinguished from
+ * {@link INTERRUPT_MESSAGE_FOR_TOOL_USE} so consumers can split "user
+ * cancelled" from "framework superseded".
  */
-declare function flattenTurns(stats: AgentStats): TurnUsage[];
+declare const TOOL_USE_SKIPPED_MESSAGE = "[Tool use skipped \u2014 superseded by user message]";
 /**
- * Group cumulative usage by `TurnUsage.modelId`. Each entry sums the input,
- * output, cache, cost, and turn-count across every turn the tree attributed
- * to that model — naturally handling cross-model runs (vision-fallback,
- * model-shifted subagents, mixed-provider workflows).
+ * Canonical tool_result text emitted when a single tool call is cancelled
+ * mid-flight via `agent.cancelTool(callId)` (typically the TUI's
+ * "cancel this tool" affordance). Distinguished from
+ * {@link INTERRUPT_MESSAGE_FOR_TOOL_USE} (run-wide user abort) and
+ * {@link TOOL_USE_SKIPPED_MESSAGE} (steered) so the model — and downstream
+ * consumers — can tell the three apart by string match.
  *
- * Turns missing `modelId` (mock providers, providers that don't echo a model
- * id) are bucketed under the literal string `'(unknown)'`.
+ * Always paired with `isError: true` on the wire so the model treats the
+ * call as failed rather than as a successful response. The remaining tool
+ * calls in the batch continue running, in contrast with a full-run abort.
  */
-declare function statsByModel(stats: AgentStats): Map<string, ModelUsage>;
-//#endregion
-//#region src/system-prompt.d.ts
+declare const TOOL_USE_CANCELLED_MESSAGE = "[Tool call cancelled by user]";
 /**
- * System-prompt boundary marker — splits a system prompt into a stable static
- * prefix (cached) and a per-turn dynamic suffix (NOT cached).
- *
- * Why this exists: providers attach `cache_control` markers on the last block
- * of the system prompt, so the cached prefix covers the entire system text.
- * Any byte change anywhere — including a per-turn `<env>` rewrite — busts the
- * cache for the doctrine that sits below. A literal marker in the system
- * string lets providers split it into:
- *
- *   ┌──────────────┐ cache_control: ephemeral
- *   │ STATIC half  │  — doctrine, skills catalog, tool catalog,
- *   │              │    user instructions
- *   ├──────────────┤  ← SYSTEM_PROMPT_BOUNDARY
- *   │ DYNAMIC half │  — env, cwd, mtimes, anything per-turn
- *   └──────────────┘ (no cache_control)
- *
- * The static prefix rides the prompt cache across turns/sessions; the dynamic
- * suffix re-bills per turn. Net effect: a cwd change between turns no longer
- * invalidates 4 KB of doctrine.
- *
- * Wire contract:
- *
- * - `splitSystemPrompt(s)` is pure; missing marker ⇒ entire string is static
- *   (current behavior — no caller is forced to opt in).
- * - `renderSystemForWire(s)` strips the marker so it never reaches the model;
- *   used by every provider before the bytes hit the wire, including the
- *   cache-disabled path on providers that DO support `cache_control`.
- * - The marker uses underscores rather than XML/punctuation so it's
- *   unambiguous when scanning prompts manually and unlikely to collide with
- *   model-written content.
- * - Providers handle the split internally (Anthropic emits a 2-block array;
- *   OpenAI-compat splits the leading `system` message into multi-part text).
- *   Callers always pass a single `string` — no API break.
+ * Canonical `tool_result.content` text emitted to siblings that were
+ * cancelled by a `shell` error in the same batch. Distinct from
+ * {@link INTERRUPT_MESSAGE_FOR_TOOL_USE} (user-issued abort) and
+ * {@link TOOL_USE_SKIPPED_MESSAGE} (steered) so consumers can split
+ * the three causes by string-match.
  */
+declare const SHELL_CASCADE_CANCEL_MESSAGE = "Cancelled: a sibling `shell` call in the same batch errored; re-run independently if still needed.";
+//#endregion
+//#region src/loop-persistence.d.ts
 /**
- * Literal marker inserted in a system prompt to separate cacheable doctrine
- * from per-turn dynamic content. Providers split on this token.
+ * Bytes of head content included in the inline preview block. 2 KiB matches
+ * Claude Code's `PREVIEW_SIZE_BYTES` — enough for the model to identify the
+ * content class (error output / structured data / log shape) and decide
+ * whether to call `read_file` on the persisted path for the full payload.
  *
- * Underscored on both sides for visual distinctiveness — a stray instance in
- * model-written prose is implausible. Don't change the value without shipping
- * a migration; existing sessions carry the old marker in their cached
- * prompts.
+ * Tail-priority preview (matching `shell`'s truncation strategy) was
+ * considered but rejected: most "what is this?" decisions get made from
+ * the head, and the path is in the stub for the rare case where the tail
+ * matters.
  */
-declare const SYSTEM_PROMPT_BOUNDARY = "__ZIDANE_SYSTEM_PROMPT_BOUNDARY__";
-/** Result of {@link splitSystemPrompt} — both halves stripped of the marker. */
-interface SystemPromptParts {
-  /** Bytes BEFORE the marker (or the entire string when no marker present). Cacheable. */
-  static: string;
-  /** Bytes AFTER the marker. Empty when no marker present. NOT cached. */
-  dynamic: string;
-}
+declare const PERSISTENCE_PREVIEW_BYTES: number;
 /**
- * Split a system prompt around the first {@link SYSTEM_PROMPT_BOUNDARY}.
- *
- * Splits on the FIRST occurrence — subsequent markers are folded into the
- * dynamic half. This way callers can append additional `<env>` style blocks
- * with extra markers without each one creating a new cache layer (Anthropic
- * caps breakpoints; we use the budget elsewhere). The marker itself is
- * stripped from both sides — providers attach `cache_control` directly to
- * the static half's text content.
- *
- * A single blank line (`\n\n`) immediately adjacent to the marker on each
- * side is trimmed — callers conventionally write
- * `<doctrine>\n\n<MARKER>\n\n<env>` and expect the rendered wire bytes to
- * read as one logical paragraph. Blank lines beyond that immediate pair
- * (e.g. `\n\n\n<env>`) are preserved verbatim so callers composing their
- * own spacing don't lose intentional gaps.
+ * Byte-stable prefix every {@link buildPersistedStub} output starts with.
+ * Exported so wire-level passes (tail compaction, future stale-output
+ * elision) can recognize a persisted stub and preserve its path attribute
+ * rather than replacing the stub with their own — losing the pointer to
+ * the on-disk blob.
  *
- * Pure / no I/O / no allocation when the marker is absent (returns the input
- * verbatim on the static side and the empty string on the dynamic side).
+ * Bound to the literal opening of the XML tag; changing the stub format
+ * requires updating this constant in lockstep (and shipping a migration
+ * for in-flight sessions).
  */
-declare function splitSystemPrompt(system: string): SystemPromptParts;
+declare const PERSISTED_STUB_PREFIX = "<persisted-output tool=\"";
 /**
- * Compose a system prompt from a static prefix and an optional dynamic
- * suffix. Inserts {@link SYSTEM_PROMPT_BOUNDARY} between them only when the
- * dynamic side is non-empty — single-block prompts stay marker-free, so
- * callers that never opt in pay zero overhead and providers fall back to the
- * existing whole-string caching path.
+ * Resolve the per-session persistence directory under `<userDir>/tool-results/<sessionId>/`.
  *
- * Spacing is `\n\n` on both sides of the marker so doctrine fragments,
- * which conventionally separate sections with a blank line, read cleanly
- * around the boundary.
+ * The chat layer calls this at session activation and forwards the result
+ * via `behavior.persistDir`. Exposed as a public helper so SDK consumers
+ * pick the same layout — single source of truth for "where do blobs live".
  */
-declare function joinSystemPrompt(staticPart: string, dynamicPart: string): string;
+declare function resolvePersistDir(opts: {
+  userDir: string;
+  sessionId: string;
+}): string;
 /**
- * Append `extra` to the STATIC half of a system prompt, preserving any
- * existing dynamic suffix.
- *
- * Used by the agent to fold in run-stable content (skills catalog, lazy tool
- * catalog) without bumping it into the dynamic half — both catalogs are
- * built once per run and remain byte-stable for the duration, so they
- * belong in the cached prefix.
+ * Resolve the per-session background-tasks directory under
+ * `<userDir>/<sessionId>/tasks/`.
  *
- * Returns a new string; the input is not mutated. When `extra` is empty,
- * returns the input verbatim.
+ * The chat layer calls this at session activation and forwards the result
+ * via `behavior.tasksDir`. Same shape as {@link resolvePersistDir}: hosts
+ * get a single source of truth for "where do task log files live".
+ * Created on first write; cleanup is the session-delete path's job.
  */
-declare function appendStaticSection(system: string, extra: string): string;
+declare function resolveTasksDir(opts: {
+  userDir: string;
+  sessionId: string;
+}): string;
 /**
- * Append `extra` to the DYNAMIC half of a system prompt. Inserts the boundary
- * marker if the input didn't already carry one.
- *
- * Used by hosts (typically the TUI) to inject per-turn state — current cwd,
- * IDE selection, project root — without forcing every caller to know the
- * marker format. The host's `system:transform` hook rewrites the dynamic
- * half each turn; the static doctrine above stays byte-stable and rides the
- * cache.
- *
- * Returns a new string; the input is not mutated. When `extra` is empty,
- * returns the input verbatim.
+ * Inputs to {@link maybePersistToolResult}. Kept as a struct so the loop's
+ * call site stays readable and additional optional knobs (compression,
+ * mime detection, …) land without re-threading every call site.
  */
-declare function appendDynamicSection(system: string, extra: string): string;
+interface PersistInput {
+  /** Canonical tool name — checked against `excludeTools`. */
+  toolName: string;
+  /** `tool_use` id from the assistant turn. Used as the filename. */
+  callId: string;
+  /** Result returned by the tool (post-`tool:transform`). */
+  output: string | ToolResultContent[];
+  /** Byte threshold; outputs at or below stay inline. */
+  threshold: number;
+  /** Canonical tool names that bypass persistence. */
+  excludeTools?: readonly string[];
+  /** Persistence root directory. Created on first write. */
+  persistDir: string;
+  /**
+   * Optional cap on the total bytes of persisted blobs under `persistDir`.
+   * When set (and > 0), after a successful write the helper sweeps the
+   * directory and removes the oldest `*.txt` blobs (by mtime) until the
+   * sum of remaining sizes is at or below the cap.
+   *
+   * Bound to the **current session** because `persistDir` is per-session
+   * (see {@link resolvePersistDir}); eviction never crosses session
+   * boundaries. The new blob is always preserved — its mtime is the
+   * latest, so the LRU sort guarantees older blobs go first.
+   *
+   * Skipped when the value isn't a positive finite number. Eviction
+   * failures (permissions, races) are surfaced through `ZIDANE_DEBUG`
+   * but never block the calling tool result; an over-cap dir is a
+   * housekeeping concern, not a correctness one.
+   */
+  maxBytes?: number;
+}
+type PersistOutcome = {
+  kind: 'skip';
+  reason: 'disabled' | 'excluded' | 'under-threshold' | 'unsupported-shape' | 'unsafe-call-id' | 'invalid-persist-dir';
+} | {
+  kind: 'persisted';
+  output: string;
+  originalBytes: number;
+  persistedPath: string;
+  evicted?: {
+    files: number;
+    bytes: number;
+  };
+} | {
+  kind: 'error';
+  reason: 'write-failed';
+  error: Error;
+};
 /**
- * Replace the entire dynamic half of a system prompt with `next`. Used by
- * the TUI's `<env>` rewriter where the entire dynamic section is regenerated
- * each turn rather than appended to.
+ * Decide-and-persist for a single tool result. Pure decision + filesystem
+ * side-effect; returns the new wire-level `output` string when substitution
+ * happened, otherwise tells the caller to leave the result alone.
  *
- * When `next` is empty, drops the dynamic half (and the marker) entirely.
+ * Atomicity: writes go through `<path>.tmp` + `rename` so a concurrent
+ * read (or a crash mid-write) never sees a half-written blob.
+ *
+ * `ToolResultContent[]` results (images, structured blocks) currently bypass
+ * persistence — the inline image bytes are the point of the call, and a
+ * mixed text/image array isn't representable as a single `.txt` file. We
+ * may revisit if a tool starts returning very large text-only arrays.
  */
-declare function replaceDynamicSection(system: string, next: string): string;
+declare function maybePersistToolResult(input: PersistInput): Promise<PersistOutcome>;
+interface BuildStubInput {
+  toolName: string;
+  originalBytes: number;
+  persistedPath: string;
+  output: string;
+}
 /**
- * Strip the boundary marker so it never reaches the wire — collapses
- * `<static>${BOUNDARY}<dynamic>` into `<static>\n\n<dynamic>` for providers
- * that can't honor `cache_control` (vanilla OpenAI Chat Completions, Codex,
- * Cerebras, ...) or for the cache-disabled path on any provider.
+ * Render the byte-stable `<persisted-output>` stub the model sees in place
+ * of the original `tool_result`.
  *
- * Cache-aware providers re-derive the split from the original (un-rendered)
- * system string via `splitSystemPrompt` — `renderSystemForWire` is the
- * marker-free counterpart used to build the actual wire bytes.
+ * Format choices:
+ *  - XML wrapper because models reliably parse it as structural.
+ *  - Byte count + path in attributes so the model can decide whether to
+ *    `read_file` the persisted blob without scanning the preview.
+ *  - Preview always shows the head — `shell`'s tail-priority truncation is
+ *    irrelevant here because the model has the full path if it needs the
+ *    tail.
+ *  - No timestamps, no random UUIDs inside the stub: every byte must be
+ *    reproducible from the inputs, otherwise re-emission on subsequent
+ *    turns would bust the prompt cache.
  *
- * No-op when the input has no marker. Pure / no I/O.
+ * Exported for tests (asserting the byte-stable contract) and for SDK
+ * consumers wiring their own persistence middleware against the same
+ * surface.
  */
-declare function renderSystemForWire(system: string): string;
-/** True when `system` contains the boundary marker. */
-declare function hasSystemPromptBoundary(system: string): boolean;
-//#endregion
-//#region src/tools/edit.d.ts
+declare function buildPersistedStub(input: BuildStubInput): string;
 /**
- * Surgical edit — replace `old_string` with `new_string` in a single file.
+ * Remove every persisted blob belonging to a session. Called by the chat
+ * layer from its session-delete path so closing a session frees the disk
+ * footprint alongside the SQLite row.
  *
- * Mirrors Claude Code's `Edit` semantics so models post-trained on Anthropic's
- * tool surface need no relearning. Fails clearly when `old_string` isn't unique
- * (unless `replace_all: true`) and when not found, with a nearest-match preview
- * so the model can recover without a separate `read_file` round-trip.
+ * Idempotent — missing directory (session never persisted anything) is a
+ * no-op, not an error. Wraps the `rm -rf` so a permissions blip on one
+ * blob doesn't propagate to the caller; the chat layer can't usefully
+ * recover from "couldn't unlink a result file" mid-delete.
  */
-declare const edit: ToolDef;
-//#endregion
-//#region src/tools/glob.d.ts
-declare const glob: ToolDef;
-//#endregion
-//#region src/tools/grep.d.ts
-declare const grep: ToolDef;
+declare function cleanupPersistedSession(persistRoot: string): Promise<void>;
 //#endregion
-//#region src/tools/interaction.d.ts
-interface InteractionToolOptions {
-  /** JSON Schema for the request payload the model sends */
-  schema: Record<string, unknown>;
-  /** Tool name (default: 'interaction') */
-  name?: string;
-  /** Tool description shown to the model */
-  description?: string;
-  /** Called when the model invokes this tool. Receives the validated payload and tool context, returns data for the model. */
-  onRequest: (payload: Record<string, unknown>, ctx: ToolContext) => Promise<Record<string, unknown> | string>;
+//#region src/mcp/oauth-provider.d.ts
+/**
+ * Per-server persisted state. Subfields are optional so a partial save
+ * (e.g. `saveCodeVerifier` arriving before `saveTokens`) doesn't blow away
+ * earlier subfields — the provider always patches, never replaces.
+ */
+interface McpCredentialEntry {
+  tokens?: OAuthTokens;
+  clientInformation?: OAuthClientInformationMixed;
+  discoveryState?: OAuthDiscoveryState;
+}
+interface McpCredentialStore {
+  load: (name: string) => McpCredentialEntry | undefined;
+  save: (name: string, entry: McpCredentialEntry) => void;
+  delete: (name: string) => void;
 }
 /**
- * Create an interaction tool that lets the agent request structured input.
- *
- * The model calls this tool with a payload matching the schema.
- * `onRequest` is called with the payload and should return the response
- * (string or object) that gets sent back to the model as the tool result.
+ * In-memory store — primarily for tests, but valid as a no-persistence option
+ * (tokens evaporate on process exit, the user re-auths every cold start).
  */
-declare function createInteractionTool(options: InteractionToolOptions): ToolDef;
-//#endregion
-//#region src/tools/list-files.d.ts
-declare const listFiles: ToolDef;
-//#endregion
-//#region src/tools/multi-edit.d.ts
-declare const multiEdit: ToolDef;
-//#endregion
-//#region src/tools/read-file.d.ts
-declare const readFile: ToolDef;
-//#endregion
-//#region src/tools/shell.d.ts
-interface CreateShellToolOptions {
-  /**
-   * Whether to expose the `run_in_background` flag in the input schema +
-   * the background-mode paragraphs in the description. When `false`, the
-   * model never sees the flag and won't try to use it. The execute path
-   * still has a defensive fallback: an explicit `run_in_background: true`
-   * call (e.g. from a hand-crafted message) returns a clean error rather
-   * than silently running foreground.
-   *
-   * Default: `true`.
+declare function createMemoryMcpCredentialStore(seed?: Record<string, McpCredentialEntry>): McpCredentialStore;
+interface McpOAuthProviderOptions {
+  /** Server name — used as the storage key. */
+  name: string;
+  /** Persistence backend. */
+  store: McpCredentialStore;
+  /**
+   * Loopback callback URI. Pass `undefined` for bootstrap (non-interactive
+   * mode — stored tokens + refresh only, never opens a browser).
    */
-  allowBackground?: boolean;
+  redirectUri?: string;
   /**
-   * Canonical names of tools registered alongside `shell` on the same
-   * agent. When non-empty, the description gains a "prefer the dedicated
-   * tool" block for each known sibling (`read_file`, `glob`, `grep`,
-   * `list_files`, `edit`, `write_file`) — useful against the
-   * `ls`/`cat`-to-re-verify loop some models fall into when both a
-   * dedicated tool AND `shell` are visible. Unknown / unrecognized names
-   * are ignored.
-   *
-   * Set by `createAgent` per-run from the tool registry; hosts that
-   * construct a `shell` directly can pass it explicitly. Omit to suppress
-   * the block entirely (no nudge for shell-only agents, no nudge for
-   * hosts that prefer to author their own anti-loop prose).
+   * Invoked when the SDK wants the user agent to navigate to the authorization
+   * URL. Typically the host opens the browser AND emits a hook so the TUI can
+   * render the URL in a status row. No-op in non-interactive mode (the SDK
+   * still calls this before throwing `UnauthorizedError` from connect).
    */
-  registeredCanonicals?: ReadonlySet<string>;
+  onAuthorizationUrl?: (url: URL) => void | Promise<void>;
   /**
-   * The agent's `toolAliases` map, used to render the wire-level name of
-   * each sibling in the swap block. Without this, the block always prints
-   * canonical names — fine for the default preset, wrong for hosts that
-   * alias-rename (the model would be told to call a name it doesn't see
-   * in the tool spec).
+   * `client_name` used in dynamic client registration. Defaults to `'zidane'`.
+   * Some servers display this string to the user on the consent screen.
    */
-  toolAliases?: Record<string, string>;
+  clientName?: string;
+  /**
+   * Override the requested OAuth scope. Default: unset (the SDK negotiates
+   * via the server's metadata).
+   */
+  scope?: string;
+}
+declare class McpOAuthProvider implements OAuthClientProvider {
+  private readonly name;
+  private readonly store;
+  private readonly _redirectUri?;
+  private readonly onAuthorizationUrl?;
+  private readonly clientName;
+  private readonly _scope?;
+  private codeVerifierValue;
+  constructor(opts: McpOAuthProviderOptions);
+  get redirectUrl(): string | URL | undefined;
+  get clientMetadata(): OAuthClientMetadata;
+  tokens(): OAuthTokens | undefined;
+  saveTokens(tokens: OAuthTokens): void;
+  clientInformation(): OAuthClientInformationMixed | undefined;
+  saveClientInformation(info: OAuthClientInformationMixed): void;
+  discoveryState(): OAuthDiscoveryState | undefined;
+  saveDiscoveryState(state: OAuthDiscoveryState): void;
+  saveCodeVerifier(verifier: string): void;
+  codeVerifier(): string;
+  redirectToAuthorization(url: URL): Promise<void>;
+  /**
+   * Wipe stored credentials when the server reports the cached state is no
+   * longer valid. The SDK calls this with a scope hint:
+   *   - `'tokens'`  → access/refresh revoked, keep client registration
+   *   - `'client'`  → client registration invalidated, reset everything
+   *   - `'verifier'`→ PKCE state stale (e.g. mismatched state param)
+   *   - `'discovery'` → discovery metadata stale (servers re-keyed)
+   *   - `'all'`     → full reset
+   */
+  invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void>;
+  private patch;
 }
 /**
- * Factory for the `shell` tool. The default exported `shell` is
- * equivalent to `createShellTool({ allowBackground: true })`. The
- * factory is the entry point hosts use when they want to override the
- * default — e.g. to ship a preset that always disables background mode
- * regardless of `behavior.tasksDir`.
- *
- * Hosts that use the framework's `createAgent` typically don't need to
- * call this directly: when `behavior.tasksDir` is unset or
- * `behavior.disableBackgroundTasks: true` is set, the agent
- * automatically rewrites the registered `shell` (if it's the
- * framework's built-in) using this factory.
- */
-declare function createShellTool(opts?: CreateShellToolOptions): ToolDef;
-/**
- * Default `shell` tool with background mode enabled.
+ * True when an HTTP transport's auth headers already include an explicit
+ * Authorization. Used by the bootstrap escape-hatch: a user who provided
+ * their own bearer token shouldn't be auto-promoted to OAuth on a 401.
  *
- * Most hosts use this directly via `basicTools`. When the agent's
- * `behavior.tasksDir` is unset OR `behavior.disableBackgroundTasks:
- * true` is set, `createAgent` auto-rewrites this identity to a
- * `createShellTool({ allowBackground: false })` variant so the model
- * never sees a flag it can't use. Hosts who want to bypass that
- * auto-rewrite can register a `createShellTool({ allowBackground })`
- * directly — the rewrite only fires on identity-equal references to
- * this constant.
+ * Case-insensitive — Node normalizes outgoing headers to lowercase but
+ * users hand-write `Authorization` in configs.
  */
-declare const shell: ToolDef;
-//#endregion
-//#region src/tools/shell-kill.d.ts
-declare const shellKill: ToolDef;
-//#endregion
-//#region src/tools/skills-read.d.ts
-interface SkillsReadToolOptions {
-  catalog: readonly SkillConfig[];
-  state: SkillActivationState;
-}
-declare function createSkillsReadTool(options: SkillsReadToolOptions): ToolDef;
+declare function hasAuthorizationHeader(headers: Record<string, string> | undefined): boolean;
 //#endregion
-//#region src/tools/skills-run-script.d.ts
-interface SkillsRunScriptToolOptions {
-  catalog: readonly SkillConfig[];
-  state: SkillActivationState;
-  /** Script timeout in milliseconds. Default 60000. */
-  scriptTimeoutMs?: number;
+//#region src/mcp/login.d.ts
+interface LoginMcpServerOptions {
+  /** Persistence — same store the bootstrap path reads from. */
+  store: McpCredentialStore;
+  /**
+   * Invoked with the authorization URL once it's ready. Hosts typically
+   * (a) emit `mcp:auth:url` for the TUI, and (b) call `tryOpenBrowser`.
+   * The URL is identical to the one passed to the `mcp:auth:url` hook
+   * fired automatically — this callback is a synchronous hook for callers
+   * that don't want to wire the agent hook machinery.
+   */
+  onAuthorizationUrl?: (url: URL) => void | Promise<void>;
+  /** Cancels the flow (esc / close modal / SIGINT). */
+  signal?: AbortSignal;
+  /** Agent hooks. The flow emits `mcp:auth:url`/`success`/`error` when wired. */
+  hooks?: Hookable<AgentHooks>;
+  /** Override `client_name` shown on consent screens. Default: 'zidane'. */
+  clientName?: string;
+  /** Override the requested OAuth scope. */
+  scope?: string;
+  /**
+   * Override the loopback callback path. Default: `/callback`. Useful only
+   * for servers that pinned a different path during registration.
+   */
+  callbackPath?: string;
+  /**
+   * Maximum time to wait for the user to complete the browser flow, in ms.
+   * The user can also cancel via `signal`. Default: 5 minutes.
+   */
+  timeoutMs?: number;
 }
-declare function createSkillsRunScriptTool(options: SkillsRunScriptToolOptions): ToolDef;
-//#endregion
-//#region src/tools/skills-use.d.ts
-interface SkillsUseToolOptions {
-  /** Resolved skills catalog for this run. */
-  catalog: readonly SkillConfig[];
-  /** Per-agent activation state the tool mutates. */
-  state: SkillActivationState;
-  /** Agent hooks — used to fire `skills:activate` on first activation. */
-  hooks: Hookable<AgentHooks>;
+interface LoginMcpServerResult {
+  /** Stored OAuth tokens after a successful exchange. */
+  tokens: NonNullable<ReturnType<McpOAuthProvider['tokens']>>;
+  /**
+   * Upstream tool descriptors discovered after re-connecting with the new
+   * tokens. Already filtered by the server's `enabledTools` / `disabledTools`
+   * is NOT applied here — that's a bootstrap concern. Hosts that want filtering
+   * should pass the result through `connectMcpServers` rebuild on the next
+   * session activation rather than reusing this list verbatim.
+   */
+  tools: Array<{
+    name: string;
+    description?: string | null;
+    inputSchema?: unknown;
+  }>;
 }
 /**
- * Factory for `skills_use`. Auto-injected into the agent's tool set by the
- * agent runtime when a non-empty skills catalog is available (unless
- * `SkillsConfig.tool === false`).
+ * Run the full interactive OAuth flow for `config`. Only supports `sse` and
+ * `streamable-http` transports — `stdio` MCP servers don't speak OAuth.
  *
- * The tool schema's `name` property is `enum`-constrained to the resolved
- * catalog so the LLM cannot hallucinate a skill that doesn't exist.
+ * Throws on:
+ *   - Wrong transport.
+ *   - Abort signal.
+ *   - Browser-side error (user denied, server rejected, etc.).
+ *   - Code exchange failure.
+ *   - Post-exchange connect failure.
+ *
+ * Always closes the loopback callback server before returning, success or
+ * failure.
  */
-declare function createSkillsUseTool(options: SkillsUseToolOptions): ToolDef;
+declare function loginMcpServer(config: McpServerConfig, options: LoginMcpServerOptions): Promise<LoginMcpServerResult>;
 //#endregion
-//#region src/tools/spawn.d.ts
-interface ChildAgent {
-  id: string;
-  task: string;
-  startedAt: number;
-  /** Subagent depth — 1 for a direct child of a top-level agent. */
-  depth: number;
+//#region src/mcp/oauth-callback.d.ts
+/**
+ * Local loopback HTTP callback for OAuth 2.0 authorization code flows.
+ *
+ * Stands up a one-shot server on `127.0.0.1:<random>` that captures the
+ * `?code=...` redirect from a browser-driven OAuth flow and resolves a
+ * promise with the code. Used as the `redirectUrl` half of the MCP SDK's
+ * `OAuthClientProvider` (the persistence half lives separately).
+ *
+ * Design:
+ *   - Loopback-only (`127.0.0.1`) — the OAuth spec treats `http://127.0.0.1:<port>`
+ *     as a public-client redirect URI per RFC 8252 §7.3. Browsers do NOT block it,
+ *     and Anthropic / OpenAI / Linear / GitHub all accept it.
+ *   - Random port (`port = 0`) — the OS picks an unused one. We read the actual
+ *     port back from `server.address()` after `listen()`.
+ *   - Single-shot — the first GET to `path` with a `code` (or `error`) wins;
+ *     subsequent requests get 404. The server keeps listening (in case the user
+ *     hits "back" and re-authorizes), so callers must `close()` once they have
+ *     the code or have given up.
+ *   - Abort-aware — wiring an external `AbortSignal` rejects the promise and
+ *     closes the server immediately. Required for the TUI's "esc cancels login"
+ *     UX.
+ *   - No HTML framework — a single inline `<html>` string keeps this isolated
+ *     from any UI dependency.
+ */
+/**
+ * Result of a successful callback. `state` is forwarded verbatim from the
+ * query string — callers verify it against their pre-flight value to defend
+ * against CSRF (the MCP SDK does this internally when it controls `state`).
+ */
+interface OAuthCallbackResult {
+  code: string;
+  state?: string;
 }
-interface SpawnToolState {
-  /** Currently running children. */
-  readonly children: ReadonlyMap<string, ChildAgent>;
+interface OAuthCallbackHandle {
   /**
-   * Cumulative stats across every completed direct child of this spawn-tool
-   * instance (returns a copy). Each child's contribution is the cumulative
-   * `AgentStats` returned by its `agent.run()` — so
-   * `totalIn`/`totalOut`/`totalCacheRead`/`totalCacheCreation` cover the
-   * entire subtree (children + grandchildren + …), while `turns` and
-   * `elapsed` stay parent-loop-only per child and are summed across direct
-   * children. `elapsed` over-counts when children ran in parallel.
+   * Full URI to register with the authorization server, e.g.
+   * `http://127.0.0.1:51823/callback`. Stable for the lifetime of the
+   * handle.
+   */
+  redirectUri: string;
+  /**
+   * Resolves with `{ code, state }` on a successful callback. Rejects with:
+   *   - The OAuth-spec `error` field (`access_denied`, `server_error`, ...)
+   *     when the authorization server redirects with `?error=...`.
+   *   - `'OAuth callback aborted'` when the external `AbortSignal` fires.
+   *   - `'OAuth callback server closed'` when `close()` is called before any
+   *     callback arrives.
    *
-   * Lives across multiple parent runs that share this instance.
+   * Single-shot — only the first matching request resolves the promise.
    */
-  readonly totalChildStats: Readonly<AgentStats>;
+  promise: Promise<OAuthCallbackResult>;
+  /**
+   * Idempotent shutdown. Safe to call from a `finally` block whether the
+   * flow succeeded, failed, or was aborted. Resolves once the server stops
+   * accepting connections.
+   */
+  close: () => Promise<void>;
 }
-interface SpawnToolOptions {
-  /** Maximum concurrent sub-agents (default: 3). */
-  maxConcurrent?: number;
+interface OAuthCallbackOptions {
+  /** Cancels the flow — rejects `promise` and closes the server. */
+  signal?: AbortSignal;
   /**
-   * Maximum subagent depth. 0 disables spawning entirely; 1 allows top-level
-   * spawns but forbids grandchildren; 3 (default) allows three levels of
-   * recursion — enough for most orchestration patterns, a sharp ceiling
-   * against runaway loops.
+   * Path component the authorization server should redirect to. Defaults
+   * to `/callback`. Useful when matching a pre-registered URI that uses a
+   * different path.
    */
-  maxDepth?: number;
-  /** Child model override. */
-  model?: string;
-  /** Child system prompt override. Per-spawn `input.system` takes precedence. */
-  system?: string;
-  /** Child thinking level. */
-  thinking?: 'off' | 'minimal' | 'low' | 'medium' | 'high';
-  /** Preset override for children. Shallow-merged over the parent's preset (parent fields still win for anything left unset). */
-  preset?: Preset;
+  path?: string;
   /**
-   * Per-child timeout, in milliseconds. When the child exceeds it the spawn
-   * tool returns a timeout marker, fires `spawn:error`, and destroys the
-   * child agent. Default: none.
+   * Override the loopback host. Defaults to `127.0.0.1`. Don't bind to
+   * `0.0.0.0` here — the OAuth code is a one-time secret and the server
+   * would otherwise accept it from any host on the LAN.
    */
-  timeoutMs?: number;
+  host?: string;
   /**
-   * When `true` and the parent has a session, the child reuses the parent's
-   * session — child turns are appended with the child's own `runId`, and the
-   * resulting `SessionRun` carries `parentRunId` so the tree is
-   * reconstructible. Default: `false` (child is in-memory only).
-   *
-   * **Read-state isolation.** Sharing the session also shares the
-   * `read_file` / `requireReadBeforeEdit` tracking map (it's keyed
-   * by `Session`). With `persist: false` the child gets no session,
-   * so reads inside the subagent populate nothing the parent can see —
-   * a follow-up `edit` / `multi_edit` in the parent will trip the
-   * gate with `"has not been read"` even though the model just
-   * read the file in the child. Use {@link shareReadState} when
-   * you want the parent's gate to honor the child's reads WITHOUT
-   * also persisting child turns to the parent's session.
+   * Override the port. Defaults to `0` (OS-assigned). Pin to a fixed port
+   * only when the authorization server requires a pre-registered redirect
+   * URI; the random-port path is preferred so concurrent flows don't clash.
    */
-  persist?: boolean;
+  port?: number;
+}
+/**
+ * Start a one-shot OAuth callback server. The returned handle's `redirectUri`
+ * should be passed to the authorization server as the `redirect_uri` query
+ * parameter; `promise` resolves once the user finishes the browser flow.
+ *
+ * Always `await handle.close()` in a `finally` block — even on success, the
+ * server stays open until told to shut down (so it can serve the
+ * "you can close this tab" page).
+ */
+declare function startOAuthCallback(opts?: OAuthCallbackOptions): Promise<OAuthCallbackHandle>;
+//#endregion
+//#region src/metrics.d.ts
+type MetricAttributes = Record<string, string | number | boolean | undefined>;
+interface Counter {
+  add: (value: number, attributes?: MetricAttributes) => void;
+}
+interface Histogram {
+  record: (value: number, attributes?: MetricAttributes) => void;
+}
+interface UpDownCounter {
+  add: (value: number, attributes?: MetricAttributes) => void;
+}
+interface InstrumentOptions {
+  description?: string;
+  unit?: string;
+}
+/**
+ * Minimal Meter interface — structurally identical to OTel's `Meter`.
+ * Hosts passing `metrics.getMeter(name)` (from `@opentelemetry/api`)
+ * satisfy this without adaptation.
+ */
+interface Meter {
+  createCounter: (name: string, options?: InstrumentOptions) => Counter;
+  createHistogram: (name: string, options?: InstrumentOptions) => Histogram;
+  createUpDownCounter: (name: string, options?: InstrumentOptions) => UpDownCounter;
+}
+interface MetricsHooksOptions {
+  meter: Meter;
   /**
-   * Forward the parent's read-state map to the child agent so the
-   * `requireReadBeforeEdit` gate and `dedupReads` cache see reads
-   * across the parent/child boundary. Orthogonal to {@link persist} —
-   * use this when you want shared read tracking without sharing the
-   * session's turn history. Default: `false`.
-   *
-   * Has no effect when the parent has no read-state to share (no
-   * session and no explicit `readState` on the parent agent's
-   * options). Implementation: passes the parent's resolved
-   * `ReadStateMap` to the child via `AgentOptions.readState`, which
-   * tools resolve via `ctx.readState ?? getReadState(ctx.session)`.
+   * Optional prefix prepended to every instrument name. Default: no prefix
+   * (instrument names follow OTel Gen AI semantic conventions verbatim,
+   * which is the most-portable shape). Set to e.g. `'zidane.'` to
+   * namespace inside a shared meter registry.
    */
-  shareReadState?: boolean;
+  namespace?: string;
   /**
-   * Forward a curated subset of child hook events (`stream:*`, `tool:*`,
-   * `turn:after`) onto the parent's hook bus as `child:*` events. Default:
-   * `true`. Grandchildren bubble through their child transparently.
+   * Optional baseline attributes applied to every measurement. Typical
+   * use: `{ service: 'tui', env: 'prod' }`. Per-event attributes win on
+   * key collision.
    */
-  forwardHooks?: boolean;
-  /** Called when a child agent starts. */
-  onSpawn?: (child: ChildAgent) => void;
-  /** Called when a child agent completes (success, abort, timeout, or error). */
-  onComplete?: (child: ChildAgent, stats: AgentStats, status: NonNullable<ChildRunStats['status']>) => void;
+  baseAttributes?: MetricAttributes;
   /**
-   * Named subagent presets the model can select via the `subagent_type`
-   * input field. Mirrors the Claude Code SDK's surface — models trained
-   * on it routinely emit `subagent_type: 'Explore' | 'Plan' |
-   * 'Verification' | 'general-purpose'`, and without a registry the
-   * field is silently dropped, so hosts wanting type-specialized
-   * subagents have to invent their own dispatch layer.
-   *
-   * Each entry overlays the base spawn config for that particular
-   * dispatch. Per-call `input.system` still wins over `subagents[type].system`
-   * so the model can always specialize further.
-   *
-   * When the registry is non-empty:
-   *   - `subagent_type` appears in the spawn input schema as a `string`
-   *     enum of the registered keys (plus the always-available
-   *     `'general-purpose'` fallback).
-   *   - Models that pass an unregistered type are routed to
-   *     `'general-purpose'` (no error — degrade gracefully so trained
-   *     models keep working even on hosts that haven't wired every
-   *     type Claude Code uses).
-   *
-   * When the registry is empty / unset, the field is omitted entirely
-   * (preserves the historical schema for hosts that never use this).
-   *
-   * Default: `undefined` (no subagent types; `subagent_type` schema
-   * field hidden).
+   * Error sink for meter failures. The helper still swallows the throw
+   * so a broken backend can't crash a run; this callback surfaces the
+   * failure for ops dashboards.
    */
-  subagents?: SubagentRegistry;
+  onError?: (kind: string, err: unknown) => void;
+}
+interface MetricsHookSet {
+  install: (hooks: Hookable<AgentHooks>) => () => void;
+}
+/**
+ * Build a set of metrics hook handlers that can be installed on an agent.
+ *
+ * @example OpenTelemetry
+ * ```ts
+ * import { metrics } from '@opentelemetry/api'
+ * const meter = metrics.getMeter('zidane')
+ * const m = createMetricsHooks({ meter, baseAttributes: { service: 'tui' } })
+ * const uninstall = m.install(agent.hooks)
+ * try { await agent.run({ prompt }) }
+ * finally { uninstall() }
+ * ```
+ */
+declare function createMetricsHooks(options: MetricsHooksOptions): MetricsHookSet;
+//#endregion
+//#region src/stats.d.ts
+/**
+ * Per-model usage rollup produced by {@link statsByModel}.
+ *
+ * `turns` counts the number of `TurnUsage` entries attributed to the model
+ * across the whole tree (parent loop + every recursively-spawned child).
+ * Cache and cost numbers are summed from the same set of turns.
+ */
+interface ModelUsage {
+  input: number;
+  output: number;
+  cost: number;
+  cacheRead: number;
+  cacheCreation: number;
+  turns: number;
 }
 /**
- * Per-type subagent override applied when the model calls
- * `spawn({ subagent_type: '…' })`. All fields are optional; absent
- * fields fall back to the parent's resolved configuration (see
- * {@link SpawnToolOptions} comments for the merge order).
+ * Depth-first walk over the stats tree, returning every `TurnUsage` entry
+ * — parent loop first, then each child subtree in completion order.
+ *
+ * Closes the cache-token aggregation gap: `TurnUsage.cacheRead` /
+ * `cacheCreation` live only on per-turn entries, and the top-level
+ * `AgentStats` deliberately doesn't carry cumulative forms (one source of
+ * truth, no risk of drift). Anything that needs a tree-wide sum walks
+ * through this.
+ */
+declare function flattenTurns(stats: AgentStats): TurnUsage[];
+/**
+ * Group cumulative usage by `TurnUsage.modelId`. Each entry sums the input,
+ * output, cache, cost, and turn-count across every turn the tree attributed
+ * to that model — naturally handling cross-model runs (vision-fallback,
+ * model-shifted subagents, mixed-provider workflows).
+ *
+ * Turns missing `modelId` (mock providers, providers that don't echo a model
+ * id) are bucketed under the literal string `'(unknown)'`.
+ */
+declare function statsByModel(stats: AgentStats): Map<string, ModelUsage>;
+//#endregion
+//#region src/system-prompt.d.ts
+/**
+ * System-prompt boundary marker — splits a system prompt into a stable static
+ * prefix (cached) and a per-turn dynamic suffix (NOT cached).
+ *
+ * Why this exists: providers attach `cache_control` markers on the last block
+ * of the system prompt, so the cached prefix covers the entire system text.
+ * Any byte change anywhere — including a per-turn `<env>` rewrite — busts the
+ * cache for the doctrine that sits below. A literal marker in the system
+ * string lets providers split it into:
+ *
+ *   ┌──────────────┐ cache_control: ephemeral
+ *   │ STATIC half  │  — doctrine, skills catalog, tool catalog,
+ *   │              │    user instructions
+ *   ├──────────────┤  ← SYSTEM_PROMPT_BOUNDARY
+ *   │ DYNAMIC half │  — env, cwd, mtimes, anything per-turn
+ *   └──────────────┘ (no cache_control)
+ *
+ * The static prefix rides the prompt cache across turns/sessions; the dynamic
+ * suffix re-bills per turn. Net effect: a cwd change between turns no longer
+ * invalidates 4 KB of doctrine.
+ *
+ * Wire contract:
+ *
+ * - `splitSystemPrompt(s)` is pure; missing marker ⇒ entire string is static
+ *   (current behavior — no caller is forced to opt in).
+ * - `renderSystemForWire(s)` strips the marker so it never reaches the model;
+ *   used by every provider before the bytes hit the wire, including the
+ *   cache-disabled path on providers that DO support `cache_control`.
+ * - The marker uses underscores rather than XML/punctuation so it's
+ *   unambiguous when scanning prompts manually and unlikely to collide with
+ *   model-written content.
+ * - Providers handle the split internally (Anthropic emits a 2-block array;
+ *   OpenAI-compat splits the leading `system` message into multi-part text).
+ *   Callers always pass a single `string` — no API break.
+ */
+/**
+ * Literal marker inserted in a system prompt to separate cacheable doctrine
+ * from per-turn dynamic content. Providers split on this token.
+ *
+ * Underscored on both sides for visual distinctiveness — a stray instance in
+ * model-written prose is implausible. Don't change the value without shipping
+ * a migration; existing sessions carry the old marker in their cached
+ * prompts.
  */
-interface SubagentDef {
-  /**
-   * System prompt override for this subagent type. Per-call
-   * `input.system` still wins — model-supplied specialization beats
-   * preset defaults.
-   */
-  system?: string;
-  /**
-   * Restrict the child agent's tool registry to this list of canonical
-   * tool names. Operates as a filter over the parent's tools (the
-   * parent's selection is the upper bound — a subagent can never gain
-   * tools the parent doesn't have). When unset, the child inherits the
-   * parent's full tool list.
-   *
-   * Tool names are canonical (registry-key) not wire/alias names — the
-   * filter runs before aliases are applied. Names that don't match a
-   * parent tool are silently dropped (matches the lenient behaviour of
-   * `enabledTools` on MCP configs).
-   */
-  tools?: readonly string[];
-  /**
-   * Mark this subagent as read-only — equivalent to listing only
-   * obviously-non-mutating tools (`read_file`, `grep`, `glob`,
-   * `list_files`) in {@link SubagentDef.tools}. Convenience for the
-   * common "Plan" / "Explore" subagent shape Claude Code ships.
-   *
-   * When both `readonly: true` and `tools` are set, `tools` wins
-   * (explicit beats implicit).
-   */
-  readonly?: boolean;
-  /**
-   * Short description rendered into the spawn tool's schema (the
-   * `subagent_type` field's description) so the model can pick a type
-   * that matches the task without round-tripping through docs.
-   */
-  description?: string;
+declare const SYSTEM_PROMPT_BOUNDARY = "__ZIDANE_SYSTEM_PROMPT_BOUNDARY__";
+/** Result of {@link splitSystemPrompt} — both halves stripped of the marker. */
+interface SystemPromptParts {
+  /** Bytes BEFORE the marker (or the entire string when no marker present). Cacheable. */
+  static: string;
+  /** Bytes AFTER the marker. Empty when no marker present. NOT cached. */
+  dynamic: string;
 }
 /**
- * Map of subagent-type key → preset. Keys are case-sensitive and
- * appear verbatim in the spawn input schema's enum so the model emits
- * them with the same casing. Common conventions: `'Explore'`,
- * `'Plan'`, `'Verification'`, `'general-purpose'` (Claude Code SDK's
- * built-in set).
+ * Split a system prompt around the first {@link SYSTEM_PROMPT_BOUNDARY}.
+ *
+ * Splits on the FIRST occurrence — subsequent markers are folded into the
+ * dynamic half. This way callers can append additional `<env>` style blocks
+ * with extra markers without each one creating a new cache layer (Anthropic
+ * caps breakpoints; we use the budget elsewhere). The marker itself is
+ * stripped from both sides — providers attach `cache_control` directly to
+ * the static half's text content.
+ *
+ * A single blank line (`\n\n`) immediately adjacent to the marker on each
+ * side is trimmed — callers conventionally write
+ * `<doctrine>\n\n<MARKER>\n\n<env>` and expect the rendered wire bytes to
+ * read as one logical paragraph. Blank lines beyond that immediate pair
+ * (e.g. `\n\n\n<env>`) are preserved verbatim so callers composing their
+ * own spacing don't lose intentional gaps.
+ *
+ * Pure / no I/O / no allocation when the marker is absent (returns the input
+ * verbatim on the static side and the empty string on the dynamic side).
  */
-type SubagentRegistry = Record<string, SubagentDef>;
+declare function splitSystemPrompt(system: string): SystemPromptParts;
 /**
- * Create a configured spawn tool.
+ * Compose a system prompt from a static prefix and an optional dynamic
+ * suffix. Inserts {@link SYSTEM_PROMPT_BOUNDARY} between them only when the
+ * dynamic side is non-empty — single-block prompts stay marker-free, so
+ * callers that never opt in pay zero overhead and providers fall back to the
+ * existing whole-string caching path.
  *
- * State (`children`, `totalChildStats`, counters, active count) is scoped to
- * the returned instance. Multiple parent agents using the same instance will
- * share counters + stats + concurrency slots — call `createSpawnTool()` per
- * agent (or use the stateless default `spawn`) to keep them isolated.
+ * Spacing is `\n\n` on both sides of the marker so doctrine fragments,
+ * which conventionally separate sections with a blank line, read cleanly
+ * around the boundary.
  */
-declare function createSpawnTool(options?: SpawnToolOptions): ToolDef & SpawnToolState;
-//#endregion
-//#region src/tools/tool-search.d.ts
-interface LazyToolEntry {
-  /**
-   * Wire name (after `toolAliases` rewrite). What the model sees in the
-   * catalog, what `tool_search` matches against, and what the provider's
-   * tool list will carry once the entry is unlocked.
-   */
-  name: string;
-  /**
-   * Canonical (registry-key) name used for unlock-set membership and for the
-   * loop's `ctx.tools[name]` dispatch lookup. Equal to `name` when no alias
-   * is configured for this tool.
-   */
-  canonicalName: string;
-  description: string;
-  inputSchema: Record<string, unknown>;
-  /** Source MCP server, when applicable. Used for `server`-bulk unlock. */
-  server?: string;
-}
-interface ToolSearchToolOptions {
-  /**
-   * Snapshot of every lazy tool the model can discover. Built once per run by
-   * the agent — the tool closes over this array and never mutates it.
-   */
-  catalog: readonly LazyToolEntry[];
-  /**
-   * Mutable per-run set of unlocked **canonical** tool names. The tool adds
-   * matches in place; the loop reads the set when rebuilding the wire-level
-   * tool list. Keyed by canonical (not wire) so dispatch lookups stay
-   * alias-stable.
-   *
-   * Prefer `addUnlock` for cache-stable wire-tool ordering: writes through a
-   * Set lose unlock order, so the wire-level rebuild that filters by `unlocked`
-   * has to fall back to registry iteration order — which moves entries every
-   * time a lazy tool earlier in the registry is unlocked, breaking provider
-   * prompt-cache breakpoints. The agent passes both when it owns the unlock
-   * tracker, with `addUnlock` mirroring writes into an ordered log.
-   */
-  unlocked: Set<string>;
-  /**
-   * Optional callback fired for every canonical name the tool unlocks. When
-   * set, the agent uses this to maintain an append-only `dynamicUnlockOrder`
-   * so the wire-level tool list emits new unlocks at the tail and keeps the
-   * provider prefix cache warm. Idempotent on repeat unlocks of the same
-   * name — callers may dedupe internally.
-   *
-   * Invoked **in addition to** the `unlocked.add` (which still happens for
-   * back-compat with callers that only watch the Set).
-   */
-  addUnlock?: (canonical: string) => void;
-  /** Default cap on returned matches when the model omits `limit`. */
-  defaultLimit?: number;
-}
+declare function joinSystemPrompt(staticPart: string, dynamicPart: string): string;
 /**
- * Factory for `tool_search`. Auto-injected by the agent when
- * `behavior.toolDisclosure === 'lazy'` and at least one MCP tool is in the
- * registry. Opt out via `behavior.toolSearch.tool === false`.
+ * Append `extra` to the STATIC half of a system prompt, preserving any
+ * existing dynamic suffix.
+ *
+ * Used by the agent to fold in run-stable content (skills catalog, lazy tool
+ * catalog) without bumping it into the dynamic half — both catalogs are
+ * built once per run and remain byte-stable for the duration, so they
+ * belong in the cached prefix.
+ *
+ * Returns a new string; the input is not mutated. When `extra` is empty,
+ * returns the input verbatim.
  */
-declare function createToolSearchTool(options: ToolSearchToolOptions): ToolDef;
-//#endregion
-//#region src/tools/validation.d.ts
+declare function appendStaticSection(system: string, extra: string): string;
 /**
- * Tool argument validation against JSON Schema-style inputSchema.
+ * Append `extra` to the DYNAMIC half of a system prompt. Inserts the boundary
+ * marker if the input didn't already carry one.
  *
- * Two passes:
- *   1. Required-field presence. Missing or null/undefined required fields fail.
- *   2. Per-property type checks with **best-effort coercion**. Small/OSS models
- *      routinely send `"true"` for a `boolean` field or `"42"` for a `number`,
- *      and rejecting outright forces a confusing retry. Instead, we auto-heal
- *      coerce when the conversion is unambiguous, fail only when the value
- *      cannot be reasonably normalized to any of the declared types.
+ * Used by hosts (typically the TUI) to inject per-turn state — current cwd,
+ * IDE selection, project root — without forcing every caller to know the
+ * marker format. The host's `system:transform` hook rewrites the dynamic
+ * half each turn; the static doctrine above stays byte-stable and rides the
+ * cache.
  *
- * Recursion: when a property declares `type: 'array'` with an `items` schema,
- * each item is validated against `items`. Object items are walked one level
- * deep (their declared `properties` get the same coercion + enum checks the
- * top level does). Items that can't be coerced are dropped rather than
- * rejecting the whole call — the model rarely benefits from an
- * all-or-nothing failure on a 20-item list because one entry was malformed.
- * Dropped items are reported back via `droppedItems` so the tool's `execute`
- * can surface a hint to the model if it wants to.
+ * Returns a new string; the input is not mutated. When `extra` is empty,
+ * returns the input verbatim.
  */
-interface ValidationResult {
-  valid: boolean;
-  /** Human-readable reason. Present on failure only. */
-  error?: string;
-  /**
-   * Possibly-coerced input. Present iff `valid: true`. Tools should call
-   * `execute(coercedInput, ctx)` so auto-healed values reach the tool body.
-   * When no coercion was applied, this is reference-equal to the input.
-   */
-  coercedInput?: Record<string, unknown>;
-  /**
-   * Names of fields whose values were coerced. Empty when nothing changed.
-   * Useful for telemetry (`validation:reject` on failure already carries the
-   * reason; this is the success-path equivalent).
-   */
-  coercions?: readonly string[];
-  /**
-   * Indexes of array items dropped during recursive validation, keyed by
-   * the property name. Empty / absent when nothing was dropped. Tools that
-   * care about the discrepancy (e.g. `todowrite` wanting to surface
-   * "ignored 2 malformed items") can inspect this.
-   */
-  droppedItems?: Readonly<Record<string, readonly number[]>>;
-}
-declare function validateToolArgs(input: Record<string, unknown>, schema: Record<string, unknown>): ValidationResult;
-//#endregion
-//#region src/tools/write-file.d.ts
+declare function appendDynamicSection(system: string, extra: string): string;
 /**
- * Write a file, with an idempotency signal when the content is unchanged.
+ * Replace the entire dynamic half of a system prompt with `next`. Used by
+ * the TUI's `<env>` rewriter where the entire dynamic section is regenerated
+ * each turn rather than appended to.
  *
- * Three return shapes — chosen so the model can recognize a no-op without a
- * separate read:
- *   - `Created path (N bytes)` — file did not exist
- *   - `Updated path (N bytes)` — content differed from on-disk
- *   - `No change needed: path already at target state (N bytes)` — equal
+ * When `next` is empty, drops the dynamic half (and the marker) entirely.
+ */
+declare function replaceDynamicSection(system: string, next: string): string;
+/**
+ * Strip the boundary marker so it never reaches the wire — collapses
+ * `<static>${BOUNDARY}<dynamic>` into `<static>\n\n<dynamic>` for providers
+ * that can't honor `cache_control` (vanilla OpenAI Chat Completions, Codex,
+ * Cerebras, ...) or for the cache-disabled path on any provider.
  *
- * Race window: in non-process execution contexts (docker, sandbox) shared by
- * multiple agents, another writer can mutate the file between our read and
- * our write. Local process context is single-writer per agent so the race is
- * a non-issue there. Documented rather than locked because the cost of
- * cross-context locking outweighs the cost of a stale "No change" message.
+ * Cache-aware providers re-derive the split from the original (un-rendered)
+ * system string via `splitSystemPrompt` — `renderSystemForWire` is the
+ * marker-free counterpart used to build the actual wire bytes.
+ *
+ * No-op when the input has no marker. Pure / no I/O.
  */
-declare const writeFile: ToolDef;
+declare function renderSystemForWire(system: string): string;
+/** True when `system` contains the boundary marker. */
+declare function hasSystemPromptBoundary(system: string): boolean;
 //#endregion
 //#region src/tracing.d.ts
 /** Minimal span shape — any tracer that provides these methods is compatible. */
@@ -2281,5 +2428,5 @@ declare function definePreset(config: Preset): Preset;
  */
 declare function composePresets(...presets: Preset[]): Preset;
 //#endregion
-export { ModelUsage as $, LoggingHooksOptions as $t, SkillsReadToolOptions as A, ANCHOR_PREVIEW_MAX_CHARS as An, McpOAuthProvider as At, createInteractionTool as B, CacheDimensionDiff as Bn, maybePersistToolResult as Bt, SubagentDef as C, NO_TOOLS_PREAMBLE as Cn, OAuthCallbackResult as Ct, createSkillsUseTool as D, buildFullCompactPrompt as Dn, loginMcpServer as Dt, SkillsUseToolOptions as E, buildFromCompactPrompt as En, LoginMcpServerResult as Et, shell as F, sliceForCompaction as Fn, PERSISTENCE_PREVIEW_BYTES as Ft, SystemPromptParts as G, installCacheBreakLogger as Gn, TOOL_USE_CANCELLED_MESSAGE as Gt, glob as H, CacheDimensionSnapshot as Hn, resolveTasksDir as Ht, readFile as I, stripImagesFromTurns as In, PersistInput as It, hasSystemPromptBoundary as J, LogLevel as Jt, appendDynamicSection as K, snapshotCacheDimensions as Kn, TOOL_USE_SKIPPED_MESSAGE as Kt, multiEdit as L, summaryToTurn as Ln, PersistOutcome as Lt, shellKill as M, CompactionSlice as Mn, createMemoryMcpCredentialStore as Mt, CreateShellToolOptions as N, SummaryToTurnInput as Nn, hasAuthorizationHeader as Nt, SkillsRunScriptToolOptions as O, buildTailCompactPrompt as On, McpCredentialEntry as Ot, createShellTool as P, anchorPreviewFor as Pn, PERSISTED_STUB_PREFIX as Pt, splitSystemPrompt as Q, LoggingHookSet as Qt, listFiles as R, truncateHeadForPtlRetry as Rn, buildPersistedStub as Rt, SpawnToolState as S, CompactPromptOptions as Sn, OAuthCallbackOptions as St, createSpawnTool as T, buildCompactPrompt as Tn, LoginMcpServerOptions as Tt, edit as U, diffCacheDimensions as Un, INTERRUPT_MESSAGE_FOR_TOOL_USE as Ut, grep as V, CacheDimensionName as Vn, resolvePersistDir as Vt, SYSTEM_PROMPT_BOUNDARY as W, fnv1a32 as Wn, SHELL_CASCADE_CANCEL_MESSAGE as Wt, renderSystemForWire as X, LogSink as Xt, joinSystemPrompt as Y, LogRecord as Yt, replaceDynamicSection as Z, Logger as Zt, LazyToolEntry as _, CompactInvalidInputError as _n, MetricsHookSet as _t, basicTools as a, estimateTokens as an, RunSummaryByModel as at, ChildAgent as b, CompactDirection as bn, createMetricsHooks as bt, Span as c, PostCompactRestoreOptions as cn, RunSummaryError as ct, TracingHookSet as d, selectFilesFromReadState as dn, createRunSummaryCollector as dt, consoleSink as en, flattenTurns as et, TracingHooksOptions as f, selectFilesFromSession as fn, Counter as ft, validateToolArgs as g, compactConversation as gn, MetricAttributes as gt, ValidationResult as h, CompactResult as hn, Meter as ht, _default as i, BYTES_PER_TOKEN as in, RunSummaryBudget as it, createSkillsReadTool as j, CompactScope as jn, McpOAuthProviderOptions as jt, createSkillsRunScriptTool as k, buildUpToCompactPrompt as kn, McpCredentialStore as kt, StartSpan as l, RecentFile as ln, RunSummaryTokens as lt, writeFile as m, CompactOptions as mn, InstrumentOptions as mt, composePresets as n, createLoggingHooks as nn, RunSummary as nt, zodToJsonSchema as o, utf8ByteLength as on, RunSummaryCollector as ot, createTracingHooks as p, selectRecentFiles as pn, Histogram as pt, appendStaticSection as q, ConsoleSinkOptions as qt, definePreset as r, jsonSink as rn, RunSummaryBlock as rt, GEN_AI_ATTRIBUTES as s, PostCompactAttachments as sn, RunSummaryCollectorOptions as st, Preset as t, createLogger as tn, statsByModel as tt, TracingConventions as u, buildPostCompactAttachments as un, RunSummaryValidation as ut, ToolSearchToolOptions as v, CompactPromptTooLongError as vn, MetricsHooksOptions as vt, SubagentRegistry as w, TRAILER as wn, startOAuthCallback as wt, SpawnToolOptions as x, CompactPromptBuilder as xn, OAuthCallbackHandle as xt, createToolSearchTool as y, BASE_INSTRUCTIONS as yn, UpDownCounter as yt, InteractionToolOptions as z, CacheBreakLoggerOptions as zn, cleanupPersistedSession as zt };
-//# sourceMappingURL=index-B6h9C_JE.d.ts.map
+export { cleanupPersistedSession as $, diffCacheDimensions as $n, InteractionToolOptions as $t, MetricAttributes as A, CompactDirection as An, validateToolArgs as At, LoginMcpServerResult as B, ANCHOR_PREVIEW_MAX_CHARS as Bn, SkillsUseToolOptions as Bt, ModelUsage as C, selectRecentFiles as Cn, HeadlessUsage as Ct, Histogram as D, CompactInvalidInputError as Dn, transcriptToOpenAIMessages as Dt, Counter as E, compactConversation as En, runHeadless as Et, OAuthCallbackHandle as F, buildCompactPrompt as Fn, SpawnToolOptions as Ft, McpOAuthProviderOptions as G, sliceForCompaction as Gn, createSkillsReadTool as Gt, McpCredentialEntry as H, CompactionSlice as Hn, SkillsRunScriptToolOptions as Ht, OAuthCallbackOptions as I, buildFromCompactPrompt as In, SpawnToolState as It, PERSISTED_STUB_PREFIX as J, truncateHeadForPtlRetry as Jn, createShellTool as Jt, createMemoryMcpCredentialStore as K, stripImagesFromTurns as Kn, shellKill as Kt, OAuthCallbackResult as L, buildFullCompactPrompt as Ln, SubagentDef as Lt, MetricsHooksOptions as M, CompactPromptOptions as Mn, ToolSearchToolOptions as Mt, UpDownCounter as N, NO_TOOLS_PREAMBLE as Nn, createToolSearchTool as Nt, InstrumentOptions as O, CompactPromptTooLongError as On, writeFile as Ot, createMetricsHooks as P, TRAILER as Pn, ChildAgent as Pt, buildPersistedStub as Q, CacheDimensionSnapshot as Qn, listFiles as Qt, startOAuthCallback as R, buildTailCompactPrompt as Rn, SubagentRegistry as Rt, splitSystemPrompt as S, selectFilesFromSession as Sn, HeadlessStatus as St, statsByModel as T, CompactResult as Tn, headlessEventToJsonl as Tt, McpCredentialStore as U, SummaryToTurnInput as Un, createSkillsRunScriptTool as Ut, loginMcpServer as V, CompactScope as Vn, createSkillsUseTool as Vt, McpOAuthProvider as W, anchorPreviewFor as Wn, SkillsReadToolOptions as Wt, PersistInput as X, CacheDimensionDiff as Xn, readFile as Xt, PERSISTENCE_PREVIEW_BYTES as Y, CacheBreakLoggerOptions as Yn, shell as Yt, PersistOutcome as Z, CacheDimensionName as Zn, multiEdit as Zt, appendStaticSection as _, PostCompactAttachments as _n, jsonSink as _t, basicTools as a, RunSummaryBlock as an, TOOL_USE_CANCELLED_MESSAGE as at, renderSystemForWire as b, buildPostCompactAttachments as bn, HeadlessOptions as bt, Span as c, RunSummaryCollector as cn, LogLevel as ct, TracingHookSet as d, RunSummaryTokens as dn, Logger as dt, createInteractionTool as en, fnv1a32 as er, maybePersistToolResult as et, TracingHooksOptions as f, RunSummaryValidation as fn, LoggingHookSet as ft, appendDynamicSection as g, utf8ByteLength as gn, createLoggingHooks as gt, SystemPromptParts as h, estimateTokens as hn, createLogger as ht, _default as i, RunSummary as in, SHELL_CASCADE_CANCEL_MESSAGE as it, MetricsHookSet as j, CompactPromptBuilder as jn, LazyToolEntry as jt, Meter as k, BASE_INSTRUCTIONS as kn, ValidationResult as kt, StartSpan as l, RunSummaryCollectorOptions as ln, LogRecord as lt, SYSTEM_PROMPT_BOUNDARY as m, BYTES_PER_TOKEN as mn, consoleSink as mt, composePresets as n, glob as nn, snapshotCacheDimensions as nr, resolveTasksDir as nt, zodToJsonSchema as o, RunSummaryBudget as on, TOOL_USE_SKIPPED_MESSAGE as ot, createTracingHooks as p, createRunSummaryCollector as pn, LoggingHooksOptions as pt, hasAuthorizationHeader as q, summaryToTurn as qn, CreateShellToolOptions as qt, definePreset as r, edit as rn, INTERRUPT_MESSAGE_FOR_TOOL_USE as rt, GEN_AI_ATTRIBUTES as s, RunSummaryByModel as sn, ConsoleSinkOptions as st, Preset as t, grep as tn, installCacheBreakLogger as tr, resolvePersistDir as tt, TracingConventions as u, RunSummaryError as un, LogSink as ut, hasSystemPromptBoundary as v, PostCompactRestoreOptions as vn, HeadlessErrorInfo as vt, flattenTurns as w, CompactOptions as wn, OpenAIChatMessage as wt, replaceDynamicSection as x, selectFilesFromReadState as xn, HeadlessResult as xt, joinSystemPrompt as y, RecentFile as yn, HeadlessEvent as yt, LoginMcpServerOptions as z, buildUpToCompactPrompt as zn, createSpawnTool as zt };
+//# sourceMappingURL=index-DEqGfnZr.d.ts.map