claude-agent-sdk 0.4.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db31632430bb28dc8f07903bfc8634a8c437da9dc988f2237606948ecc71f7e0
-  data.tar.gz: e7574810137063aef37a0a78fb9d855645a0a479ba0b909b63a491f0ea7060f6
+  metadata.gz: 8934de13efa22ba9e3e679393dfb3ef39e8eed194a9db4af8ef5981c8fa66570
+  data.tar.gz: 79bfbe222fb677a49be4249e00bdc5148a43e9e0a9bac8e9e4e7fa7d3a34abd7
 SHA512:
-  metadata.gz: e394102a18bace179f7745b2b10cc721393ff25e8dcbc75f9492e6822aa6a80afa1455eb168b6567857cbf10a7d1d2e96e7293e43b043ad69ac2b41f95a3eb99
-  data.tar.gz: 03b94423b5d2369eb974e9cf82b2523e36aea4a09d05181e86528da11b3432d8685256705989210941b644333b5f9d3173b2efa0fd3b5f1b74e5e5aea3705bc6
+  metadata.gz: c3c722b1a6ab8ff9ca7484a7b6fd59c1d60660d6fb1e111864c2afe81852bb913c5cc9bf241eb7ad635686b9d1dd8cc6ff849f2a2b6acf2eec3546c09e0e7de2
+  data.tar.gz: 2ae9442e915901908b5c48496a348479685273701182a18ace8a20402b1e15c8630b38fd82f2ea480bf97af4e5c25c697711f5ffcc768bf15868081b9b5f24e4

data/CHANGELOG.md

@@ -5,6 +5,31 @@ 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
+- **Default configuration:** `ClaudeAgentSDK.configure` block for setting default options that merge with every `ClaudeAgentOptions` instance, ideal for Rails initializers (PR #8)
+- `ClaudeAgentSDK.reset_configuration` for resetting defaults (useful in tests)
+- Deep merge for `env` and `mcp_servers` hashes; provided values override configured defaults
+- `OPTION_DEFAULTS` constant on `ClaudeAgentOptions` for introspectable non-nil defaults
+
+### Changed
+- `ClaudeAgentOptions#initialize` now uses `**kwargs` internally to correctly distinguish caller-provided values from method signature defaults
+
 ## [0.4.2] - 2026-02-07
 
 ### Fixed

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.4.0'
+gem 'claude-agent-sdk', '~> 0.6.0'
 ```
 
 And then execute:

data/lib/claude_agent_sdk/configuration.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ClaudeAgentSDK
+  # Configuration class for setting default options
+  #
+  # Use this to set default options that will be merged with every request.
+  # This is especially useful in Rails applications where you want to
+  # configure defaults once during initialization.
+  #
+  # @example In a Rails initializer (config/initializers/claude_agent_sdk.rb)
+  #   ClaudeAgentSDK.configure do |config|
+  #     config.default_options = {
+  #       env: {
+  #         'ANTHROPIC_API_KEY' => ENV['ANTHROPIC_API_KEY'],
+  #         'CUSTOM_VAR' => 'value'
+  #       },
+  #       permission_mode: 'bypassPermissions',
+  #       model: 'sonnet'
+  #     }
+  #   end
+  #
+  # @example Then use ClaudeAgentSDK without repeating options
+  #   # env and other defaults will be automatically applied
+  #   ClaudeAgentSDK.query(prompt: "Hello!")
+  #
+  #   # You can still override defaults when needed
+  #   ClaudeAgentSDK.query(
+  #     prompt: "Hello!",
+  #     options: ClaudeAgentOptions.new(model: 'opus')  # overrides default
+  #   )
+  class Configuration
+    attr_accessor :default_options
+
+    def initialize
+      @default_options = {}
+    end
+  end
+
+  class << self
+    # Configure the SDK with default options
+    #
+    # @yield [Configuration] The configuration object
+    #
+    # @example Set default env and other options
+    #   ClaudeAgentSDK.configure do |config|
+    #     config.default_options = {
+    #       env: { 'API_KEY' => 'xxx' },
+    #       permission_mode: 'bypassPermissions'
+    #     }
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # Get the configuration object
+    #
+    # @return [Configuration] The current configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Reset configuration to defaults (useful for testing)
+    def reset_configuration
+      @configuration = Configuration.new
+    end
+
+    # Get merged default options for use with ClaudeAgentOptions
+    #
+    # @return [Hash] Default options hash
+    def default_options
+      configuration.default_options || {}
+    end
+  end
+end

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/types.rb

@@ -784,87 +784,62 @@ module ClaudeAgentSDK
                   :fallback_model, :plugins, :debug_stderr,
                   :betas, :tools, :sandbox, :enable_file_checkpointing, :append_allowed_tools
 
-    def initialize(
-      allowed_tools: [],
-      system_prompt: nil,
-      mcp_servers: {},
-      permission_mode: nil,
-      continue_conversation: false,
-      resume: nil,
-      max_turns: nil,
-      disallowed_tools: [],
-      model: nil,
-      permission_prompt_tool_name: nil,
-      cwd: nil,
-      cli_path: nil,
-      settings: nil,
-      add_dirs: [],
-      env: {},
-      extra_args: {},
-      max_buffer_size: nil,
-      stderr: nil,
-      can_use_tool: nil,
-      hooks: nil,
-      user: nil,
-      include_partial_messages: false,
-      fork_session: false,
-      agents: nil,
-      setting_sources: nil,
-      output_format: nil,
-      max_budget_usd: nil,
-      max_thinking_tokens: nil,
-      fallback_model: nil,
-      plugins: nil,
-      debug_stderr: nil,
-      betas: nil,
-      tools: nil,
-      sandbox: nil,
-      enable_file_checkpointing: false,
-      append_allowed_tools: nil
-    )
-      @allowed_tools = allowed_tools
-      @system_prompt = system_prompt
-      @mcp_servers = mcp_servers
-      @permission_mode = permission_mode
-      @continue_conversation = continue_conversation
-      @resume = resume
-      @max_turns = max_turns
-      @disallowed_tools = disallowed_tools
-      @model = model
-      @permission_prompt_tool_name = permission_prompt_tool_name
-      @cwd = cwd
-      @cli_path = cli_path
-      @settings = settings
-      @add_dirs = add_dirs
-      @env = env
-      @extra_args = extra_args
-      @max_buffer_size = max_buffer_size
-      @stderr = stderr
-      @can_use_tool = can_use_tool
-      @hooks = hooks
-      @user = user
-      @include_partial_messages = include_partial_messages
-      @fork_session = fork_session
-      @agents = agents
-      @setting_sources = setting_sources
-      @output_format = output_format # JSON schema for structured output
-      @max_budget_usd = max_budget_usd # Spending cap in dollars
-      @max_thinking_tokens = max_thinking_tokens # Extended thinking token budget
-      @fallback_model = fallback_model # Backup model if primary unavailable
-      @plugins = plugins # Array of SdkPluginConfig
-      @debug_stderr = debug_stderr # Debug output file object/path
-      @betas = betas # Array of beta feature strings (e.g., ["context-1m-2025-08-07"])
-      @tools = tools # Base tools selection: Array, empty array [], or ToolsPreset
-      @sandbox = sandbox # SandboxSettings instance for isolated command execution
-      @enable_file_checkpointing = enable_file_checkpointing # Enable file checkpointing for rewind support
-      @append_allowed_tools = append_allowed_tools # Array of tools to append to allowed_tools
+    # Non-nil defaults for options that need them.
+    # Keys absent from here default to nil.
+    OPTION_DEFAULTS = {
+      allowed_tools: [], disallowed_tools: [], add_dirs: [],
+      mcp_servers: {}, env: {}, extra_args: {},
+      continue_conversation: false, include_partial_messages: false,
+      fork_session: false, enable_file_checkpointing: false
+    }.freeze
+
+    # Valid option names derived from attr_accessor declarations.
+    VALID_OPTIONS = instance_methods.grep(/=\z/).map { |m| m.to_s.chomp('=').to_sym }.freeze
+
+    # Using **kwargs lets us distinguish "caller passed allowed_tools: []"
+    # from "caller omitted allowed_tools" — critical for correct merge with
+    # configured defaults.
+    def initialize(**kwargs)
+      unknown = kwargs.keys - VALID_OPTIONS
+      raise ArgumentError, "unknown keyword#{'s' if unknown.size > 1}: #{unknown.join(', ')}" if unknown.any?
+
+      merged = merge_with_defaults(kwargs)
+      OPTION_DEFAULTS.merge(merged).each do |key, value|
+        instance_variable_set(:"@#{key}", value)
+      end
     end
 
     def dup_with(**changes)
       new_options = self.dup
-      changes.each { |key, value| new_options.send("#{key}=", value) }
+      changes.each { |key, value| new_options.send(:"#{key}=", value) }
       new_options
     end
+
+    private
+
+    # Merge caller-provided kwargs with configured defaults.
+    # Only keys the caller explicitly passed are treated as overrides;
+    # method-signature defaults ([], {}, false) are NOT in kwargs unless the caller wrote them.
+    def merge_with_defaults(kwargs)
+      return OPTION_DEFAULTS.merge(kwargs) unless defined?(ClaudeAgentSDK) && ClaudeAgentSDK.respond_to?(:default_options)
+
+      defaults = ClaudeAgentSDK.default_options
+      return OPTION_DEFAULTS.merge(kwargs) unless defaults.any?
+
+      # Start from configured defaults (deep dup hashes to prevent mutation)
+      result = defaults.transform_values { |v| v.is_a?(Hash) ? v.dup : v }
+      kwargs.each do |key, value|
+        default_val = result[key]
+        result[key] = if value.nil?
+                        default_val # nil means "no preference" — keep the configured default
+                      elsif default_val.is_a?(Hash) && value.is_a?(Hash)
+                        default_val.merge(value)
+                      else
+                        value
+                      end
+      end
+      OPTION_DEFAULTS.merge(result)
+    end
   end
 
   # SDK MCP Tool definition

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -2,6 +2,7 @@
 
 require_relative 'claude_agent_sdk/version'
 require_relative 'claude_agent_sdk/errors'
+require_relative 'claude_agent_sdk/configuration'
 require_relative 'claude_agent_sdk/types'
 require_relative 'claude_agent_sdk/transport'
 require_relative 'claude_agent_sdk/subprocess_cli_transport'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  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
@@ -104,6 +104,7 @@ files:
 - LICENSE
 - README.md
 - lib/claude_agent_sdk.rb
+- lib/claude_agent_sdk/configuration.rb
 - lib/claude_agent_sdk/errors.rb
 - lib/claude_agent_sdk/message_parser.rb
 - lib/claude_agent_sdk/query.rb