@pivanov/claude-wire 0.0.3 → 0.0.4

package/README.md

@@ -25,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** - 16.2 kB gzipped
+- **Zero dependencies** - 25.6 kB gzipped
 
 ## Install
 
@@ -37,6 +37,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 +67,7 @@ apps/examples/          interactive example runner
 
 ```bash
 bun install
-bun run test        # 147 tests
+bun run test        # 192 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/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,4 +1,5 @@
 import type { TCostSnapshot } from "./types/results.js";
+import type { TWarn } from "./warnings.js";
 export interface ICostTracker {
     update: (totalCostUsd: number, totalInputTokens: number, totalOutputTokens: number) => void;
     snapshot: () => TCostSnapshot;
@@ -8,5 +9,6 @@ export interface ICostTracker {
 export interface ICostTrackerOptions {
     maxCostUsd?: number;
     onCostUpdate?: (cost: TCostSnapshot) => void;
+    onWarning?: TWarn;
 }
 export declare const createCostTracker: (options?: ICostTrackerOptions) => ICostTracker;

package/dist/cost.js

@@ -1,6 +1,9 @@
-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;
@@ -18,7 +21,7 @@ export const createCostTracker = (options = {}) => {
                 options.onCostUpdate(snapshot());
             }
             catch (error) {
-                console.warn("[claude-wire] onCostUpdate callback threw:", error instanceof Error ? error.message : error);
+                warn("onCostUpdate callback threw", error);
             }
         }
     };

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"];
 export type TKnownErrorCode = (typeof KNOWN_ERROR_CODES)[number];
 export declare class KnownError extends ClaudeError {
     readonly code: TKnownErrorCode;
@@ -25,4 +25,4 @@ 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;
+export declare const processExitedEarly: (stderr: string, exitCode?: number) => ProcessError;

package/dist/errors.js

@@ -34,7 +34,10 @@ 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"];
 export class KnownError extends ClaudeError {
     code;
     constructor(code, message) {
@@ -46,7 +49,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 +70,8 @@ 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.
+export const processExitedEarly = (stderr, exitCode) => new ProcessError(stderr || "Process exited without completing the turn", exitCode);

package/dist/index.d.ts

@@ -4,13 +4,13 @@ export { BINARY, LIMITS, TIMEOUTS } from "./constants.js";
 export type { 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 { 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";
@@ -19,9 +19,10 @@ 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 { writer } from "./writer.js";

package/dist/index.js

@@ -2,15 +2,15 @@ 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 { 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 { 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";
 export const claude = createClient();

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 };

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, inputTokens: 0, outputTokens: 0 };
+    costTracker.update(base.totalUsd + (event.costUsd ?? 0), base.inputTokens + (event.inputTokens ?? 0), base.outputTokens + (event.outputTokens ?? 0));
+    costTracker.checkBudget();
 };
 export const extractText = (events) => {
     return events

package/dist/process.d.ts

@@ -1,7 +1,7 @@
 import type { IClaudeOptions } from "./types/options.js";
 export interface IClaudeProcess {
     write: (message: string) => void;
-    kill: () => void;
+    kill: (signal?: NodeJS.Signals | number) => void;
     exited: Promise<number>;
     stdout: ReadableStream<Uint8Array>;
     stderr: ReadableStream<Uint8Array>;
@@ -10,8 +10,20 @@ export interface IClaudeProcess {
 export interface ISpawnOptions extends IClaudeOptions {
     prompt?: string;
 }
+export declare const safeKill: (proc: Pick<IClaudeProcess, "kill">, signal?: NodeJS.Signals | number) => void;
+export declare const safeWrite: (proc: Pick<IClaudeProcess, "write">, line: string) => boolean;
 export declare const ALIAS_PATTERN: RegExp;
-export declare const resolveConfigDirFromAlias: () => string | undefined;
-export declare const resetBinaryCache: () => void;
+/**
+ * Clears the cached resolved environment (binary path + alias-detected
+ * `CLAUDE_CONFIG_DIR`). Call this when either has changed mid-process -- for
+ * example after installing the Claude CLI during a test run, or when a long-
+ * running daemon updates the user's shell rc file. The next `spawnClaude()`
+ * will re-resolve from scratch.
+ *
+ * Normal applications should never need this; the cache is populated once at
+ * first use and kept for the process lifetime.
+ */
+export declare const resetResolvedEnvCache: () => void;
 export declare const buildArgs: (options: ISpawnOptions, binaryPath: string) => string[];
+export declare const buildSpawnEnv: (baseEnv: Record<string, string | undefined>, aliasConfigDir: string | undefined, options: Pick<ISpawnOptions, "configDir" | "env">) => Record<string, string | undefined> | undefined;
 export declare const spawnClaude: (options: ISpawnOptions) => IClaudeProcess;

package/dist/process.js

@@ -2,16 +2,41 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { BINARY } from "./constants.js";
-import { assertPositiveNumber, errorMessage, KnownError, ProcessError } from "./errors.js";
-import { fileExists, spawnProcess, whichSync } from "./runtime.js";
+import { errorMessage, KnownError, ProcessError } from "./errors.js";
+import { isExecutableNonEmpty, spawnProcess, whichSync } from "./runtime.js";
+import { assertPositiveNumber } from "./validation.js";
 import { writer } from "./writer.js";
+// Swallow ESRCH/EPIPE-style throws from kill()/write() when the child is
+// already gone. Every call site had the same try/catch -- keeping it in one
+// place stops future adders from forgetting the guard.
+export const safeKill = (proc, signal) => {
+    try {
+        proc.kill(signal);
+    }
+    catch {
+        // already dead
+    }
+};
+export const safeWrite = (proc, line) => {
+    try {
+        proc.write(line);
+        return true;
+    }
+    catch {
+        // stdin closed / process died -- caller surfaces the error via the read path
+        return false;
+    }
+};
+// Resolves the `claude` CLI binary path. POSIX-only today: uses `which` and
+// `$HOME`-rooted common install paths. Windows users running under WSL get
+// the Linux layout, which works; native Windows is not supported yet.
 const resolveBinaryPath = () => {
     const found = whichSync("claude");
     if (found) {
         return found;
     }
     for (const p of BINARY.commonPaths) {
-        if (fileExists(p)) {
+        if (isExecutableNonEmpty(p)) {
             return p;
         }
     }
@@ -20,9 +45,12 @@ const resolveBinaryPath = () => {
 // 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 resolveConfigDirFromAlias = () => {
     const home = homedir();
-    const rcFiles = [".zshrc", ".bashrc", ".zprofile", ".bash_profile", ".aliases"];
+    // .zshenv is the one file zsh sources for NON-interactive shells, so
+    // users who export CLAUDE_CONFIG_DIR for cron/CI-like contexts often
+    // put it there. Include it alongside the interactive-shell rc files.
+    const rcFiles = [".zshenv", ".zshrc", ".bashrc", ".zprofile", ".bash_profile", ".aliases"];
     for (const rcFile of rcFiles) {
         try {
             const content = readFileSync(join(home, rcFile), "utf-8");
@@ -38,7 +66,17 @@ export const resolveConfigDirFromAlias = () => {
     return undefined;
 };
 let cached;
-export const resetBinaryCache = () => {
+/**
+ * Clears the cached resolved environment (binary path + alias-detected
+ * `CLAUDE_CONFIG_DIR`). Call this when either has changed mid-process -- for
+ * example after installing the Claude CLI during a test run, or when a long-
+ * running daemon updates the user's shell rc file. The next `spawnClaude()`
+ * will re-resolve from scratch.
+ *
+ * Normal applications should never need this; the cache is populated once at
+ * first use and kept for the process lifetime.
+ */
+export const resetResolvedEnvCache = () => {
     cached = undefined;
 };
 const resolve = () => {
@@ -62,6 +100,9 @@ export const buildArgs = (options, binaryPath) => {
             args.push(name, value);
         }
     };
+    // Default ON: the translator's block-dedup relies on --verbose emitting
+    // cumulative assistant content. Consumers must explicitly pass `false`
+    // to opt out (`undefined` still yields --verbose).
     flag(options.verbose !== false, "--verbose");
     kv(options.model, "--model");
     kv(options.systemPrompt, "--system-prompt");
@@ -103,36 +144,56 @@ export const buildArgs = (options, binaryPath) => {
     flag(options.disableSlashCommands, "--disable-slash-commands");
     return args;
 };
+// Priority (lowest → highest): baseEnv < alias-detected config <
+// user's explicit `options.env` < explicit `options.configDir`. User
+// input always outranks the alias heuristic. Returns undefined when no
+// override is needed, so spawnProcess can pass the parent env through.
+export const buildSpawnEnv = (baseEnv, aliasConfigDir, options) => {
+    const needsEnv = aliasConfigDir || options.configDir || options.env;
+    if (!needsEnv) {
+        return undefined;
+    }
+    const spawnEnv = { ...baseEnv };
+    if (aliasConfigDir) {
+        spawnEnv.CLAUDE_CONFIG_DIR = aliasConfigDir;
+    }
+    if (options.env) {
+        Object.assign(spawnEnv, options.env);
+    }
+    if (options.configDir) {
+        spawnEnv.CLAUDE_CONFIG_DIR = options.configDir;
+    }
+    return spawnEnv;
+};
 export const spawnClaude = (options) => {
     assertPositiveNumber(options.maxBudgetUsd, "maxBudgetUsd");
     const resolved = resolve();
     const args = buildArgs(options, resolved.binaryPath);
     try {
-        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 (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;
-            }
-        }
+        const spawnEnv = buildSpawnEnv(process.env, resolved.aliasConfigDir, options);
         const rawProc = spawnProcess(args, { cwd: options.cwd, env: spawnEnv });
         rawProc.exited.catch(() => { });
+        // Tear the child down when the caller's signal aborts. Without this,
+        // a signal that fires BEFORE stdout emits anything leaves the reader
+        // loop to eventually notice -- the child keeps running in the meantime.
+        // Register FIRST, then re-check `aborted`: closes the gap where abort
+        // could fire between the check and listener attach. `once: true` lets
+        // the listener be GC'd after firing.
+        if (options.signal) {
+            const onAbort = () => {
+                safeKill(rawProc);
+            };
+            options.signal.addEventListener("abort", onAbort, { once: true });
+            if (options.signal.aborted) {
+                safeKill(rawProc);
+            }
+        }
         const claudeProc = {
             write: (msg) => {
                 rawProc.stdin.write(msg);
             },
-            kill: () => {
-                rawProc.kill();
+            kill: (signal) => {
+                rawProc.kill(signal);
             },
             exited: rawProc.exited,
             stdout: rawProc.stdout,

package/dist/reader.d.ts

@@ -2,16 +2,19 @@ import type { ITranslator } from "./parser/translator.js";
 import type { IClaudeProcess } from "./process.js";
 import type { IToolHandlerInstance } from "./tools/handler.js";
 import type { TRelayEvent } from "./types/events.js";
+import type { TWarn } from "./warnings.js";
 export interface IReaderOptions {
     reader: ReadableStreamDefaultReader<Uint8Array>;
     translator: ITranslator;
     toolHandler?: IToolHandlerInstance;
     proc?: IClaudeProcess;
     signal?: AbortSignal;
+    onWarning?: TWarn;
 }
 export interface IStderrDrain {
     chunks: string[];
     done: Promise<void>;
+    text: () => string;
 }
 export declare const drainStderr: (proc: {
     stderr: ReadableStream<Uint8Array>;