@namzu/sdk 2.0.0 → 3.1.0

package/dist/types/sandbox/index.d.ts

@@ -3,6 +3,25 @@ import type { SandboxId } from '../ids/index.js';
 export type SandboxStatus = 'creating' | 'ready' | 'busy' | 'destroyed';
 export declare function assertSandboxStatus(status: SandboxStatus): void;
 export type SandboxEnvironment = 'linux-namespace' | 'macos-seatbelt' | 'basic';
+/**
+ * A security control a sandbox tier either provides or does not.
+ *
+ * The environment name alone does not say what a caller actually gets:
+ * one tier denies the network outright while another leaves the host
+ * filesystem fully visible, and both used to answer to the same provider
+ * name. A caller that turned isolation on for a reason needs to state
+ * which control it is relying on, so a host that cannot supply it can
+ * refuse instead of quietly handing back less.
+ *
+ *  - `filesystem` — the spawned process cannot read or write outside the
+ *    sandbox root.
+ *  - `network` — the spawned process cannot reach the network.
+ *  - `process` — the spawned process cannot see or signal host processes.
+ */
+export type SandboxIsolationControl = 'filesystem' | 'network' | 'process';
+export declare const SANDBOX_ISOLATION_CONTROLS: readonly SandboxIsolationControl[];
+/** What a tier actually enforces, per control. */
+export type SandboxIsolationReport = Readonly<Record<SandboxIsolationControl, boolean>>;
 export declare function assertSandboxEnvironment(env: SandboxEnvironment): void;
 export interface SandboxExecResult {
     readonly exitCode: number;
@@ -11,11 +30,31 @@ export interface SandboxExecResult {
     readonly signal?: string;
     readonly timedOut: boolean;
     readonly durationMs: number;
+    /**
+     * Set when the backend clipped the stream at its output cap.
+     *
+     * The firecracker protocol already computed these, but they had no slot
+     * in this contract, so they were dropped at the type boundary and the
+     * model saw a complete-looking result that had silently lost its tail —
+     * against the kernel's own convention that it does not truncate
+     * silently.
+     */
+    readonly stdoutTruncated?: boolean;
+    readonly stderrTruncated?: boolean;
 }
 export interface SandboxExecOptions {
     readonly timeout?: number;
     readonly env?: Record<string, string>;
     readonly cwd?: string;
+    /**
+     * Cancellation for the command. A backend that honours it kills the
+     * process; one that does not simply ignores it, so this is additive.
+     *
+     * Without it a Stop (or a per-tool deadline) could only ever abandon
+     * the *wait* — the sandboxed process kept running after the host
+     * believed the run had been cancelled.
+     */
+    readonly signal?: AbortSignal;
 }
 /**
  * One regular file inside the sandbox filesystem. Backends return
@@ -26,6 +65,26 @@ export interface SandboxFileEntry {
     readonly path: string;
     readonly size: number;
 }
+/**
+ * A network policy applied to a LIVE sandbox.
+ *
+ * The whole point is that it can change mid-life. The common shape —
+ * "fetch the repository with a token, then drop to deny-all before running
+ * anything the repository contains" — was not expressible at all: the
+ * policy was frozen at provider construction, so a host had to build a
+ * second provider and a second sandbox, copying the work across.
+ */
+export interface SandboxNetworkPolicy {
+    /**
+     * Hosts the sandbox may reach. Empty denies everything.
+     *
+     * `api.example.com` matches that host; `.example.com` matches the
+     * domain and its subdomains. Substring matching is deliberately not
+     * offered — `example.com` as a substring would admit
+     * `example.com.attacker.net`.
+     */
+    readonly allowedHosts: readonly string[];
+}
 export interface Sandbox {
     readonly id: SandboxId;
     readonly status: SandboxStatus;
@@ -33,9 +92,15 @@ export interface Sandbox {
     readonly environment: SandboxEnvironment;
     exec(command: string, args?: string[], opts?: SandboxExecOptions): Promise<SandboxExecResult>;
     /**
-     * Atomically replace the destination body: readers must observe either the
-     * previous complete body or the new complete body, never a truncated file.
+     * Narrow or widen what this sandbox can reach, while it is running.
+     *
+     * Optional, and a backend that cannot enforce it must **throw** rather
+     * than accept and ignore. A network policy that is accepted and not
+     * applied is worse than one that was never offered: the caller stops
+     * looking, and the run proceeds believing it is confined. That is the
+     * same rule the tiered sandbox provider follows, for the same reason.
      */
+    setNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>;
     writeFile(path: string, content: string | Buffer): Promise<void>;
     readFile(path: string): Promise<Buffer>;
     /**
@@ -121,9 +186,9 @@ export interface ContainerSandboxLayoutMount {
     readonly containerPath?: string;
 }
 /**
- * Declarative multi-mount taxonomy for a CONTAINER sandbox. Mirrors
- * the layout Anthropic's container architecture exposes to the model
- * (Claude container blueprint, Code Interpreter, "skills"):
+ * Declarative multi-mount taxonomy for a CONTAINER sandbox. A container
+ * needs one place the user will see and several the user will not, and
+ * the difference has to be legible to the model from the path alone:
  *
  *  - `outputs` — RW bind. User-visible output surface that the
  *    user consumes after the run. Default container path
@@ -166,7 +231,7 @@ export interface ContainerSandboxLayout {
      * not a child of it: the output collector / output watcher
      * scans `outputs` only, so anything the agent writes under
      * `scratch` is invisible to the user by construction. Mirrors the
-     * Anthropic Cowork pattern (`/home/claude` as scratch vs.
+     * separation between scratch space (invisible to the collector) and
      * `/mnt/user-data/outputs` as the user-visible output area).
      * Hosts that don't need a separate scratch mount may omit this.
      */
@@ -226,7 +291,7 @@ export interface SandboxCreateConfig {
  * Putting layout on `SandboxCreateConfig` would let the SDK runtime
  * (`drainQuery`) call `provider.create()` without it and trigger a
  * runtime validation failure that the type system cannot catch — a
- * trap Codex flagged in the second review round. Hosts spawning a
+ * trap flagged in the second review round. Hosts spawning a
  * sandbox per task construct one provider per task too; the same
  * closure that knows the per-task `hostPath`s is the one that calls
  * `createSandboxProvider`.
@@ -243,21 +308,28 @@ export declare const SandboxConfigSchema: z.ZodObject<{
     timeoutMs: z.ZodDefault<z.ZodNumber>;
     memoryLimitMb: z.ZodDefault<z.ZodNumber>;
     maxProcesses: z.ZodDefault<z.ZodNumber>;
-    cleanupOnDestroy: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Controls the run depends on. Provider construction throws when the
+     * host cannot enforce one of them. Empty by default, which keeps
+     * best-effort behaviour for callers that never asked for a guarantee —
+     * but a caller that did ask now gets it or gets an error, never a
+     * quiet downgrade.
+     */
+    requireIsolation: z.ZodDefault<z.ZodArray<z.ZodEnum<["filesystem", "network", "process"]>, "many">>;
 }, "strip", z.ZodTypeAny, {
     enabled: boolean;
     provider: "local";
     timeoutMs: number;
     memoryLimitMb: number;
     maxProcesses: number;
-    cleanupOnDestroy: boolean;
+    requireIsolation: ("filesystem" | "network" | "process")[];
 }, {
     enabled?: boolean | undefined;
     provider?: "local" | undefined;
     timeoutMs?: number | undefined;
     memoryLimitMb?: number | undefined;
     maxProcesses?: number | undefined;
-    cleanupOnDestroy?: boolean | undefined;
+    requireIsolation?: ("filesystem" | "network" | "process")[] | undefined;
 }>;
 export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;
 //# sourceMappingURL=index.d.ts.map

package/dist/types/sandbox/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/sandbox/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/sandbox/index.ts"],"names":[],"mappings":"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"}

package/dist/types/sandbox/index.js

@@ -13,6 +13,11 @@ export function assertSandboxStatus(status) {
         }
     }
 }
+export const SANDBOX_ISOLATION_CONTROLS = [
+    'filesystem',
+    'network',
+    'process',
+];
 export function assertSandboxEnvironment(env) {
     switch (env) {
         case 'linux-namespace':
@@ -34,6 +39,13 @@ export const SandboxConfigSchema = z.object({
     timeoutMs: z.number().positive().default(SANDBOX_DEFAULT_TIMEOUT_MS),
     memoryLimitMb: z.number().positive().default(SANDBOX_DEFAULT_MEMORY_LIMIT_MB),
     maxProcesses: z.number().positive().default(SANDBOX_DEFAULT_MAX_PROCESSES),
-    cleanupOnDestroy: z.boolean().default(true),
+    /**
+     * Controls the run depends on. Provider construction throws when the
+     * host cannot enforce one of them. Empty by default, which keeps
+     * best-effort behaviour for callers that never asked for a guarantee —
+     * but a caller that did ask now gets it or gets an error, never a
+     * quiet downgrade.
+     */
+    requireIsolation: z.array(z.enum(['filesystem', 'network', 'process'])).default([]),
 });
 //# sourceMappingURL=index.js.map

package/dist/types/sandbox/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/sandbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EACN,6BAA6B,EAC7B,+BAA+B,EAC/B,0BAA0B,GAC1B,MAAM,kCAAkC,CAAA;AASzC,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACxD,QAAQ,MAAM,EAAE,CAAC;QAChB,KAAK,UAAU,CAAC;QAChB,KAAK,OAAO,CAAC;QACb,KAAK,MAAM,CAAC;QACZ,KAAK,WAAW;YACf,OAAM;QACP,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,MAAM,CAAA;YACjC,MAAM,IAAI,KAAK,CAAC,0BAA0B,WAAW,EAAE,CAAC,CAAA;QACzD,CAAC;IACF,CAAC;AACF,CAAC;AAQD,MAAM,UAAU,wBAAwB,CAAC,GAAuB;IAC/D,QAAQ,GAAG,EAAE,CAAC;QACb,KAAK,iBAAiB,CAAC;QACvB,KAAK,gBAAgB,CAAC;QACtB,KAAK,OAAO;YACX,OAAM;QACP,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,GAAG,CAAA;YAC9B,MAAM,IAAI,KAAK,CAAC,+BAA+B,WAAW,EAAE,CAAC,CAAA;QAC9D,CAAC;IACF,CAAC;AACF,CAAC;AA8RD,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACnC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IAC5C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,0BAA0B,CAAC;IACpE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,+BAA+B,CAAC;IAC7E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,6BAA6B,CAAC;IAC1E,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CAC3C,CAAC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/sandbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EACN,6BAA6B,EAC7B,+BAA+B,EAC/B,0BAA0B,GAC1B,MAAM,kCAAkC,CAAA;AASzC,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACxD,QAAQ,MAAM,EAAE,CAAC;QAChB,KAAK,UAAU,CAAC;QAChB,KAAK,OAAO,CAAC;QACb,KAAK,MAAM,CAAC;QACZ,KAAK,WAAW;YACf,OAAM;QACP,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,MAAM,CAAA;YACjC,MAAM,IAAI,KAAK,CAAC,0BAA0B,WAAW,EAAE,CAAC,CAAA;QACzD,CAAC;IACF,CAAC;AACF,CAAC;AAyBD,MAAM,CAAC,MAAM,0BAA0B,GAAuC;IAC7E,YAAY;IACZ,SAAS;IACT,SAAS;CACT,CAAA;AAKD,MAAM,UAAU,wBAAwB,CAAC,GAAuB;IAC/D,QAAQ,GAAG,EAAE,CAAC;QACb,KAAK,iBAAiB,CAAC;QACvB,KAAK,gBAAgB,CAAC;QACtB,KAAK,OAAO;YACX,OAAM;QACP,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,GAAG,CAAA;YAC9B,MAAM,IAAI,KAAK,CAAC,+BAA+B,WAAW,EAAE,CAAC,CAAA;QAC9D,CAAC;IACF,CAAC;AACF,CAAC;AA8UD,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACnC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IAC5C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,0BAA0B,CAAC;IACpE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,+BAA+B,CAAC;IAC7E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,6BAA6B,CAAC;IAC1E;;;;;;OAMG;IACH,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACnF,CAAC,CAAA"}

package/dist/types/structured-output/index.d.ts

@@ -12,12 +12,13 @@ export interface StructuredOutputConfig<TSchema extends z.ZodType = z.ZodType> {
      */
     schema: TSchema;
     /**
-     * Whether to force the model to use the structured_output tool.
-     * When true, sets tool_choice to force the tool.
-     * When false, the model may choose to call it or not.
-     * Default: true
+     * Turns spent re-prompting when the model answers in prose or fails
+     * validation. Defaults to {@link DEFAULT_STRUCTURED_OUTPUT_RETRIES}.
+     *
+     * Bounded so a model that cannot satisfy the schema fails loudly rather
+     * than iterating against `maxIterations`.
      */
-    enforceToolChoice?: boolean;
+    maxRetries?: number;
 }
 /**
  * Result from structured output tool execution.

package/dist/types/structured-output/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/structured-output/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB,CAAC,OAAO,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IAC5E;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAA;IAEf;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC,GAAG,OAAO;IAClD;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,CAAA;IAER;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/structured-output/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB,CAAC,OAAO,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IAC5E;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAA;IAEf;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC,GAAG,OAAO;IAClD;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,CAAA;IAER;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB"}

package/dist/types/thread/entity.d.ts

@@ -42,9 +42,8 @@ export type ThreadStatus = 'open' | 'archived';
  * - **Sessions are the immediate work unit.** A user or agent enters a
  *   Thread and opens/resumes Sessions for the concrete interval of work.
  *
- * This is the mental model ses_001 ratified (Phase 0, 2026-04-18). Industry
- * frameworks (OpenAI Responses, LangGraph, Claude Agent SDK, Temporal) do
- * not have an exact analogue for the Thread layer — it is Namzu's answer to
+ * This is the mental model ses_001 ratified (Phase 0, 2026-04-18). The
+ * Thread layer has no counterpart elsewhere — it is Namzu's answer to
  * the question "how do you expose a multi-session topic to A2A without
  * coupling it to the Project's filesystem identity?".
  *

package/dist/types/thread/entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/types/thread/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAE5D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,WAAW,MAAM;IACtB,EAAE,EAAE,QAAQ,CAAA;IACZ,SAAS,EAAE,SAAS,CAAA;IACpB,QAAQ,EAAE,QAAQ,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,YAAY,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CACf"}
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/types/thread/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAE5D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,WAAW,MAAM;IACtB,EAAE,EAAE,QAAQ,CAAA;IACZ,SAAS,EAAE,SAAS,CAAA;IACpB,QAAQ,EAAE,QAAQ,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,YAAY,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CACf"}

package/dist/types/tool/index.d.ts

@@ -12,14 +12,74 @@ export interface ToolRegistryRef {
 /**
  * Tracks which files the agent has read in the current run.
  * Write tool consults this to enforce the "read before overwrite" invariant
- * (Claude Code parity): an existing file must be read first or the write fails.
+ * an existing file must be read first or the write fails.
  * Keys are the resolved path used by the tool — sandbox-relative when a sandbox
  * is active, absolute (`workingDirectory`-resolved) otherwise.
  */
 export interface FileReadTracker {
-    recordRead(key: string): void;
+    /**
+     * `content` lets the tracker fingerprint what was read, which is what
+     * makes drift detectable later. Optional so a host that only needs the
+     * read-before-overwrite guard can keep its existing implementation.
+     */
+    recordRead(key: string, content?: string): void;
     hasRead(key: string): boolean;
+    /**
+     * Fingerprint of the body captured at the last read, when one was.
+     *
+     * A file mutation is computed against what the agent READ, and between
+     * that read and the write the file may have moved under it — a person
+     * editing in an editor, another process, a second agent. The in-process
+     * lock cannot see any of those. Comparing this against the body actually
+     * on disk at mutation time is what turns a silent lost update into a
+     * refusal the agent can act on by re-reading.
+     */
+    fingerprint?(key: string): string | undefined;
+}
+export interface ToolPauseOption {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
 }
+export interface ToolPauseRequest {
+    /**
+     * Names this pause within the call.
+     *
+     * A tool call may pause more than once — "which environment", then
+     * "are you sure" — and the answers have to be told apart. The name is
+     * what a resume payload is routed by, so it is the author's to choose
+     * and should describe the decision, not the tool.
+     */
+    readonly name: string;
+    /** The question, in the words the human will read. */
+    readonly prompt: string;
+    /** Short topic label, when the surface showing this has room for one. */
+    readonly header?: string;
+    readonly options?: readonly ToolPauseOption[];
+    readonly multiSelect?: boolean;
+    /** Defaults to true: a human who disagrees with every option can say so. */
+    readonly allowFreeText?: boolean;
+}
+/**
+ * How a pause ended.
+ *
+ * `unanswered` is deliberately not a variant of `answered` with an empty
+ * selection. A tool that pauses to ask "may I charge this card" and reads
+ * silence as yes is worse than one that never asked, so the absence of an
+ * answer has its own shape and cannot be destructured into consent by
+ * accident.
+ */
+export type ToolPauseOutcome = {
+    readonly status: 'answered';
+    readonly selectedOptionIds: readonly string[];
+    readonly text?: string;
+} | {
+    readonly status: 'unanswered';
+    readonly reason: string;
+} | {
+    readonly status: 'aborted';
+};
+export type RequestToolPause = (request: ToolPauseRequest) => Promise<ToolPauseOutcome>;
 export interface ToolContext {
     runId: RunId;
     workingDirectory: string;
@@ -45,12 +105,90 @@ export interface ToolContext {
      * Optional because not every executor path provides it yet.
      */
     toolUseId?: string;
+    /**
+     * Raise a durable pause and wait for a human to resolve it.
+     *
+     * The pause machinery is excellent and was reachable from exactly four
+     * kernel-owned points — the plan gate, the tool-review gate, the
+     * iteration cadence, and one built-in question tool. A host-authored
+     * tool had no seam to it, so the operations that most want their own
+     * confirmation with their own wording (a spend, an outbound post, a
+     * destructive migration) had to settle for the generic tool-review
+     * gate or hand-thread a recorder and a resume callback into a private
+     * builder, which nothing in this type suggested was possible.
+     *
+     * The park is a real checkpoint, so a host can see the pause on every
+     * surface a tool-review park appears on, and the answer routes back by
+     * name on resume — several tools pausing in one batch each get their
+     * own, and one tool may pause more than once.
+     *
+     * Absent when whatever is driving the tool provides no route to a
+     * human — a host calling a tool directly, outside a run. A tool must
+     * treat it as optional and decide what to do without one, and must
+     * never read an unanswered pause as consent; the outcome says which it
+     * was, in its own shape, so silence cannot be destructured into a yes.
+     */
+    requestPause?: RequestToolPause;
+    /**
+     * Span to parent this tool's `execute_tool` span to.
+     *
+     * OTel's GenAI conventions define a strict hierarchy —
+     * `invoke_agent` → `chat {model}` → `execute_tool` — and vendor
+     * dashboards rely on it. `startActiveSpan` cannot supply the parent
+     * here: the span-owning bodies upstream are async GENERATORS, and a
+     * generator resumes on its consumer's async context, so the ambient
+     * context is already gone by the time a tool runs. Passing the parent
+     * explicitly is the only approach that actually works, and
+     * `ToolContext` is already threaded to exactly the right place.
+     */
+    parentSpan?: import('@opentelemetry/api').Span;
+    /**
+     * Say how far along you are, for a host rendering a live view.
+     *
+     * A tool may run for the full per-tool deadline — two minutes by
+     * default — and before this it was silent for all of it: a host could
+     * show that a build had started and then nothing until it finished or
+     * timed out.
+     *
+     * Fire-and-forget and never throws, so a tool can call it freely
+     * without wrapping it. The model never sees these: progress answers
+     * "is it still working?", which is a question only a human asks, and
+     * putting it in the conversation would spend tokens telling the model
+     * something it cannot act on.
+     *
+     * Absent when the executing surface has no event stream to write to.
+     */
+    report?: (message: string, fraction?: number) => void;
 }
 export interface ToolResult {
     success: boolean;
     output: string;
     data?: unknown;
     error?: string;
+    /**
+     * Rich content for the MODEL, when a string cannot carry it — a
+     * screenshot, a chart, a PDF. `output` stays the text the host and the
+     * transcript see; when this is set it is what reaches the provider.
+     *
+     * Keeping the two separate is deliberate: a host UI wants "screenshot
+     * (1280x800)", the model wants the pixels, and forcing one channel to
+     * serve both is what made `computer-use` send megabytes of base64 as
+     * text.
+     */
+    content?: import('../message/index.js').ToolResultContent;
+    /**
+     * This failure might succeed if tried again — a network blip, a lock
+     * contention, a rate limit — as opposed to one that never will, like a
+     * missing file or a rejected argument.
+     *
+     * Nothing distinguished the two before, so a transient failure cost a
+     * full model round trip to retry: the error went back as a
+     * `tool_result`, the model read it, and decided (or didn't) to call
+     * again. Only meaningful alongside {@link ToolDefinition.maxRetries};
+     * a tool that has not opted into retries is never retried no matter
+     * what it sets here.
+     */
+    retryable?: boolean;
 }
 export interface ToolDefinition<TInput = unknown> {
     name: string;
@@ -76,10 +214,79 @@ export interface ToolDefinition<TInput = unknown> {
      * cannot be reconstructed from JSON Schema's top-level `required` list.
      */
     validationErrorHint?: string;
+    /**
+     * The shape this tool returns, as JSON Schema, appended to the
+     * description the model sees.
+     *
+     * JSON Schema rather than Zod because it is **shown, never validated**:
+     * namzu does not check a tool's return value against it, so converting
+     * through Zod would only cost fidelity. Native tools that want one can
+     * render their Zod type with `renderToolSchema`.
+     *
+     * Optional and omitted by default — a tool whose return shape is
+     * obvious from its description gains nothing from spending prompt on
+     * it, and every tool schema rides in the cached prefix of every
+     * request.
+     */
+    outputSchema?: Record<string, unknown>;
     execute(input: TInput, context: ToolContext): Promise<ToolResult>;
     tier?: string;
     permissions?: ToolPermission[];
     category?: 'filesystem' | 'shell' | 'network' | 'analysis' | 'custom';
+    /**
+     * Deadline for a single execution, overriding the run-level default.
+     *
+     * On expiry the executor stops waiting and returns a model-visible
+     * error result, so a slow dependency becomes something the agent can
+     * route around instead of a turn that never comes back. The tool's
+     * `context.abortSignal` fires at the same moment; a tool that honours
+     * it also stops doing work, and one that ignores it merely becomes
+     * detached.
+     *
+     * Omit to inherit the executor's default.
+     */
+    timeoutMs?: number;
+    /**
+     * How many times a FAILED execution may be retried in-loop before the
+     * error is handed to the model.
+     *
+     * **Defaults to 0, and that default is load-bearing.** Retrying is only
+     * safe if the tool is idempotent, and the SDK cannot know that: silently
+     * re-running a `write_file`, a `git push` or a payment call is worse
+     * than never retrying at all. The tool author opts in, per tool.
+     *
+     * Even then, only failures the tool marked
+     * {@link ToolResult.retryable} are retried — a missing file is not
+     * going to appear on the second attempt, and burning the budget on it
+     * just delays the error the model needs to see.
+     */
+    maxRetries?: number;
+    /**
+     * This tool's output IS the run's answer: settle with it instead of
+     * asking the model to restate it.
+     *
+     * Every delegation path is blocking and returns the worker's final
+     * text as the dispatching call's result, after which the loop went
+     * round again — so a router agent, whose entire job is to pick a
+     * specialist, paid one extra model call per request at the parent's
+     * full context size, the most expensive call in the run. The relay is
+     * also LOSSY: the parent paraphrases the worker's answer through its
+     * own (compacted) context, so what the caller receives is not what the
+     * worker produced.
+     *
+     * Honoured only when the terminal call is the ONLY call in the turn
+     * and it did not fail. A model that asked for other work in the same
+     * turn meant to see those results, and ending the run would discard
+     * answers it requested; that turn takes the ordinary path and the
+     * reason is logged. A failed terminal call is not an answer either —
+     * the error goes back to the model, which is the point of returning
+     * errors to it at all.
+     *
+     * Off by default. The generic case is `structured_output`, which the
+     * runtime has always settled on; this is that rule made available to
+     * any tool.
+     */
+    terminal?: boolean;
     isReadOnly?(input: TInput): boolean;
     isDestructive?(input: TInput): boolean;
     isConcurrencySafe?(input: TInput): boolean;
@@ -144,4 +351,5 @@ export interface ToolRegistryContract {
     toTierGuidance(): string | null;
     assignTiers(mapping: Record<string, string>): void;
 }
+export * from './repair.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/tool/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/tool/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/tool/index.ts"],"names":[],"mappings":"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"}

package/dist/types/tool/index.js

@@ -1,2 +1,2 @@
-export {};
+export * from './repair.js';
 //# sourceMappingURL=index.js.map

package/dist/types/tool/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/tool/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/tool/index.ts"],"names":[],"mappings":"AAyYA,cAAc,aAAa,CAAA"}

package/dist/types/tool/repair.d.ts

@@ -0,0 +1,49 @@
+import type { ToolCall } from '../message/index.js';
+import type { ToolDefinition } from './index.js';
+/**
+ * Why a tool call could not be executed as issued.
+ *
+ * `invalid_json` — the arguments string is not parseable JSON at all,
+ *   typically a truncated stream or an unescaped quote.
+ * `schema_validation` — the JSON parsed but does not satisfy the tool's
+ *   schema: a missing required field, a string where a number belongs.
+ * `unknown_tool` — the model named a tool that is not registered, usually
+ *   a near-miss on a real name.
+ */
+export type ToolCallRepairReason = 'invalid_json' | 'schema_validation' | 'unknown_tool';
+export interface ToolCallRepairContext {
+    /** The call as the model issued it, arguments still raw. */
+    readonly toolCall: ToolCall;
+    readonly reason: ToolCallRepairReason;
+    /** The error the model would otherwise have been shown. */
+    readonly message: string;
+    /** The target tool. Absent for `unknown_tool`. */
+    readonly tool?: ToolDefinition;
+    /** The tool's JSON Schema, so a repair model has something to aim at. */
+    readonly jsonSchema?: Record<string, unknown>;
+    /** Every registered tool name — the useful context for `unknown_tool`. */
+    readonly availableTools: readonly string[];
+}
+/**
+ * Fix a tool call the model got wrong, before the error reaches it.
+ *
+ * A malformed call used to cost a full round trip: the error went back as
+ * a `tool_result`, the model read it, and tried again — a second inference
+ * on the entire context to fix a missing brace. A host that can repair the
+ * arguments locally (a cheap model with the schema, or plain string
+ * surgery) turns that into nothing.
+ *
+ * Return the corrected call, or `null` to decline — declining is not a
+ * failure, it just means the original error proceeds to the model as
+ * before. Deliberately narrow: a repair may rewrite the ARGUMENTS and the
+ * tool NAME, and nothing else. It cannot invent a call the model never
+ * made, and it cannot suppress one.
+ */
+export type RepairToolCall = (context: ToolCallRepairContext) => Promise<ToolCallRepair | null> | ToolCallRepair | null;
+export interface ToolCallRepair {
+    /** Corrected arguments, as a JSON string. */
+    readonly arguments: string;
+    /** Corrected tool name. Omit to keep the one the model used. */
+    readonly toolName?: string;
+}
+//# sourceMappingURL=repair.d.ts.map

package/dist/types/tool/repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair.d.ts","sourceRoot":"","sources":["../../../src/types/tool/repair.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,mBAAmB,GAAG,cAAc,CAAA;AAExF,MAAM,WAAW,qBAAqB;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;IACrC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,CAAA;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7C,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1C;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GAAG,CAC5B,OAAO,EAAE,qBAAqB,KAC1B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,cAAc,GAAG,IAAI,CAAA;AAE3D,MAAM,WAAW,cAAc;IAC9B,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC1B"}

package/dist/types/tool/repair.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=repair.js.map

package/dist/types/tool/repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair.js","sourceRoot":"","sources":["../../../src/types/tool/repair.ts"],"names":[],"mappings":""}