@pivanov/claude-wire 0.0.2 → 0.0.4

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** - 25.6 kB gzipped
 
 ## Install
 
@@ -38,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
@@ -66,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/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

@@ -1,12 +1,16 @@
 export declare const TIMEOUTS: {
     readonly defaultAbortMs: 300000;
     readonly gracefulExitMs: 5000;
+    readonly stderrDrainGraceMs: 500;
 };
 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 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,12 +2,22 @@ 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,
     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];
+// 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;
@@ -17,8 +20,8 @@ export const createCostTracker = (options = {}) => {
             try {
                 options.onCostUpdate(snapshot());
             }
-            catch {
-                // user callback error - don't crash the stream/session
+            catch (error) {
+                warn("onCostUpdate callback threw", 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", "permission-denied", "retry-exhausted"];
+export type TKnownErrorCode = (typeof KNOWN_ERROR_CODES)[number];
 export declare class KnownError extends ClaudeError {
     readonly code: TKnownErrorCode;
     constructor(code: TKnownErrorCode, message?: string);
@@ -25,5 +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 {};
+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";
     }
 }
-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,14 +49,20 @@ 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;
+// 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]);
 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);
@@ -61,8 +70,8 @@ export const isTransientError = (error) => {
 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`);
-    }
-};
+// 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

@@ -3,13 +3,14 @@ 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, 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";
@@ -18,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

@@ -1,16 +1,16 @@
+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, 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";
-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

@@ -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 };
@@ -41,13 +46,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/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,6 +10,20 @@ export interface IClaudeProcess {
 export interface ISpawnOptions extends IClaudeOptions {
     prompt?: string;
 }
-export declare const resetBinaryCache: () => void;
+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;
+/**
+ * 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;