claude-agent-sdk 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acfb2780cc551ed4ff8cd1d96286636dd2d8d24b1ca3d34b93eadf15d1bbf49c
-  data.tar.gz: b3857039975c72fbf730e261831783db37efd00706bf30b2863b2feeceb58b3a
+  metadata.gz: 8934de13efa22ba9e3e679393dfb3ef39e8eed194a9db4af8ef5981c8fa66570
+  data.tar.gz: 79bfbe222fb677a49be4249e00bdc5148a43e9e0a9bac8e9e4e7fa7d3a34abd7
 SHA512:
-  metadata.gz: fa211da2013526662038143ed0cc7e04639a1821e5de8fdd7a6cc305f4d30fe495dd7b827796fd6e85e98612c61df2335120cbd2938a74736b1d31840719cf0f
-  data.tar.gz: 1bf84df24c779a99dbeeea776e00e53dc131bb2aca21a3bb2658ea7c3a972222bbfb0abef7d0ef48ec402490bd992074b82d7f806b8c3a98eb616f9d76421d20
+  metadata.gz: c3c722b1a6ab8ff9ca7484a7b6fd59c1d60660d6fb1e111864c2afe81852bb913c5cc9bf241eb7ad635686b9d1dd8cc6ff849f2a2b6acf2eec3546c09e0e7de2
+  data.tar.gz: 2ae9442e915901908b5c48496a348479685273701182a18ace8a20402b1e15c8630b38fd82f2ea480bf97af4e5c25c697711f5ffcc768bf15868081b9b5f24e4

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:

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 = [
@@ -326,35 +333,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.0'
 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.0
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2026-02-06 00:00:00.000000000 Z
+date: 2026-02-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async