@wrongstack/core 0.277.2 → 0.280.0

package/dist/{context-DPlA6kid.d.ts → tool-BkOgs_KL.d.ts}

@@ -1,37 +1,3 @@
-/**
- * Side-effect risk classification for structured audit recording (P2 #5).
- *
- * @see {@link import('../core/context.js').Context.recordSideEffect}
- */
-/**
- * The kind of risk a tool side-effect poses. Used by /diag and session
- * replay to filter and group side effects.
- */
-type SideEffectRisk = 'fs.write' | 'shell' | 'package' | 'network' | 'config';
-/**
- * A structured record of a non-filesystem side effect produced by a tool.
- * Appended to the session JSONL as a `side_effect` event for audit and
- * observability.
- */
-interface SideEffect {
-    /** Session-unique tool call ID (from the tool_use block). */
-    toolUseId: string;
-    /** Tool name: 'bash' | 'install' | 'fetch' | ... */
-    toolName: string;
-    /** ISO timestamp. */
-    ts: string;
-    /** The input the tool received (command, url, packages). */
-    input: Record<string, unknown>;
-    /**
-     * Optional outcome summary — NOT the full output (that's already in the
-     * tool_result block). A short string like "exit 0", "installed 42 packages",
-     * "HTTP 200 (12KB)", or "timed out".
-     */
-    outcome?: string | undefined;
-    /** Risk classification for filtering in /diag. */
-    risk: SideEffectRisk;
-}
-
 interface TextBlock {
     type: 'text';
     text: string;
@@ -109,6 +75,40 @@ declare function isToolResultBlock(b: ContentBlock): b is ToolResultBlock;
 declare function isImageBlock(b: ContentBlock): b is ImageBlock;
 declare function isThinkingBlock(b: ContentBlock): b is ThinkingBlock;
 
+/**
+ * Side-effect risk classification for structured audit recording (P2 #5).
+ *
+ * @see {@link import('../core/context.js').Context.recordSideEffect}
+ */
+/**
+ * The kind of risk a tool side-effect poses. Used by /diag and session
+ * replay to filter and group side effects.
+ */
+type SideEffectRisk = 'fs.write' | 'shell' | 'package' | 'network' | 'config';
+/**
+ * A structured record of a non-filesystem side effect produced by a tool.
+ * Appended to the session JSONL as a `side_effect` event for audit and
+ * observability.
+ */
+interface SideEffect {
+    /** Session-unique tool call ID (from the tool_use block). */
+    toolUseId: string;
+    /** Tool name: 'bash' | 'install' | 'fetch' | ... */
+    toolName: string;
+    /** ISO timestamp. */
+    ts: string;
+    /** The input the tool received (command, url, packages). */
+    input: Record<string, unknown>;
+    /**
+     * Optional outcome summary — NOT the full output (that's already in the
+     * tool_result block). A short string like "exit 0", "installed 42 packages",
+     * "HTTP 200 (12KB)", or "timed out".
+     */
+    outcome?: string | undefined;
+    /** Risk classification for filtering in /diag. */
+    risk: SideEffectRisk;
+}
+
 type MessageRole = 'user' | 'assistant' | 'system';
 interface Message {
     role: MessageRole;
@@ -395,258 +395,21 @@ declare class ParseError extends WrongStackError {
          * from different upstream APIs without parsing the message.
          */
         source?: string | undefined;
-        context?: Record<string, unknown> | undefined;
-        cause?: unknown | undefined;
-    });
-}
-declare function isWrongStackError(err: unknown): err is WrongStackError;
-declare function isToolError(err: unknown): err is ToolError;
-declare function isConfigError(err: unknown): err is ConfigError;
-declare function isPluginError(err: unknown): err is PluginError;
-declare function isSessionError(err: unknown): err is SessionError;
-declare function isAgentError(err: unknown): err is AgentError;
-declare function isFsError(err: unknown): err is FsError;
-declare function isToolValidationError(err: unknown): err is ToolValidationError;
-declare function isFetchError(err: unknown): err is FetchError;
-declare function isParseError(err: unknown): err is ParseError;
-declare function isSddError(err: unknown): err is SddError;
-
-type Permission = 'auto' | 'confirm' | 'deny';
-/**
- * Risk tier for tools in YOLO mode. YOLO auto-approves normal project work,
- * while clearly destructive calls still require confirmation.
- *
- * - `safe`       — read-only, no side effects (read, glob, grep, etc.)
- * - `standard`   — non-destructive writes and mutations (write, edit, safe shell commands)
- * - `destructive` — irreversible or broadside effects (recursive deletes, db drops, etc.)
- */
-type RiskTier = 'safe' | 'standard' | 'destructive';
-/**
- * Icon identifiers for tools — each UI (WebUI/TUI/REPL) maps these to its own icon library.
- * Add the icon directly on each Tool so all UIs consume the same canonical value.
- */
-type ToolIconId = 'file' | 'edit' | 'search' | 'folder' | 'terminal' | 'web' | 'git' | 'tree' | 'code' | 'test' | 'package' | 'document' | 'scaffold' | 'todo' | 'plan' | 'task' | 'meta' | 'index' | 'json' | 'diff' | 'logs' | 'settings' | 'fallback';
-interface JSONSchema {
-    type?: string | undefined;
-    properties?: Record<string, JSONSchema>;
-    required?: string[] | undefined;
-    items?: JSONSchema | undefined;
-    enum?: unknown[] | undefined;
-    description?: string | undefined;
-    [k: string]: unknown;
-}
-/**
- * Tool progress event — yielded by `Tool.executeStream` to give the UI
- * something to render while a long-running tool works. The executor
- * publishes each event via EventBus as `tool.progress` so the TUI, logger,
- * and observability layer can consume them uniformly.
- *
- * Keep events small. They are buffered through the EventBus synchronously
- * and rendered on the main thread.
- */
-interface ToolProgressEvent {
-    /**
-     * - `log`           — verbose informational message (e.g. "scanning…")
-     * - `warning`       — non-fatal issue (e.g. "skipped X due to ENOENT")
-     * - `metric`        — numeric data (e.g. files scanned so far)
-     * - `file_changed`  — a tool that mutates the workspace announces a write
-     * - `partial_output` — stream of textual output (bash stdout, fetch body)
-     */
-    type: 'log' | 'warning' | 'metric' | 'file_changed' | 'partial_output';
-    text?: string | undefined;
-    data?: Record<string, unknown>;
-}
-/**
- * Terminal event for `executeStream`. The output must match the tool's
- * declared output type — the executor unwraps `output` and treats it like
- * a normal `execute` return value.
- */
-interface ToolFinalEvent<O> {
-    type: 'final';
-    output: O;
-}
-type ToolStreamEvent<O = unknown> = ToolProgressEvent | ToolFinalEvent<O>;
-interface Tool<I = unknown, O = unknown> {
-    name: string;
-    description: string;
-    /**
-     * Pre-computed token estimate for this tool's definition (name +
-     * description + JSON-serialized inputSchema). Set by ToolRegistry on
-     * registration; consumed by estimateToolDefTokens / estimateRequestTokens
-     * to skip redundant JSON.stringify on every context-pressure check.
-     */
-    _estDefTokens?: number | undefined;
-    usageHint?: string | undefined;
-    /** Optional category for grouping in help lists and system prompts. */
-    category?: string | undefined;
-    inputSchema: JSONSchema;
-    permission: Permission;
-    mutating: boolean;
-    /**
-     * Risk tier for selective YOLO gating. When YOLO is active, clearly
-     * destructive calls still emit `confirm`. Defaults to `standard` when
-     * omitted — callers should always check `riskTier` after the basic
-     * permission decision.
-     */
-    riskTier?: RiskTier | undefined;
-    /**
-     * Input-field name that the permission policy should match trust rules
-     * against. Without this, the policy falls back to a heuristic
-     * (`command` / `path` / `url` / `name`) that can collide across tools —
-     * e.g. an HTTP tool whose `path` means "request path" would be checked
-     * against filesystem-path trust rules. Set explicitly to avoid the
-     * cross-tool subject collision.
-     *
-     * The named field's value must be a string at runtime; non-string values
-     * fall back to the heuristic.
-     */
-    subjectKey?: string | undefined;
-    maxOutputBytes?: number | undefined;
-    timeoutMs?: number | undefined;
-    /**
-     * Hint for the TUI spinner — does NOT affect actual timeout enforcement.
-     * Use `timeoutMs` for hard limits. Leave undefined when duration varies
-     * unpredictably.
-     */
-    estimatedDurationMs?: number | undefined;
-    /**
-     * Declarative security capabilities granted by this tool.
-     *
-     * Examples: "shell.arbitrary", "fs.write", "fs.write.outside-project",
-     * "net.outbound", "mcp.proxy", "subagent.spawn", "config.mutate".
-     *
-     * These are used by permission policies (especially subagent guards) and
-     * future capability-based allowlists. Prefer well-known values over ad-hoc strings.
-     *
-     * This field is optional for backward compatibility. Tools without it are
-     * treated conservatively by guards.
-     */
-    capabilities?: readonly string[] | undefined;
-    /**
-     * Icon identifier for this tool — consumed by all UIs (WebUI/TUI/REPL) to
-     * render a tool-specific icon instead of a generic fallback.
-     * Each UI maps this id to its own icon library.
-     */
-    icon?: ToolIconId | undefined;
-    execute(input: I, ctx: Context, opts: {
-        signal: AbortSignal;
-    }): Promise<O>;
-    /**
-     * Optional cross-field validation hook. Called by the executor AFTER
-     * JSON Schema validation passes and AFTER PreToolUse hooks may have
-     * rewritten the input, but BEFORE permission checks and execution.
-     *
-     * Use this for invariants the JSON Schema cannot express — e.g.
-     * `old_string !== new_string` in edit, or `end > start` in a range tool.
-     * Return an array of validation errors (empty = valid). The executor
-     * surfaces them to the model just like schema validation errors, so the
-     * model can self-correct without the tool's `execute()` running.
-     *
-     * P3 #16 (before-release.md): tools that implement cross-field checks
-     * inside `execute()` can migrate them here for earlier rejection and
-     * consistent error formatting.
-     */
-    validate?(input: I): string[];
-    /**
-     * Optional streaming variant. When defined, the executor prefers this
-     * over `execute` — yielded events become `tool.progress` EventBus events
-     * and the terminal `final` event provides the output. Tools that don't
-     * have intermediate state shouldn't implement this; the default `execute`
-     * path is more efficient.
-     */
-    executeStream?(input: I, ctx: Context, opts: {
-        signal: AbortSignal;
-    }): AsyncIterable<ToolStreamEvent<O>>;
-    /**
-     * Optional teardown hook fired by the executor when the tool's run is
-     * aborted (signal triggered). Errors thrown here are swallowed so they
-     * never mask the originating failure.
-     *
-     * **When to use `cleanup` vs `ctx.registerAbortHook`:**
-     *
-     * - Use `cleanup` for resources **owned by the tool author** that are
-     *   established at execute-time: child processes spawned by the tool,
-     *   file handles opened by the tool, network connections initiated by
-     *   the tool. The lifecycle is co-located with the tool definition, so
-     *   readers see the resource and its teardown in one place.
-     *
-     *   ```ts
-     *   async execute(input, ctx, opts) {
-     *     const child = spawn(...);
-     *     // … tool work …
-     *   },
-     *   async cleanup(_input, _ctx) {
-     *     // best-effort kill of any child still running
-     *   }
-     *   ```
-     *
-     * - Use `ctx.registerAbortHook` for **context-scoped teardown** registered
-     *   dynamically inside `execute`: when the tool delegates to a library
-     *   that needs cancellation, or when the resource is created lazily
-     *   somewhere down the call stack and the natural cleanup point isn't
-     *   at the tool boundary. The hook fires when the **agent run** ends,
-     *   not when this specific tool call aborts.
-     *
-     *   ```ts
-     *   async execute(input, ctx, opts) {
-     *     const handle = openHelper();
-     *     ctx.registerAbortHook(() => handle.dispose());
-     *     // … work …
-     *   }
-     *   ```
-     *
-     * If both are registered for the same resource, `cleanup` fires first
-     * (on tool abort) and the abort-hook fires after on the wider run abort.
-     * Avoid double-free by gating one on the other's effect, or pick a single
-     * teardown channel per resource.
-     */
-    cleanup?(input: I, ctx: Context): Promise<void>;
-    /**
-     * Optional custom output serializer. When present, the executor's output
-     * serializer calls this INSTEAD of the central `renderToolObject()` switch
-     * — the tool owns its own pretty-printing.
-     *
-     * Return a string representation of the output that the model will see in
-     * its tool_result block. The serializer applies the iteration output cap
-     * AFTER this runs, so don't worry about truncation.
-     *
-     * P3 #21 (before-release.md): `renderToolObject()` is a god function with
-     * 30+ per-tool branches, far from each tool's definition. New tools that
-     * want custom output no longer need to add a branch there — they implement
-     * this method instead. Existing branches stay until migrated incrementally.
-     */
-    serialize?(output: O, input: I): string;
-}
-interface ToolCallContext {
-    tool: Tool;
-    input: unknown;
-    callId: string;
-    ctx: Context;
-    signal: AbortSignal;
-}
-/**
- * Error categories for tool execution failures.
- * Used by the executor to classify errors and determine retry strategy.
- */
-declare enum ToolErrorCategory {
-    TRANSIENT = "transient",// ETIMEDOUT, ECONNRESET, network timeout, HTTP 429/503
-    NOT_FOUND = "not_found",// ENOENT, ENOTDIR, HTTP 404
-    PERMISSION = "permission",// EACCES, EPERM, HTTP 401/403
-    VALIDATION = "validation",// schema validation error, HTTP 400
-    FATAL = "fatal"
-}
-/**
- * Structured tool error information for the LLM and retry logic.
- */
-interface ToolErrorInfo {
-    readonly category: ToolErrorCategory;
-    /** Whether the operation can be retried automatically. */
-    readonly retryable: boolean;
-    /** User-facing message describing the error. */
-    readonly userMessage: string;
-    /** Optional technical detail for debugging. */
-    readonly detail?: string;
+        context?: Record<string, unknown> | undefined;
+        cause?: unknown | undefined;
+    });
 }
+declare function isWrongStackError(err: unknown): err is WrongStackError;
+declare function isToolError(err: unknown): err is ToolError;
+declare function isConfigError(err: unknown): err is ConfigError;
+declare function isPluginError(err: unknown): err is PluginError;
+declare function isSessionError(err: unknown): err is SessionError;
+declare function isAgentError(err: unknown): err is AgentError;
+declare function isFsError(err: unknown): err is FsError;
+declare function isToolValidationError(err: unknown): err is ToolValidationError;
+declare function isFetchError(err: unknown): err is FetchError;
+declare function isParseError(err: unknown): err is ParseError;
+declare function isSddError(err: unknown): err is SddError;
 
 /**
  * Token usage for a single provider call, normalized across providers.
@@ -1532,6 +1295,24 @@ interface ContextRepeatedReadEvidence {
     count: number;
     lastToolUseId: string;
 }
+/** Where a completed-work ledger entry came from. */
+type CompletedWorkSource = 'todo' | 'plan' | 'task' | 'verification' | 'manual';
+/**
+ * One unit of finished work, kept in the session's completed-work ledger so
+ * the model (and a resumed session) can see what is already done and build
+ * on it instead of redoing it. Persisted via the completed-work checkpoint
+ * (`storage/completed-work-checkpoint.ts`).
+ */
+interface CompletedWorkEvidence {
+    /** Stable dedupe key — completing the same unit twice updates in place (e.g. "task:<id>"). */
+    key: string;
+    source: CompletedWorkSource;
+    summary: string;
+    /** Epoch ms when the work was marked complete. */
+    completedAt: number;
+    /** Optional pointer to proof (test run, commit hash, file path). */
+    evidence?: string | undefined;
+}
 interface ContextEvidenceState {
     currentIntent?: ContextIntentEvidence | undefined;
     sessionGoals: string[];
@@ -1540,6 +1321,8 @@ interface ContextEvidenceState {
     toolCalls: ToolOutputMetadata[];
     fileGraph: Record<string, ContextFileEvidence>;
     repeatedReads: ContextRepeatedReadEvidence[];
+    /** Ledger of finished work (tasks, todos, verifications) — see {@link CompletedWorkEvidence}. */
+    completedWork: CompletedWorkEvidence[];
     lastReadPath?: string | undefined;
     updatedAt: number;
 }
@@ -1954,4 +1737,241 @@ declare class Context implements RunEnv {
     usage(): Usage;
 }
 
-export { type ProviderErrorBody as $, AgentError as A, ConfigError as B, Context as C, type ContextEvidenceState as D, type ContextFileEvidence as E, type ContextInit as F, type ContextIntentEvidence as G, type ContextRepeatedReadEvidence as H, ERROR_CODES as I, type JSONSchema as J, type ErrorCode as K, type ErrorSeverity as L, type Message as M, type ErrorSubsystem as N, FetchError as O, type Provider as P, type FileSnapshot as Q, type ReasoningRequest as R, type SessionEvent as S, type Tool as T, type Usage as U, FsError as V, type ImageBlock as W, type JsonSchemaSpec as X, type MessageRole as Y, ParseError as Z, PluginError as _, type ReasoningConfig as a, type ReadonlyConversationState as a0, type RequestCacheControl as a1, type ResponseFormat as a2, type RiskTier as a3, type RunEnv as a4, type SafetySetting as a5, SddError as a6, SessionError as a7, type SideEffect as a8, type SideEffectRisk as a9, isSessionError as aA, isTextBlock as aB, isThinkingBlock as aC, isToolError as aD, isToolResultBlock as aE, isToolUseBlock as aF, isToolValidationError as aG, isWrongStackError as aH, toWrongStackError as aI, wrapAsState as aJ, type StateChange as aa, type StateChangeHandler as ab, type StopReason as ac, type StreamEvent as ad, StreamHangError as ae, type ThinkingBlock as af, type ToolCallContext as ag, ToolError as ah, type ToolErrorInfo as ai, type ToolEvidenceStatus as aj, type ToolFinalEvent as ak, type ToolIconId as al, type ToolStreamEvent as am, ToolValidationError as an, WrongStackError as ao, asBlocks as ap, asText as aq, extractRunEnv as ar, isAgentError as as, isConfigError as at, isFetchError as au, isFsError as av, isImageBlock as aw, isParseError as ax, isPluginError as ay, isSddError as az, type SessionWriter as b, type Request as c, type Response as d, type TokenCounter as e, type CacheStats as f, ProviderError as g, type Permission as h, type ContentBlock as i, type SessionMetadata as j, type SessionStore as k, ToolErrorCategory as l, type ToolProgressEvent as m, type ToolOutputMetadata as n, type Capabilities as o, type ReasoningEffort as p, type CacheTtl as q, type TextBlock as r, type ToolUseBlock as s, type ToolResultBlock as t, type RunOptions as u, ConversationState as v, type ResumedSession as w, type SessionData as x, type SessionSummary as y, type TodoItem as z };
+type Permission = 'auto' | 'confirm' | 'deny';
+/**
+ * Risk tier for tools in YOLO mode. YOLO auto-approves normal project work,
+ * while clearly destructive calls still require confirmation.
+ *
+ * - `safe`       — read-only, no side effects (read, glob, grep, etc.)
+ * - `standard`   — non-destructive writes and mutations (write, edit, safe shell commands)
+ * - `destructive` — irreversible or broadside effects (recursive deletes, db drops, etc.)
+ */
+type RiskTier = 'safe' | 'standard' | 'destructive';
+/**
+ * Icon identifiers for tools — each UI (WebUI/TUI/REPL) maps these to its own icon library.
+ * Add the icon directly on each Tool so all UIs consume the same canonical value.
+ */
+type ToolIconId = 'file' | 'edit' | 'search' | 'folder' | 'terminal' | 'web' | 'git' | 'tree' | 'code' | 'test' | 'package' | 'document' | 'scaffold' | 'todo' | 'plan' | 'task' | 'meta' | 'index' | 'json' | 'diff' | 'logs' | 'settings' | 'fallback';
+interface JSONSchema {
+    type?: string | undefined;
+    properties?: Record<string, JSONSchema>;
+    required?: string[] | undefined;
+    items?: JSONSchema | undefined;
+    enum?: unknown[] | undefined;
+    description?: string | undefined;
+    [k: string]: unknown;
+}
+/**
+ * Tool progress event — yielded by `Tool.executeStream` to give the UI
+ * something to render while a long-running tool works. The executor
+ * publishes each event via EventBus as `tool.progress` so the TUI, logger,
+ * and observability layer can consume them uniformly.
+ *
+ * Keep events small. They are buffered through the EventBus synchronously
+ * and rendered on the main thread.
+ */
+interface ToolProgressEvent {
+    /**
+     * - `log`           — verbose informational message (e.g. "scanning…")
+     * - `warning`       — non-fatal issue (e.g. "skipped X due to ENOENT")
+     * - `metric`        — numeric data (e.g. files scanned so far)
+     * - `file_changed`  — a tool that mutates the workspace announces a write
+     * - `partial_output` — stream of textual output (bash stdout, fetch body)
+     */
+    type: 'log' | 'warning' | 'metric' | 'file_changed' | 'partial_output';
+    text?: string | undefined;
+    data?: Record<string, unknown>;
+}
+/**
+ * Terminal event for `executeStream`. The output must match the tool's
+ * declared output type — the executor unwraps `output` and treats it like
+ * a normal `execute` return value.
+ */
+interface ToolFinalEvent<O> {
+    type: 'final';
+    output: O;
+}
+type ToolStreamEvent<O = unknown> = ToolProgressEvent | ToolFinalEvent<O>;
+interface Tool<I = unknown, O = unknown> {
+    name: string;
+    description: string;
+    /**
+     * Pre-computed token estimate for this tool's definition (name +
+     * description + JSON-serialized inputSchema). Set by ToolRegistry on
+     * registration; consumed by estimateToolDefTokens / estimateRequestTokens
+     * to skip redundant JSON.stringify on every context-pressure check.
+     */
+    _estDefTokens?: number | undefined;
+    usageHint?: string | undefined;
+    /** Optional category for grouping in help lists and system prompts. */
+    category?: string | undefined;
+    inputSchema: JSONSchema;
+    permission: Permission;
+    mutating: boolean;
+    /**
+     * Risk tier for selective YOLO gating. When YOLO is active, clearly
+     * destructive calls still emit `confirm`. Defaults to `standard` when
+     * omitted — callers should always check `riskTier` after the basic
+     * permission decision.
+     */
+    riskTier?: RiskTier | undefined;
+    /**
+     * Input-field name that the permission policy should match trust rules
+     * against. Without this, the policy falls back to a heuristic
+     * (`command` / `path` / `url` / `name`) that can collide across tools —
+     * e.g. an HTTP tool whose `path` means "request path" would be checked
+     * against filesystem-path trust rules. Set explicitly to avoid the
+     * cross-tool subject collision.
+     *
+     * The named field's value must be a string at runtime; non-string values
+     * fall back to the heuristic.
+     */
+    subjectKey?: string | undefined;
+    maxOutputBytes?: number | undefined;
+    timeoutMs?: number | undefined;
+    /**
+     * Hint for the TUI spinner — does NOT affect actual timeout enforcement.
+     * Use `timeoutMs` for hard limits. Leave undefined when duration varies
+     * unpredictably.
+     */
+    estimatedDurationMs?: number | undefined;
+    /**
+     * Declarative security capabilities granted by this tool.
+     *
+     * Examples: "shell.arbitrary", "fs.write", "fs.write.outside-project",
+     * "net.outbound", "mcp.proxy", "subagent.spawn", "config.mutate".
+     *
+     * These are used by permission policies (especially subagent guards) and
+     * future capability-based allowlists. Prefer well-known values over ad-hoc strings.
+     *
+     * This field is optional for backward compatibility. Tools without it are
+     * treated conservatively by guards.
+     */
+    capabilities?: readonly string[] | undefined;
+    /**
+     * Icon identifier for this tool — consumed by all UIs (WebUI/TUI/REPL) to
+     * render a tool-specific icon instead of a generic fallback.
+     * Each UI maps this id to its own icon library.
+     */
+    icon?: ToolIconId | undefined;
+    execute(input: I, ctx: Context, opts: {
+        signal: AbortSignal;
+    }): Promise<O>;
+    /**
+     * Optional cross-field validation hook. Called by the executor AFTER
+     * JSON Schema validation passes and AFTER PreToolUse hooks may have
+     * rewritten the input, but BEFORE permission checks and execution.
+     *
+     * Use this for invariants the JSON Schema cannot express — e.g.
+     * `old_string !== new_string` in edit, or `end > start` in a range tool.
+     * Return an array of validation errors (empty = valid). The executor
+     * surfaces them to the model just like schema validation errors, so the
+     * model can self-correct without the tool's `execute()` running.
+     *
+     * P3 #16 (before-release.md): tools that implement cross-field checks
+     * inside `execute()` can migrate them here for earlier rejection and
+     * consistent error formatting.
+     */
+    validate?(input: I): string[];
+    /**
+     * Optional streaming variant. When defined, the executor prefers this
+     * over `execute` — yielded events become `tool.progress` EventBus events
+     * and the terminal `final` event provides the output. Tools that don't
+     * have intermediate state shouldn't implement this; the default `execute`
+     * path is more efficient.
+     */
+    executeStream?(input: I, ctx: Context, opts: {
+        signal: AbortSignal;
+    }): AsyncIterable<ToolStreamEvent<O>>;
+    /**
+     * Optional teardown hook fired by the executor when the tool's run is
+     * aborted (signal triggered). Errors thrown here are swallowed so they
+     * never mask the originating failure.
+     *
+     * **When to use `cleanup` vs `ctx.registerAbortHook`:**
+     *
+     * - Use `cleanup` for resources **owned by the tool author** that are
+     *   established at execute-time: child processes spawned by the tool,
+     *   file handles opened by the tool, network connections initiated by
+     *   the tool. The lifecycle is co-located with the tool definition, so
+     *   readers see the resource and its teardown in one place.
+     *
+     *   ```ts
+     *   async execute(input, ctx, opts) {
+     *     const child = spawn(...);
+     *     // … tool work …
+     *   },
+     *   async cleanup(_input, _ctx) {
+     *     // best-effort kill of any child still running
+     *   }
+     *   ```
+     *
+     * - Use `ctx.registerAbortHook` for **context-scoped teardown** registered
+     *   dynamically inside `execute`: when the tool delegates to a library
+     *   that needs cancellation, or when the resource is created lazily
+     *   somewhere down the call stack and the natural cleanup point isn't
+     *   at the tool boundary. The hook fires when the **agent run** ends,
+     *   not when this specific tool call aborts.
+     *
+     *   ```ts
+     *   async execute(input, ctx, opts) {
+     *     const handle = openHelper();
+     *     ctx.registerAbortHook(() => handle.dispose());
+     *     // … work …
+     *   }
+     *   ```
+     *
+     * If both are registered for the same resource, `cleanup` fires first
+     * (on tool abort) and the abort-hook fires after on the wider run abort.
+     * Avoid double-free by gating one on the other's effect, or pick a single
+     * teardown channel per resource.
+     */
+    cleanup?(input: I, ctx: Context): Promise<void>;
+    /**
+     * Optional custom output serializer. When present, the executor's output
+     * serializer calls this INSTEAD of the central `renderToolObject()` switch
+     * — the tool owns its own pretty-printing.
+     *
+     * Return a string representation of the output that the model will see in
+     * its tool_result block. The serializer applies the iteration output cap
+     * AFTER this runs, so don't worry about truncation.
+     *
+     * P3 #21 (before-release.md): `renderToolObject()` is a god function with
+     * 30+ per-tool branches, far from each tool's definition. New tools that
+     * want custom output no longer need to add a branch there — they implement
+     * this method instead. Existing branches stay until migrated incrementally.
+     */
+    serialize?(output: O, input: I): string;
+}
+interface ToolCallContext {
+    tool: Tool;
+    input: unknown;
+    callId: string;
+    ctx: Context;
+    signal: AbortSignal;
+}
+/**
+ * Error categories for tool execution failures.
+ * Used by the executor to classify errors and determine retry strategy.
+ */
+declare enum ToolErrorCategory {
+    TRANSIENT = "transient",// ETIMEDOUT, ECONNRESET, network timeout, HTTP 429/503
+    NOT_FOUND = "not_found",// ENOENT, ENOTDIR, HTTP 404
+    PERMISSION = "permission",// EACCES, EPERM, HTTP 401/403
+    VALIDATION = "validation",// schema validation error, HTTP 400
+    FATAL = "fatal"
+}
+/**
+ * Structured tool error information for the LLM and retry logic.
+ */
+interface ToolErrorInfo {
+    readonly category: ToolErrorCategory;
+    /** Whether the operation can be retried automatically. */
+    readonly retryable: boolean;
+    /** User-facing message describing the error. */
+    readonly userMessage: string;
+    /** Optional technical detail for debugging. */
+    readonly detail?: string;
+}
+
+export { type MessageRole as $, type TodoItem as A, AgentError as B, Context as C, type CompletedWorkEvidence as D, type CompletedWorkSource as E, ConfigError as F, type ContextEvidenceState as G, type ContextFileEvidence as H, type ContextInit as I, type JSONSchema as J, type ContextIntentEvidence as K, type ContextRepeatedReadEvidence as L, type Message as M, ERROR_CODES as N, type ErrorCode as O, type Provider as P, type ErrorSeverity as Q, type ReasoningRequest as R, type SessionEvent as S, type Tool as T, type Usage as U, type ErrorSubsystem as V, FetchError as W, type FileSnapshot as X, FsError as Y, type ImageBlock as Z, type JsonSchemaSpec as _, type ReasoningConfig as a, ParseError as a0, PluginError as a1, type ProviderErrorBody as a2, type ReadonlyConversationState as a3, type RequestCacheControl as a4, type ResponseFormat as a5, type RunEnv as a6, type SafetySetting as a7, SddError as a8, SessionError as a9, isPluginError as aA, isSddError as aB, isSessionError as aC, isTextBlock as aD, isThinkingBlock as aE, isToolError as aF, isToolResultBlock as aG, isToolUseBlock as aH, isToolValidationError as aI, isWrongStackError as aJ, toWrongStackError as aK, wrapAsState as aL, type SideEffect as aa, type SideEffectRisk as ab, type StateChange as ac, type StateChangeHandler as ad, type StopReason as ae, type StreamEvent as af, StreamHangError as ag, type ThinkingBlock as ah, type ToolCallContext as ai, ToolError as aj, type ToolErrorInfo as ak, type ToolEvidenceStatus as al, type ToolFinalEvent as am, type ToolIconId as an, type ToolStreamEvent as ao, ToolValidationError as ap, WrongStackError as aq, asBlocks as ar, asText as as, extractRunEnv as at, isAgentError as au, isConfigError as av, isFetchError as aw, isFsError as ax, isImageBlock as ay, isParseError as az, type SessionWriter as b, type Request as c, type Response as d, type Permission as e, type TokenCounter as f, type CacheStats as g, ProviderError as h, type ContentBlock as i, type SessionMetadata as j, type SessionStore as k, ToolErrorCategory as l, type ToolProgressEvent as m, type RiskTier as n, type ToolOutputMetadata as o, type ReasoningEffort as p, type CacheTtl as q, type Capabilities as r, type TextBlock as s, type ToolUseBlock as t, type ToolResultBlock as u, type RunOptions as v, ConversationState as w, type ResumedSession as x, type SessionData as y, type SessionSummary as z };

package/dist/{tool-executor-SVFq7IOR.d.ts → tool-executor-SiE1wlZo.d.ts}

@@ -1,12 +1,12 @@
-import { C as Context, g as ProviderError, T as Tool, s as ToolUseBlock, t as ToolResultBlock, l as ToolErrorCategory } from './context-DPlA6kid.js';
-import { C as Compactor, a as CompactReport } from './compactor-D3BGw26y.js';
-import { E as ErrorHandler, a as RecoveryDecision, R as RetryPolicy } from './retry-policy-Git9WF6d.js';
-import { M as ModelsRegistry, C as Config } from './config-DAOjriz9.js';
-import { h as Agent, i as AgentFactory } from './agent-subagent-runner-BimKihiC.js';
-import { B as BrainArbiter, E as EventBus } from './brain-CCfuEOdp.js';
-import { J as JournalEntry } from './goal-store-C1uH4srH.js';
-import { D as DispatchClassifier, a as DefaultMultiAgentCoordinator } from './multi-agent-coordinator-CcrcncvG.js';
-import { T as ToolExecutorOptions, a as ToolExecutorStrategy, b as ToolBatchResult } from './index-DJXj-dcr.js';
+import { C as Context, h as ProviderError, T as Tool, t as ToolUseBlock, u as ToolResultBlock, l as ToolErrorCategory } from './tool-BkOgs_KL.js';
+import { C as Compactor, a as CompactReport } from './compactor-U3agvUIG.js';
+import { E as ErrorHandler, a as RecoveryDecision, R as RetryPolicy } from './retry-policy-D4feSLk3.js';
+import { M as ModelsRegistry, C as Config } from './config-Cr3312zc.js';
+import { h as Agent, i as AgentFactory } from './agent-subagent-runner-PoqNKiR4.js';
+import { B as BrainArbiter, E as EventBus } from './events-Bs2fmldo.js';
+import { J as JournalEntry } from './goal-store-C4F6DjC0.js';
+import { D as DispatchClassifier, a as DefaultMultiAgentCoordinator } from './multi-agent-coordinator-CieyUoEL.js';
+import { T as ToolExecutorOptions, a as ToolExecutorStrategy, b as ToolBatchResult } from './index-kidebiDh.js';
 
 interface CompactorOptions {
     preserveK?: number | undefined;

package/dist/tools/index.d.ts

@@ -1,5 +1,5 @@
-import { T as Tool } from '../context-DPlA6kid.js';
-import { c as MCPServerConfig, C as Config } from '../config-DAOjriz9.js';
+import { T as Tool } from '../tool-BkOgs_KL.js';
+import { c as MCPServerConfig, C as Config } from '../config-Cr3312zc.js';
 import '../dispatcher-types.d-BBeXBQgS.js';
 import 'node:https';
 import 'undici';