@pivanov/claude-wire 0.0.3 → 0.1.0

package/dist/session.js

@@ -1,53 +1,104 @@
-import { LIMITS, RESPAWN_BACKOFF_MS, TIMEOUTS } from "./constants.js";
+import { withTimeout } from "./async.js";
+import { LIMITS, MAX_BACKOFF_INDEX, RESPAWN_BACKOFF_MS, TIMEOUTS } from "./constants.js";
 import { createCostTracker } from "./cost.js";
-import { AbortError, BudgetExceededError, ClaudeError, isTransientError, KnownError, ProcessError, TimeoutError } from "./errors.js";
+import { AbortError, BudgetExceededError, ClaudeError, isTransientError, KnownError, processExitedEarly, TimeoutError } from "./errors.js";
+import { parseAndValidate } from "./json.js";
 import { createTranslator } from "./parser/translator.js";
-import { buildResult } from "./pipeline.js";
-import { spawnClaude } from "./process.js";
-import { drainStderr, readNdjsonEvents } from "./reader.js";
+import { applyTurnComplete, buildResult, startPipeline } from "./pipeline.js";
+import { safeKill, safeWrite } from "./process.js";
+import { readNdjsonEvents } from "./reader.js";
 import { createToolHandler } from "./tools/handler.js";
 import { writer } from "./writer.js";
-const gracefulKill = async (p) => {
-    p.kill();
-    let timer;
-    let timedOut = false;
+// Two-stage termination: SIGTERM first, escalate to SIGKILL after the
+// graceful-exit timeout. A stuck child (e.g. blocked on a syscall that
+// ignores SIGTERM) would otherwise survive the "graceful" path and leak.
+// The sentinel value distinguishes "exited on time" from "timeout fired"
+// without a side-channel boolean.
+// Compose two optional AbortSignals into one. If either fires, the
+// returned signal aborts. Returns undefined when both inputs are undefined.
+const composeSignals = (a, b) => {
+    if (!a && !b) {
+        return undefined;
+    }
+    if (!a) {
+        return b;
+    }
+    if (!b) {
+        return a;
+    }
+    const ctrl = new AbortController();
+    const abort = () => ctrl.abort();
+    a.addEventListener("abort", abort, { once: true });
+    b.addEventListener("abort", abort, { once: true });
+    if (a.aborted || b.aborted) {
+        ctrl.abort();
+    }
+    return ctrl.signal;
+};
+// Fire both session-level and per-ask onRetry, swallowing throws from either.
+const fireRetry = (attempt, error, sessionLevel, askLevel) => {
     try {
-        await Promise.race([
-            p.exited,
-            new Promise((r) => {
-                timer = setTimeout(() => {
-                    timedOut = true;
-                    r();
-                }, TIMEOUTS.gracefulExitMs);
-            }),
-        ]);
+        sessionLevel?.(attempt, error);
     }
-    finally {
-        if (timer) {
-            clearTimeout(timer);
-        }
+    catch {
+        // observer threw -- retry still happens
     }
-    if (timedOut) {
-        try {
-            p.kill();
-        }
-        catch {
-            // already dead
-        }
+    try {
+        askLevel?.(attempt, error);
+    }
+    catch {
+        // observer threw -- retry still happens
     }
 };
+const KILL_TIMED_OUT = Symbol("kill-timed-out");
+const gracefulKill = async (p) => {
+    safeKill(p, "SIGTERM");
+    const outcome = await withTimeout(p.exited, TIMEOUTS.gracefulExitMs, () => KILL_TIMED_OUT);
+    if (outcome === KILL_TIMED_OUT) {
+        safeKill(p, "SIGKILL");
+    }
+};
+/**
+ * Creates a multi-turn Claude session backed by a single long-lived CLI
+ * process. Each `ask()` sends a user prompt and resolves with `TAskResult`
+ * for that turn. Calls are serialized -- a second `ask()` waits for the
+ * first to complete. Use `close()` (or `await using`) to free the process.
+ *
+ * ### Retry behavior
+ * Each `ask()` automatically retries transient failures -- process crashes
+ * matching SIGKILL/SIGTERM/SIGPIPE exit codes, `ECONNRESET`, `ECONNREFUSED`,
+ * `ETIMEDOUT`, `EHOSTUNREACH`, `ENETUNREACH`, `EAI_AGAIN`, Anthropic
+ * `overloaded_error` / 529s, broken-pipe / "socket hang up" messages, etc.
+ * (see `isTransientError`). Backoff is `500ms → 1s → 2s`; the budget is
+ * `LIMITS.maxRespawnAttempts` (currently 3) and is shared across a single
+ * `ask()`. When the budget is exhausted the session throws
+ * `KnownError("retry-exhausted")` and marks itself closed.
+ *
+ * Fatal errors -- `KnownError` and `BudgetExceededError` -- also close the
+ * session. Any subsequent `ask()` on a closed session rejects with
+ * `ClaudeError("Session is closed")`. All other errors (abort, timeout,
+ * non-transient `ProcessError`) propagate without closing, and the caller
+ * may decide whether to retry at a higher level.
+ *
+ * ### Observability
+ * - `onCostUpdate(snapshot)` -- fires after every `turn_complete`.
+ * - `onRetry(attempt, error)` -- fires each time a transient failure triggers
+ *   a respawn inside one `ask()`. Attempt is 1-indexed.
+ * - `onWarning(message, cause)` -- routes all library-emitted warnings.
+ */
 export const createSession = (options = {}) => {
     let proc;
     let currentSessionId;
     let consecutiveCrashes = 0;
     let turnCount = 0;
-    let costOffsets = { totalUsd: 0, inputTokens: 0, outputTokens: 0 };
+    let costOffsets = { totalUsd: 0, tokens: { input: 0, output: 0 } };
     const translator = createTranslator();
     const costTracker = createCostTracker({
         maxCostUsd: options.maxCostUsd,
         onCostUpdate: options.onCostUpdate,
+        onWarning: options.onWarning,
     });
-    const toolHandler = options.tools ? createToolHandler(options.tools) : undefined;
+    const toolHandler = options.toolHandler ? createToolHandler(options.toolHandler) : undefined;
     let inFlight;
     let reader;
     const cleanupProcess = () => {
@@ -61,9 +112,11 @@ export const createSession = (options = {}) => {
         }
         reader = undefined;
     };
-    let lastStderrChunks = [];
-    let lastDrainDone;
-    const getStderrText = () => lastStderrChunks.join("").trim();
+    // Drain handle from the most recent spawn. Stored as a whole so we
+    // can call `.text()` (shared helper on IStderrDrain) instead of
+    // reimplementing chunks.join/trim at every use site.
+    let lastStderrDrain;
+    const getStderrText = () => lastStderrDrain?.text() ?? "";
     const killProc = () => {
         if (proc) {
             proc.kill();
@@ -75,20 +128,27 @@ export const createSession = (options = {}) => {
     const spawnFresh = (prompt, resumeId) => {
         if (consecutiveCrashes >= LIMITS.maxRespawnAttempts) {
             killProc();
-            throw new ProcessError(`Process crashed ${consecutiveCrashes} times, giving up`);
+            // Typed code so consumers can pattern-match on
+            // `KnownError && err.code === "retry-exhausted"` without parsing strings.
+            throw new KnownError("retry-exhausted", `Process crashed ${consecutiveCrashes} times, giving up`);
         }
         costOffsets = costTracker.snapshot();
         killProc();
         translator.reset();
+        // Respawn always overrides caller-supplied options.resume with the live
+        // session id when one is available: mid-session recovery must resume the
+        // same conversation, not whatever static id was passed at construction.
         const spawnOpts = resumeId ? { prompt, ...options, resume: resumeId } : { prompt, ...options };
-        proc = spawnClaude(spawnOpts);
-        reader = proc.stdout.getReader();
-        const drain = drainStderr(proc);
-        lastStderrChunks = drain.chunks;
-        lastDrainDone = drain.done;
+        const pipeline = startPipeline(spawnOpts);
+        proc = pipeline.proc;
+        reader = pipeline.reader;
+        lastStderrDrain = pipeline.stderr;
     };
     const respawnBackoff = async () => {
-        const idx = Math.min(consecutiveCrashes, RESPAWN_BACKOFF_MS.length) - 1;
+        // consecutiveCrashes starts at 1 for the first retry; idx points
+        // into RESPAWN_BACKOFF_MS and clamps to the last defined entry for
+        // any crash count beyond the table length.
+        const idx = Math.min(consecutiveCrashes, MAX_BACKOFF_INDEX) - 1;
         const delay = idx >= 0 ? RESPAWN_BACKOFF_MS[idx] : 0;
         if (delay) {
             await new Promise((r) => setTimeout(r, delay));
@@ -106,14 +166,14 @@ export const createSession = (options = {}) => {
             toolHandler,
             proc,
             signal,
+            onWarning: options.onWarning,
         })) {
             if (event.type === "session_meta") {
                 currentSessionId = event.sessionId;
             }
             events.push(event);
             if (event.type === "turn_complete") {
-                costTracker.update(costOffsets.totalUsd + (event.costUsd ?? 0), costOffsets.inputTokens + (event.inputTokens ?? 0), costOffsets.outputTokens + (event.outputTokens ?? 0));
-                costTracker.checkBudget();
+                applyTurnComplete(event, costTracker, costOffsets);
                 gotTurnComplete = true;
                 break;
             }
@@ -122,46 +182,49 @@ export const createSession = (options = {}) => {
             if (signal?.aborted) {
                 throw new AbortError();
             }
-            // stdout closed → process is dying. Race `exited` against a short
-            // timeout so a zombie/unreaped child doesn't hang us. If exited doesn't
-            // resolve in time we leave exitCode undefined (→ non-transient).
+            // stdout closed → process is dying. Wait briefly for exited so we
+            // can attach an exit code to the error; if it doesn't resolve in
+            // time, force-kill and leave exitCode undefined (→ non-transient).
             let exitCode;
             if (proc) {
                 const live = proc;
-                exitCode = await Promise.race([
-                    live.exited,
-                    new Promise((r) => setTimeout(() => r(undefined), TIMEOUTS.gracefulExitMs)),
-                ]);
+                exitCode = await withTimeout(live.exited, TIMEOUTS.gracefulExitMs);
                 if (exitCode === undefined) {
                     live.kill();
                 }
             }
-            if (lastDrainDone) {
-                await Promise.race([lastDrainDone, new Promise((r) => setTimeout(r, 500))]);
+            if (lastStderrDrain) {
+                await withTimeout(lastStderrDrain.done, TIMEOUTS.stderrDrainGraceMs);
             }
-            const stderrMsg = getStderrText();
-            throw new ProcessError(stderrMsg || "Process exited without completing the turn", exitCode);
+            throw processExitedEarly(getStderrText(), exitCode);
         }
         return events;
     };
-    const doAsk = async (prompt) => {
+    const doAsk = async (prompt, askOpts) => {
         if (!proc) {
             spawnFresh(prompt, currentSessionId);
         }
-        else {
+        else if (!safeWrite(proc, writer.user(prompt))) {
+            // stdin write failed -- process probably died. Try to respawn.
+            // spawnFresh can itself throw ProcessError synchronously when the
+            // respawn cap is already hit; surface as an Error like the retry
+            // loop below would, instead of a raw synchronous throw.
+            consecutiveCrashes++;
+            translator.reset();
             try {
-                proc.write(writer.user(prompt));
-            }
-            catch {
-                consecutiveCrashes++;
-                translator.reset();
                 spawnFresh(prompt, currentSessionId);
             }
+            catch (respawnError) {
+                killProc();
+                throw respawnError;
+            }
         }
+        // Compose per-ask signal with session-level signal: either firing aborts.
+        const effectiveSignal = composeSignals(options.signal, askOpts?.signal);
         let events;
         while (true) {
             try {
-                events = await readUntilTurnComplete(options.signal);
+                events = await readUntilTurnComplete(effectiveSignal);
                 break;
             }
             catch (error) {
@@ -175,6 +238,9 @@ export const createSession = (options = {}) => {
                     throw error;
                 }
                 consecutiveCrashes++;
+                // Fire both session-level and per-ask onRetry. Both are safe-invoked
+                // so a throwing observer doesn't prevent the retry.
+                fireRetry(consecutiveCrashes, error, options.onRetry, askOpts?.onRetry);
                 await respawnBackoff();
                 spawnFresh(prompt, currentSessionId);
                 // Loop to retry; stops when budget exhausted or turn completes.
@@ -194,7 +260,7 @@ export const createSession = (options = {}) => {
         return buildResult(events, costTracker, currentSessionId);
     };
     let closed = false;
-    const ask = (prompt) => {
+    const ask = (prompt, askOpts) => {
         if (closed) {
             return Promise.reject(new ClaudeError("Session is closed"));
         }
@@ -209,7 +275,7 @@ export const createSession = (options = {}) => {
             if (closed) {
                 throw new ClaudeError("Session is closed");
             }
-            return doAsk(prompt);
+            return doAsk(prompt, askOpts);
         })
             .catch((error) => {
             if (error instanceof KnownError || error instanceof BudgetExceededError) {
@@ -225,23 +291,24 @@ export const createSession = (options = {}) => {
         if (inFlight) {
             // Cap the wait: a stuck reader.read() inside the queued ask would
             // otherwise hang close() forever before gracefulKill gets a chance.
-            await Promise.race([inFlight.catch(() => { }), new Promise((r) => setTimeout(r, TIMEOUTS.gracefulExitMs))]);
+            await withTimeout(inFlight.catch(() => { }), TIMEOUTS.gracefulExitMs);
             inFlight = undefined;
         }
         if (proc) {
-            try {
-                proc.write(writer.abort());
-            }
-            catch {
-                // stdin may already be closed
-            }
+            safeWrite(proc, writer.abort());
             await gracefulKill(proc);
             proc = undefined;
         }
         cleanupProcess();
     };
+    const askJson = async (prompt, schema, askOpts) => {
+        const raw = await ask(prompt, askOpts);
+        const data = parseAndValidate(raw.text, schema);
+        return { data, raw };
+    };
     return {
         ask,
+        askJson,
         close,
         get sessionId() {
             return currentSessionId;

package/dist/stderr.d.ts

@@ -0,0 +1,10 @@
+import type { TKnownErrorCode } from "./errors.js";
+/**
+ * Attempts to classify an opaque stderr string into a typed `TKnownErrorCode`.
+ * Returns `undefined` when no pattern matches -- the caller should keep the
+ * original `ProcessError` as-is in that case.
+ *
+ * The exit code is accepted but not currently used (all classification is
+ * text-based). Reserved for future exit-code-specific rules.
+ */
+export declare const classifyStderr: (stderr: string, _exitCode?: number) => TKnownErrorCode | undefined;

package/dist/stderr.js

@@ -0,0 +1,31 @@
+// Conservative pattern table for classifying CLI stderr into typed error
+// codes. Intentionally small -- false classification is worse than no
+// classification. Documented as "may drift across CLI versions."
+//
+// Each entry: [pattern to test against stderr text, resulting code].
+const STDERR_PATTERNS = [
+    [/rate[_ -]?limit|429|too many requests/i, "rate-limit"],
+    [/overloaded|529|temporarily unavailable/i, "overloaded"],
+    [/context[_ -]?length|context[_ -]?window|too long|maximum.*tokens/i, "context-length-exceeded"],
+    [/invalid.*json[_ -]?schema|schema.*invalid|json.*schema.*error/i, "invalid-json-schema"],
+    [/mcp.*error|mcp.*fail|mcp.*server/i, "mcp-error"],
+    [/not authenticated|authentication|unauthorized|401/i, "not-authenticated"],
+    [/permission denied|forbidden|403/i, "permission-denied"],
+    [/binary.*not found|command not found|ENOENT.*claude/i, "binary-not-found"],
+];
+/**
+ * Attempts to classify an opaque stderr string into a typed `TKnownErrorCode`.
+ * Returns `undefined` when no pattern matches -- the caller should keep the
+ * original `ProcessError` as-is in that case.
+ *
+ * The exit code is accepted but not currently used (all classification is
+ * text-based). Reserved for future exit-code-specific rules.
+ */
+export const classifyStderr = (stderr, _exitCode) => {
+    for (const [pattern, code] of STDERR_PATTERNS) {
+        if (pattern.test(stderr)) {
+            return code;
+        }
+    }
+    return undefined;
+};

package/dist/stream.js

@@ -1,68 +1,99 @@
+import { withTimeout } from "./async.js";
+import { TIMEOUTS } from "./constants.js";
 import { createCostTracker } from "./cost.js";
-import { AbortError, ClaudeError, ProcessError } from "./errors.js";
+import { AbortError, ClaudeError, ProcessError, processExitedEarly } from "./errors.js";
 import { createTranslator } from "./parser/translator.js";
-import { buildResult, extractText } from "./pipeline.js";
-import { spawnClaude } from "./process.js";
-import { drainStderr, readNdjsonEvents } from "./reader.js";
+import { applyTurnComplete, buildResult, extractText, startPipeline } from "./pipeline.js";
+import { readNdjsonEvents } from "./reader.js";
 import { createToolHandler } from "./tools/handler.js";
+// Enforced exclusivity between iterating the stream and consuming via
+// text()/cost()/result(). Sharing the base message keeps the two throw
+// sites from drifting apart over time.
+const MIX_ITER_CONSUME = "Cannot mix for-await iteration with text()/cost()/result() on the same stream -- use one or the other.";
 export const createStream = (prompt, options = {}) => {
-    if (options.signal?.aborted) {
-        throw new AbortError();
-    }
+    // Abort check happens inside `ensureSpawned` -- at factory time we only
+    // capture config. A pre-aborted signal surfaces on the first access
+    // (iterate / text / cost / result), which is when spawn would happen.
     const translator = createTranslator();
-    const toolHandler = options.tools ? createToolHandler(options.tools) : undefined;
+    const toolHandler = options.toolHandler ? createToolHandler(options.toolHandler) : undefined;
     const costTracker = createCostTracker({
         maxCostUsd: options.maxCostUsd,
         onCostUpdate: options.onCostUpdate,
+        onWarning: options.onWarning,
     });
     let proc;
     let stderr;
+    let stdoutReader;
     let cachedGenerator;
     const ensureSpawned = () => {
         if (!proc) {
             if (options.signal?.aborted) {
                 throw new AbortError();
             }
-            proc = spawnClaude({ prompt, ...options });
-            stderr = drainStderr(proc);
+            // Shared boot: spawnClaude → getReader → drainStderr in one call.
+            // Matches session.ts so future refactors can't let the two drift.
+            const pipeline = startPipeline({ prompt, ...options });
+            proc = pipeline.proc;
+            stdoutReader = pipeline.reader;
+            stderr = pipeline.stderr;
         }
         return proc;
     };
     const generate = async function* () {
         const p = ensureSpawned();
-        const stdoutReader = p.stdout.getReader();
+        // ensureSpawned always populates stdoutReader alongside proc. Typed
+        // assertion so consumers can treat it as non-null below.
+        const currentReader = stdoutReader;
         let turnComplete = false;
         try {
             for await (const event of readNdjsonEvents({
-                reader: stdoutReader,
+                reader: currentReader,
                 translator,
                 toolHandler,
                 proc: p,
                 signal: options.signal,
+                onWarning: options.onWarning,
             })) {
                 if (event.type === "turn_complete") {
-                    costTracker.update(event.costUsd ?? 0, event.inputTokens ?? 0, event.outputTokens ?? 0);
-                    costTracker.checkBudget();
+                    applyTurnComplete(event, costTracker);
                     turnComplete = true;
                 }
                 yield event;
             }
             if (!turnComplete) {
-                const exitCode = await p.exited;
+                // Don't wait forever on p.exited -- a stuck child that never closes
+                // stdout would hang the generator. Cap at gracefulExitMs, then
+                // force-kill so cleanup() isn't left waiting too.
+                const exitCode = await withTimeout(p.exited, TIMEOUTS.gracefulExitMs);
+                if (exitCode === undefined) {
+                    p.kill();
+                }
+                // Give stderr a brief chance to drain so the thrown error carries
+                // the CLI's actual complaint instead of an empty string. Uniform
+                // across all three branches below so users never get "no context".
+                if (stderr) {
+                    await withTimeout(stderr.done, TIMEOUTS.stderrDrainGraceMs);
+                }
+                const stderrText = stderr ? stderr.text() : "";
+                if (exitCode === undefined) {
+                    throw processExitedEarly(stderrText);
+                }
                 if (exitCode !== 0) {
-                    if (stderr) {
-                        await stderr.done;
-                    }
-                    const stderrText = stderr ? stderr.chunks.join("").trim() : "";
                     const exitMsg = stderrText || `Claude process exited with code ${exitCode}`;
                     throw new ProcessError(exitMsg, exitCode);
                 }
-                throw new ProcessError("Process exited without completing the turn");
+                throw processExitedEarly(stderrText);
             }
         }
         finally {
-            stdoutReader.releaseLock();
+            currentReader.releaseLock();
             p.kill();
+            // Let stderr catch up so any trailing lines aren't silently dropped --
+            // session's error path does the same via withTimeout. Capped so a
+            // stuck drain can't hold up consumer cleanup.
+            if (stderr) {
+                await withTimeout(stderr.done, TIMEOUTS.stderrDrainGraceMs);
+            }
         }
     };
     const bufferedEvents = [];
@@ -70,7 +101,7 @@ export const createStream = (prompt, options = {}) => {
     const ensureConsumed = () => {
         if (!consumePromise) {
             if (cachedGenerator) {
-                throw new ClaudeError("Cannot call text()/cost()/result() after iterating with for-await. Use one or the other.");
+                throw new ClaudeError(MIX_ITER_CONSUME);
             }
             const gen = generate();
             cachedGenerator = gen;
@@ -96,9 +127,13 @@ export const createStream = (prompt, options = {}) => {
         return buildResult(bufferedEvents, costTracker, sessionId);
     };
     const cleanup = () => {
-        // Always kill if a proc was ever spawned — the generator's finally may not
-        // have run yet (e.g., iterator created but never ticked). Redundant kill
-        // on an already-exited process is a harmless ESRCH.
+        // One-shot kill: streams are single-turn, so unlike session.gracefulKill
+        // there's no second ask() to worry about leaving the child stranded for.
+        // SIGTERM is sufficient -- a stuck child would be the CLI's bug, and we
+        // wouldn't gain anything by blocking cleanup() on a SIGKILL escalation.
+        // Always kill if a proc was ever spawned -- the generator's finally may
+        // not have run yet (e.g., iterator created but never ticked). Redundant
+        // kill on an already-exited process is a harmless ESRCH.
         if (proc) {
             proc.kill();
         }
@@ -106,7 +141,7 @@ export const createStream = (prompt, options = {}) => {
     return {
         [Symbol.asyncIterator]: () => {
             if (consumePromise) {
-                throw new ClaudeError("Cannot iterate after calling text()/cost()/result(). Use one or the other.");
+                throw new ClaudeError(MIX_ITER_CONSUME);
             }
             cachedGenerator ??= generate();
             return cachedGenerator;

package/dist/tools/handler.d.ts

@@ -2,6 +2,7 @@ import type { TToolUseEvent } from "../types/events.js";
 import type { IToolHandler } from "../types/options.js";
 export type TToolDecision = "approve" | "deny" | {
     result: string;
+    isError?: boolean;
 };
 export interface IToolHandlerInstance {
     decide: (tool: TToolUseEvent) => Promise<TToolDecision>;

package/dist/tools/registry.d.ts

@@ -1,2 +1,4 @@
-export declare const BUILT_IN_TOOLS: Set<string>;
-export declare const isBuiltInTool: (name: string) => boolean;
+export declare const BUILT_IN_TOOL_NAMES: readonly ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Agent", "NotebookEdit", "WebFetch", "WebSearch", "TaskCreate", "TaskUpdate", "TaskGet", "TaskList", "TaskStop", "TaskOutput", "ToolSearch", "Monitor", "EnterPlanMode", "ExitPlanMode", "SendMessage", "LSP", "AskUserQuestion", "Skill", "CronCreate", "CronDelete", "CronList", "RemoteTrigger", "TeamCreate", "TeamDelete", "EnterWorktree", "ExitWorktree", "ScheduleWakeup"];
+export type TBuiltInToolName = (typeof BUILT_IN_TOOL_NAMES)[number];
+export declare const BUILT_IN_TOOLS: ReadonlySet<TBuiltInToolName>;
+export declare const isBuiltInTool: (name: string) => name is TBuiltInToolName;

package/dist/tools/registry.js

@@ -1,6 +1,10 @@
 // Best-effort snapshot of known Claude Code tools. May not be exhaustive.
 // For the authoritative list, check session_meta.tools from a live session.
-export const BUILT_IN_TOOLS = new Set([
+//
+// Declared as a literal tuple so `TBuiltInToolName` is the exact union of
+// known names -- lets callers narrow `allowedTools` / `disallowedTools`
+// arrays at compile time instead of accepting any string[].
+export const BUILT_IN_TOOL_NAMES = [
     "Read",
     "Write",
     "Edit",
@@ -11,8 +15,6 @@ export const BUILT_IN_TOOLS = new Set([
     "NotebookEdit",
     "WebFetch",
     "WebSearch",
-    "TodoRead",
-    "TodoWrite",
     "TaskCreate",
     "TaskUpdate",
     "TaskGet",
@@ -36,7 +38,8 @@ export const BUILT_IN_TOOLS = new Set([
     "EnterWorktree",
     "ExitWorktree",
     "ScheduleWakeup",
-]);
+];
+export const BUILT_IN_TOOLS = new Set(BUILT_IN_TOOL_NAMES);
 export const isBuiltInTool = (name) => {
     return BUILT_IN_TOOLS.has(name);
 };

package/dist/types/events.d.ts

@@ -10,7 +10,7 @@ export type TToolUseEvent = {
     type: "tool_use";
     toolUseId: string;
     toolName: string;
-    input: string;
+    input: unknown;
 };
 export type TToolResultEvent = {
     type: "tool_result";

package/dist/types/options.d.ts

@@ -1,9 +1,11 @@
 import type { TToolDecision } from "../tools/handler.js";
+import type { TBuiltInToolName } from "../tools/registry.js";
 import type { TToolUseEvent } from "./events.js";
 import type { TCostSnapshot } from "./results.js";
+export type TToolName = TBuiltInToolName | (string & {});
 export interface IToolHandler {
-    allowed?: string[];
-    blocked?: string[];
+    allowed?: TToolName[];
+    blocked?: TToolName[];
     onToolUse?: (tool: TToolUseEvent) => Promise<TToolDecision>;
     onError?: (error: unknown, tool: TToolUseEvent) => TToolDecision | Promise<TToolDecision>;
 }
@@ -12,9 +14,9 @@ export interface IClaudeOptions {
     model?: "opus" | "sonnet" | "haiku" | (string & {});
     systemPrompt?: string;
     appendSystemPrompt?: string;
-    allowedTools?: string[];
-    disallowedTools?: string[];
-    tools?: IToolHandler;
+    allowedTools?: TToolName[];
+    disallowedTools?: TToolName[];
+    toolHandler?: IToolHandler;
     /**
      * SDK-side budget limit, evaluated after each turn. Throws `BudgetExceededError`
      * and kills the process when `total_cost_usd` exceeds this value. `0` means
@@ -45,8 +47,43 @@ export interface IClaudeOptions {
     forkSession?: boolean;
     noSessionPersistence?: boolean;
     sessionId?: string;
-    settingSources?: string;
+    settingSources?: "project" | "user" | "local" | "all" | "" | (string & {});
     disableSlashCommands?: boolean;
+    /**
+     * Called for every library-emitted warning (user-callback threw, malformed
+     * tool decision, etc.). Set this to route warnings to your telemetry or
+     * silence them with `() => {}`. When omitted, warnings go to `console.warn`
+     * prefixed with `[claude-wire]`.
+     */
+    onWarning?: (message: string, cause?: unknown) => void;
 }
 export interface ISessionOptions extends IClaudeOptions {
+    /**
+     * Fires each time a transient failure triggers a respawn inside a single
+     * `ask()`. `attempt` is 1-indexed. The error is the one that caused the
+     * retry (e.g. `ProcessError` with a SIGKILL exit code). Use this to
+     * surface retry activity in UI/telemetry; the SDK still handles the retry.
+     *
+     * Can also be passed per-ask via `session.ask(prompt, { onRetry })` for
+     * request-scoped correlation. Both fire if both are set.
+     */
+    onRetry?: (attempt: number, error: unknown) => void;
+}
+/**
+ * Per-ask options passed to `session.ask(prompt, options?)`. Override or
+ * supplement session-level callbacks for a single call -- useful for
+ * request-scoped logging/correlation in daemon-style consumers.
+ */
+export interface IAskOptions {
+    /**
+     * Per-ask retry observer. Fires alongside the session-level `onRetry` when
+     * both are set, so callers can attach request-scoped context (request id,
+     * trace span, user id) without reaching outside the callback.
+     */
+    onRetry?: (attempt: number, error: unknown) => void;
+    /**
+     * Per-ask abort signal. Aborts this ask only (the session stays alive).
+     * Composes with the session-level `signal` -- either firing aborts the ask.
+     */
+    signal?: AbortSignal;
 }