claude-agent-sdk 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8934de13efa22ba9e3e679393dfb3ef39e8eed194a9db4af8ef5981c8fa66570
-  data.tar.gz: 79bfbe222fb677a49be4249e00bdc5148a43e9e0a9bac8e9e4e7fa7d3a34abd7
+  metadata.gz: 8044b53b9c1c89e75c789b94a1ca000bb4a4a6e94d380bef3ded209585517b29
+  data.tar.gz: a3effbef7a3cbf1faed47cecb6f69df37e17266eabae7e56a556855b85707c4f
 SHA512:
-  metadata.gz: c3c722b1a6ab8ff9ca7484a7b6fd59c1d60660d6fb1e111864c2afe81852bb913c5cc9bf241eb7ad635686b9d1dd8cc6ff849f2a2b6acf2eec3546c09e0e7de2
-  data.tar.gz: 2ae9442e915901908b5c48496a348479685273701182a18ace8a20402b1e15c8630b38fd82f2ea480bf97af4e5c25c697711f5ffcc768bf15868081b9b5f24e4
+  metadata.gz: 3c9360caa6e3fc1ffa7d359e4d2195aecf003e1fc37655bfe15355efc2dce3cfd896f30a0b7bdc504a88d90056bab05b7ad2a90c33f0ad03867abcaf0ccb16a7
+  data.tar.gz: 68059199d80d3f10ff03b18b6fbb505348070f8a1a53d8d00cd56550fdfe7c337a4b53d39d7e41d0238c954dd2106656c6f8eaf6e39b5ac516278ac4c7c57ff4

data/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.2] - 2026-02-17
+
+### Fixed
+- **Large prompt `Errno::E2BIG` crash:** Prompts exceeding 200KB are now piped via stdin instead of passed as CLI arguments, avoiding the OS `ARG_MAX` limit (typically 1MB on macOS/Linux). This fixes `CLIConnectionError: Failed to start Claude Code: Argument list too long` when using `query()` with large prompts.
+- **Stderr pipe deadlock (`Errno::EPIPE`):** Always drain stderr in a background thread, even when `stderr` option is not set. Without this, `--verbose` output fills the 64KB OS pipe buffer, the subprocess blocks on write, and all pipes stall. Previously only manifested with long-running Opus sessions.
+
 ## [0.6.0] - 2026-02-13
 
 ### Added

data/README.md

@@ -996,15 +996,18 @@ end
 # Base exception class for all SDK errors
 class ClaudeSDKError < StandardError; end
 
+# Raised when connection to Claude Code fails
+class CLIConnectionError < ClaudeSDKError; end
+
+# Raised when the control protocol does not respond in time
+class ControlRequestTimeoutError < CLIConnectionError; end
+
 # Raised when Claude Code CLI is not found
 class CLINotFoundError < CLIConnectionError
   # @param message [String] Error message (default: "Claude Code not found")
   # @param cli_path [String, nil] Optional path to the CLI that was not found
 end
 
-# Raised when connection to Claude Code fails
-class CLIConnectionError < ClaudeSDKError; end
-
 # Raised when the Claude Code process fails
 class ProcessError < ClaudeSDKError
   attr_reader :exit_code,  # Integer | nil
@@ -1027,6 +1030,7 @@ end
 
 | Type | Description |
 |------|-------------|
+| `Configuration` | Global defaults via `ClaudeAgentSDK.configure` block |
 | `ClaudeAgentOptions` | Main configuration for queries and clients |
 | `HookMatcher` | Hook configuration with matcher pattern and timeout |
 | `PermissionResultAllow` | Permission callback result to allow tool use |
@@ -1088,6 +1092,8 @@ begin
   ClaudeAgentSDK.query(prompt: "Hello") do |message|
     puts message
   end
+rescue ClaudeAgentSDK::ControlRequestTimeoutError
+  puts "Control protocol timed out — consider increasing the timeout"
 rescue ClaudeAgentSDK::CLINotFoundError
   puts "Please install Claude Code"
 rescue ClaudeAgentSDK::ProcessError => e
@@ -1097,13 +1103,23 @@ rescue ClaudeAgentSDK::CLIJSONDecodeError => e
 end
 ```
 
+#### Configuring Timeout
+
+The control request timeout defaults to **1200 seconds** (20 minutes) to accommodate long-running agent sessions. Override it via environment variable:
+
+```bash
+# Set a custom timeout (in seconds)
+export CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS=300  # 5 minutes
+```
+
 ### Error Types
 
 | Error | Description |
 |-------|-------------|
 | `ClaudeSDKError` | Base error for all SDK errors |
-| `CLINotFoundError` | Claude Code not installed |
 | `CLIConnectionError` | Connection issues |
+| `ControlRequestTimeoutError` | Control protocol timeout (configurable via env var) |
+| `CLINotFoundError` | Claude Code not installed |
 | `ProcessError` | Process failed (includes `exit_code` and `stderr`) |
 | `CLIJSONDecodeError` | JSON parsing issues |
 | `MessageParseError` | Message parsing issues |

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -13,6 +13,11 @@ module ClaudeAgentSDK
     DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024 # 1MB buffer limit
     MINIMUM_CLAUDE_CODE_VERSION = '2.0.0'
 
+    # Prompts larger than this are piped via stdin instead of CLI args
+    # to avoid Errno::E2BIG (ARG_MAX is typically 1MB on macOS/Linux,
+    # shared with environment variables).
+    PROMPT_STDIN_THRESHOLD = 200 * 1024 # 200KB
+
     def initialize(prompt, options)
       @prompt = prompt
       @is_streaming = !prompt.is_a?(String)
@@ -27,6 +32,7 @@ module ClaudeAgentSDK
       @exit_error = nil
       @max_buffer_size = options.max_buffer_size || DEFAULT_MAX_BUFFER_SIZE
       @stderr_task = nil
+      @pipe_prompt_via_stdin = false
     end
 
     def find_cli
@@ -245,6 +251,11 @@ module ClaudeAgentSDK
       # Prompt handling
       if @is_streaming
         cmd.concat(['--input-format', 'stream-json'])
+      elsif @prompt.to_s.bytesize > PROMPT_STDIN_THRESHOLD
+        # Large prompts are piped via stdin to avoid OS argument size limits.
+        # Claude CLI reads from stdin when --print is used without a trailing argument.
+        cmd << '--print'
+        @pipe_prompt_via_stdin = true
       else
         cmd.concat(['--print', '--', @prompt.to_s])
       end
@@ -262,7 +273,9 @@ module ClaudeAgentSDK
       # Build environment
       # Convert symbol keys to strings for spawn compatibility
       custom_env = @options.env.transform_keys { |k| k.to_s }
-      process_env = ENV.to_h.merge('CLAUDE_AGENT_SDK_VERSION' => VERSION).merge(custom_env)
+      # Strip CLAUDECODE to prevent "nested session" detection when the SDK
+      # launches Claude Code from within an existing Claude Code terminal
+      process_env = ENV.to_h.except('CLAUDECODE').merge('CLAUDE_AGENT_SDK_VERSION' => VERSION).merge(custom_env)
       process_env['CLAUDE_CODE_ENTRYPOINT'] ||= 'sdk-rb'
       process_env['PWD'] = @cwd.to_s if @cwd
 
@@ -275,15 +288,32 @@ module ClaudeAgentSDK
 
         @stdin, @stdout, @stderr, @process = Open3.popen3(process_env, *cmd, opts)
 
-        # Handle stderr if piped
-        if should_pipe_stderr && @stderr
-          @stderr_task = Thread.new do
-            handle_stderr
-          rescue StandardError
-            # Ignore errors during stderr reading
+        # Always drain stderr to prevent pipe buffer deadlock.
+        # Without this, --verbose output fills the OS pipe buffer (~64KB),
+        # the subprocess blocks on write, and all pipes stall → EPIPE.
+        if @stderr
+          if should_pipe_stderr
+            @stderr_task = Thread.new do
+              handle_stderr
+            rescue StandardError
+              # Ignore errors during stderr reading
+            end
+          else
+            # Silently drain stderr so the subprocess never blocks
+            @stderr_task = Thread.new do
+              @stderr.each_line { |_| } # discard
+            rescue StandardError
+              # Ignore — process may have already exited
+            end
           end
         end
 
+        # For large prompts, pipe the prompt text to stdin before closing.
+        # This avoids Errno::E2BIG when the prompt exceeds ARG_MAX.
+        if @pipe_prompt_via_stdin && @stdin
+          @stdin.write(@prompt.to_s)
+        end
+
         # Close stdin for non-streaming mode
         @stdin.close unless @is_streaming
         @stdin = nil unless @is_streaming

data/lib/claude_agent_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '0.6.0'
+  VERSION = '0.6.2'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.2
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2026-02-12 00:00:00.000000000 Z
+date: 2026-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async