claude-agent-sdk 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c723c3e660d135ab87311e27be6a80b8d13127f9e42789a66b1d30ec0395278
-  data.tar.gz: 0652f808dd792a6bef8db32afc567567fe9f016abdf095f1d13ae0ac07af0d03
+  metadata.gz: b625dde6e1777c93be6e4bcfb6c9565087d798d414a03078f8de4184c39dfa7f
+  data.tar.gz: 30117f8eac89f94aabae5c37fdc12c012ed779a0f1c58062d70e9b727ee5ce3c
 SHA512:
-  metadata.gz: 399925ff55a9a23ab54cbe97adb18fea804be6c92cf21aa3ca3fdcd4cbe54693dfc8b77b85f15ed2eaf1517acaecd09935701d0248fb99a23be6325d151c99aa
-  data.tar.gz: dd14802c444f4d6609cbb8215e79c3f5d8c4d9453e20d0d3af40cd853d653625c93e117082118beee2c5fb0ad29447a170687a44d56f88be6785affb8d118060
+  metadata.gz: 2a36e3ff75415bb4c2f42b27a8280b4828199af2972d20aa5fa4366a24daefd325e5a11c3e39ee9396144561c98e2ea1ddcc94157b80fc7aeef72f58a526e36b
+  data.tar.gz: f0fde6a0779679869bd4d6607f7220ea016c021896a97a421be650e169ef53719d5810cf614613c7cb52b24c19ebbf2f3908f3cc49f07bc5b13aa58f377e1a8b

data/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.8.1] - 2026-03-08
+
+Python SDK parity fixes for one-shot `query()` control protocol and CLI transport.
+
+### Fixed
+
+#### One-Shot Query Control Protocol
+- **Hooks and `can_use_tool` in `query()`:** One-shot `query()` now passes `hooks`, `can_use_tool`, and SDK MCP servers through to the `Query` handler, matching the Python SDK (previously these were Client-only)
+- **`can_use_tool` validation:** String prompts with `can_use_tool` now raise `ArgumentError` (streaming mode required); conflicting `permission_prompt_tool_name` also raises early
+- **`session_id` parity:** One-shot queries now send `session_id: ''` (was `'default'`), matching Python SDK behavior
+- **Premature stdin close:** Added `wait_for_result_and_end_input` that holds stdin open until the first result when hooks or SDK MCP servers need control message exchange
+- **`stream_input` stdin leak:** Moved `end_input` to `ensure` block so stdin is always closed even when the stream enumerator raises
+- **`Async::Condition` race:** Added `@first_result_received` flag guard to prevent lost signals when result arrives before `wait` is called
+
+#### CLI Transport Parity
+- **File checkpointing:** Moved from deprecated `--enable-file-checkpointing` CLI flag to `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` environment variable
+- **Partial messages:** Now also sets `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1` environment variable when `include_partial_messages` is enabled
+- **Tools preset:** `ToolsPreset` objects and preset hashes now map to `--tools default` (was `--tools <json>`)
+- **Plugins:** Changed from `--plugins <json>` to `--plugin-dir <path>` per-plugin, matching current CLI interface
+- **Plugin type:** `SdkPluginConfig` now defaults to `type: 'local'` (was `'plugin'`), normalizes legacy `'plugin'` type
+- **Rewind control request:** Changed key from `userMessageUuid` to `user_message_id` for Python SDK parity
+- **Settings file with sandbox:** When sandbox is enabled and settings is a file path, now reads and parses the file to merge sandbox settings (raises on missing/invalid files instead of silently dropping settings)
+
+#### Hook Input Parsing
+- **Falsy value preservation:** `parse_hook_input` now uses `key?`-based lookup instead of `||`, correctly preserving `false` and `nil` values (e.g., `stop_hook_active: false`)
+- **Empty hooks normalization:** `query()` now skips empty matcher lists and normalizes hooks to `nil` when no matchers survive, preventing unnecessary 60s close-wait timeout
+
+### Changed
+- **`build_command` refactored:** Extracted `build_settings_args`, `build_tools_args`, `build_output_format_args`, `build_mcp_servers_args`, `build_plugins_args` private helpers to reduce method complexity
+
 ## [0.8.0] - 2026-03-05
 
 Port of Python SDK v0.1.46 features.

data/lib/claude_agent_sdk/query.rb

@@ -22,6 +22,8 @@ module ClaudeAgentSDK
 
     CONTROL_REQUEST_TIMEOUT_ENV_VAR = 'CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS'
     DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS = 1200.0
+    STREAM_CLOSE_TIMEOUT_ENV_VAR = 'CLAUDE_CODE_STREAM_CLOSE_TIMEOUT'
+    DEFAULT_STREAM_CLOSE_TIMEOUT_SECONDS = 60.0
 
     def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil, agents: nil)
       @transport = transport
@@ -42,6 +44,8 @@ module ClaudeAgentSDK
 
       # Message stream
       @message_queue = Async::Queue.new
+      @first_result_received = false
+      @first_result_condition = Async::Condition.new
       @task = nil
       @initialized = false
       @closed = false
@@ -124,6 +128,16 @@ module ClaudeAgentSDK
       DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS
     end
 
+    def stream_close_timeout_seconds
+      raw_value = ENV.fetch(STREAM_CLOSE_TIMEOUT_ENV_VAR, nil)
+      return DEFAULT_STREAM_CLOSE_TIMEOUT_SECONDS if raw_value.nil? || raw_value.strip.empty?
+
+      value = Float(raw_value) / 1000.0
+      value.positive? ? value : DEFAULT_STREAM_CLOSE_TIMEOUT_SECONDS
+    rescue ArgumentError
+      DEFAULT_STREAM_CLOSE_TIMEOUT_SECONDS
+    end
+
     def read_messages
       @transport.read_messages do |message|
         break if @closed
@@ -150,6 +164,10 @@ module ClaudeAgentSDK
           task&.stop
           next
         else
+          if message[:type] == 'result' && !@first_result_received
+            @first_result_received = true
+            @first_result_condition.signal
+          end
           # Regular SDK messages go to the queue
           @message_queue.enqueue(message)
         end
@@ -164,6 +182,10 @@ module ClaudeAgentSDK
       # Put error in queue so iterators can handle it
       @message_queue.enqueue({ type: 'error', error: e })
     ensure
+      unless @first_result_received
+        @first_result_received = true
+        @first_result_condition.signal
+      end
       # Always signal end of stream
       @message_queue.enqueue({ type: 'end' })
     end
@@ -308,7 +330,13 @@ module ClaudeAgentSDK
 
     def parse_hook_input(input_data)
       event_name = input_data[:hook_event_name] || input_data['hook_event_name']
-      fetch = ->(key) { input_data[key] || input_data[key.to_s] }
+      fetch = lambda do |key|
+        if input_data.key?(key)
+          input_data[key]
+        elsif input_data.key?(key.to_s)
+          input_data[key.to_s]
+        end
+      end
       base_args = {
         session_id: fetch.call(:session_id),
         transcript_path: fetch.call(:transcript_path),
@@ -704,20 +732,42 @@ module ClaudeAgentSDK
     def rewind_files(user_message_uuid)
       send_control_request({
                              subtype: 'rewind_files',
-                             userMessageUuid: user_message_uuid
+                             user_message_id: user_message_uuid
                            })
     end
 
+    # Wait for the first result before closing stdin when hooks or SDK MCP
+    # servers may still need to exchange control messages with the CLI.
+    def wait_for_result_and_end_input
+      if !@first_result_received &&
+         ((@sdk_mcp_servers && !@sdk_mcp_servers.empty?) || (@hooks && !@hooks.empty?))
+        Async::Task.current.with_timeout(stream_close_timeout_seconds) do
+          @first_result_condition.wait unless @first_result_received
+        end
+      end
+    rescue Async::TimeoutError
+      nil
+    ensure
+      @transport.end_input
+    end
+
     # Stream input messages to transport
     def stream_input(stream)
       stream.each do |message|
         break if @closed
-        @transport.write(JSON.generate(message) + "\n")
+        serialized = if message.is_a?(Hash)
+                       JSON.generate(message) + "\n"
+                     else
+                       message.to_s
+                     end
+        serialized += "\n" unless serialized.end_with?("\n")
+        @transport.write(serialized)
       end
-      @transport.end_input
     rescue StandardError => e
       # Log error but don't raise
       warn "Error streaming input: #{e.message}"
+    ensure
+      wait_for_result_and_end_input
     end
 
     # Receive SDK messages (not control messages)

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -98,46 +98,7 @@ module ClaudeAgentSDK
       cmd.concat(['--resume', @options.resume]) if @options.resume
 
       # Settings handling with sandbox merge
-      # Sandbox settings are merged into the main settings JSON
-      if @options.settings || @options.sandbox
-        settings_hash = {}
-        settings_is_path = false
-
-        # Parse existing settings if provided
-        if @options.settings
-          if @options.settings.is_a?(String)
-            begin
-              settings_hash = JSON.parse(@options.settings)
-            rescue JSON::ParserError
-              # If not valid JSON, treat as file path and pass as-is
-              settings_is_path = true
-              cmd.concat(['--settings', @options.settings])
-              if @options.sandbox
-                warn "Warning: Cannot merge sandbox settings when settings is a file path. " \
-                     "Sandbox settings will be ignored. Use a Hash or JSON string for settings " \
-                     "to enable sandbox merging."
-              end
-            end
-          elsif @options.settings.is_a?(Hash)
-            settings_hash = @options.settings.dup
-          end
-        end
-
-        # Merge sandbox settings if provided (only when settings is not a file path)
-        if !settings_is_path && @options.sandbox
-          sandbox_hash = if @options.sandbox.is_a?(SandboxSettings)
-                           @options.sandbox.to_h
-                         else
-                           @options.sandbox
-                         end
-          settings_hash[:sandbox] = sandbox_hash unless sandbox_hash.empty?
-        end
-
-        # Output merged settings (only when settings is not a file path)
-        if !settings_is_path && !settings_hash.empty?
-          cmd.concat(['--settings', JSON.generate(settings_hash)])
-        end
-      end
+      build_settings_args(cmd)
 
       # Budget limit option
       cmd.concat(['--max-budget-usd', @options.max_budget_usd.to_s]) if @options.max_budget_usd
@@ -155,39 +116,15 @@ module ClaudeAgentSDK
       end
 
       # Tools option for base tools selection
-      if @options.tools
-        if @options.tools.is_a?(Array)
-          cmd.concat(['--tools', @options.tools.join(',')])
-        elsif @options.tools.is_a?(ToolsPreset)
-          cmd.concat(['--tools', JSON.generate(@options.tools.to_h)])
-        elsif @options.tools.is_a?(Hash)
-          cmd.concat(['--tools', JSON.generate(@options.tools)])
-        end
-      end
+      build_tools_args(cmd)
 
       # Append allowed tools option
       if @options.append_allowed_tools && !@options.append_allowed_tools.empty?
         cmd.concat(['--append-allowed-tools', @options.append_allowed_tools.join(',')])
       end
 
-      # File checkpointing for rewind support
-      cmd << '--enable-file-checkpointing' if @options.enable_file_checkpointing
-
       # JSON schema for structured output
-      # Accepts either:
-      # 1. Direct schema: { type: 'object', properties: {...} }
-      # 2. Wrapped format: { type: 'json_schema', schema: {...} }
-      if @options.output_format
-        schema = if @options.output_format.is_a?(Hash) && @options.output_format[:type] == 'json_schema'
-                   @options.output_format[:schema]
-                 elsif @options.output_format.is_a?(Hash) && @options.output_format['type'] == 'json_schema'
-                   @options.output_format['schema']
-                 else
-                   @options.output_format
-                 end
-        schema_json = schema.is_a?(String) ? schema : JSON.generate(schema)
-        cmd.concat(['--json-schema', schema_json])
-      end
+      build_output_format_args(cmd)
 
       # Add directories
       @options.add_dirs.each do |dir|
@@ -195,23 +132,7 @@ module ClaudeAgentSDK
       end
 
       # MCP servers
-      if @options.mcp_servers && !@options.mcp_servers.empty?
-        if @options.mcp_servers.is_a?(Hash)
-          servers_for_cli = {}
-          @options.mcp_servers.each do |name, config|
-            if config.is_a?(Hash) && config[:type] == 'sdk'
-              # For SDK servers, exclude instance field
-              sdk_config = config.reject { |k, _| k == :instance }
-              servers_for_cli[name] = sdk_config
-            else
-              servers_for_cli[name] = config
-            end
-          end
-          cmd.concat(['--mcp-config', JSON.generate({ mcpServers: servers_for_cli })]) unless servers_for_cli.empty?
-        else
-          cmd.concat(['--mcp-config', @options.mcp_servers.to_s])
-        end
-      end
+      build_mcp_servers_args(cmd)
 
       cmd << '--include-partial-messages' if @options.include_partial_messages
       cmd << '--fork-session' if @options.fork_session
@@ -220,12 +141,7 @@ module ClaudeAgentSDK
       # to avoid OS ARG_MAX limits with large agent configurations.
 
       # Plugins
-      if @options.plugins && !@options.plugins.empty?
-        plugins_config = @options.plugins.map do |plugin|
-          plugin.is_a?(SdkPluginConfig) ? plugin.to_h : plugin
-        end
-        cmd.concat(['--plugins', JSON.generate(plugins_config)])
-      end
+      build_plugins_args(cmd)
 
       # Setting sources
       sources_value = @options.setting_sources ? @options.setting_sources.join(',') : ''
@@ -264,6 +180,10 @@ module ClaudeAgentSDK
       # the env hash on top of the parent environment; a nil value actively unsets.
       process_env = ENV.to_h.merge('CLAUDECODE' => nil, 'CLAUDE_AGENT_SDK_VERSION' => VERSION).merge(custom_env)
       process_env['CLAUDE_CODE_ENTRYPOINT'] ||= 'sdk-rb'
+      process_env['CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING'] = 'true' if @options.enable_file_checkpointing
+      if @options.include_partial_messages
+        process_env['CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING'] ||= '1'
+      end
       process_env['PWD'] = @cwd.to_s if @cwd
 
       # Determine stderr handling
@@ -554,6 +474,107 @@ module ClaudeAgentSDK
 
     private
 
+    def build_settings_args(cmd)
+      return unless @options.settings || @options.sandbox
+
+      settings_hash = {}
+      settings_is_path = false
+
+      if @options.settings
+        if @options.settings.is_a?(String)
+          begin
+            settings_hash = JSON.parse(@options.settings)
+          rescue JSON::ParserError
+            if @options.sandbox
+              settings_hash = load_settings_file(@options.settings)
+            else
+              settings_is_path = true
+              cmd.concat(['--settings', @options.settings])
+            end
+          end
+        elsif @options.settings.is_a?(Hash)
+          settings_hash = @options.settings.dup
+        end
+      end
+
+      if !settings_is_path && @options.sandbox
+        sandbox_hash = @options.sandbox.is_a?(SandboxSettings) ? @options.sandbox.to_h : @options.sandbox
+        settings_hash[:sandbox] = sandbox_hash unless sandbox_hash.empty?
+      end
+
+      cmd.concat(['--settings', JSON.generate(settings_hash)]) if !settings_is_path && !settings_hash.empty?
+    end
+
+    def build_tools_args(cmd)
+      return if @options.tools.nil?
+
+      if @options.tools.is_a?(Array)
+        tools_value = @options.tools.empty? ? '' : @options.tools.join(',')
+        cmd.concat(['--tools', tools_value])
+      elsif @options.tools.is_a?(ToolsPreset)
+        cmd.concat(['--tools', 'default'])
+      elsif @options.tools.is_a?(Hash)
+        if (@options.tools[:type] || @options.tools['type']) == 'preset'
+          cmd.concat(['--tools', 'default'])
+        else
+          cmd.concat(['--tools', JSON.generate(@options.tools)])
+        end
+      end
+    end
+
+    def build_output_format_args(cmd)
+      return unless @options.output_format
+
+      schema = if @options.output_format.is_a?(Hash) && @options.output_format[:type] == 'json_schema'
+                 @options.output_format[:schema]
+               elsif @options.output_format.is_a?(Hash) && @options.output_format['type'] == 'json_schema'
+                 @options.output_format['schema']
+               else
+                 @options.output_format
+               end
+      schema_json = schema.is_a?(String) ? schema : JSON.generate(schema)
+      cmd.concat(['--json-schema', schema_json])
+    end
+
+    def build_mcp_servers_args(cmd)
+      return unless @options.mcp_servers && !@options.mcp_servers.empty?
+
+      if @options.mcp_servers.is_a?(Hash)
+        servers_for_cli = {}
+        @options.mcp_servers.each do |name, config|
+          servers_for_cli[name] = if config.is_a?(Hash) && config[:type] == 'sdk'
+                                    config.reject { |k, _| k == :instance }
+                                  else
+                                    config
+                                  end
+        end
+        cmd.concat(['--mcp-config', JSON.generate({ mcpServers: servers_for_cli })]) unless servers_for_cli.empty?
+      else
+        cmd.concat(['--mcp-config', @options.mcp_servers.to_s])
+      end
+    end
+
+    def build_plugins_args(cmd)
+      return unless @options.plugins && !@options.plugins.empty?
+
+      @options.plugins.each do |plugin|
+        plugin_config = plugin.is_a?(SdkPluginConfig) ? plugin.to_h : plugin
+        plugin_type = plugin_config[:type] || plugin_config['type']
+        plugin_path = plugin_config[:path] || plugin_config['path']
+
+        raise ArgumentError, "Unsupported plugin type: #{plugin_type.inspect}" unless %w[local plugin].include?(plugin_type)
+        next unless plugin_path
+
+        cmd.concat(['--plugin-dir', plugin_path])
+      end
+    end
+
+    def load_settings_file(path)
+      raise CLIConnectionError, "Settings file not found: #{path}" unless File.file?(path)
+
+      JSON.parse(File.read(path))
+    end
+
     def resolve_thinking_tokens
       if @options.thinking
         case @options.thinking

data/lib/claude_agent_sdk/types.rb

@@ -866,8 +866,10 @@ module ClaudeAgentSDK
   class SdkPluginConfig
     attr_accessor :type, :path
 
-    def initialize(path:)
-      @type = 'plugin'
+    def initialize(path:, type: 'local')
+      raise ArgumentError, "unsupported plugin type: #{type}" unless %w[local plugin].include?(type)
+
+      @type = 'local'
       @path = path
     end
 

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -82,29 +82,66 @@ module ClaudeAgentSDK
     return enum_for(:query, prompt: prompt, options: options) unless block
 
     options ||= ClaudeAgentOptions.new
-    options = options.dup_with(env: (options.env || {}).merge('CLAUDE_CODE_ENTRYPOINT' => 'sdk-rb'))
+
+    configured_options = options
+    if options.can_use_tool
+      if prompt.is_a?(String)
+        raise ArgumentError,
+              'can_use_tool callback requires streaming mode. Please provide prompt as an Enumerator instead of a String.'
+      end
+
+      raise ArgumentError, 'can_use_tool callback cannot be used with permission_prompt_tool_name' if options.permission_prompt_tool_name
+
+      configured_options = options.dup_with(permission_prompt_tool_name: 'stdio')
+    end
+
+    configured_options = configured_options.dup_with(
+      env: (configured_options.env || {}).merge('CLAUDE_CODE_ENTRYPOINT' => 'sdk-rb')
+    )
 
     Async do
       # Always use streaming mode with control protocol (matches Python SDK).
       # This sends agents via initialize request instead of CLI args,
       # avoiding OS ARG_MAX limits.
-      transport = SubprocessCLITransport.new(options)
+      transport = SubprocessCLITransport.new(configured_options)
       begin
         transport.connect
 
         # Extract SDK MCP servers
         sdk_mcp_servers = {}
-        if options.mcp_servers.is_a?(Hash)
-          options.mcp_servers.each do |name, config|
+        if configured_options.mcp_servers.is_a?(Hash)
+          configured_options.mcp_servers.each do |name, config|
             sdk_mcp_servers[name] = config[:instance] if config.is_a?(Hash) && config[:type] == 'sdk'
           end
         end
 
+        hooks = nil
+        if configured_options.hooks
+          hooks = {}
+          configured_options.hooks.each do |event, matchers|
+            next if matchers.nil? || matchers.empty?
+
+            entries = []
+            matchers.each do |matcher|
+              config = {
+                matcher: matcher.matcher,
+                hooks: matcher.hooks
+              }
+              config[:timeout] = matcher.timeout if matcher.timeout
+              entries << config
+            end
+            hooks[event.to_s] = entries unless entries.empty?
+          end
+          hooks = nil if hooks.empty?
+        end
+
         # Create Query handler for control protocol
         query_handler = Query.new(
           transport: transport,
           is_streaming_mode: true,
-          agents: options.agents,
+          can_use_tool: configured_options.can_use_tool,
+          hooks: hooks,
+          agents: configured_options.agents,
           sdk_mcp_servers: sdk_mcp_servers
         )
 
@@ -120,19 +157,13 @@ module ClaudeAgentSDK
             type: 'user',
             message: { role: 'user', content: prompt },
             parent_tool_use_id: nil,
-            session_id: 'default'
+            session_id: ''
           }
           transport.write(JSON.generate(message) + "\n")
-          transport.end_input
+          query_handler.wait_for_result_and_end_input
         elsif prompt.is_a?(Enumerator) || prompt.respond_to?(:each)
           Async do
-            begin
-              prompt.each do |message_json|
-                transport.write(message_json)
-              end
-            ensure
-              transport.end_input
-            end
+            query_handler.stream_input(prompt)
           end
         end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2026-03-05 00:00:00.000000000 Z
+date: 2026-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -123,6 +123,7 @@ metadata:
   source_code_uri: https://github.com/ya-luotao/claude-agent-sdk-ruby
   changelog_uri: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/CHANGELOG.md
   documentation_uri: https://docs.anthropic.com/en/docs/claude-code/sdk
+  allowed_push_host: https://rubygems.org
 rdoc_options: []
 require_paths:
 - lib