open-claude-agent-sdk 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 open-claude contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# Open Claude Agent SDK
+
+A compatible open-source replacement for `@anthropic-ai/claude-agent-sdk` — thin wrapper that uses your local Claude CLI.
+
+## Why?
+
+| | Open SDK | Official SDK |
+|---|---|---|
+| **Source** | Open, readable TypeScript | Closed, minified |
+| **How it works** | Spawns local CLI | Bundles CLI |
+| **Debuggable** | Breakpoints, source maps | Minified blob |
+| **AI-friendly** | Agents can read source | Agents can't parse minified code |
+| **Type compatible** | Yes (re-exports) | - |
+| **Streaming** | Yes | Yes |
+| **Multi-turn** | Yes | Yes |
+| **MCP servers** | Yes | Yes |
+| **Subagents** | Yes | Yes |
+| **Hooks** | Yes | Yes |
+
+Same API, same types — open and debuggable.
+
+## Install
+
+```bash
+bun add open-claude-agent-sdk
+
+# Requires Claude CLI
+npm install -g @anthropic-ai/claude-code
+```
+
+## Usage
+
+```typescript
+import { query } from 'open-claude-agent-sdk';
+
+for await (const msg of query({
+  prompt: 'Write a haiku about coding',
+  options: { maxTurns: 3 }
+})) {
+  if (msg.type === 'assistant') {
+    console.log(msg.message.content);
+  }
+  if (msg.type === 'result') break;
+}
+```
+
+Drop-in replacement — just change the import:
+
+```diff
+- import { query } from '@anthropic-ai/claude-agent-sdk';
++ import { query } from 'open-claude-agent-sdk';
+```
+
+## Features
+
+### Core
+
+- **Query modes** — one-shot, multi-turn (AsyncIterable + streamInput), streaming
+- **Control methods** — interrupt, close, setModel, setPermissionMode, setMaxThinkingTokens
+- **Query methods** — supportedCommands, supportedModels, accountInfo, mcpServerStatus
+- **Structured outputs** — JSON schema with `outputFormat`
+- **Extended thinking** — `maxThinkingTokens` option
+- **System prompts** — string, preset (`claude_code`), preset with append
+- **Permission callbacks** — `canUseTool` with allow/deny/selective/async
+- **AbortController** — signal-based cancellation
+- **Session management** — resume, fork, continue, custom sessionId
+- **Cost tracking** — `total_cost_usd`, usage, modelUsage
+
+### MCP Servers
+
+- **In-process SDK servers** — `createSdkMcpServer()` + `tool()` helper with Zod schemas
+- **Process-based servers** — stdio MCP server config via `mcpServers` option
+- **Control methods** — `reconnectMcpServer()`, `toggleMcpServer()`, `setMcpServers()`
+
+### Subagents & Hooks
+
+- **Programmatic subagents** — `agents` option, Task tool invocation, `parent_tool_use_id`
+- **Hooks** — 10 of 15 events tested E2E (PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStart, SubagentStop, plus matchers)
+- **Skills & commands** — via `settingSources` + `.claude/` directories
+- **Output styles** — custom styles via `.claude/output-styles/`
+- **Sandbox** — sandbox configuration pass-through
+
+### Open SDK Extensions
+
+Extra convenience methods beyond the official SDK:
+
+```typescript
+import { query, type ExtendedQuery } from 'open-claude-agent-sdk';
+
+const q = query({ prompt: '...' }) as ExtendedQuery;
+
+await q.availableOutputStyles(); // string[]
+await q.currentOutputStyle();    // string
+```
+
+### Not Yet Implemented
+
+- `rewindFiles()` — no CLI protocol support
+- Agent teams — experimental, no env var support
+- V2 API (`unstable_v2_*`) — experimental preview
+
+See [FEATURES.md](./docs/planning/FEATURES.md) for full status matrix.
+
+## Demos
+
+Three demo apps ported from the official SDK, running on both SDKs:
+
+```bash
+# Hello world
+bun demos/open/hello-world/hello-world.ts
+
+# Interactive chat (has its own dev server)
+cd demos/open/simple-chatapp && npm install && npm run dev
+
+# Resume generator
+bun demos/open/resume-generator/resume-generator.ts
+```
+
+## Testing
+
+```bash
+# Integration tests (primary)
+bun test tests/integration/
+
+# Unit tests (SDK compatibility)
+bun test tests/unit/
+
+# Type check
+bun run typecheck
+```
+
+## Documentation
+
+- [API Reference](./docs/api/API.md) — query function, message types, examples
+- [Options Reference](./docs/api/OPTIONS.md) — all query options
+- [Feature Matrix](./docs/planning/FEATURES.md) — full feature comparison
+- [Migration Guide](./docs/guides/MIGRATION.md) — migrate from official SDK
+
+## License
+
+MIT

package/dist/api/MessageQueue.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Generic async message queue with iterator protocol support
+ *
+ * Handles the producer-consumer pattern for streaming messages:
+ * - Producer: pushes messages via push()
+ * - Consumer: awaits messages via next() (AsyncIterator protocol)
+ *
+ * @internal
+ */
+export declare class MessageQueue<T> {
+    private queue;
+    private waiters;
+    private done;
+    private error;
+    /**
+     * Add a message to the queue
+     * If there are waiting consumers, resolves the first one immediately
+     */
+    push(item: T): void;
+    /**
+     * Mark the queue as complete (no more messages)
+     * @param error Optional error to propagate to consumers
+     */
+    complete(error?: Error): void;
+    /**
+     * Get the next message (AsyncIterator protocol)
+     * Waits if no messages are available
+     */
+    next(): Promise<IteratorResult<T>>;
+    /**
+     * Check if the queue is completed
+     */
+    isDone(): boolean;
+    /**
+     * Get the current error (if any)
+     */
+    getError(): Error | null;
+}
+//# sourceMappingURL=MessageQueue.d.ts.map

package/dist/api/MessageQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageQueue.d.ts","sourceRoot":"","sources":["../../src/api/MessageQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,qBAAa,YAAY,CAAC,CAAC;IACzB,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,OAAO,CAGP;IACR,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,KAAK,CAAsB;IAEnC;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAanB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI;IAkB7B;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAuBxC;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;OAEG;IACH,QAAQ,IAAI,KAAK,GAAG,IAAI;CAGzB"}

package/dist/api/MessageQueue.js

@@ -0,0 +1,90 @@
+/**
+ * Generic async message queue with iterator protocol support
+ *
+ * Handles the producer-consumer pattern for streaming messages:
+ * - Producer: pushes messages via push()
+ * - Consumer: awaits messages via next() (AsyncIterator protocol)
+ *
+ * @internal
+ */
+export class MessageQueue {
+    queue = [];
+    waiters = [];
+    done = false;
+    error = null;
+    /**
+     * Add a message to the queue
+     * If there are waiting consumers, resolves the first one immediately
+     */
+    push(item) {
+        if (this.done)
+            return; // Ignore pushes after completion
+        // If someone is waiting, resolve immediately
+        if (this.waiters.length > 0) {
+            // biome-ignore lint/style/noNonNullAssertion: length > 0 guarantees shift returns a value
+            const waiter = this.waiters.shift();
+            waiter.resolve({ value: item, done: false });
+        }
+        else {
+            this.queue.push(item);
+        }
+    }
+    /**
+     * Mark the queue as complete (no more messages)
+     * @param error Optional error to propagate to consumers
+     */
+    complete(error) {
+        if (this.done)
+            return;
+        this.done = true;
+        this.error = error ?? null;
+        // Resolve all waiting consumers
+        const waiters = this.waiters.splice(0);
+        for (const waiter of waiters) {
+            if (this.error) {
+                waiter.reject(this.error);
+            }
+            else {
+                // biome-ignore lint/suspicious/noExplicitAny: IteratorResult requires undefined for done=true
+                waiter.resolve({ value: undefined, done: true });
+            }
+        }
+    }
+    /**
+     * Get the next message (AsyncIterator protocol)
+     * Waits if no messages are available
+     */
+    async next() {
+        // Return from queue if available
+        if (this.queue.length > 0) {
+            // biome-ignore lint/style/noNonNullAssertion: length > 0 guarantees shift returns a value
+            const item = this.queue.shift();
+            return { value: item, done: false };
+        }
+        // If done, return completion or throw error
+        if (this.done) {
+            if (this.error) {
+                throw this.error;
+            }
+            // biome-ignore lint/suspicious/noExplicitAny: IteratorResult requires undefined for done=true
+            return { value: undefined, done: true };
+        }
+        // Wait for next message
+        return new Promise((resolve, reject) => {
+            this.waiters.push({ resolve, reject });
+        });
+    }
+    /**
+     * Check if the queue is completed
+     */
+    isDone() {
+        return this.done;
+    }
+    /**
+     * Get the current error (if any)
+     */
+    getError() {
+        return this.error;
+    }
+}
+//# sourceMappingURL=MessageQueue.js.map

package/dist/api/MessageQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageQueue.js","sourceRoot":"","sources":["../../src/api/MessageQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,OAAO,YAAY;IACf,KAAK,GAAQ,EAAE,CAAC;IAChB,OAAO,GAGV,EAAE,CAAC;IACA,IAAI,GAAG,KAAK,CAAC;IACb,KAAK,GAAiB,IAAI,CAAC;IAEnC;;;OAGG;IACH,IAAI,CAAC,IAAO;QACV,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO,CAAC,iCAAiC;QAExD,6CAA6C;QAC7C,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,0FAA0F;YAC1F,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAG,CAAC;YACrC,MAAM,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/C,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,KAAa;QACpB,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO;QAEtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,IAAI,IAAI,CAAC;QAE3B,gCAAgC;QAChC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC5B,CAAC;iBAAM,CAAC;gBACN,8FAA8F;gBAC9F,MAAM,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,SAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI;QACR,iCAAiC;QACjC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,0FAA0F;YAC1F,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAG,CAAC;YACjC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACtC,CAAC;QAED,4CAA4C;QAC5C,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,CAAC,KAAK,CAAC;YACnB,CAAC;YACD,8FAA8F;YAC9F,OAAO,EAAE,KAAK,EAAE,SAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACjD,CAAC;QAED,wBAAwB;QACxB,OAAO,IAAI,OAAO,CAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF"}

package/dist/api/MessageRouter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Message router for stdout processing
+ *
+ * Reads NDJSON from stdout and routes messages:
+ * - control_request → controlHandler
+ * - control_response → filtered (internal protocol)
+ * - regular messages → onMessage callback
+ *
+ * @internal
+ */
+import type { Readable } from 'node:stream';
+import type { ControlProtocolHandler } from '../core/control.ts';
+import type { SDKMessage } from '../types/index.ts';
+export type MessageCallback = (msg: SDKMessage) => void;
+export type DoneCallback = (error?: Error) => void;
+export type ControlResponsePayload = {
+    subtype: string;
+    request_id: string;
+    response?: Record<string, unknown>;
+    error?: string;
+};
+export type ControlResponseCallback = (response: ControlResponsePayload) => void;
+export declare class MessageRouter {
+    private stdout;
+    private controlHandler;
+    private onMessage;
+    private onDone;
+    private onControlResponse?;
+    private readline;
+    constructor(stdout: Readable, controlHandler: ControlProtocolHandler, onMessage: MessageCallback, onDone: DoneCallback, onControlResponse?: ControlResponseCallback | undefined);
+    /**
+     * Start reading from stdout and routing messages
+     * This runs in the background until the stream ends
+     */
+    startReading(): Promise<void>;
+    /**
+     * Close the readline interface
+     */
+    close(): void;
+}
+//# sourceMappingURL=MessageRouter.d.ts.map

package/dist/api/MessageRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageRouter.d.ts","sourceRoot":"","sources":["../../src/api/MessageRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,CAAC;AACxD,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC;AACnD,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,QAAQ,EAAE,sBAAsB,KAAK,IAAI,CAAC;AAMjF,qBAAa,aAAa;IAItB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,iBAAiB,CAAC;IAP5B,OAAO,CAAC,QAAQ,CAA0B;gBAGhC,MAAM,EAAE,QAAQ,EAChB,cAAc,EAAE,sBAAsB,EACtC,SAAS,EAAE,eAAe,EAC1B,MAAM,EAAE,YAAY,EACpB,iBAAiB,CAAC,EAAE,uBAAuB,YAAA;IAGrD;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAwDnC;;OAEG;IACH,KAAK,IAAI,IAAI;CAMd"}

package/dist/api/MessageRouter.js

@@ -0,0 +1,95 @@
+/**
+ * Message router for stdout processing
+ *
+ * Reads NDJSON from stdout and routes messages:
+ * - control_request → controlHandler
+ * - control_response → filtered (internal protocol)
+ * - regular messages → onMessage callback
+ *
+ * @internal
+ */
+import { createInterface } from 'node:readline';
+import { MessageType } from "../types/control.js";
+export class MessageRouter {
+    stdout;
+    controlHandler;
+    onMessage;
+    onDone;
+    onControlResponse;
+    readline = null;
+    constructor(stdout, controlHandler, onMessage, onDone, onControlResponse) {
+        this.stdout = stdout;
+        this.controlHandler = controlHandler;
+        this.onMessage = onMessage;
+        this.onDone = onDone;
+        this.onControlResponse = onControlResponse;
+    }
+    /**
+     * Start reading from stdout and routing messages
+     * This runs in the background until the stream ends
+     */
+    async startReading() {
+        try {
+            this.readline = createInterface({
+                input: this.stdout,
+                crlfDelay: Infinity,
+            });
+            for await (const line of this.readline) {
+                if (!line.trim())
+                    continue;
+                // Debug: log raw line
+                if (process.env.DEBUG_HOOKS) {
+                    console.error('[DEBUG] Raw line:', line.substring(0, 200));
+                }
+                try {
+                    const msg = JSON.parse(line);
+                    // Debug: log message type
+                    if (process.env.DEBUG_HOOKS) {
+                        console.error('[DEBUG] Message type:', msg.type);
+                    }
+                    if (msg.type === MessageType.CONTROL_REQUEST) {
+                        if (process.env.DEBUG_HOOKS) {
+                            console.error('[DEBUG] !!! CONTROL REQUEST !!!:', msg.request?.subtype);
+                        }
+                        // Handle control request internally (don't yield to user)
+                        await this.controlHandler.handleControlRequest(msg);
+                    }
+                    else if (msg.type === MessageType.CONTROL_RESPONSE) {
+                        // Route control_response to callback if provided, otherwise filter silently
+                        if (process.env.DEBUG_HOOKS) {
+                            console.error('[DEBUG] control_response received');
+                        }
+                        if (this.onControlResponse) {
+                            this.onControlResponse(msg.response);
+                        }
+                    }
+                    else {
+                        // Regular message - pass to callback
+                        this.onMessage(msg);
+                    }
+                }
+                catch (parseError) {
+                    // Log but don't crash on parse errors
+                    const errMsg = parseError instanceof Error ? parseError.message : String(parseError);
+                    console.error('Failed to parse line:', line.substring(0, 200), '-', errMsg);
+                }
+            }
+        }
+        catch (err) {
+            this.onDone(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        // Stream ended normally
+        this.onDone();
+    }
+    /**
+     * Close the readline interface
+     */
+    close() {
+        if (this.readline) {
+            this.readline.close();
+            this.readline = null;
+        }
+    }
+}
+//# sourceMappingURL=MessageRouter.js.map

package/dist/api/MessageRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageRouter.js","sourceRoot":"","sources":["../../src/api/MessageRouter.ts"],"names":[],"mappings":"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"}

package/dist/api/ProcessFactory.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Process factory for dependency injection
+ *
+ * Allows unit tests to inject mock processes without spawning real CLI.
+ *
+ * @internal
+ */
+import type { ChildProcess } from 'node:child_process';
+import type { Options } from '../types/index.ts';
+/**
+ * Interface for creating CLI processes
+ * Allows dependency injection for testing
+ */
+export interface ProcessFactory {
+    spawn(options: Options): ChildProcess;
+}
+/**
+ * Default implementation that spawns real Claude CLI
+ */
+export declare class DefaultProcessFactory implements ProcessFactory {
+    spawn(options: Options): ChildProcess;
+}
+//# sourceMappingURL=ProcessFactory.d.ts.map

package/dist/api/ProcessFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessFactory.d.ts","sourceRoot":"","sources":["../../src/api/ProcessFactory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,CAAC;CACvC;AAiBD;;GAEG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAC1D,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY;CAmFtC"}

package/dist/api/ProcessFactory.js

@@ -0,0 +1,103 @@
+/**
+ * Process factory for dependency injection
+ *
+ * Allows unit tests to inject mock processes without spawning real CLI.
+ *
+ * @internal
+ */
+import { buildCliArgs } from "../core/argBuilder.js";
+import { detectClaudeBinary, spawnClaude } from "../core/spawn.js";
+/**
+ * Check if a path is a native binary (not a JS file)
+ * Matches official SDK: if NOT .js/.mjs/.tsx/.ts/.jsx, it's a native binary
+ */
+function isNativeBinary(path) {
+    return !['.js', '.mjs', '.tsx', '.ts', '.jsx'].some((ext) => path.endsWith(ext));
+}
+/**
+ * Get default JavaScript runtime
+ */
+function getDefaultExecutable() {
+    return typeof process.versions.bun !== 'undefined' ? 'bun' : 'node';
+}
+/**
+ * Default implementation that spawns real Claude CLI
+ */
+export class DefaultProcessFactory {
+    spawn(options) {
+        const args = buildCliArgs({ ...options, prompt: '' });
+        // Build environment with enableFileCheckpointing support
+        const env = { ...(options.env ?? {}) };
+        if (options.enableFileCheckpointing) {
+            env.CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING = 'true';
+        }
+        // Custom spawn function takes priority
+        if (options.spawnClaudeCodeProcess) {
+            const scriptPath = detectClaudeBinary(options);
+            const native = isNativeBinary(scriptPath);
+            const executable = options.executable ?? getDefaultExecutable();
+            const executableArgs = options.executableArgs ?? [];
+            const command = native ? scriptPath : executable;
+            const spawnArgs = native
+                ? [...executableArgs, ...args]
+                : [...executableArgs, scriptPath, ...args];
+            // Build full env for SpawnOptions
+            const fullEnv = { ...process.env, ...env };
+            if (!fullEnv.CLAUDE_CODE_ENTRYPOINT)
+                fullEnv.CLAUDE_CODE_ENTRYPOINT = 'sdk-ts';
+            delete fullEnv.NODE_OPTIONS;
+            if (fullEnv.DEBUG_CLAUDE_AGENT_SDK)
+                fullEnv.DEBUG = '1';
+            else
+                delete fullEnv.DEBUG;
+            const spawnedProcess = options.spawnClaudeCodeProcess({
+                command,
+                args: spawnArgs,
+                cwd: options.cwd,
+                env: fullEnv,
+                signal: AbortSignal.timeout(3600000), // 1 hour default
+            });
+            // Wrap SpawnedProcess to ChildProcess-compatible object
+            return spawnedProcess;
+        }
+        const scriptPath = detectClaudeBinary(options);
+        // When executable is explicitly set, use it as the command with script as arg
+        if (options.executable) {
+            const executableArgs = options.executableArgs ?? [];
+            const fullArgs = [...executableArgs, scriptPath, ...args];
+            return spawnClaude(options.executable, fullArgs, {
+                cwd: options.cwd,
+                env,
+                stderr: options.stderr,
+            });
+        }
+        // Default: use detected binary directly (shebang handles runtime)
+        const executableArgs = options.executableArgs ?? [];
+        if (isNativeBinary(scriptPath)) {
+            // Native binary: command is the binary, executableArgs before CLI args
+            const fullArgs = [...executableArgs, ...args];
+            return spawnClaude(scriptPath, fullArgs, {
+                cwd: options.cwd,
+                env,
+                stderr: options.stderr,
+            });
+        }
+        // JS file with executableArgs: need explicit runtime
+        if (executableArgs.length > 0) {
+            const executable = getDefaultExecutable();
+            const fullArgs = [...executableArgs, scriptPath, ...args];
+            return spawnClaude(executable, fullArgs, {
+                cwd: options.cwd,
+                env,
+                stderr: options.stderr,
+            });
+        }
+        // JS file without executableArgs: use script directly (shebang handles runtime)
+        return spawnClaude(scriptPath, args, {
+            cwd: options.cwd,
+            env,
+            stderr: options.stderr,
+        });
+    }
+}
+//# sourceMappingURL=ProcessFactory.js.map

package/dist/api/ProcessFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessFactory.js","sourceRoot":"","sources":["../../src/api/ProcessFactory.ts"],"names":[],"mappings":"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"}