@pivanov/claude-wire 0.0.3 → 0.1.0

package/README.md

@@ -20,12 +20,14 @@ console.log(result.costUsd);  // 0.0084
 ## Features
 
 - **Simple API** - `claude.ask()` returns a typed result, `claude.stream()` yields events
+- **Structured JSON** - `claude.askJson(prompt, schema)` with Standard Schema (Zod/Valibot/ArkType) validation
 - **Tool control** - allow, block, or intercept any tool at runtime
 - **Multi-turn sessions** - persistent process across multiple prompts
-- **Cost tracking** - per-request budgets with auto-abort
+- **Cost tracking** - per-request budgets with auto-abort and projection primitives
+- **Typed errors** - rate-limit, overload, context-length, retry-exhausted as `KnownError` codes
 - **Fully typed** - discriminated union events, full IntelliSense
-- **Resilient** - auto-respawn, transient error detection, AbortSignal
-- **Zero dependencies** - 16.2 kB gzipped
+- **Resilient** - auto-respawn with backoff, transient error detection, AbortSignal
+- **Zero dependencies** - ~29 kB gzipped
 
 ## Install
 
@@ -37,6 +39,8 @@ npm install @pivanov/claude-wire
 
 Requires [Claude Code CLI](https://claude.ai/download) installed and authenticated. Runs on [Bun](https://bun.sh) >= 1.0 or Node.js >= 22.
 
+> **Platform:** POSIX only (macOS, Linux, WSL). Native Windows isn't supported yet -- binary resolution relies on `which` and POSIX path conventions.
+
 > This SDK wraps Claude Code's `--output-format stream-json` protocol, which is not officially documented by Anthropic and may change between releases.
 
 ## Documentation
@@ -65,7 +69,7 @@ apps/examples/          interactive example runner
 
 ```bash
 bun install
-bun run test        # 147 tests
+bun run test        # 217 tests
 bun run typecheck
 bun run lint
 bun run docs:dev    # local docs server

package/dist/async.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Races `promise` against a timeout. When the timer fires first, resolves
+ * with `onTimeout()` (or `undefined` if omitted). The caller decides
+ * whether that's an acceptable fallback or a signal to kill/retry.
+ *
+ * Intentionally does NOT reject on timeout -- callers usually have a
+ * specific action to take (kill the process, bail early with undefined)
+ * that a thrown error would force into a catch branch for no reason.
+ */
+export declare const withTimeout: <T, F = undefined>(promise: Promise<T>, ms: number, onTimeout?: () => F) => Promise<T | F>;

package/dist/async.js

@@ -0,0 +1,27 @@
+// Small async helpers shared between session.ts and stream.ts. Kept in
+// their own file because both consumers care about the *shape* of the
+// timeout pattern, not its underlying mechanics -- drop a single
+// withTimeout() next to whatever else needs it rather than carrying the
+// Promise.race idiom inline at every site.
+/**
+ * Races `promise` against a timeout. When the timer fires first, resolves
+ * with `onTimeout()` (or `undefined` if omitted). The caller decides
+ * whether that's an acceptable fallback or a signal to kill/retry.
+ *
+ * Intentionally does NOT reject on timeout -- callers usually have a
+ * specific action to take (kill the process, bail early with undefined)
+ * that a thrown error would force into a catch branch for no reason.
+ */
+export const withTimeout = (promise, ms, onTimeout) => {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            resolve(onTimeout ? onTimeout() : undefined);
+        }, ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    });
+};

package/dist/client.d.ts

@@ -1,9 +1,11 @@
+import { type IJsonResult, type TSchemaInput } from "./json.js";
 import type { IClaudeSession } from "./session.js";
 import type { IClaudeStream } from "./stream.js";
 import type { IClaudeOptions, ISessionOptions } from "./types/options.js";
 import type { TAskResult } from "./types/results.js";
 export interface IClaudeClient {
     ask: (prompt: string, options?: IClaudeOptions) => Promise<TAskResult>;
+    askJson: <T>(prompt: string, schema: TSchemaInput<T>, options?: IClaudeOptions) => Promise<IJsonResult<T>>;
     stream: (prompt: string, options?: IClaudeOptions) => IClaudeStream;
     session: (options?: ISessionOptions) => IClaudeSession;
     create: (defaults: IClaudeOptions) => IClaudeClient;

package/dist/client.js

@@ -1,9 +1,10 @@
+import { isStandardSchema, parseAndValidate } from "./json.js";
 import { createSession } from "./session.js";
 import { createStream } from "./stream.js";
 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 && "toolHandler" in overrides) {
+        merged.toolHandler = overrides.toolHandler ? { ...defaults.toolHandler, ...overrides.toolHandler } : overrides.toolHandler;
     }
     if (overrides && "env" in overrides) {
         merged.env = overrides.env ? { ...defaults.env, ...overrides.env } : overrides.env;
@@ -16,6 +17,23 @@ export const createClient = (defaults = {}) => {
         const stream = createStream(prompt, merged);
         return stream.result();
     };
+    const askJson = async (prompt, schema, options) => {
+        const merged = mergeOptions(defaults, options);
+        // Forward the raw JSON Schema string to the CLI via --json-schema when
+        // the caller passes a string. Standard Schema objects are validated
+        // SDK-side after the response arrives.
+        if (typeof schema === "string") {
+            merged.jsonSchema = schema;
+        }
+        else if (isStandardSchema(schema)) {
+            // Extract JSON Schema representation if available for CLI-side
+            // constraint. Many Standard Schema libs expose this via toJsonSchema()
+            // but it's not part of the protocol. We validate SDK-side regardless.
+        }
+        const raw = await ask(prompt, merged);
+        const data = parseAndValidate(raw.text, schema);
+        return { data, raw };
+    };
     const stream = (prompt, options) => {
         const merged = mergeOptions(defaults, options);
         return createStream(prompt, merged);
@@ -28,5 +46,5 @@ export const createClient = (defaults = {}) => {
         const merged = mergeOptions(defaults, newDefaults);
         return createClient(merged);
     };
-    return { ask, stream, session, create };
+    return { ask, askJson, stream, session, create };
 };

package/dist/constants.d.ts

@@ -1,6 +1,7 @@
 export declare const TIMEOUTS: {
     readonly defaultAbortMs: 300000;
     readonly gracefulExitMs: 5000;
+    readonly stderrDrainGraceMs: 500;
 };
 export declare const LIMITS: {
     readonly maxRespawnAttempts: 3;
@@ -9,6 +10,7 @@ export declare const LIMITS: {
     readonly fingerprintTextLen: 64;
 };
 export declare const RESPAWN_BACKOFF_MS: readonly [500, 1000, 2000];
+export declare const MAX_BACKOFF_INDEX: 3;
 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

@@ -2,6 +2,9 @@ import { homedir } from "node:os";
 export const TIMEOUTS = {
     defaultAbortMs: 300_000,
     gracefulExitMs: 5_000,
+    // Grace period for stderr drain to catch up before an error is thrown so
+    // the error message carries the CLI's actual complaint instead of "".
+    stderrDrainGraceMs: 500,
 };
 export const LIMITS = {
     maxRespawnAttempts: 3,
@@ -11,6 +14,10 @@ export const LIMITS = {
 };
 // Respawn backoff in ms, indexed by consecutiveCrashes (1st=500ms, 2nd=1s, 3rd=2s).
 export const RESPAWN_BACKOFF_MS = [500, 1000, 2000];
+// Highest index into RESPAWN_BACKOFF_MS[]. Used by respawnBackoff() to
+// clamp the delay lookup to the last defined backoff when crashes exceed
+// the table length -- keeps the table and its bound co-located.
+export const MAX_BACKOFF_INDEX = RESPAWN_BACKOFF_MS.length;
 const home = homedir();
 export const BINARY = {
     name: "claude",

package/dist/cost.d.ts

@@ -1,12 +1,20 @@
 import type { TCostSnapshot } from "./types/results.js";
+import type { TWarn } from "./warnings.js";
+export interface ICostProjection {
+    projectedUsd: number;
+}
 export interface ICostTracker {
     update: (totalCostUsd: number, totalInputTokens: number, totalOutputTokens: number) => void;
     snapshot: () => TCostSnapshot;
     checkBudget: () => void;
     reset: () => void;
+    turnCount: number;
+    averagePerTurn: number;
+    project: (remainingTurns: number) => ICostProjection;
 }
 export interface ICostTrackerOptions {
     maxCostUsd?: number;
     onCostUpdate?: (cost: TCostSnapshot) => void;
+    onWarning?: TWarn;
 }
 export declare const createCostTracker: (options?: ICostTrackerOptions) => ICostTracker;

package/dist/cost.js

@@ -1,24 +1,28 @@
-import { assertPositiveNumber, BudgetExceededError } from "./errors.js";
+import { BudgetExceededError } from "./errors.js";
+import { assertPositiveNumber } from "./validation.js";
+import { createWarn } from "./warnings.js";
 export const createCostTracker = (options = {}) => {
     assertPositiveNumber(options.maxCostUsd, "maxCostUsd");
+    const warn = createWarn(options.onWarning);
     let totalUsd = 0;
-    let inputTokens = 0;
-    let outputTokens = 0;
+    let input = 0;
+    let output = 0;
+    let turns = 0;
     const snapshot = () => ({
         totalUsd,
-        inputTokens,
-        outputTokens,
+        tokens: { input, output },
     });
     const update = (totalCostUsd, totalInputToks, totalOutputToks) => {
         totalUsd = totalCostUsd;
-        inputTokens = totalInputToks;
-        outputTokens = totalOutputToks;
+        input = totalInputToks;
+        output = totalOutputToks;
+        turns++;
         if (options.onCostUpdate) {
             try {
                 options.onCostUpdate(snapshot());
             }
             catch (error) {
-                console.warn("[claude-wire] onCostUpdate callback threw:", error instanceof Error ? error.message : error);
+                warn("onCostUpdate callback threw", error);
             }
         }
     };
@@ -29,8 +33,25 @@ export const createCostTracker = (options = {}) => {
     };
     const reset = () => {
         totalUsd = 0;
-        inputTokens = 0;
-        outputTokens = 0;
+        input = 0;
+        output = 0;
+        turns = 0;
+    };
+    const project = (remainingTurns) => {
+        const avg = turns > 0 ? totalUsd / turns : 0;
+        return { projectedUsd: totalUsd + avg * remainingTurns };
+    };
+    return {
+        update,
+        snapshot,
+        checkBudget,
+        reset,
+        get turnCount() {
+            return turns;
+        },
+        get averagePerTurn() {
+            return turns > 0 ? totalUsd / turns : 0;
+        },
+        project,
     };
-    return { update, snapshot, checkBudget, reset };
 };

package/dist/errors.d.ts

@@ -16,7 +16,7 @@ export declare class ProcessError extends ClaudeError {
     readonly exitCode?: number | undefined;
     constructor(message: string, exitCode?: number | undefined);
 }
-export declare const KNOWN_ERROR_CODES: readonly ["not-authenticated", "binary-not-found", "session-expired", "permission-denied", "invalid-model"];
+export declare const KNOWN_ERROR_CODES: readonly ["not-authenticated", "binary-not-found", "permission-denied", "retry-exhausted", "rate-limit", "overloaded", "context-length-exceeded", "invalid-json-schema", "mcp-error"];
 export type TKnownErrorCode = (typeof KNOWN_ERROR_CODES)[number];
 export declare class KnownError extends ClaudeError {
     readonly code: TKnownErrorCode;
@@ -25,4 +25,7 @@ export declare class KnownError extends ClaudeError {
 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;
+declare let stderrClassifier: ((stderr: string, exitCode?: number) => TKnownErrorCode | undefined) | undefined;
+export declare const setStderrClassifier: (fn: typeof stderrClassifier) => void;
+export declare const processExitedEarly: (stderr: string, exitCode?: number) => ProcessError | KnownError;
+export {};

package/dist/errors.js

@@ -34,7 +34,21 @@ export class ProcessError extends ClaudeError {
         this.name = "ProcessError";
     }
 }
-export const KNOWN_ERROR_CODES = ["not-authenticated", "binary-not-found", "session-expired", "permission-denied", "invalid-model"];
+// Only codes the SDK actually constructs are listed. Add a new code here
+// alongside the throw site that needs it -- aspirational entries give
+// consumers false confidence that they can pattern-match on them.
+export const KNOWN_ERROR_CODES = [
+    "not-authenticated",
+    "binary-not-found",
+    "permission-denied",
+    "retry-exhausted",
+    // Classified from stderr by classifyStderr (src/stderr.ts):
+    "rate-limit",
+    "overloaded",
+    "context-length-exceeded",
+    "invalid-json-schema",
+    "mcp-error",
+];
 export class KnownError extends ClaudeError {
     code;
     constructor(code, message) {
@@ -46,7 +60,11 @@ export class KnownError extends ClaudeError {
 export const isKnownError = (error) => {
     return error instanceof KnownError;
 };
-const TRANSIENT_PATTERN = /fetch failed|ECONNREFUSED|ETIMEDOUT|ECONNRESET|ECONNABORTED|ENETUNREACH|EAI_AGAIN|network error|network timeout|EPIPE|SIGPIPE|broken pipe/i;
+// Network-level transients (ECONNRESET/REFUSED/ABORTED, ENETUNREACH, EHOSTUNREACH),
+// DNS transients (EAI_AGAIN), pipe resets (EPIPE/SIGPIPE, broken pipe), fetch
+// errors, ad-hoc "socket hang up" messages from node, and Anthropic
+// overloaded_error which the CLI bubbles up verbatim for 529 responses.
+const TRANSIENT_PATTERN = /fetch failed|ECONNREFUSED|ETIMEDOUT|ECONNRESET|ECONNABORTED|ENETUNREACH|EHOSTUNREACH|EAI_AGAIN|network error|network timeout|EPIPE|SIGPIPE|broken pipe|socket hang up|overloaded_error/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]);
@@ -63,9 +81,23 @@ export const isTransientError = (error) => {
 export const errorMessage = (error) => {
     return error instanceof Error ? error.message : String(error);
 };
-export const assertPositiveNumber = (value, name) => {
-    // 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`);
+// Shared error factory for the "process died before emitting turn_complete"
+// case. session.ts + stream.ts both need this; the string used to be
+// duplicated verbatim, which drifted at least once. Prefix stderr when
+// available because CLI error output is the most actionable signal.
+// Auto-promotes to KnownError when stderr matches a classifiable pattern.
+// The classifier is injected to avoid a circular import (stderr.ts imports
+// types from this file). Wire it at boot via `setStderrClassifier`.
+let stderrClassifier;
+export const setStderrClassifier = (fn) => {
+    stderrClassifier = fn;
+};
+export const processExitedEarly = (stderr, exitCode) => {
+    if (stderr && stderrClassifier) {
+        const code = stderrClassifier(stderr, exitCode);
+        if (code) {
+            return new KnownError(code, stderr);
+        }
     }
+    return new ProcessError(stderr || "Process exited without completing the turn", exitCode);
 };

package/dist/index.d.ts

@@ -1,28 +1,32 @@
 export type { IClaudeClient } from "./client.js";
 export { createClient } from "./client.js";
 export { BINARY, LIMITS, TIMEOUTS } from "./constants.js";
-export type { ICostTracker, ICostTrackerOptions } from "./cost.js";
+export type { ICostProjection, ICostTracker, ICostTrackerOptions } from "./cost.js";
 export { createCostTracker } from "./cost.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 { AbortError, BudgetExceededError, ClaudeError, errorMessage, isKnownError, isTransientError, KNOWN_ERROR_CODES, KnownError, ProcessError, TimeoutError, } from "./errors.js";
+export type { IJsonResult, IStandardSchema, TSchemaInput } from "./json.js";
+export { JsonValidationError, parseAndValidate, stripFences } from "./json.js";
 export { blockFingerprint, extractContent, parseDoubleEncoded } from "./parser/content.js";
 export { parseLine } from "./parser/ndjson.js";
 export type { ITranslator } from "./parser/translator.js";
 export { createTranslator } from "./parser/translator.js";
 export type { IClaudeProcess, ISpawnOptions } from "./process.js";
-export { buildArgs, resetBinaryCache, spawnClaude } from "./process.js";
+export { buildArgs, resetResolvedEnvCache, spawnClaude } from "./process.js";
 export type { IReaderOptions } from "./reader.js";
 export { readNdjsonEvents } from "./reader.js";
 export type { IClaudeSession } from "./session.js";
 export { createSession } from "./session.js";
+export { classifyStderr } from "./stderr.js";
 export type { IClaudeStream } from "./stream.js";
 export { createStream } from "./stream.js";
 export type { IToolHandlerInstance, TToolDecision } from "./tools/handler.js";
 export { createToolHandler } from "./tools/handler.js";
-export { BUILT_IN_TOOLS, isBuiltInTool } from "./tools/registry.js";
+export type { TBuiltInToolName } from "./tools/registry.js";
+export { BUILT_IN_TOOL_NAMES, BUILT_IN_TOOLS, isBuiltInTool } from "./tools/registry.js";
 export type { TErrorEvent, TRelayEvent, TSessionMetaEvent, TTextEvent, TThinkingEvent, TToolResultEvent, TToolUseEvent, TTurnCompleteEvent, } from "./types/events.js";
-export type { IClaudeOptions, ISessionOptions, IToolHandler } from "./types/options.js";
+export type { IAskOptions, IClaudeOptions, ISessionOptions, IToolHandler } from "./types/options.js";
 export type { TClaudeContent, TClaudeContentType, TClaudeEvent, TClaudeEventType, TClaudeMessage, TModelUsageEntry } from "./types/protocol.js";
-export type { TAskResult, TCostSnapshot } from "./types/results.js";
+export type { TAskResult, TCostSnapshot, TTokens } from "./types/results.js";
 export { writer } from "./writer.js";
 export declare const claude: import("./client.js").IClaudeClient;

package/dist/index.js

@@ -2,15 +2,22 @@ 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, KNOWN_ERROR_CODES, KnownError, ProcessError, TimeoutError, } from "./errors.js";
+export { AbortError, BudgetExceededError, ClaudeError, errorMessage, isKnownError, isTransientError, KNOWN_ERROR_CODES, KnownError, ProcessError, TimeoutError, } from "./errors.js";
+export { JsonValidationError, parseAndValidate, stripFences } from "./json.js";
 export { blockFingerprint, extractContent, parseDoubleEncoded } from "./parser/content.js";
 export { parseLine } from "./parser/ndjson.js";
 export { createTranslator } from "./parser/translator.js";
-export { buildArgs, resetBinaryCache, spawnClaude } from "./process.js";
+export { buildArgs, resetResolvedEnvCache, spawnClaude } from "./process.js";
 export { readNdjsonEvents } from "./reader.js";
 export { createSession } from "./session.js";
+export { classifyStderr } from "./stderr.js";
 export { createStream } from "./stream.js";
 export { createToolHandler } from "./tools/handler.js";
-export { BUILT_IN_TOOLS, isBuiltInTool } from "./tools/registry.js";
+export { BUILT_IN_TOOL_NAMES, BUILT_IN_TOOLS, isBuiltInTool } from "./tools/registry.js";
 export { writer } from "./writer.js";
+// Wire the stderr classifier into the error factory at module load so
+// processExitedEarly can auto-promote ProcessError -> KnownError.
+import { setStderrClassifier } from "./errors.js";
+import { classifyStderr as _classifyStderr } from "./stderr.js";
+setStderrClassifier(_classifyStderr);
 export const claude = createClient();

package/dist/json.d.ts

@@ -0,0 +1,35 @@
+import { ClaudeError } from "./errors.js";
+export interface IStandardSchema<T = unknown> {
+    "~standard": {
+        version: 1;
+        vendor: string;
+        validate: (value: unknown) => IStandardResult<T>;
+    };
+}
+interface IStandardResult<T> {
+    value?: T;
+    issues?: ReadonlyArray<{
+        message?: string;
+        path?: ReadonlyArray<string | number>;
+    }>;
+}
+export declare class JsonValidationError extends ClaudeError {
+    readonly rawText: string;
+    readonly issues: ReadonlyArray<{
+        message?: string;
+        path?: ReadonlyArray<string | number>;
+    }>;
+    constructor(message: string, rawText: string, issues: ReadonlyArray<{
+        message?: string;
+        path?: ReadonlyArray<string | number>;
+    }>);
+}
+export interface IJsonResult<T> {
+    data: T;
+    raw: import("./types/results.js").TAskResult;
+}
+export declare const stripFences: (text: string) => string;
+export type TSchemaInput<T> = IStandardSchema<T> | string;
+export declare const isStandardSchema: <T>(schema: TSchemaInput<T>) => schema is IStandardSchema<T>;
+export declare const parseAndValidate: <T>(text: string, schema: TSchemaInput<T>) => T;
+export {};

package/dist/json.js

@@ -0,0 +1,43 @@
+import { ClaudeError } from "./errors.js";
+export class JsonValidationError extends ClaudeError {
+    rawText;
+    issues;
+    constructor(message, rawText, issues) {
+        super(message);
+        this.rawText = rawText;
+        this.issues = issues;
+        this.name = "JsonValidationError";
+    }
+}
+// Strip common fences: ```json ... ```, ``` ... ```, or bare JSON.
+const FENCE_RE = /^\s*```(?:json)?\s*\n?([\s\S]*?)\n?\s*```\s*$/;
+export const stripFences = (text) => {
+    const match = text.match(FENCE_RE);
+    return match?.[1] ?? text.trim();
+};
+export const isStandardSchema = (schema) => {
+    return typeof schema === "object" && schema !== null && "~standard" in schema;
+};
+export const parseAndValidate = (text, schema) => {
+    const stripped = stripFences(text);
+    let parsed;
+    try {
+        parsed = JSON.parse(stripped);
+    }
+    catch (err) {
+        throw new JsonValidationError(`Failed to parse JSON from Claude response: ${err instanceof Error ? err.message : String(err)}`, text, [
+            { message: "Invalid JSON" },
+        ]);
+    }
+    if (isStandardSchema(schema)) {
+        const result = schema["~standard"].validate(parsed);
+        if (result.issues && result.issues.length > 0) {
+            const summary = result.issues.map((i) => i.message ?? "validation error").join("; ");
+            throw new JsonValidationError(`Schema validation failed: ${summary}`, text, result.issues);
+        }
+        return result.value;
+    }
+    // Raw JSON Schema string -- no runtime validation, just parse. The CLI's
+    // --json-schema constrains the model output, so we trust it here.
+    return parsed;
+};

package/dist/parser/translator.js

@@ -7,7 +7,12 @@ const extractTokens = (modelUsage) => {
         for (const entry of Object.values(modelUsage)) {
             inputTokens = (inputTokens ?? 0) + entry.inputTokens + (entry.cacheReadInputTokens ?? 0) + (entry.cacheCreationInputTokens ?? 0);
             outputTokens = (outputTokens ?? 0) + entry.outputTokens;
-            contextWindow = entry.contextWindow;
+            // Multi-model turns (e.g. sub-agent fan-out) report distinct windows
+            // per model. Take max so consumers see the widest context available,
+            // not whichever model happened to iterate last.
+            if (entry.contextWindow !== undefined && (contextWindow === undefined || entry.contextWindow > contextWindow)) {
+                contextWindow = entry.contextWindow;
+            }
         }
     }
     return { inputTokens, outputTokens, contextWindow };
@@ -50,7 +55,7 @@ const translateContentBlock = (block) => {
                 type: "tool_use",
                 toolUseId: block.id,
                 toolName: block.name,
-                input: typeof block.input === "string" ? block.input : JSON.stringify(block.input ?? {}),
+                input: block.input ?? {},
             };
         }
         case "tool_result": {

package/dist/pipeline.d.ts

@@ -1,8 +1,18 @@
 import type { ICostTracker } from "./cost.js";
-import type { IClaudeProcess } from "./process.js";
+import type { IClaudeProcess, ISpawnOptions } from "./process.js";
+import { type IStderrDrain } from "./reader.js";
 import type { IToolHandlerInstance } from "./tools/handler.js";
-import type { TRelayEvent, TToolUseEvent } from "./types/events.js";
-import type { TAskResult } from "./types/results.js";
-export declare const dispatchToolDecision: (proc: IClaudeProcess, toolHandler: IToolHandlerInstance, event: TToolUseEvent) => Promise<void>;
+import type { TRelayEvent, TToolUseEvent, TTurnCompleteEvent } from "./types/events.js";
+import type { TAskResult, TCostSnapshot } from "./types/results.js";
+import type { TWarn } from "./warnings.js";
+interface IPipeline {
+    proc: IClaudeProcess;
+    reader: ReadableStreamDefaultReader<Uint8Array>;
+    stderr: IStderrDrain;
+}
+export declare const startPipeline: (options: ISpawnOptions) => IPipeline;
+export declare const dispatchToolDecision: (proc: IClaudeProcess, toolHandler: IToolHandlerInstance, event: TToolUseEvent, onWarning?: TWarn) => Promise<void>;
+export declare const applyTurnComplete: (event: TTurnCompleteEvent, costTracker: ICostTracker, offsets?: TCostSnapshot) => void;
 export declare const extractText: (events: TRelayEvent[]) => string;
 export declare const buildResult: (events: TRelayEvent[], costTracker: ICostTracker, sessionId: string | undefined) => TAskResult;
+export {};

package/dist/pipeline.js

@@ -1,31 +1,51 @@
+import { safeWrite, spawnClaude } from "./process.js";
+import { drainStderr } from "./reader.js";
+import { createWarn } from "./warnings.js";
 import { writer } from "./writer.js";
-export const dispatchToolDecision = async (proc, toolHandler, event) => {
+// Shared process-boot: spawn the CLI, lock the stdout reader, drain
+// stderr. session.ts and stream.ts both need this exact trio; keeping
+// the order in one place prevents the "one forgot to drain stderr and
+// the other swallows exits silently" class of bug.
+export const startPipeline = (options) => {
+    const proc = spawnClaude(options);
+    const reader = proc.stdout.getReader();
+    const stderr = drainStderr(proc);
+    return { proc, reader, stderr };
+};
+export const dispatchToolDecision = async (proc, toolHandler, event, onWarning) => {
+    const warn = createWarn(onWarning);
     let decision;
     try {
         decision = await toolHandler.decide(event);
     }
     catch (error) {
-        console.warn(`[claude-wire] Tool handler threw, defaulting to deny: ${error instanceof Error ? error.message : String(error)}`);
+        warn("Tool handler threw, defaulting to deny", error);
         decision = "deny";
     }
-    try {
-        if (decision === "approve") {
-            proc.write(writer.approve(event.toolUseId));
-        }
-        else if (decision === "deny") {
-            proc.write(writer.deny(event.toolUseId));
-        }
-        else if (typeof decision === "object" && decision !== null && typeof decision.result === "string") {
-            proc.write(writer.toolResult(event.toolUseId, decision.result));
-        }
-        else {
-            console.warn("[claude-wire] Invalid tool decision, defaulting to deny");
-            proc.write(writer.deny(event.toolUseId));
-        }
+    if (decision === "approve") {
+        safeWrite(proc, writer.approve(event.toolUseId));
+    }
+    else if (decision === "deny") {
+        safeWrite(proc, writer.deny(event.toolUseId));
     }
-    catch {
-        // stdin closed - process died, error will surface through read path
+    else if (typeof decision === "object" && decision !== null && typeof decision.result === "string") {
+        const isError = "isError" in decision ? decision.isError : undefined;
+        safeWrite(proc, writer.toolResult(event.toolUseId, decision.result, isError ? { isError: true } : undefined));
     }
+    else {
+        warn("Invalid tool decision, defaulting to deny");
+        safeWrite(proc, writer.deny(event.toolUseId));
+    }
+};
+// Applies a turn_complete event's cumulative totals to the cost tracker
+// and enforces the budget. `offsets` covers session's respawn case where
+// the new process starts its cumulative count from zero but the session
+// wants to carry forward what previous processes already spent -- stream
+// has no such concept and passes it undefined.
+export const applyTurnComplete = (event, costTracker, offsets) => {
+    const base = offsets ?? { totalUsd: 0, tokens: { input: 0, output: 0 } };
+    costTracker.update(base.totalUsd + (event.costUsd ?? 0), base.tokens.input + (event.inputTokens ?? 0), base.tokens.output + (event.outputTokens ?? 0));
+    costTracker.checkBudget();
 };
 export const extractText = (events) => {
     return events
@@ -39,7 +59,7 @@ export const buildResult = (events, costTracker, sessionId) => {
     return {
         text: extractText(events),
         costUsd: snap.totalUsd,
-        tokens: { input: snap.inputTokens, output: snap.outputTokens },
+        tokens: snap.tokens,
         duration: tc?.durationMs ?? 0,
         sessionId,
         events,