@pivanov/claude-wire 0.0.2 → 0.0.3

package/README.md

@@ -3,8 +3,7 @@
 Run [Claude Code](https://claude.ai/download) programmatically from TypeScript.
 
 [![npm](https://img.shields.io/npm/v/@pivanov/claude-wire)](https://www.npmjs.com/package/@pivanov/claude-wire)
-[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@pivanov/claude-wire)](https://bundlephobia.com/package/@pivanov/claude-wire)
-[![license](https://img.shields.io/npm/l/claude-wire)](./LICENSE)
+[![license](https://img.shields.io/npm/l/@pivanov/claude-wire)](./LICENSE)
 
 ```ts
 import { claude } from "@pivanov/claude-wire";
@@ -26,7 +25,7 @@ console.log(result.costUsd);  // 0.0084
 - **Cost tracking** - per-request budgets with auto-abort
 - **Fully typed** - discriminated union events, full IntelliSense
 - **Resilient** - auto-respawn, transient error detection, AbortSignal
-- **Zero dependencies** - 13 kB gzipped
+- **Zero dependencies** - 16.2 kB gzipped
 
 ## Install
 

package/dist/client.js

@@ -1,11 +1,15 @@
 import { createSession } from "./session.js";
 import { createStream } from "./stream.js";
-const mergeOptions = (defaults, overrides) => ({
-    ...defaults,
-    ...overrides,
-    tools: overrides && "tools" in overrides ? (overrides.tools ? { ...defaults.tools, ...overrides.tools } : overrides.tools) : defaults.tools,
-    env: overrides && "env" in overrides ? (overrides.env ? { ...defaults.env, ...overrides.env } : overrides.env) : defaults.env,
-});
+const mergeOptions = (defaults, overrides) => {
+    const merged = { ...defaults, ...overrides };
+    if (overrides && "tools" in overrides) {
+        merged.tools = overrides.tools ? { ...defaults.tools, ...overrides.tools } : overrides.tools;
+    }
+    if (overrides && "env" in overrides) {
+        merged.env = overrides.env ? { ...defaults.env, ...overrides.env } : overrides.env;
+    }
+    return merged;
+};
 export const createClient = (defaults = {}) => {
     const ask = async (prompt, options) => {
         const merged = mergeOptions(defaults, options);

package/dist/constants.d.ts

@@ -6,7 +6,9 @@ export declare const LIMITS: {
     readonly maxRespawnAttempts: 3;
     readonly sessionMaxTurnsBeforeRecycle: 100;
     readonly ndjsonMaxLineChars: number;
+    readonly fingerprintTextLen: 64;
 };
+export declare const RESPAWN_BACKOFF_MS: readonly [500, 1000, 2000];
 export declare const BINARY: {
     readonly name: "claude";
     readonly commonPaths: readonly [`${string}/.local/bin/claude`, `${string}/.claude/bin/claude`, "/usr/local/bin/claude", "/opt/homebrew/bin/claude"];

package/dist/constants.js

@@ -7,7 +7,10 @@ export const LIMITS = {
     maxRespawnAttempts: 3,
     sessionMaxTurnsBeforeRecycle: 100,
     ndjsonMaxLineChars: 10 * 1024 * 1024,
+    fingerprintTextLen: 64,
 };
+// Respawn backoff in ms, indexed by consecutiveCrashes (1st=500ms, 2nd=1s, 3rd=2s).
+export const RESPAWN_BACKOFF_MS = [500, 1000, 2000];
 const home = homedir();
 export const BINARY = {
     name: "claude",

package/dist/cost.js

@@ -17,8 +17,8 @@ export const createCostTracker = (options = {}) => {
             try {
                 options.onCostUpdate(snapshot());
             }
-            catch {
-                // user callback error - don't crash the stream/session
+            catch (error) {
+                console.warn("[claude-wire] onCostUpdate callback threw:", error instanceof Error ? error.message : error);
             }
         }
     };

package/dist/errors.d.ts

@@ -16,8 +16,8 @@ export declare class ProcessError extends ClaudeError {
     readonly exitCode?: number | undefined;
     constructor(message: string, exitCode?: number | undefined);
 }
-declare const KNOWN_ERROR_CODES: readonly ["not-authenticated", "binary-not-found", "session-expired", "permission-denied", "invalid-model"];
-type TKnownErrorCode = (typeof KNOWN_ERROR_CODES)[number];
+export declare const KNOWN_ERROR_CODES: readonly ["not-authenticated", "binary-not-found", "session-expired", "permission-denied", "invalid-model"];
+export type TKnownErrorCode = (typeof KNOWN_ERROR_CODES)[number];
 export declare class KnownError extends ClaudeError {
     readonly code: TKnownErrorCode;
     constructor(code: TKnownErrorCode, message?: string);
@@ -26,4 +26,3 @@ export declare const isKnownError: (error: unknown) => error is KnownError;
 export declare const isTransientError: (error: unknown) => boolean;
 export declare const errorMessage: (error: unknown) => string;
 export declare const assertPositiveNumber: (value: number | undefined, name: string) => void;
-export {};

package/dist/errors.js

@@ -34,7 +34,7 @@ export class ProcessError extends ClaudeError {
         this.name = "ProcessError";
     }
 }
-const KNOWN_ERROR_CODES = ["not-authenticated", "binary-not-found", "session-expired", "permission-denied", "invalid-model"];
+export const KNOWN_ERROR_CODES = ["not-authenticated", "binary-not-found", "session-expired", "permission-denied", "invalid-model"];
 export class KnownError extends ClaudeError {
     code;
     constructor(code, message) {
@@ -46,14 +46,16 @@ export class KnownError extends ClaudeError {
 export const isKnownError = (error) => {
     return error instanceof KnownError;
 };
-const TRANSIENT_PATTERN = /fetch failed|ECONNREFUSED|ETIMEDOUT|ECONNRESET|EAI_AGAIN|network error|network timeout|EPIPE|SIGPIPE|broken pipe/i;
+const TRANSIENT_PATTERN = /fetch failed|ECONNREFUSED|ETIMEDOUT|ECONNRESET|ECONNABORTED|ENETUNREACH|EAI_AGAIN|network error|network timeout|EPIPE|SIGPIPE|broken pipe/i;
+// Exit codes we treat as transient: 137 = SIGKILL (OOM), 141 = SIGPIPE,
+// 143 = SIGTERM. Non-zero normal exits (e.g. 1) stay non-transient.
+const TRANSIENT_EXIT_CODES = new Set([137, 141, 143]);
 export const isTransientError = (error) => {
     if (error instanceof AbortError || error instanceof BudgetExceededError) {
         return false;
     }
     if (error instanceof ProcessError) {
-        const transientCodes = [137, 143];
-        return error.exitCode !== undefined && transientCodes.includes(error.exitCode);
+        return error.exitCode !== undefined && TRANSIENT_EXIT_CODES.has(error.exitCode);
     }
     const message = errorMessage(error);
     return TRANSIENT_PATTERN.test(message);
@@ -62,7 +64,8 @@ export const errorMessage = (error) => {
     return error instanceof Error ? error.message : String(error);
 };
 export const assertPositiveNumber = (value, name) => {
-    if (value !== undefined && (!Number.isFinite(value) || value <= 0)) {
-        throw new ClaudeError(`${name} must be a finite positive number`);
+    // Allow 0 so callers can express "no spend permitted" (useful in tests).
+    if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
+        throw new ClaudeError(`${name} must be a finite non-negative number`);
     }
 };

package/dist/index.d.ts

@@ -3,7 +3,8 @@ export { createClient } from "./client.js";
 export { BINARY, LIMITS, TIMEOUTS } from "./constants.js";
 export type { ICostTracker, ICostTrackerOptions } from "./cost.js";
 export { createCostTracker } from "./cost.js";
-export { AbortError, assertPositiveNumber, BudgetExceededError, ClaudeError, errorMessage, isKnownError, isTransientError, KnownError, ProcessError, TimeoutError, } from "./errors.js";
+export type { TKnownErrorCode } from "./errors.js";
+export { AbortError, assertPositiveNumber, BudgetExceededError, ClaudeError, errorMessage, isKnownError, isTransientError, KNOWN_ERROR_CODES, KnownError, ProcessError, TimeoutError, } from "./errors.js";
 export { blockFingerprint, extractContent, parseDoubleEncoded } from "./parser/content.js";
 export { parseLine } from "./parser/ndjson.js";
 export type { ITranslator } from "./parser/translator.js";

package/dist/index.js

@@ -1,7 +1,8 @@
+import { createClient } from "./client.js";
 export { createClient } from "./client.js";
 export { BINARY, LIMITS, TIMEOUTS } from "./constants.js";
 export { createCostTracker } from "./cost.js";
-export { AbortError, assertPositiveNumber, BudgetExceededError, ClaudeError, errorMessage, isKnownError, isTransientError, KnownError, ProcessError, TimeoutError, } from "./errors.js";
+export { AbortError, assertPositiveNumber, BudgetExceededError, ClaudeError, errorMessage, isKnownError, isTransientError, KNOWN_ERROR_CODES, KnownError, ProcessError, TimeoutError, } from "./errors.js";
 export { blockFingerprint, extractContent, parseDoubleEncoded } from "./parser/content.js";
 export { parseLine } from "./parser/ndjson.js";
 export { createTranslator } from "./parser/translator.js";
@@ -12,5 +13,4 @@ export { createStream } from "./stream.js";
 export { createToolHandler } from "./tools/handler.js";
 export { BUILT_IN_TOOLS, isBuiltInTool } from "./tools/registry.js";
 export { writer } from "./writer.js";
-import { createClient } from "./client.js";
 export const claude = createClient();

package/dist/parser/content.js

@@ -1,10 +1,11 @@
+import { LIMITS } from "../constants.js";
 export const blockFingerprint = (block) => {
     if (block.type === "tool_use" && block.id) {
         return `tool_use:${block.id}`;
     }
     const text = block.type === "thinking" ? (block.thinking ?? block.text ?? "") : (block.text ?? "");
     if (text) {
-        return `${block.type}:${text.slice(0, 64)}`;
+        return `${block.type}:${text.slice(0, LIMITS.fingerprintTextLen)}`;
     }
     return `${block.type}:${block.tool_use_id ?? "unknown"}`;
 };
@@ -17,7 +18,7 @@ export const extractContent = (content) => {
     }
     if (Array.isArray(content)) {
         return content
-            .filter((block) => typeof block === "object" && block !== null && "text" in block)
+            .filter((block) => typeof block === "object" && block !== null && "text" in block && typeof block.text === "string")
             .map((block) => block.text)
             .join("\n");
     }

package/dist/parser/translator.js

@@ -41,13 +41,15 @@ const translateContentBlock = (block) => {
             return undefined;
         }
         case "tool_use": {
-            if (!block.id) {
+            // Drop malformed tool_use events entirely. An empty toolName would
+            // otherwise bypass allow/block lists by matching nothing.
+            if (!block.id || !block.name) {
                 return undefined;
             }
             return {
                 type: "tool_use",
                 toolUseId: block.id,
-                toolName: block.name ?? "",
+                toolName: block.name,
                 input: typeof block.input === "string" ? block.input : JSON.stringify(block.input ?? {}),
             };
         }

package/dist/process.d.ts

@@ -10,6 +10,8 @@ export interface IClaudeProcess {
 export interface ISpawnOptions extends IClaudeOptions {
     prompt?: string;
 }
+export declare const ALIAS_PATTERN: RegExp;
+export declare const resolveConfigDirFromAlias: () => string | undefined;
 export declare const resetBinaryCache: () => void;
 export declare const buildArgs: (options: ISpawnOptions, binaryPath: string) => string[];
 export declare const spawnClaude: (options: ISpawnOptions) => IClaudeProcess;

package/dist/process.js

@@ -17,8 +17,10 @@ const resolveBinaryPath = () => {
     }
     return BINARY.name;
 };
-const ALIAS_PATTERN = /(?:alias\s+claude\s*=|export\s+).*CLAUDE_CONFIG_DIR=["']?\$?(?:HOME|\{HOME\}|~)\/?([^\s"']+?)["']?(?:\s|\/|$)/;
-const resolveConfigDirFromAlias = () => {
+// Rejects lines whose first non-whitespace char is `#` so commented-out
+// aliases/exports don't silently apply. /m anchors to each line in rc files.
+export const ALIAS_PATTERN = /^(?!\s*#).*?(?:alias\s+claude\s*=|export\s+).*CLAUDE_CONFIG_DIR=["']?\$?(?:HOME|\{HOME\}|~)\/?([^\s"']+?)["']?(?:\s|$)/m;
+export const resolveConfigDirFromAlias = () => {
     const home = homedir();
     const rcFiles = [".zshrc", ".bashrc", ".zprofile", ".bash_profile", ".aliases"];
     for (const rcFile of rcFiles) {
@@ -50,18 +52,20 @@ const resolve = () => {
 };
 export const buildArgs = (options, binaryPath) => {
     const args = [binaryPath, "-p", "--output-format", "stream-json", "--input-format", "stream-json"];
-    if (options.verbose !== false) {
-        args.push("--verbose");
-    }
-    if (options.model) {
-        args.push("--model", options.model);
-    }
-    if (options.systemPrompt) {
-        args.push("--system-prompt", options.systemPrompt);
-    }
-    if (options.appendSystemPrompt) {
-        args.push("--append-system-prompt", options.appendSystemPrompt);
-    }
+    const flag = (cond, name) => {
+        if (cond) {
+            args.push(name);
+        }
+    };
+    const kv = (value, name) => {
+        if (value) {
+            args.push(name, value);
+        }
+    };
+    flag(options.verbose !== false, "--verbose");
+    kv(options.model, "--model");
+    kv(options.systemPrompt, "--system-prompt");
+    kv(options.appendSystemPrompt, "--append-system-prompt");
     if (options.allowedTools) {
         if (options.allowedTools.length === 0) {
             args.push("--tools", "");
@@ -76,53 +80,27 @@ export const buildArgs = (options, binaryPath) => {
     if (options.maxBudgetUsd !== undefined) {
         args.push("--max-budget-usd", String(options.maxBudgetUsd));
     }
-    if (options.resume) {
-        args.push("--resume", options.resume);
-    }
-    if (options.mcpConfig) {
-        args.push("--mcp-config", options.mcpConfig);
-    }
-    if (options.continueSession) {
-        args.push("--continue");
-    }
-    if (options.permissionMode) {
-        args.push("--permission-mode", options.permissionMode);
-    }
+    kv(options.resume, "--resume");
+    kv(options.mcpConfig, "--mcp-config");
+    flag(options.continueSession, "--continue");
+    kv(options.permissionMode, "--permission-mode");
     if (options.addDirs && options.addDirs.length > 0) {
         for (const dir of options.addDirs) {
             args.push("--add-dir", dir);
         }
     }
-    if (options.effort) {
-        args.push("--effort", options.effort);
-    }
-    if (options.includeHookEvents) {
-        args.push("--include-hook-events");
-    }
-    if (options.includePartialMessages) {
-        args.push("--include-partial-messages");
-    }
-    if (options.bare) {
-        args.push("--bare");
-    }
-    if (options.jsonSchema) {
-        args.push("--json-schema", options.jsonSchema);
-    }
-    if (options.forkSession) {
-        args.push("--fork-session");
-    }
-    if (options.noSessionPersistence) {
-        args.push("--no-session-persistence");
-    }
-    if (options.sessionId) {
-        args.push("--session-id", options.sessionId);
-    }
+    kv(options.effort, "--effort");
+    flag(options.includeHookEvents, "--include-hook-events");
+    flag(options.includePartialMessages, "--include-partial-messages");
+    flag(options.bare, "--bare");
+    kv(options.jsonSchema, "--json-schema");
+    flag(options.forkSession, "--fork-session");
+    flag(options.noSessionPersistence, "--no-session-persistence");
+    kv(options.sessionId, "--session-id");
     if (options.settingSources !== undefined) {
         args.push("--setting-sources", options.settingSources);
     }
-    if (options.disableSlashCommands) {
-        args.push("--disable-slash-commands");
-    }
+    flag(options.disableSlashCommands, "--disable-slash-commands");
     return args;
 };
 export const spawnClaude = (options) => {
@@ -133,13 +111,16 @@ export const spawnClaude = (options) => {
         const needsEnv = resolved.aliasConfigDir || options.configDir || options.env;
         let spawnEnv;
         if (needsEnv) {
+            // Priority (lowest → highest): process.env < alias-detected config <
+            // user's explicit `options.env` < explicit `options.configDir`. User
+            // input always outranks the alias heuristic.
             spawnEnv = { ...process.env };
-            if (options.env) {
-                Object.assign(spawnEnv, options.env);
-            }
             if (resolved.aliasConfigDir) {
                 spawnEnv.CLAUDE_CONFIG_DIR = resolved.aliasConfigDir;
             }
+            if (options.env) {
+                Object.assign(spawnEnv, options.env);
+            }
             if (options.configDir) {
                 spawnEnv.CLAUDE_CONFIG_DIR = options.configDir;
             }

package/dist/reader.d.ts

@@ -9,5 +9,11 @@ export interface IReaderOptions {
     proc?: IClaudeProcess;
     signal?: AbortSignal;
 }
+export interface IStderrDrain {
+    chunks: string[];
+    done: Promise<void>;
+}
+export declare const drainStderr: (proc: {
+    stderr: ReadableStream<Uint8Array>;
+}) => IStderrDrain;
 export declare function readNdjsonEvents(opts: IReaderOptions): AsyncGenerator<TRelayEvent>;
-export type { TRelayEvent };

package/dist/reader.js

@@ -2,17 +2,68 @@ import { LIMITS, TIMEOUTS } from "./constants.js";
 import { AbortError, ClaudeError, TimeoutError } from "./errors.js";
 import { parseLine } from "./parser/ndjson.js";
 import { dispatchToolDecision } from "./pipeline.js";
+import { writer } from "./writer.js";
+export const drainStderr = (proc) => {
+    const chunks = [];
+    const stderrReader = proc.stderr.getReader();
+    const decoder = new TextDecoder();
+    const done = (async () => {
+        try {
+            while (true) {
+                const { done: isDone, value } = await stderrReader.read();
+                if (isDone) {
+                    break;
+                }
+                chunks.push(decoder.decode(value, { stream: true }));
+            }
+        }
+        catch {
+            // process exited
+        }
+        finally {
+            // Flush any trailing partial multibyte sequence.
+            const tail = decoder.decode();
+            if (tail) {
+                chunks.push(tail);
+            }
+            stderrReader.releaseLock();
+        }
+    })().catch(() => { });
+    return { chunks, done };
+};
 export async function* readNdjsonEvents(opts) {
     const { reader, translator, signal } = opts;
     const decoder = new TextDecoder();
     let buffer = "";
     let timeoutId;
     let turnComplete = false;
+    let abortReject;
+    const abortPromise = new Promise((_, reject) => {
+        abortReject = reject;
+    });
+    // Swallow unhandled rejection if nothing ever races against this promise.
+    abortPromise.catch(() => { });
+    // Single resettable timeout shared across all iterations — avoids leaking
+    // a new Promise + setTimeout per read loop.
+    let timeoutReject;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutReject = reject;
+    });
+    timeoutPromise.catch(() => { });
+    const resetReadTimeout = () => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => {
+            timeoutReject?.(new TimeoutError(`No data received within ${TIMEOUTS.defaultAbortMs}ms`));
+        }, TIMEOUTS.defaultAbortMs);
+    };
     const abortHandler = signal
         ? () => {
+            abortReject?.(new AbortError());
             if (opts.proc) {
                 try {
-                    opts.proc.write('{"type":"abort"}\n');
+                    opts.proc.write(writer.abort());
                 }
                 catch {
                     // stdin closed
@@ -32,13 +83,8 @@ export async function* readNdjsonEvents(opts) {
             if (signal?.aborted) {
                 throw new AbortError();
             }
-            const timeoutPromise = new Promise((_, reject) => {
-                timeoutId = setTimeout(() => {
-                    reject(new TimeoutError(`No data received within ${TIMEOUTS.defaultAbortMs}ms`));
-                }, TIMEOUTS.defaultAbortMs);
-            });
-            const readResult = await Promise.race([reader.read(), timeoutPromise]);
-            clearTimeout(timeoutId);
+            resetReadTimeout();
+            const readResult = await Promise.race([reader.read(), timeoutPromise, abortPromise]);
             const { done, value } = readResult;
             if (done) {
                 break;

package/dist/runtime.js

@@ -1,6 +1,7 @@
 import { execFileSync, spawn as nodeSpawn } from "node:child_process";
 import { accessSync, constants, statSync } from "node:fs";
 import { Readable } from "node:stream";
+import { ProcessError } from "./errors.js";
 const isBun = typeof globalThis.Bun !== "undefined";
 export const spawnProcess = (args, opts) => {
     if (isBun) {
@@ -30,15 +31,6 @@ export const whichSync = (name) => {
     }
 };
 export const fileExists = (path) => {
-    if (isBun) {
-        try {
-            accessSync(path, constants.X_OK);
-            return statSync(path).size > 0;
-        }
-        catch {
-            return false;
-        }
-    }
     try {
         accessSync(path, constants.X_OK);
         return statSync(path).size > 0;
@@ -73,43 +65,20 @@ const spawnBun = (args, opts) => {
         pid: proc.pid,
     };
 };
-const nodeReadableToWeb = (readable) => {
-    return new ReadableStream({
-        start(controller) {
-            let closed = false;
-            readable.on("data", (chunk) => {
-                if (!closed) {
-                    controller.enqueue(new Uint8Array(chunk));
-                }
-            });
-            readable.on("end", () => {
-                if (!closed) {
-                    closed = true;
-                    controller.close();
-                }
-            });
-            readable.on("error", (err) => {
-                if (!closed) {
-                    closed = true;
-                    controller.error(err);
-                }
-            });
-        },
-        cancel() {
-            readable.destroy();
-        },
-    });
-};
+const toWeb = (readable) => Readable.toWeb(readable);
 const spawnNode = (args, opts) => {
     const [cmd, ...rest] = args;
     if (!cmd) {
-        throw new Error("No command specified");
+        throw new ProcessError("No command specified");
     }
     const child = nodeSpawn(cmd, rest, {
         cwd: opts.cwd,
         stdio: ["pipe", "pipe", "pipe"],
         env: opts.env,
     });
+    if (child.pid === undefined) {
+        throw new ProcessError(`Failed to spawn ${cmd}: no PID assigned`);
+    }
     const exited = new Promise((resolve, reject) => {
         child.on("exit", (code) => {
             resolve(code ?? 1);
@@ -119,18 +88,21 @@ const spawnNode = (args, opts) => {
     return {
         stdin: {
             write: (data) => {
-                child.stdin?.write(data);
+                if (!child.stdin || child.stdin.destroyed) {
+                    throw new ProcessError("Cannot write: stdin is not writable");
+                }
+                child.stdin.write(data);
             },
             end: () => {
                 child.stdin?.end();
             },
         },
-        stdout: child.stdout ? nodeReadableToWeb(child.stdout) : new ReadableStream(),
-        stderr: child.stderr ? nodeReadableToWeb(child.stderr) : new ReadableStream(),
+        stdout: child.stdout ? toWeb(child.stdout) : new ReadableStream(),
+        stderr: child.stderr ? toWeb(child.stderr) : new ReadableStream(),
         kill: () => {
             child.kill();
         },
         exited,
-        pid: child.pid ?? 0,
+        pid: child.pid,
     };
 };

package/dist/session.js

@@ -1,10 +1,10 @@
-import { LIMITS, TIMEOUTS } from "./constants.js";
+import { LIMITS, RESPAWN_BACKOFF_MS, TIMEOUTS } from "./constants.js";
 import { createCostTracker } from "./cost.js";
 import { AbortError, BudgetExceededError, ClaudeError, isTransientError, KnownError, ProcessError, TimeoutError } from "./errors.js";
 import { createTranslator } from "./parser/translator.js";
 import { buildResult } from "./pipeline.js";
 import { spawnClaude } from "./process.js";
-import { readNdjsonEvents } from "./reader.js";
+import { drainStderr, readNdjsonEvents } from "./reader.js";
 import { createToolHandler } from "./tools/handler.js";
 import { writer } from "./writer.js";
 const gracefulKill = async (p) => {
@@ -62,29 +62,7 @@ export const createSession = (options = {}) => {
         reader = undefined;
     };
     let lastStderrChunks = [];
-    const drainStderr = (p) => {
-        const chunks = [];
-        lastStderrChunks = chunks;
-        const stderrReader = p.stderr.getReader();
-        const decoder = new TextDecoder();
-        (async () => {
-            try {
-                while (true) {
-                    const { done, value } = await stderrReader.read();
-                    if (done) {
-                        break;
-                    }
-                    chunks.push(decoder.decode(value, { stream: true }));
-                }
-            }
-            catch {
-                // process exited
-            }
-            finally {
-                stderrReader.releaseLock();
-            }
-        })().catch(() => { });
-    };
+    let lastDrainDone;
     const getStderrText = () => lastStderrChunks.join("").trim();
     const killProc = () => {
         if (proc) {
@@ -105,7 +83,16 @@ export const createSession = (options = {}) => {
         const spawnOpts = resumeId ? { prompt, ...options, resume: resumeId } : { prompt, ...options };
         proc = spawnClaude(spawnOpts);
         reader = proc.stdout.getReader();
-        drainStderr(proc);
+        const drain = drainStderr(proc);
+        lastStderrChunks = drain.chunks;
+        lastDrainDone = drain.done;
+    };
+    const respawnBackoff = async () => {
+        const idx = Math.min(consecutiveCrashes, RESPAWN_BACKOFF_MS.length) - 1;
+        const delay = idx >= 0 ? RESPAWN_BACKOFF_MS[idx] : 0;
+        if (delay) {
+            await new Promise((r) => setTimeout(r, delay));
+        }
     };
     const readUntilTurnComplete = async (signal) => {
         if (!proc || !reader) {
@@ -135,8 +122,25 @@ 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).
+            let exitCode;
+            if (proc) {
+                const live = proc;
+                exitCode = await Promise.race([
+                    live.exited,
+                    new Promise((r) => setTimeout(() => r(undefined), TIMEOUTS.gracefulExitMs)),
+                ]);
+                if (exitCode === undefined) {
+                    live.kill();
+                }
+            }
+            if (lastDrainDone) {
+                await Promise.race([lastDrainDone, new Promise((r) => setTimeout(r, 500))]);
+            }
             const stderrMsg = getStderrText();
-            throw new ProcessError(stderrMsg || "Process exited without completing the turn");
+            throw new ProcessError(stderrMsg || "Process exited without completing the turn", exitCode);
         }
         return events;
     };
@@ -155,30 +159,25 @@ export const createSession = (options = {}) => {
             }
         }
         let events;
-        try {
-            events = await readUntilTurnComplete(options.signal);
-        }
-        catch (error) {
-            if (error instanceof AbortError || error instanceof TimeoutError) {
-                killProc();
-                throw error;
+        while (true) {
+            try {
+                events = await readUntilTurnComplete(options.signal);
+                break;
             }
-            if (isTransientError(error) && consecutiveCrashes < LIMITS.maxRespawnAttempts) {
-                consecutiveCrashes++;
-                spawnFresh(prompt, currentSessionId);
-                try {
-                    events = await readUntilTurnComplete(options.signal);
+            catch (error) {
+                if (error instanceof AbortError || error instanceof TimeoutError) {
+                    killProc();
+                    throw error;
                 }
-                catch (retryError) {
+                if (!isTransientError(error) || consecutiveCrashes >= LIMITS.maxRespawnAttempts) {
                     killProc();
                     translator.reset();
-                    throw retryError;
+                    throw error;
                 }
-            }
-            else {
-                killProc();
-                translator.reset();
-                throw error;
+                consecutiveCrashes++;
+                await respawnBackoff();
+                spawnFresh(prompt, currentSessionId);
+                // Loop to retry; stops when budget exhausted or turn completes.
             }
         }
         consecutiveCrashes = 0;
@@ -201,19 +200,32 @@ export const createSession = (options = {}) => {
         }
         const prev = inFlight ?? Promise.resolve();
         const run = prev
-            .catch((prevError) => {
-            if (prevError instanceof KnownError || prevError instanceof BudgetExceededError) {
-                throw prevError;
+            .catch(() => {
+            // Prior ask failure shouldn't prevent this one from running. Fatal
+            // errors (KnownError/BudgetExceededError) set `closed` in the .catch
+            // below, which the sync check above picks up on the NEXT ask.
+        })
+            .then(() => {
+            if (closed) {
+                throw new ClaudeError("Session is closed");
             }
+            return doAsk(prompt);
         })
-            .then(() => doAsk(prompt));
+            .catch((error) => {
+            if (error instanceof KnownError || error instanceof BudgetExceededError) {
+                closed = true;
+            }
+            throw error;
+        });
         inFlight = run;
         return run;
     };
     const close = async () => {
         closed = true;
         if (inFlight) {
-            await inFlight.catch(() => { });
+            // 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))]);
             inFlight = undefined;
         }
         if (proc) {

package/dist/stream.js

@@ -3,53 +3,41 @@ import { AbortError, ClaudeError, ProcessError } from "./errors.js";
 import { createTranslator } from "./parser/translator.js";
 import { buildResult, extractText } from "./pipeline.js";
 import { spawnClaude } from "./process.js";
-import { readNdjsonEvents } from "./reader.js";
+import { drainStderr, readNdjsonEvents } from "./reader.js";
 import { createToolHandler } from "./tools/handler.js";
-const drainStderr = (proc) => {
-    const chunks = [];
-    const stderrReader = proc.stderr.getReader();
-    const decoder = new TextDecoder();
-    const done = (async () => {
-        try {
-            while (true) {
-                const { done: isDone, value } = await stderrReader.read();
-                if (isDone) {
-                    break;
-                }
-                chunks.push(decoder.decode(value, { stream: true }));
-            }
-        }
-        catch {
-            // process exited
-        }
-        finally {
-            stderrReader.releaseLock();
-        }
-    })().catch(() => { });
-    return { chunks, done };
-};
 export const createStream = (prompt, options = {}) => {
     if (options.signal?.aborted) {
         throw new AbortError();
     }
-    const proc = spawnClaude({ prompt, ...options });
-    const stderr = drainStderr(proc);
     const translator = createTranslator();
     const toolHandler = options.tools ? createToolHandler(options.tools) : undefined;
     const costTracker = createCostTracker({
         maxCostUsd: options.maxCostUsd,
         onCostUpdate: options.onCostUpdate,
     });
+    let proc;
+    let stderr;
     let cachedGenerator;
+    const ensureSpawned = () => {
+        if (!proc) {
+            if (options.signal?.aborted) {
+                throw new AbortError();
+            }
+            proc = spawnClaude({ prompt, ...options });
+            stderr = drainStderr(proc);
+        }
+        return proc;
+    };
     const generate = async function* () {
-        const stdoutReader = proc.stdout.getReader();
+        const p = ensureSpawned();
+        const stdoutReader = p.stdout.getReader();
         let turnComplete = false;
         try {
             for await (const event of readNdjsonEvents({
                 reader: stdoutReader,
                 translator,
                 toolHandler,
-                proc,
+                proc: p,
                 signal: options.signal,
             })) {
                 if (event.type === "turn_complete") {
@@ -60,22 +48,21 @@ export const createStream = (prompt, options = {}) => {
                 yield event;
             }
             if (!turnComplete) {
-                const exitCode = await proc.exited;
+                const exitCode = await p.exited;
                 if (exitCode !== 0) {
-                    let errorMessage = `Claude process exited with code ${exitCode}`;
-                    await stderr.done;
-                    const stderrText = stderr.chunks.join("").trim();
-                    if (stderrText) {
-                        errorMessage = stderrText;
+                    if (stderr) {
+                        await stderr.done;
                     }
-                    throw new ProcessError(errorMessage, exitCode);
+                    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");
             }
         }
         finally {
             stdoutReader.releaseLock();
-            proc.kill();
+            p.kill();
         }
     };
     const bufferedEvents = [];
@@ -85,9 +72,10 @@ export const createStream = (prompt, options = {}) => {
             if (cachedGenerator) {
                 throw new ClaudeError("Cannot call text()/cost()/result() after iterating with for-await. Use one or the other.");
             }
+            const gen = generate();
+            cachedGenerator = gen;
             consumePromise = (async () => {
-                cachedGenerator = generate();
-                for await (const event of { [Symbol.asyncIterator]: () => cachedGenerator }) {
+                for await (const event of gen) {
                     bufferedEvents.push(event);
                 }
             })();
@@ -108,7 +96,10 @@ export const createStream = (prompt, options = {}) => {
         return buildResult(bufferedEvents, costTracker, sessionId);
     };
     const cleanup = () => {
-        if (!cachedGenerator) {
+        // 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();
         }
     };

package/dist/tools/handler.js

@@ -1,5 +1,5 @@
 export const createToolHandler = (options = {}) => {
-    const { allowed, blocked, onToolUse } = options;
+    const { allowed, blocked, onToolUse, onError } = options;
     const allowedSet = allowed ? new Set(allowed) : undefined;
     const blockedSet = blocked ? new Set(blocked) : undefined;
     const decide = async (tool) => {
@@ -9,10 +9,18 @@ export const createToolHandler = (options = {}) => {
         if (allowedSet && !allowedSet.has(tool.toolName)) {
             return "deny";
         }
-        if (onToolUse) {
-            return onToolUse(tool);
+        if (!onToolUse) {
+            return "approve";
+        }
+        try {
+            return await onToolUse(tool);
+        }
+        catch (error) {
+            if (!onError) {
+                throw error;
+            }
+            return onError(error, tool);
         }
-        return "approve";
     };
     return { decide };
 };

package/dist/types/options.d.ts

@@ -5,6 +5,7 @@ export interface IToolHandler {
     allowed?: string[];
     blocked?: string[];
     onToolUse?: (tool: TToolUseEvent) => Promise<TToolDecision>;
+    onError?: (error: unknown, tool: TToolUseEvent) => TToolDecision | Promise<TToolDecision>;
 }
 export interface IClaudeOptions {
     cwd?: string;
@@ -14,7 +15,17 @@ export interface IClaudeOptions {
     allowedTools?: string[];
     disallowedTools?: string[];
     tools?: IToolHandler;
+    /**
+     * SDK-side budget limit, evaluated after each turn. Throws `BudgetExceededError`
+     * and kills the process when `total_cost_usd` exceeds this value. `0` means
+     * "disallow any spend" (useful for tests).
+     */
     maxCostUsd?: number;
+    /**
+     * CLI-level budget forwarded as `--max-budget-usd`. Enforced by the Claude
+     * binary itself, independent of {@link IClaudeOptions.maxCostUsd}. Either
+     * can fire first; set both for belt-and-suspenders.
+     */
     maxBudgetUsd?: number;
     onCostUpdate?: (cost: TCostSnapshot) => void;
     signal?: AbortSignal;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pivanov/claude-wire",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Run Claude Code programmatically. Typed SDK for spawning, streaming, and controlling the CLI.",
   "type": "module",
   "engines": {