@anthropic-ai/claude-agent-sdk 0.1.63 → 0.1.66

package/sdk.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // (c) Anthropic PBC. All rights reserved. Use is subject to the Legal Agreements outlined here: https://code.claude.com/docs/en/legal-and-compliance.
 
-// Version: 0.1.63
+// Version: 0.1.66
 
 // Want to see the unminified source? We're hiring!
 // https://job-boards.greenhouse.io/anthropic/jobs/4816199008
@@ -7037,6 +7037,9 @@ var NodeFsOperations = {
   statSync(fsPath) {
     return withSlowLogging("statSync", () => fs.statSync(fsPath));
   },
+  lstatSync(fsPath) {
+    return withSlowLogging("lstatSync", () => fs.lstatSync(fsPath));
+  },
   readFileSync(fsPath, options) {
     return withSlowLogging("readFileSync", () => fs.readFileSync(fsPath, { encoding: options.encoding }));
   },
@@ -7238,9 +7241,9 @@ function mergeSandboxIntoExtraArgs(extraArgs, sandbox) {
 // ../src/transport/ProcessTransport.ts
 class ProcessTransport {
   options;
-  child;
-  childStdin;
-  childStdout;
+  process;
+  processStdin;
+  processStdout;
   ready = false;
   abortController;
   exitError;
@@ -7252,13 +7255,50 @@ class ProcessTransport {
     this.abortController = options.abortController || createAbortController();
     this.initialize();
   }
+  getDefaultExecutable() {
+    return isRunningWithBun() ? "bun" : "node";
+  }
+  spawnLocalProcess(spawnOptions) {
+    const { command, args, cwd: cwd2, env, signal } = spawnOptions;
+    const stderrMode = env.DEBUG_CLAUDE_AGENT_SDK || this.options.stderr ? "pipe" : "ignore";
+    const childProcess = spawn(command, args, {
+      cwd: cwd2,
+      stdio: ["pipe", "pipe", stderrMode],
+      signal,
+      env
+    });
+    if (env.DEBUG_CLAUDE_AGENT_SDK || this.options.stderr) {
+      childProcess.stderr.on("data", (data) => {
+        const message = data.toString();
+        logForSdkDebugging(message);
+        if (this.options.stderr) {
+          this.options.stderr(message);
+        }
+      });
+    }
+    const mappedProcess = {
+      stdin: childProcess.stdin,
+      stdout: childProcess.stdout,
+      get killed() {
+        return childProcess.killed;
+      },
+      get exitCode() {
+        return childProcess.exitCode;
+      },
+      kill: childProcess.kill.bind(childProcess),
+      on: childProcess.on.bind(childProcess),
+      once: childProcess.once.bind(childProcess),
+      off: childProcess.off.bind(childProcess)
+    };
+    return mappedProcess;
+  }
   initialize() {
     try {
       const {
         additionalDirectories = [],
         betas,
         cwd: cwd2,
-        executable = isRunningWithBun() ? "bun" : "node",
+        executable = this.getDefaultExecutable(),
         executableArgs = [],
         extraArgs = {},
         pathToClaudeCodeExecutable,
@@ -7278,6 +7318,7 @@ class ProcessTransport {
         settingSources,
         allowedTools = [],
         disallowedTools = [],
+        tools,
         mcpServers,
         strictMcpConfig,
         canUseTool,
@@ -7329,7 +7370,6 @@ class ProcessTransport {
       if (disallowedTools.length > 0) {
         args.push("--disallowedTools", disallowedTools.join(","));
       }
-      const { tools } = this.options;
       if (tools !== undefined) {
         if (Array.isArray(tools)) {
           if (tools.length === 0) {
@@ -7403,47 +7443,44 @@ class ProcessTransport {
       } else {
         delete env.DEBUG;
       }
-      const fs2 = getFsImplementation();
-      if (!fs2.existsSync(pathToClaudeCodeExecutable)) {
-        const errorMessage = isNativeBinary(pathToClaudeCodeExecutable) ? `Claude Code native binary not found at ${pathToClaudeCodeExecutable}. Please ensure Claude Code is installed via native installer or specify a valid path with options.pathToClaudeCodeExecutable.` : `Claude Code executable not found at ${pathToClaudeCodeExecutable}. Is options.pathToClaudeCodeExecutable set?`;
-        throw new ReferenceError(errorMessage);
-      }
       const isNative = isNativeBinary(pathToClaudeCodeExecutable);
       const spawnCommand = isNative ? pathToClaudeCodeExecutable : executable;
       const spawnArgs = isNative ? [...executableArgs, ...args] : [...executableArgs, pathToClaudeCodeExecutable, ...args];
-      const spawnMessage = isNative ? `Spawning Claude Code native binary: ${spawnCommand} ${spawnArgs.join(" ")}` : `Spawning Claude Code process: ${spawnCommand} ${spawnArgs.join(" ")}`;
-      logForSdkDebugging(spawnMessage);
-      if (stderr) {
-        stderr(spawnMessage);
-      }
-      const stderrMode = env.DEBUG_CLAUDE_AGENT_SDK || stderr ? "pipe" : "ignore";
-      this.child = spawn(spawnCommand, spawnArgs, {
+      const spawnOptions = {
+        command: spawnCommand,
+        args: spawnArgs,
         cwd: cwd2,
-        stdio: ["pipe", "pipe", stderrMode],
-        signal: this.abortController.signal,
-        env
-      });
-      this.childStdin = this.child.stdin;
-      this.childStdout = this.child.stdout;
-      if (env.DEBUG_CLAUDE_AGENT_SDK || stderr) {
-        this.child.stderr.on("data", (data) => {
-          const message = data.toString();
-          logForSdkDebugging(message);
-          if (stderr) {
-            stderr(message);
-          }
-        });
+        env,
+        signal: this.abortController.signal
+      };
+      if (this.options.spawnClaudeCodeProcess) {
+        logForSdkDebugging(`Spawning Claude Code (custom): ${spawnCommand} ${spawnArgs.join(" ")}`);
+        this.process = this.options.spawnClaudeCodeProcess(spawnOptions);
+      } else {
+        const fs2 = getFsImplementation();
+        if (!fs2.existsSync(pathToClaudeCodeExecutable)) {
+          const errorMessage = isNative ? `Claude Code native binary not found at ${pathToClaudeCodeExecutable}. Please ensure Claude Code is installed via native installer or specify a valid path with options.pathToClaudeCodeExecutable.` : `Claude Code executable not found at ${pathToClaudeCodeExecutable}. Is options.pathToClaudeCodeExecutable set?`;
+          throw new ReferenceError(errorMessage);
+        }
+        const spawnMessage = `Spawning Claude Code: ${spawnCommand} ${spawnArgs.join(" ")}`;
+        logForSdkDebugging(spawnMessage);
+        if (stderr) {
+          stderr(spawnMessage);
+        }
+        this.process = this.spawnLocalProcess(spawnOptions);
       }
+      this.processStdin = this.process.stdin;
+      this.processStdout = this.process.stdout;
       const cleanup = () => {
-        if (this.child && !this.child.killed) {
-          this.child.kill("SIGTERM");
+        if (this.process && !this.process.killed) {
+          this.process.kill("SIGTERM");
         }
       };
       this.processExitHandler = cleanup;
       this.abortHandler = cleanup;
       process.on("exit", this.processExitHandler);
       this.abortController.signal.addEventListener("abort", this.abortHandler);
-      this.child.on("error", (error) => {
+      this.process.on("error", (error) => {
         this.ready = false;
         if (this.abortController.signal.aborted) {
           this.exitError = new AbortError("Claude Code process aborted by user");
@@ -7452,7 +7489,7 @@ class ProcessTransport {
           logForSdkDebugging(this.exitError.message);
         }
       });
-      this.child.on("close", (code, signal) => {
+      this.process.on("exit", (code, signal) => {
         this.ready = false;
         if (this.abortController.signal.aborted) {
           this.exitError = new AbortError("Claude Code process aborted by user");
@@ -7482,10 +7519,10 @@ class ProcessTransport {
     if (this.abortController.signal.aborted) {
       throw new AbortError("Operation aborted");
     }
-    if (!this.ready || !this.childStdin) {
+    if (!this.ready || !this.processStdin) {
       throw new Error("ProcessTransport is not ready for writing");
     }
-    if (this.child?.killed || this.child?.exitCode !== null) {
+    if (this.process?.killed || this.process?.exitCode !== null) {
       throw new Error("Cannot write to terminated process");
     }
     if (this.exitError) {
@@ -7493,7 +7530,7 @@ class ProcessTransport {
     }
     logForSdkDebugging(`[ProcessTransport] Writing to stdin: ${data.substring(0, 100)}`);
     try {
-      const written = this.childStdin.write(data);
+      const written = this.processStdin.write(data);
       if (!written) {
         logForSdkDebugging("[ProcessTransport] Write buffer full, data queued");
       }
@@ -7503,40 +7540,40 @@ class ProcessTransport {
     }
   }
   close() {
-    if (this.childStdin) {
-      this.childStdin.end();
-      this.childStdin = undefined;
-    }
-    if (this.processExitHandler) {
-      process.off("exit", this.processExitHandler);
-      this.processExitHandler = undefined;
+    if (this.processStdin) {
+      this.processStdin.end();
+      this.processStdin = undefined;
     }
     if (this.abortHandler) {
       this.abortController.signal.removeEventListener("abort", this.abortHandler);
       this.abortHandler = undefined;
     }
     for (const { handler } of this.exitListeners) {
-      this.child?.off("exit", handler);
+      this.process?.off("exit", handler);
     }
     this.exitListeners = [];
-    if (this.child && !this.child.killed) {
-      this.child.kill("SIGTERM");
+    if (this.process && !this.process.killed) {
+      this.process.kill("SIGTERM");
       setTimeout(() => {
-        if (this.child && !this.child.killed) {
-          this.child.kill("SIGKILL");
+        if (this.process && !this.process.killed) {
+          this.process.kill("SIGKILL");
         }
       }, 5000);
     }
     this.ready = false;
+    if (this.processExitHandler) {
+      process.off("exit", this.processExitHandler);
+      this.processExitHandler = undefined;
+    }
   }
   isReady() {
     return this.ready;
   }
   async* readMessages() {
-    if (!this.childStdout) {
+    if (!this.processStdout) {
       throw new Error("ProcessTransport output stream not available");
     }
-    const rl = createInterface({ input: this.childStdout });
+    const rl = createInterface({ input: this.processStdout });
     try {
       for await (const line of rl) {
         if (line.trim()) {
@@ -7552,25 +7589,25 @@ class ProcessTransport {
     }
   }
   endInput() {
-    if (this.childStdin) {
-      this.childStdin.end();
+    if (this.processStdin) {
+      this.processStdin.end();
     }
   }
   getInputStream() {
-    return this.childStdin;
+    return this.processStdin;
   }
   onExit(callback) {
-    if (!this.child)
+    if (!this.process)
       return () => {};
     const handler = (code, signal) => {
       const error = this.getProcessExitError(code, signal);
       callback(error);
     };
-    this.child.on("exit", handler);
+    this.process.on("exit", handler);
     this.exitListeners.push({ callback, handler });
     return () => {
-      if (this.child) {
-        this.child.off("exit", handler);
+      if (this.process) {
+        this.process.off("exit", handler);
       }
       const index = this.exitListeners.findIndex((l) => l.handler === handler);
       if (index !== -1) {
@@ -7579,13 +7616,13 @@ class ProcessTransport {
     };
   }
   async waitForExit() {
-    if (!this.child) {
+    if (!this.process) {
       if (this.exitError) {
         throw this.exitError;
       }
       return;
     }
-    if (this.child.exitCode !== null || this.child.killed) {
+    if (this.process.exitCode !== null || this.process.killed) {
       if (this.exitError) {
         throw this.exitError;
       }
@@ -7604,14 +7641,14 @@ class ProcessTransport {
           resolve();
         }
       };
-      this.child.once("exit", exitHandler);
+      this.process.once("exit", exitHandler);
       const errorHandler = (error) => {
-        this.child.off("exit", exitHandler);
+        this.process.off("exit", exitHandler);
         reject(error);
       };
-      this.child.once("error", errorHandler);
-      this.child.once("exit", () => {
-        this.child.off("error", errorHandler);
+      this.process.once("error", errorHandler);
+      this.process.once("exit", () => {
+        this.process.off("error", errorHandler);
       });
     });
   }
@@ -8167,7 +8204,17 @@ class SessionImpl {
   query;
   queryIterator = null;
   abortController;
+  _sessionId = null;
+  get sessionId() {
+    if (this._sessionId === null) {
+      throw new Error("Session ID not available until after receiving messages");
+    }
+    return this._sessionId;
+  }
   constructor(options) {
+    if (options.resume) {
+      this._sessionId = options.resume;
+    }
     this.inputStream = new Stream;
     let pathToClaudeCodeExecutable = options.pathToClaudeCodeExecutable;
     if (!pathToClaudeCodeExecutable) {
@@ -8175,7 +8222,7 @@ class SessionImpl {
       const dirname2 = join4(filename, "..");
       pathToClaudeCodeExecutable = join4(dirname2, "cli.js");
     }
-    const processEnv = { ...process.env };
+    const processEnv = { ...options.env ?? process.env };
     if (!processEnv.CLAUDE_CODE_ENTRYPOINT) {
       processEnv.CLAUDE_CODE_ENTRYPOINT = "sdk-ts";
     }
@@ -8234,6 +8281,9 @@ class SessionImpl {
       if (done) {
         return;
       }
+      if (value.type === "system" && value.subtype === "init") {
+        this._sessionId = value.session_id;
+      }
       yield value;
       if (value.type === "result") {
         return;
@@ -15159,7 +15209,7 @@ function query({
     const dirname2 = join5(filename, "..");
     pathToClaudeCodeExecutable = join5(dirname2, "cli.js");
   }
-  process.env.CLAUDE_AGENT_SDK_VERSION = "0.1.63";
+  process.env.CLAUDE_AGENT_SDK_VERSION = "0.1.66";
   const {
     abortController = createAbortController(),
     additionalDirectories = [],
@@ -15261,7 +15311,8 @@ function query({
     includePartialMessages,
     persistSession,
     plugins,
-    sandbox
+    sandbox,
+    spawnClaudeCodeProcess: rest.spawnClaudeCodeProcess
   });
   const initConfig = {
     systemPrompt: customSystemPrompt,

package/transport/processTransportTypes.d.ts

@@ -0,0 +1,60 @@
+import type { Readable, Writable } from 'stream';
+/**
+ * Represents a spawned process with stdin/stdout streams and lifecycle management.
+ * Implementers provide this interface to abstract the process spawning mechanism.
+ * ChildProcess already satisfies this interface.
+ */
+export interface SpawnedProcess {
+    /** Writable stream for sending data to the process stdin */
+    stdin: Writable;
+    /** Readable stream for receiving data from the process stdout */
+    stdout: Readable;
+    /** Whether the process has been killed */
+    readonly killed: boolean;
+    /** Exit code if the process has exited, null otherwise */
+    readonly exitCode: number | null;
+    /**
+     * Kill the process with the given signal
+     * @param signal - The signal to send (e.g., 'SIGTERM', 'SIGKILL')
+     */
+    kill(signal: NodeJS.Signals): boolean;
+    /**
+     * Register a callback for when the process exits
+     * @param event - Must be 'exit'
+     * @param listener - Callback receiving exit code and signal
+     */
+    on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+    /**
+     * Register a callback for process errors
+     * @param event - Must be 'error'
+     * @param listener - Callback receiving the error
+     */
+    on(event: 'error', listener: (error: Error) => void): void;
+    /**
+     * Register a one-time callback for when the process exits
+     */
+    once(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+    once(event: 'error', listener: (error: Error) => void): void;
+    /**
+     * Remove an event listener
+     */
+    off(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+    off(event: 'error', listener: (error: Error) => void): void;
+}
+/**
+ * Options passed to the spawn function.
+ */
+export interface SpawnOptions {
+    /** Command to execute */
+    command: string;
+    /** Arguments to pass to the command */
+    args: string[];
+    /** Working directory */
+    cwd?: string;
+    /** Environment variables */
+    env: {
+        [envVar: string]: string | undefined;
+    };
+    /** Abort signal for cancellation */
+    signal: AbortSignal;
+}

package/transport/transport.d.ts

@@ -0,0 +1,30 @@
+import type { StdoutMessage } from '../entrypoints/sdkControlTypes.js';
+/**
+ * Transport interface for Claude Code SDK communication
+ * Abstracts the communication layer to support both process and WebSocket transports
+ */
+export interface Transport {
+    /**
+     * Write data to the transport
+     * May be async for network-based transports
+     */
+    write(data: string): void | Promise<void>;
+    /**
+     * Close the transport connection and clean up resources
+     * This also closes stdin if still open (eliminating need for endInput)
+     */
+    close(): void;
+    /**
+     * Check if transport is ready for communication
+     */
+    isReady(): boolean;
+    /**
+     * Read and parse messages from the transport
+     * Each transport handles its own protocol and error checking
+     */
+    readMessages(): AsyncGenerator<StdoutMessage, void, unknown>;
+    /**
+     * End the input stream
+     */
+    endInput(): void;
+}