zidane 5.3.0 → 5.3.2

package/dist/{agent-CYpPKn5Z.d.ts → agent-BXRCCHeq.d.ts}

@@ -14,7 +14,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
  * unclassified errors in `AgentProviderError` automatically.
  */
 /** Kind of classified provider error */
-type ClassifiedErrorKind = 'context_exceeded' | 'provider_error' | 'aborted';
+type ClassifiedErrorKind = 'context_exceeded' | 'provider_error' | 'aborted' | 'tool_pairing_corruption';
 /** Structured classification returned by `Provider.classifyError` */
 interface ClassifiedError {
   kind: ClassifiedErrorKind;
@@ -75,6 +75,49 @@ declare class AgentAbortedError extends Error {
     cause?: unknown;
   });
 }
+/**
+ * Thrown by the pre-send pairing repair when {@link AgentBehavior.strictToolPairing}
+ * is `true` and {@link ensureToolResultPairing} would otherwise patch over
+ * corruption. Strict mode opts into fail-fast for training-data collectors and
+ * any consumer that prefers to bail out rather than ship a transcript carrying
+ * a {@link SYNTHETIC_TOOL_RESULT_PLACEHOLDER}.
+ *
+ * The `repairs` field carries every repair the loop would have made — useful
+ * for postmortems and for surfacing exactly which transcripts were rejected.
+ *
+ * Note: callers consuming the chat layer (TUI/SDK presets) typically leave
+ * `strictToolPairing` off so user-facing sessions auto-heal instead of
+ * crashing.
+ */
+declare class AgentToolPairingError extends Error {
+  readonly code: "tool_pairing_corruption";
+  /** Provider whose wire format the corruption would have hit. */
+  readonly provider?: string;
+  /** Upstream error code when the corruption was detected from a 400 response. */
+  readonly providerCode?: string;
+  /**
+   * Repairs the harness would have performed had strict mode been off.
+   * Preserves the full diagnostic so consumers can route to telemetry,
+   * `/rewind` flows, or training-data quarantine without re-walking the
+   * transcript.
+   */
+  readonly repairs: ReadonlyArray<{
+    mode: string;
+    callId?: string;
+    messageIndex: number;
+  }>;
+  constructor(options: {
+    message: string;
+    provider?: string;
+    providerCode?: string;
+    repairs: ReadonlyArray<{
+      mode: string;
+      callId?: string;
+      messageIndex: number;
+    }>;
+    cause?: unknown;
+  });
+}
 /**
  * Thrown (well — constructed; attach via the `tool:gate` block signal) when the
  * union of `allowed-tools` across active skills does not permit a tool call.
@@ -123,7 +166,7 @@ declare function errorMessage(err: unknown): string;
 /**
  * Convert a `ClassifiedError` + underlying cause into the matching typed error instance.
  */
-declare function toTypedError(classification: ClassifiedError, provider: string, cause: unknown): AgentContextExceededError | AgentProviderError | AgentAbortedError;
+declare function toTypedError(classification: ClassifiedError, provider: string, cause: unknown): AgentContextExceededError | AgentProviderError | AgentAbortedError | AgentToolPairingError;
 //#endregion
 //#region src/types.d.ts
 /**
@@ -437,7 +480,7 @@ interface AgentBehavior {
    *
    * ```ts
    * // Always cache by full input — every identical re-call dedups.
-   * dedupTools: { todowrite: input => JSON.stringify(input) }
+   * dedupTools: { my_pure_tool: input => JSON.stringify(input) }
    *
    * // Cache by a normalized subset; non-cacheable shapes opt out.
    * dedupTools: {
@@ -655,6 +698,26 @@ interface AgentBehavior {
    * Default: `undefined`.
    */
   persistDir?: string;
+  /**
+   * Fail-fast instead of repair when the pre-send pairing pass detects
+   * corruption (orphan `tool_use` / `tool_result`, duplicate ids,
+   * compaction-stranded blocks). Throws {@link AgentToolPairingError} from
+   * the next `agent.run()` turn carrying the structured repair list the
+   * loop would have performed.
+   *
+   * Use case: training-data collectors that must reject any transcript
+   * containing the synthetic `SYNTHETIC_TOOL_RESULT_PLACEHOLDER` rather
+   * than ship poisoned data to the fine-tuning pipeline. User-facing chat
+   * sessions should leave this off (the repair-on-the-fly behavior is the
+   * point of the pass).
+   *
+   * Telemetry note: `pairing:repair` still fires for every repair before
+   * the throw, so observability handlers see exactly what would have
+   * happened.
+   *
+   * Default: `false`.
+   */
+  strictToolPairing?: boolean;
 }
 /**
  * One block of a multimodal user prompt.
@@ -1040,6 +1103,28 @@ interface ToolHookContext {
   /** Aliased (wire) name — equal to `name` when no alias is defined. */
   displayName: string;
   input: Record<string, unknown>;
+  /**
+   * The run this tool call belongs to (the `SessionRun.id`). Lets a single
+   * `tool:*` listener disambiguate calls across parallel runs / subagent
+   * trees without subscribing to the `child:tool:*` bubble events.
+   */
+  runId?: string;
+  /**
+   * Parent run id when this tool call's agent is a subagent — i.e. the
+   * `SessionRun.parentRunId` of the run that owns the call. Absent on
+   * top-level runs. Useful for observability stitching: a UI grouping
+   * subagent-scoped state (e.g. todowrite, edit batches) by parent
+   * run can read this directly off `tool:before` / `tool:after`
+   * without resolving the run row.
+   */
+  parentRunId?: string;
+  /**
+   * Subagent depth for this tool call. 0 = top-level, 1 = first-level
+   * child, etc. Mirrors `ToolContext.depth` so hook consumers don't
+   * have to cross-reference the tool context. Omitted on top-level
+   * runs (treated as 0).
+   */
+  depth?: number;
 }
 /**
  * Base context for MCP tool hooks.
@@ -1059,6 +1144,12 @@ interface McpToolHookContext {
   /** Aliased wire name for this MCP tool, or the canonical `mcp_{server}_{tool}` name. */
   displayName: string;
   input: Record<string, unknown>;
+  /** Owning run id — same semantics as `ToolHookContext.runId`. */
+  runId?: string;
+  /** Parent run id when this tool call's agent is a subagent — see `ToolHookContext.parentRunId`. */
+  parentRunId?: string;
+  /** Subagent depth — see `ToolHookContext.depth`. */
+  depth?: number;
 }
 /** Base context for session hooks */
 interface SessionHookContext {
@@ -1357,6 +1448,100 @@ interface OpenRouterParams {
  */
 declare function openrouter(params?: OpenRouterParams): Provider;
 //#endregion
+//#region src/providers/schema-sanitize.d.ts
+/**
+ * JSON Schema sanitizer for tool `inputSchema` forwarded to LLM providers.
+ *
+ * Why this exists: MCP servers ship arbitrary JSON Schema in `tools/list`.
+ * Anthropic and (to a lesser extent) OpenAI reject specific keyword
+ * combinations with a 400 on `messages.create`, and the error message
+ * lands deep inside an SDK exception that consumers blame on their own
+ * code. The most common failure modes in the wild:
+ *
+ *   - Root `$ref` (server-published schema lives under `#/$defs/X`).
+ *   - Root `oneOf` / `anyOf` / `allOf` (Anthropic allows neither at the
+ *     top level; expects `type: 'object'`).
+ *   - `type: ['object', 'null']` at the root (nullable variants of an
+ *     otherwise valid object schema).
+ *   - Missing `properties` on an object root.
+ *   - `nullable: true` (Swagger / OpenAPI 3.0 idiom — not standard JSON
+ *     Schema, ignored by every modern provider but Anthropic warns).
+ *   - Nested `$ref` pointing at `#/definitions/X` without the schema
+ *     actually inlining the referenced definition.
+ *
+ * Pure rewrite. Returns a new schema (or the same reference when nothing
+ * needed to change — the hot path on stable tool registries) and a list
+ * of `warnings` describing each rewrite. Providers call
+ * `sanitizeToolSpecs` from `formatTools` so every tool — eager MCP, lazy
+ * MCP, native, skill — gets the same treatment, and warnings surface
+ * through `console.warn` once per batch (the seen-set in
+ * `sanitizeToolSpecs` is local to one call, so a stable bad schema logs
+ * once per request rather than every turn).
+ *
+ * Scope:
+ *   - Pure function. No I/O, no globals.
+ *   - Bounded recursion (`MAX_DEPTH = 32`) so a malicious server can't
+ *     wedge the agent with a deeply self-referential schema.
+ *   - Bounded `$ref` resolution (`MAX_REF_HOPS = 16`) for the same
+ *     reason. Cycles fall back to `{}` (permissive) rather than
+ *     throwing — the request still succeeds, the schema is just looser.
+ *
+ * Non-goals:
+ *   - Validating that the schema is internally consistent.
+ *   - Cleaning up tool *descriptions* (handled elsewhere).
+ *   - Provider-side feature detection (handled by the provider's own
+ *     `formatTools`; this module is a syntactic guard, not a semantic one).
+ */
+/** Strictness profile — picks which transformations to apply. */
+type SchemaSanitizeProfile = 'anthropic' | 'openai' | 'permissive';
+interface SchemaSanitizeOptions {
+  /** Strictness profile. Defaults to `'permissive'`. */
+  profile?: SchemaSanitizeProfile;
+  /**
+   * Tool name for context in warnings. Optional — when set, every warning
+   * is prefixed with `[tool:<name>] ` so log lines correlate to the tool.
+   */
+  toolName?: string;
+}
+interface SchemaSanitizeResult {
+  /** Sanitized schema, safe to forward to the provider. */
+  schema: Record<string, unknown>;
+  /**
+   * Human-readable strings describing each rewrite the sanitizer performed.
+   * Empty on a clean schema. Consumers may log these (recommended) or
+   * thread them through a hook for observability.
+   */
+  warnings: string[];
+}
+/**
+ * Sanitize a single tool's `inputSchema` for safe forwarding to the
+ * provider. Returns the rewritten schema + a list of warnings describing
+ * everything that changed.
+ *
+ * Never mutates the input. Returns the **same reference** when no rewrite
+ * was needed (clean-schema fast path) — `sanitizeToolSpecs` relies on
+ * this to keep the formatTools hot loop allocation-free across turns
+ * when the registered tool set is already wire-valid.
+ */
+declare function sanitizeToolSchema(input: unknown, options?: SchemaSanitizeOptions): SchemaSanitizeResult;
+/**
+ * Convenience: sanitize a batch of tools and emit a single de-duped
+ * `console.warn` per unique warning line. Returns the rewritten tools
+ * preserving original ordering and reference identity for clean schemas
+ * (no reallocation when nothing needed to change).
+ *
+ * The sanitiser runs every request, so log noise from a stable bad
+ * schema would multiply across turns; the de-dupe keeps the signal
+ * useful in production logs without dropping the first occurrence.
+ */
+declare function sanitizeToolSpecs<T extends {
+  name: string;
+  inputSchema?: unknown;
+}>(tools: readonly T[], options?: {
+  profile?: SchemaSanitizeProfile;
+  onWarning?: (line: string) => void;
+}): T[];
+//#endregion
 //#region src/providers/index.d.ts
 interface ToolSpec {
   name: string;
@@ -1378,6 +1563,25 @@ interface ToolResult {
    * Use `toolResultToText(content)` when a downstream consumer only handles strings.
    */
   content: string | ToolResultContent[];
+  /**
+   * Marks this result as an error. Propagates to `tool_result.is_error: true`
+   * on the Anthropic wire (and to the equivalent on every other provider that
+   * exposes the field). Models treat error-flagged results as "the tool tried
+   * but failed" — distinct from "the tool returned this string" — so they can
+   * decide whether to retry, fall back, or surface the error to the user.
+   *
+   * Set by the loop on:
+   * - Tool body throws (`tool:error` path).
+   * - Gate refusal (`Blocked: <reason>`).
+   * - Validation rejection (`Validation error: …`).
+   * - Mid-tool abort (`INTERRUPT_MESSAGE_FOR_TOOL_USE`).
+   * - Sequential-batch skips when a sibling threw / a steering message
+   *   arrived.
+   *
+   * Custom tools may set it via the `tool:error` hook's `ctx.result`
+   * substitute when they want the framework to flag a structured error.
+   */
+  isError?: boolean;
 }
 /**
  * Provider-level capability flags used by the agent loop to route tool results
@@ -1539,6 +1743,151 @@ declare function toOpenAI(msg: SessionMessage): {
   role: string;
   content: unknown;
 };
+/**
+ * Placeholder content inserted into a synthetic `tool_result` when the harness
+ * has to repair an orphan `tool_use`. Exported so downstream consumers
+ * (training-data collectors, HFI submission) can reject any payload containing
+ * it — the marker satisfies the wire-level pairing contract structurally but
+ * the content itself is fake and would poison fine-tuning data.
+ */
+declare const SYNTHETIC_TOOL_RESULT_PLACEHOLDER = "[Tool result missing due to internal error]";
+/**
+ * Replacement text for an assistant message whose every content block was
+ * stripped during pairing repair (e.g. the only blocks were orphan
+ * `tool_call`s). Providers reject empty `content` arrays — the marker keeps
+ * the turn shape valid while signaling "this assistant turn lost its
+ * outputs" to the model so it can recover.
+ */
+declare const TOOL_USE_INTERRUPTED_MARKER = "[Tool use interrupted]";
+/**
+ * Replacement text for a user message whose every content block was a
+ * `tool_result` with no matching upstream `tool_call` (e.g. the assistant
+ * pair was stripped by an earlier compaction). Same role as
+ * {@link TOOL_USE_INTERRUPTED_MARKER} on the user side.
+ */
+declare const ORPHANED_TOOL_RESULT_MARKER = "[Orphaned tool result removed due to conversation resume]";
+/**
+ * Classification of a single repair the pairing pass performed. Surfaced via
+ * {@link EnsureToolResultPairingOptions.onRepair} so consumers can wire
+ * telemetry, debug logs, or strict-mode rejection without re-implementing the
+ * walk.
+ *
+ * Each entry corresponds to one of the corruption modes documented on
+ * {@link ensureToolResultPairing}.
+ */
+type PairingRepairMode = 'orphan-tool-use-prepend' | 'orphan-tool-use-append' | 'orphan-tool-result-strip' | 'duplicate-tool-use-strip' | 'duplicate-tool-result-strip' | 'empty-assistant-marker';
+interface PairingRepair {
+  mode: PairingRepairMode;
+  /** Tool-use / tool-result id this repair concerns. Absent for empty-marker repairs. */
+  callId?: string;
+  /** Zero-based index into the INPUT `messages` array where the corruption was found. */
+  messageIndex: number;
+}
+interface EnsureToolResultPairingOptions {
+  /**
+   * Fired once per repair the pass performed. Synchronous so the loop can
+   * stay on its hot path. Throwing from the callback aborts the pass —
+   * consumers wanting fail-fast (strict mode) can re-throw with their own
+   * typed error.
+   */
+  onRepair?: (repair: PairingRepair) => void;
+}
+/**
+ * Defensive repair pass that rewrites a message list so it satisfies the
+ * wire-level `tool_use` ↔ `tool_result` adjacency contract every modern
+ * provider enforces.
+ *
+ * Anthropic 400s on orphans with `'tool_use' ids were found without
+ * 'tool_result' blocks immediately after` (and its inverse, `tool_result
+ * must be preceded by a tool_call with the same toolCallId`). OpenAI's
+ * Chat Completions API rejects most mismatches with a 400 too.
+ *
+ * Six repair modes — modeled after Anthropic's Claude Code defenses:
+ *
+ * | # | Corruption | Repair |
+ * |---|------------|--------|
+ * | 1 | assistant `tool_use` whose next user msg lacks a matching `tool_result` | **Prepend** a synthetic `tool_result` block carrying {@link SYNTHETIC_TOOL_RESULT_PLACEHOLDER} with `isError: true` |
+ * | 2 | assistant `tool_use` followed by nothing (or by a non-user msg) | **Insert** a new synthetic user message with the same placeholder |
+ * | 3 | user `tool_result` with no preceding assistant `tool_call` | **Strip** the orphan block; if it empties the msg, replace with {@link ORPHANED_TOOL_RESULT_MARKER} text block |
+ * | 4 | duplicate `tool_call.id` across assistant messages (CC-1212) | **Strip** later instances + their matching tool_results |
+ * | 5 | duplicate `tool_result.callId` within a single user message | **Dedupe** by `callId`, keep first |
+ * | 6 | assistant message emptied by mode-4 stripping | **Replace** content with {@link TOOL_USE_INTERRUPTED_MARKER} text block |
+ *
+ * **Repair, not drop.** Earlier versions of this pass simply dropped orphan
+ * blocks, which (a) silently rewrote history the model had reasoned over and
+ * (b) cascaded — dropping an assistant tool_call would orphan its
+ * tool_result, which would then get dropped too, removing any trace of
+ * "what the model tried to do" from the transcript. The repair-based pass
+ * preserves the model's tool_use shape and patches the dangling result with
+ * an `is_error` placeholder so the model sees "I tried X, the result was
+ * lost" and can retry intelligently.
+ *
+ * Adjacency contract: `tool_result` blocks must live in the user message
+ * IMMEDIATELY following the assistant message that emitted the matching
+ * `tool_use`. The pass enforces strict adjacency — a tool_result two
+ * messages downstream of its tool_call is still an orphan.
+ *
+ * Idempotent: returns the input reference unchanged when no repairs were
+ * necessary. Re-running on already-repaired output is a no-op.
+ *
+ * Pure: does not mutate input messages or their content arrays — every
+ * repair allocates a fresh array / object.
+ */
+declare function ensureToolResultPairing(messages: SessionMessage[], options?: EnsureToolResultPairingOptions): SessionMessage[];
+/**
+ * Drop ASSISTANT turns whose every `tool_call` block is unresolved
+ * (no matching `tool_result` block anywhere later in the transcript).
+ * Tool_call blocks with at least one matching tool_result are kept — modes
+ * 1/3 of {@link ensureToolResultPairing} handle the partial-pair case at
+ * wire-send time.
+ *
+ * Use case: session resume. A turn that emitted three `tool_use` blocks but
+ * never persisted the matching `tool_result` turn (process death, crash,
+ * `kill -9`) leaves the transcript with an orphan that Anthropic rejects on
+ * the FIRST API call after reload. Dropping the whole assistant turn — not
+ * just the orphan blocks — preserves text-only turns that legitimately
+ * carry reasoning the model wants to see again.
+ *
+ * Does NOT mint fresh ids: re-id'ing on every resume would cause
+ * exponential transcript growth across repeated resumes of an interrupted
+ * session.
+ *
+ * Pure: returns the input reference unchanged when no turn was dropped.
+ */
+declare function filterUnresolvedToolUses<T extends {
+  role: string;
+  content: SessionContentBlock[];
+}>(turns: T[]): T[];
+/**
+ * Classification of a session's tail state for resume purposes.
+ *
+ * - `'clean'` — the trailing turn is a user message (the model would respond
+ *   next), or the transcript is empty. Safe to resume by appending a fresh
+ *   user prompt.
+ * - `'interrupted'` — the trailing turn is an assistant message that has at
+ *   least one `tool_call` block with no matching `tool_result` anywhere
+ *   later. The run was almost certainly killed between persisting the
+ *   assistant turn and persisting its tool-results turn. Hosts that want
+ *   Claude-Code-style auto-resume can detect this and inject a
+ *   `"Continue from where you left off."` user message before the next run.
+ * - `'completed'` — the trailing turn is an assistant message with no
+ *   orphan tool_calls. The model considers itself done. Hosts that want to
+ *   resume must supply a new prompt; auto-continuation here would be a
+ *   non-sequitur.
+ */
+type TurnInterruptionState = 'clean' | 'interrupted' | 'completed';
+/**
+ * Inspect a session's trailing turn to classify whether the run was
+ * interrupted mid-tool-call. Pure / synchronous — does not modify the input.
+ *
+ * Pair with {@link filterUnresolvedToolUses} on the resume path: filter
+ * first so the result reflects the post-cleanup state (a turn whose orphans
+ * were stripped reads as 'completed', not 'interrupted').
+ */
+declare function detectTurnInterruption<T extends {
+  role: string;
+  content: SessionContentBlock[];
+}>(turns: T[]): TurnInterruptionState;
 declare function autoDetectAndConvert(msg: {
   role: string;
   content: unknown;
@@ -1866,6 +2215,76 @@ interface SkillsConfig {
   trustProjectSkills?: boolean;
 }
 //#endregion
+//#region src/tools/read-state.d.ts
+interface ReadStateEntry {
+  contentHash: string;
+  /** Slice parameters for the last read. */
+  offset: number;
+  limit: number;
+  maxBytes: number;
+  /**
+   * Whether the prior read emitted line-number prefixes. Tracked so a
+   * read with `lineNumbers: true` doesn't dedup against one with
+   * `lineNumbers: false` (or vice versa) — the dedup stub would mislead
+   * the model about the prior output's shape.
+   */
+  lineNumbers?: boolean;
+  /** Wall-clock at last read — diagnostic only, not used for invalidation. */
+  mtimeMs: number;
+}
+type ReadStateMap = Map<string, ReadStateEntry>;
+/**
+ * Get or lazily create the per-session read-state map. Returns `undefined`
+ * when no session is provided.
+ *
+ * Most tool callers should prefer {@link resolveReadStateMap}, which
+ * additionally honors an explicit `ctx.readState` (the path
+ * `spawn`'s `shareReadState: true` uses to forward the parent's map
+ * into a sessionless child). Use this helper directly only when the
+ * Session-keyed map is exactly what you want and you don't need to
+ * accept an override.
+ */
+declare function getReadState(session: Session | undefined): ReadStateMap | undefined;
+/**
+ * Resolve the active read-state map from a tool context. An explicit
+ * `ctx.readState` wins (used by `spawn`'s `shareReadState` opt-in to
+ * forward the parent's map into a sessionless child); otherwise the
+ * usual `Session`-keyed lookup applies.
+ *
+ * Tools should call this helper instead of `getReadState(ctx.session)`
+ * directly so the `shareReadState` plumbing is honored uniformly.
+ */
+declare function resolveReadStateMap(ctx: {
+  session?: Session;
+  readState?: ReadStateMap;
+}): ReadStateMap | undefined;
+/**
+ * Canonical read-state key for a `(cwd, path)` pair.
+ *
+ * `ctx.execution.readFile(handle, path)` resolves the model-provided
+ * path against `handle.cwd` before touching disk — so `src/App.tsx`,
+ * `./src/App.tsx`, and `/abs/cwd/src/App.tsx` all read the **same**
+ * bytes. The read-state map MUST mirror that resolution: without it,
+ * a model that reads `src/App.tsx` and then edits `./src/App.tsx`
+ * trips the `requireReadBeforeEdit` gate for a file it demonstrably
+ * already saw (the gate's "has not been read in this session" message
+ * fires on a stale key).
+ *
+ * `node:path`'s `resolve(cwd, path)` short-circuits when `path` is
+ * already absolute, so absolute and relative shapes converge on the
+ * same canonical form. We don't `realpath()` symlinks — the file IS
+ * the path the model addressed, not the realpath behind it; the host's
+ * execution context decides how to dereference.
+ */
+declare function readStateKey(cwd: string, path: string): string;
+/**
+ * FNV-1a 32-bit hash, hex-encoded. Fast, non-cryptographic — we only need
+ * collision resistance against accidental matches between different file
+ * contents within one session (~1 in 4 billion). Cheaper than allocating
+ * a Buffer and pulling in `crypto`.
+ */
+declare function hashContent(text: string): string;
+//#endregion
 //#region src/tools/types.d.ts
 /**
  * Runtime context passed to every tool execution.
@@ -1921,12 +2340,30 @@ interface ToolContext {
    * the subagent tree can be reconstructed from a persisted session.
    */
   runId?: string;
+  /**
+   * Parent run id when the agent owning this tool call is a subagent.
+   * Mirrors `SessionRun.parentRunId`; absent on top-level runs. Tools
+   * that need to walk up to the spawning run (telemetry, scoped
+   * caches, todowrite-style state keyed by the parent thread) read it
+   * directly off the context instead of resolving via the session.
+   */
+  parentRunId?: string;
   /**
    * The agent's session, when one was provided to `createAgent`. Tools that
    * want to persist their own state (or, in the case of `spawn`, inherit the
    * parent's session for child persistence) can read from here.
    */
   session?: Session;
+  /**
+   * Explicit read-state map forwarded from the agent's options. When set,
+   * tools should prefer it over the `Session`-keyed lookup so the
+   * `requireReadBeforeEdit` gate and `dedupReads` cache honor cross-context
+   * sharing — `spawn`'s `shareReadState` opt-in is the canonical caller.
+   * Resolve uniformly via `resolveReadStateMap(ctx)` (see
+   * `tools/read-state.ts`); custom tools that need read tracking should do
+   * the same.
+   */
+  readState?: ReadStateMap;
   /**
    * Subagent depth for the agent owning this tool call. 0 = top-level,
    * 1 = first-level child, … Used by spawn to enforce a `maxDepth` cap.
@@ -2139,6 +2576,23 @@ interface AgentHooks {
     delta: string;
     thinking: string;
   }) => void;
+  /**
+   * Fires when the provider's stream rejects BEFORE `stream:end` — provider
+   * errors, network blips, malformed `tools` payloads (400 invalid_request_error).
+   *
+   * `err` is the original thrown value, not the typed `AgentProviderError`
+   * the loop subsequently constructs; subscribe here to capture the native
+   * SDK exception (status codes, request ids) for telemetry without having
+   * to walk `cause` chains. Observational — the loop still wraps + throws
+   * after this hook resolves, so handlers cannot suppress the failure.
+   *
+   * Does NOT fire on user-initiated aborts; those land on `agent:abort`
+   * instead. Use `err instanceof Error && err.name === 'AbortError'` to
+   * distinguish if you also subscribe here for raw error logging.
+   */
+  'stream:error': (ctx: StreamHookContext & {
+    err: unknown;
+  }) => void;
   'oauth:refresh': (ctx: OAuthRefreshHookContext) => void;
   /**
    * Fires before validation, `tool:before`, and `execute`. Two ways to
@@ -2190,6 +2644,54 @@ interface AgentHooks {
      */
     priorContent?: string;
   }) => void;
+  /**
+   * Symmetric notification fired ONCE per call the model dispatched,
+   * regardless of the path the call ultimately took through the loop.
+   * Pair with `tool:after` (which also fires uniformly across paths) to
+   * get a guaranteed `tool` ↔ `tool-result` event pairing for downstream
+   * consumers reconstructing message history from live events.
+   *
+   * Distinct from `tool:before`: `tool:before` only fires when the tool
+   * body is about to execute (the legacy "I'm running this tool" notification),
+   * skipping gate-block / gate-substitute / unknown-tool / validation-reject
+   * paths. `tool:dispatched` fires on all five paths with an `outcome`
+   * discriminator so live consumers never see a `tool:after` whose
+   * matching dispatch event was suppressed.
+   *
+   * Strict ordering: `tool:dispatched` fires AFTER `tool:gate` /
+   * `validation:reject` / `tool:unknown` so the resolved `outcome` is
+   * always accurate. Fires BEFORE `tool:before` on the execute path so
+   * consumers binding both events see dispatched-then-before.
+   *
+   * `reason` is set only when `outcome === 'gate-block'` and carries the
+   * gate's refusal text (so consumers can render denied-diff badges, etc.
+   * without a side channel).
+   */
+  'tool:dispatched': (ctx: ToolHookContext & {
+    outcome: 'execute' | 'gate-substitute' | 'gate-block' | 'unknown' | 'invalid-input';
+    reason?: string;
+    runToolCounts: Readonly<Record<string, number>>;
+  }) => void;
+  /**
+   * Fires after a tool body produced a result (the execute path) or a
+   * `tool:gate` listener substituted one via `ctx.result` (the Z20
+   * cache-substitute path). Carries the post-`tool:transform` payload —
+   * what the model actually sees on the wire.
+   *
+   * Does NOT fire on gate-block / unknown-tool / validation-reject
+   * paths: the loop synthesizes their `tool_result` text inline and
+   * sends it back to the model, but no tool body produced output and
+   * no `tool:transform` ran. Consumers wanting symmetric per-call
+   * notification across every dispatch path should listen to
+   * `tool:dispatched` instead (which fires once per call regardless of
+   * path, with an `outcome` discriminator).
+   *
+   * This narrow contract is deliberate: tracing spans opened in
+   * `tool:before` only get closed where they were opened, byte budgets
+   * only count real tool output, and chat-layer transcript renderers
+   * keep their `tool` ↔ `tool-result` pairing without special-casing
+   * the synthesized paths.
+   */
   'tool:after': (ctx: ToolHookContext & {
     result: string | ToolResultContent[];
     outputBytes: number;
@@ -2301,6 +2803,12 @@ interface AgentHooks {
     childId: string;
     depth: number;
   }) => void;
+  /** Bubbled `stream:error` from a subagent's turn. See {@link AgentHooks['stream:error']}. */
+  'child:stream:error': (ctx: StreamHookContext & {
+    err: unknown;
+    childId: string;
+    depth: number;
+  }) => void;
   /**
    * Gate-style child events. Unlike the other `child:*` events, the bubble
    * passes the **same `ctx` reference** the subagent's loop is awaiting on:
@@ -2342,6 +2850,19 @@ interface AgentHooks {
      */
     priorContent?: string;
   }) => void;
+  /**
+   * Bubbled sibling of {@link AgentHooks['tool:dispatched']} — fires when a
+   * subagent dispatches a call. Symmetric with `child:tool:after` so live
+   * UI rendering of subagent transcripts stays paired across all five
+   * dispatch paths (gate-block/gate-substitute/unknown/invalid-input/execute).
+   */
+  'child:tool:dispatched': (ctx: ToolHookContext & {
+    outcome: 'execute' | 'gate-substitute' | 'gate-block' | 'unknown' | 'invalid-input';
+    reason?: string;
+    runToolCounts: Readonly<Record<string, number>>;
+    childId: string;
+    depth: number;
+  }) => void;
   'child:tool:after': (ctx: ToolHookContext & {
     result: string | ToolResultContent[];
     outputBytes: number;
@@ -2539,6 +3060,26 @@ interface AgentHooks {
     skill: SkillConfig;
     reason: DeactivationReason;
   }) => void;
+  /**
+   * Fires once per repair performed by the pre-send pairing pass
+   * ({@link ensureToolResultPairing}). The pass runs immediately before every
+   * provider call and patches over the wire-level corruption modes that
+   * Anthropic / OpenAI 400 on (orphan `tool_use` / `tool_result`, duplicate
+   * ids, compaction-stranded blocks).
+   *
+   * Observational — handlers can mirror to Sentry/PostHog/etc. for
+   * postmortems on new corruption sources but cannot suppress the repair.
+   * The companion `behavior.strictToolPairing` flag is the consumer escape
+   * hatch for "throw instead of repair" (training-data collectors).
+   *
+   * `turnId` lets handlers correlate a repair burst with the run-loop turn
+   * that observed it. Absent on repairs detected from the synthetic
+   * fallback path in `agent.run()`'s error catch (the orphan-tool_use
+   * fallback for crash recovery), where no turn is in flight.
+   */
+  'pairing:repair': (ctx: PairingRepair & {
+    turnId?: string;
+  }) => void;
   'usage': (ctx: {
     turn: number;
     turnId: string;
@@ -2645,6 +3186,16 @@ interface AgentOptions {
   mcpServers?: McpServerConfig[];
   /** Session for identity, turn persistence, and run tracking */
   session?: Session;
+  /**
+   * Explicit read-state map for `read_file` dedup + `requireReadBeforeEdit`
+   * tracking. When omitted, the read-state lives in a `WeakMap<Session, …>`
+   * keyed by the agent's session; providing an explicit map lets a parent
+   * agent share its tracking with a sessionless child (the canonical caller
+   * is `spawn`'s `shareReadState: true` option). Tools resolve uniformly
+   * via `resolveReadStateMap(ctx)` so the explicit map (when present)
+   * wins over the session-keyed lookup.
+   */
+  readState?: ReadStateMap;
   /** Skills configuration */
   skills?: SkillsConfig;
   /**
@@ -2751,11 +3302,12 @@ declare function createAgent({
   execution,
   mcpServers,
   session,
+  readState: agentReadState,
   skills: agentSkills,
   mcpConnector,
   eager,
   hooks: initialHooks
 }: AgentOptions): Agent;
 //#endregion
-export { openrouter as $, SessionStore as A, SpawnHookContext as At, createMemoryStore as B, toolOutputByteLength as Bt, SkillResource as C, PromptTextPart as Ct, Session as D, SessionHookContext as Dt, CreateSessionOptions as E, SessionEndStatus as Et, autoDetectAndConvert as F, ToolResultContent as Ft, ProviderCapabilities as G, AgentToolNotAllowedError as Gt, FileMapStoreOptions as H, AgentAbortedError as Ht, fromAnthropic as I, ToolResultImageContent as It, ToolCall as J, ClassifiedErrorKind as Jt, StreamCallbacks as K, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as Kt, fromOpenAI as L, ToolResultTextContent as Lt, loadSession as M, ThinkingLevel as Mt, RemoteStoreOptions as N, ToolExecutionMode as Nt, SessionData as O, SessionMessage as Ot, createRemoteStore as P, ToolHookContext as Pt, OpenRouterParams as Q, toAnthropic as R, TurnFinishReason as Rt, SkillDiagnostic as S, PromptPart as St, SkillsConfig as T, SessionContentBlock as Tt, createFileMapStore as U, AgentContextExceededError as Ut, FileMapAdapter as V, toolResultToText as Vt, Provider as W, AgentProviderError as Wt, ToolSpec as X, matchesContextExceeded as Xt, ToolResult as Y, errorMessage as Yt, TurnResult as Z, toTypedError as Zt, resultToString as _, McpToolHookContext as _t, createAgent as a, openaiCompat as at, ToolMap as b, PromptDocumentPart as bt, DeactivationReason as c, CerebrasParams as ct, createSkillActivationState as d, anthropic as dt, OpenAICompatAuthHeader as et, ConnectMcpServersOptions as f, AgentBehavior as ft, normalizeMcpServers as g, McpServerConfig as gt, normalizeMcpBlocks as h, ChildRunStats as ht, AgentOptions as i, mapOAIFinishReason as it, createSession as j, StreamHookContext as jt, SessionRun as k, SessionTurn as kt, SkillActivationState as l, cerebras as lt, connectMcpServers as m, AgentStats as mt, AgentHookMap as n, OpenAICompatParams as nt, ActivationVia as o, OpenAIParams as ot, McpConnection as p, AgentRunOptions as pt, StreamOptions as q, ClassifiedError as qt, AgentHooks as r, classifyOpenAICompatError as rt, ActiveSkill as s, openai as st, Agent as t, OpenAICompatHttpError as tt, SkillActivationStateOptions as u, AnthropicParams as ut, ToolContext as v, McpToolSchema as vt, SkillSource as w, RunHookMap as wt, SkillConfig as x, PromptImagePart as xt, ToolDef as y, OAuthRefreshHookContext as yt, toOpenAI as z, TurnUsage as zt };
-//# sourceMappingURL=agent-CYpPKn5Z.d.ts.map
+export { fromOpenAI as $, ThinkingLevel as $t, SkillSource as A, cerebras as At, createRemoteStore as B, OAuthRefreshHookContext as Bt, getReadState as C, OpenAICompatParams as Ct, SkillConfig as D, OpenAIParams as Dt, resolveReadStateMap as E, openaiCompat as Et, SessionRun as F, AgentStats as Ft, SYNTHETIC_TOOL_RESULT_PLACEHOLDER as G, RunHookMap as Gt, ORPHANED_TOOL_RESULT_MARKER as H, PromptImagePart as Ht, SessionStore as I, ChildRunStats as It, autoDetectAndConvert as J, SessionHookContext as Jt, TOOL_USE_INTERRUPTED_MARKER as K, SessionContentBlock as Kt, createSession as L, McpServerConfig as Lt, CreateSessionOptions as M, anthropic as Mt, Session as N, AgentBehavior as Nt, SkillDiagnostic as O, openai as Ot, SessionData as P, AgentRunOptions as Pt, fromAnthropic as Q, StreamHookContext as Qt, loadSession as R, McpToolHookContext as Rt, ReadStateMap as S, OpenAICompatHttpError as St, readStateKey as T, mapOAIFinishReason as Tt, PairingRepair as U, PromptPart as Ut, EnsureToolResultPairingOptions as V, PromptDocumentPart as Vt, PairingRepairMode as W, PromptTextPart as Wt, ensureToolResultPairing as X, SessionTurn as Xt, detectTurnInterruption as Y, SessionMessage as Yt, filterUnresolvedToolUses as Z, SpawnHookContext as Zt, resultToString as _, errorMessage as _n, sanitizeToolSchema as _t, createAgent as a, TurnFinishReason as an, createFileMapStore as at, ToolMap as b, openrouter as bt, DeactivationReason as c, toolResultToText as cn, StreamCallbacks as ct, createSkillActivationState as d, AgentProviderError as dn, ToolResult as dt, ToolExecutionMode as en, toAnthropic as et, ConnectMcpServersOptions as f, AgentToolNotAllowedError as fn, ToolSpec as ft, normalizeMcpServers as g, ClassifiedErrorKind as gn, SchemaSanitizeResult as gt, normalizeMcpBlocks as h, ClassifiedError as hn, SchemaSanitizeProfile as ht, AgentOptions as i, ToolResultTextContent as in, FileMapStoreOptions as it, SkillsConfig as j, AnthropicParams as jt, SkillResource as k, CerebrasParams as kt, SkillActivationState as l, AgentAbortedError as ln, StreamOptions as lt, connectMcpServers as m, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as mn, SchemaSanitizeOptions as mt, AgentHookMap as n, ToolResultContent as nn, createMemoryStore as nt, ActivationVia as o, TurnUsage as on, Provider as ot, McpConnection as p, AgentToolPairingError as pn, TurnResult as pt, TurnInterruptionState as q, SessionEndStatus as qt, AgentHooks as r, ToolResultImageContent as rn, FileMapAdapter as rt, ActiveSkill as s, toolOutputByteLength as sn, ProviderCapabilities as st, Agent as t, ToolHookContext as tn, toOpenAI as tt, SkillActivationStateOptions as u, AgentContextExceededError as un, ToolCall as ut, ToolContext as v, matchesContextExceeded as vn, sanitizeToolSpecs as vt, hashContent as w, classifyOpenAICompatError as wt, ReadStateEntry as x, OpenAICompatAuthHeader as xt, ToolDef as y, toTypedError as yn, OpenRouterParams as yt, RemoteStoreOptions as z, McpToolSchema as zt };
+//# sourceMappingURL=agent-BXRCCHeq.d.ts.map