claude-agent-sdk 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acfb2780cc551ed4ff8cd1d96286636dd2d8d24b1ca3d34b93eadf15d1bbf49c
-  data.tar.gz: b3857039975c72fbf730e261831783db37efd00706bf30b2863b2feeceb58b3a
+  metadata.gz: 74a467e8e7f814ad55325db2de60cee2bd1f7a8bd849945b28302cf7776db2b9
+  data.tar.gz: b0c9dc121f7500f314ebe03ba77db2e16a112c60222a7e7d50ca68897d36af41
 SHA512:
-  metadata.gz: fa211da2013526662038143ed0cc7e04639a1821e5de8fdd7a6cc305f4d30fe495dd7b827796fd6e85e98612c61df2335120cbd2938a74736b1d31840719cf0f
-  data.tar.gz: 1bf84df24c779a99dbeeea776e00e53dc131bb2aca21a3bb2658ea7c3a972222bbfb0abef7d0ef48ec402490bd992074b82d7f806b8c3a98eb616f9d76421d20
+  metadata.gz: 5c6b145098e0e8489838f4d9b6e1a3f0af50a18e20a15055497fca65c1922e6f0e556bfb1e1844720989b81811eaf50d1605392d4d6bbf500fe367cbd744c172
+  data.tar.gz: 7ca8630977ebe60f00d8592c993d80eab1cc9754a1190dbd579b239a6f8ee105c48bbf3e5fe3b1aaa3da26c6ea62f369ee00d040d48eab002253f27aecee26a5

data/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.0] - 2026-02-13
+
+### Added
+- **Configurable control request timeout:** New `CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS` environment variable (default 1200s) for tuning the control protocol timeout — essential for long-running agent sessions and agent teams
+- **`ControlRequestTimeoutError`:** Dedicated error class (`< CLIConnectionError`) raised on control request timeouts, enabling typed exception handling instead of string matching
+
+### Fixed
+- **camelCase `requestId` fallback:** All control message routing (`read_messages`, `handle_control_response`, `handle_control_request`) now tolerates both `request_id` and `requestId` keys from the CLI
+- **Outbound `requestId` parity:** Control requests and responses now include both `request_id` and `requestId` for maximum CLI compatibility
+- **Pending request unblocking:** Transport errors now signal all pending control request conditions, preventing callers from hanging until timeout
+- **Error object in message queue:** `read_messages` rescue now enqueues the exception object (not just `e.message`), preserving error class for typed handling
+- **Thread-safe CLI discovery:** `find_cli` uses `Open3.capture2` instead of backtick shell for thread safety
+- **Robust process cleanup:** `close` now uses SIGTERM → 2s grace period → SIGKILL escalation (was immediate SIGTERM with no fallback), handles `Errno::ESRCH` for already-dead processes, and logs cleanup warnings instead of silently swallowing errors
+
 ## [0.5.0] - 2026-02-07
 
 ### Added

data/README.md

@@ -38,7 +38,7 @@ Add this line to your application's Gemfile:
 gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
 
 # Or use a stable version from RubyGems
-gem 'claude-agent-sdk', '~> 0.5.0'
+gem 'claude-agent-sdk', '~> 0.6.0'
 ```
 
 And then execute:
@@ -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/errors.rb

@@ -7,6 +7,9 @@ module ClaudeAgentSDK
   # Raised when unable to connect to Claude Code
   class CLIConnectionError < ClaudeSDKError; end
 
+  # Raised when the control protocol does not respond in time
+  class ControlRequestTimeoutError < CLIConnectionError; end
+
   # Raised when Claude Code is not found or not installed
   class CLINotFoundError < CLIConnectionError
     def initialize(message = 'Claude Code not found', cli_path: nil)

data/lib/claude_agent_sdk/query.rb

@@ -6,6 +6,7 @@ require 'async/queue'
 require 'async/condition'
 require 'securerandom'
 require_relative 'transport'
+require_relative 'errors'
 
 module ClaudeAgentSDK
   # Handles bidirectional control protocol on top of Transport
@@ -19,6 +20,9 @@ module ClaudeAgentSDK
   class Query
     attr_reader :transport, :is_streaming_mode, :sdk_mcp_servers
 
+    CONTROL_REQUEST_TIMEOUT_ENV_VAR = 'CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS'
+    DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS = 1200.0
+
     def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil)
       @transport = transport
       @is_streaming_mode = is_streaming_mode
@@ -95,6 +99,16 @@ module ClaudeAgentSDK
 
     private
 
+    def control_request_timeout_seconds
+      raw_value = ENV.fetch(CONTROL_REQUEST_TIMEOUT_ENV_VAR, nil)
+      return DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS if raw_value.nil? || raw_value.strip.empty?
+
+      value = Float(raw_value)
+      value.positive? ? value : DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS
+    rescue ArgumentError
+      DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS
+    end
+
     def read_messages
       @transport.read_messages do |message|
         break if @closed
@@ -106,7 +120,7 @@ module ClaudeAgentSDK
         when 'control_response'
           handle_control_response(message)
         when 'control_request'
-          request_id = message[:request_id]
+          request_id = message[:request_id] || message[:requestId]
           task = Async do
             begin
               handle_control_request(message)
@@ -126,8 +140,14 @@ module ClaudeAgentSDK
         end
       end
     rescue StandardError => e
+      # Unblock pending control requests (e.g., initialize) so callers don't hang until timeout.
+      @pending_control_responses.dup.each do |request_id, condition|
+        @pending_control_results[request_id] ||= e
+        condition.signal
+      end
+
       # Put error in queue so iterators can handle it
-      @message_queue.enqueue({ type: 'error', error: e.message })
+      @message_queue.enqueue({ type: 'error', error: e })
     ensure
       # Always signal end of stream
       @message_queue.enqueue({ type: 'end' })
@@ -135,7 +155,7 @@ module ClaudeAgentSDK
 
     def handle_control_response(message)
       response = message[:response] || {}
-      request_id = response[:request_id]
+      request_id = response[:request_id] || response[:requestId] || message[:request_id] || message[:requestId]
       return unless @pending_control_responses.key?(request_id)
 
       if response[:subtype] == 'error'
@@ -149,7 +169,7 @@ module ClaudeAgentSDK
     end
 
     def handle_control_request(request)
-      request_id = request[:request_id]
+      request_id = request[:request_id] || request[:requestId]
       request_data = request[:request]
       subtype = request_data[:subtype]
 
@@ -172,6 +192,7 @@ module ClaudeAgentSDK
         response: {
           subtype: 'success',
           request_id: request_id,
+          requestId: request_id,
           response: response_data
         }
       }
@@ -183,6 +204,7 @@ module ClaudeAgentSDK
         response: {
           subtype: 'error',
           request_id: request_id,
+          requestId: request_id,
           error: 'Cancelled'
         }
       }
@@ -194,6 +216,7 @@ module ClaudeAgentSDK
         response: {
           subtype: 'error',
           request_id: request_id,
+          requestId: request_id,
           error: e.message
         }
       }
@@ -398,6 +421,8 @@ module ClaudeAgentSDK
     def send_control_request(request)
       raise 'Control requests require streaming mode' unless @is_streaming_mode
 
+      timeout_seconds = control_request_timeout_seconds
+
       # Generate unique request ID
       @request_counter += 1
       request_id = "req_#{@request_counter}_#{SecureRandom.hex(4)}"
@@ -410,14 +435,15 @@ module ClaudeAgentSDK
       control_request = {
         type: 'control_request',
         request_id: request_id,
+        requestId: request_id,
         request: request
       }
 
       @transport.write(JSON.generate(control_request) + "\n")
 
-      # Wait for response with timeout
+      # Wait for response with timeout (default 1200s to handle slow CLI startup)
       Async do |task|
-        task.with_timeout(60.0) do
+        task.with_timeout(timeout_seconds) do
           condition.wait
         end
 
@@ -431,7 +457,7 @@ module ClaudeAgentSDK
     rescue Async::TimeoutError
       @pending_control_responses.delete(request_id)
       @pending_control_results.delete(request_id)
-      raise "Control request timeout: #{request[:subtype]}"
+      raise ControlRequestTimeoutError, "Control request timeout: #{request[:subtype]}"
     end
 
     def handle_sdk_mcp_request(server_name, message)

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'open3'
+require 'timeout'
 require_relative 'transport'
 require_relative 'errors'
 require_relative 'version'
@@ -29,9 +30,15 @@ module ClaudeAgentSDK
     end
 
     def find_cli
-      # Try which command first
-      cli = `which claude 2>/dev/null`.strip
-      return cli unless cli.empty?
+      # Try which command first (using Open3 for thread safety)
+      cli = nil
+      begin
+        stdout, _status = Open3.capture2('which', 'claude')
+        cli = stdout.strip
+      rescue StandardError
+        # which command failed, try common locations
+      end
+      return cli if cli && !cli.empty? && File.executable?(cli)
 
       # Try common locations
       locations = [
@@ -255,7 +262,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
 
@@ -326,35 +335,67 @@ module ClaudeAgentSDK
       @ready = false
       return unless @process
 
+      cleanup_errors = []
+
       # Kill stderr thread
       if @stderr_task&.alive?
-        @stderr_task.kill
-        @stderr_task.join(1) rescue nil
+        begin
+          @stderr_task.kill
+          @stderr_task.join(1)
+        rescue StandardError => e
+          cleanup_errors << "stderr thread: #{e.message}"
+        end
       end
 
       # Close streams
       begin
         @stdin&.close
-      rescue StandardError
-        # Ignore
+      rescue IOError
+        # Already closed, ignore
+      rescue StandardError => e
+        cleanup_errors << "stdin: #{e.message}"
       end
+
       begin
         @stdout&.close
-      rescue StandardError
-        # Ignore
+      rescue IOError
+        # Already closed, ignore
+      rescue StandardError => e
+        cleanup_errors << "stdout: #{e.message}"
       end
+
       begin
         @stderr&.close
-      rescue StandardError
-        # Ignore
+      rescue IOError
+        # Already closed, ignore
+      rescue StandardError => e
+        cleanup_errors << "stderr: #{e.message}"
       end
 
       # Terminate process
       begin
-        Process.kill('TERM', @process.pid) if @process.alive?
-        @process.value
-      rescue StandardError
-        # Ignore
+        if @process.alive?
+          Process.kill('TERM', @process.pid)
+          # Wait briefly for graceful shutdown
+          Timeout.timeout(2) { @process.value }
+        end
+      rescue Timeout::Error
+        # Force kill if graceful shutdown failed
+        begin
+          Process.kill('KILL', @process.pid)
+          @process.value
+        rescue StandardError => e
+          cleanup_errors << "force kill: #{e.message}"
+        end
+      rescue Errno::ESRCH
+        # Process already dead, ignore
+      rescue StandardError => e
+        cleanup_errors << "process termination: #{e.message}"
+      end
+
+      # Log any cleanup errors (non-fatal)
+      if cleanup_errors.any?
+        warn "Claude SDK: Cleanup warnings: #{cleanup_errors.join(', ')}"
       end
 
       @process = nil

data/lib/claude_agent_sdk/version.rb

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

metadata

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