claude-agent-sdk 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c723c3e660d135ab87311e27be6a80b8d13127f9e42789a66b1d30ec0395278
-  data.tar.gz: 0652f808dd792a6bef8db32afc567567fe9f016abdf095f1d13ae0ac07af0d03
+  metadata.gz: 52b6649f2a72ef33e746d168e4016dcc72c1439157fbe5b971edbd55b0a0d404
+  data.tar.gz: a344cc38d96ef7185630c1e1518a5cf6d08a855f40b39092728236d5a48df50d
 SHA512:
-  metadata.gz: 399925ff55a9a23ab54cbe97adb18fea804be6c92cf21aa3ca3fdcd4cbe54693dfc8b77b85f15ed2eaf1517acaecd09935701d0248fb99a23be6325d151c99aa
-  data.tar.gz: dd14802c444f4d6609cbb8215e79c3f5d8c4d9453e20d0d3af40cd853d653625c93e117082118beee2c5fb0ad29447a170687a44d56f88be6785affb8d118060
+  metadata.gz: 18a32d856585a36aa39a9aa586829a305c099cd4686a338e6f1df5310490abb81808821940a6be5d6c830a1fc86cb1cd95dab5ca8e2c5737574e3e91da513f5f
+  data.tar.gz: c6dadb9b32d373e1fac9246b5bafc8456f3779cf0187abceb7bd85ecdd96b823c95c49c751db9bcd4b384ceb34141057b9e48d4540366d1e3d7d951a69e0aa7f

data/CHANGELOG.md

@@ -5,6 +5,57 @@ 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.9.0] - 2026-03-12
+
+Port of Python SDK v0.1.48 parity improvements.
+
+### Added
+
+#### Typed Rate Limit Events
+- `RateLimitInfo` class with `status`, `resets_at`, `rate_limit_type`, `utilization`, `overage_status`, `overage_resets_at`, `overage_disabled_reason`, `raw` attributes
+- `RATE_LIMIT_STATUSES` constant (`allowed`, `allowed_warning`, `rejected`)
+- `RATE_LIMIT_TYPES` constant (`five_hour`, `seven_day`, `seven_day_opus`, `seven_day_sonnet`, `overage`)
+- `RateLimitEvent` now has typed `rate_limit_info`, `uuid`, `session_id` attributes (previously raw `data` hash)
+- Backward-compatible `data` accessor on `RateLimitEvent` returns raw hash from `rate_limit_info.raw`
+
+#### MCP Status Output Types
+- `McpClaudeAIProxyServerConfig` type for `claudeai-proxy` servers in MCP status responses
+- `McpSdkServerConfigStatus` type for serializable SDK server config in status responses
+- `McpServerStatus.parse` handles `claudeai-proxy` config type
+
+#### Effort Level
+- `effort` option now supports `"max"` value in addition to `"low"`, `"medium"`, `"high"`
+
+## [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/message_parser.rb

@@ -120,7 +120,23 @@ module ClaudeAgentSDK
     end
 
     def self.parse_rate_limit_event(data)
-      RateLimitEvent.new(data: data)
+      info = data[:rate_limit_info] || {}
+      rate_limit_info = RateLimitInfo.new(
+        status: info[:status],
+        resets_at: info[:resetsAt],
+        rate_limit_type: info[:rateLimitType],
+        utilization: info[:utilization],
+        overage_status: info[:overageStatus],
+        overage_resets_at: info[:overageResetsAt],
+        overage_disabled_reason: info[:overageDisabledReason],
+        raw: info
+      )
+      RateLimitEvent.new(
+        rate_limit_info: rate_limit_info,
+        uuid: data[:uuid],
+        session_id: data[:session_id],
+        raw_data: data
+      )
     end
 
     def self.parse_content_block(block)

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

@@ -75,14 +75,14 @@ module ClaudeAgentSDK
       elsif @options.system_prompt.is_a?(String)
         cmd.concat(['--system-prompt', @options.system_prompt])
       elsif @options.system_prompt.is_a?(SystemPromptPreset)
-        cmd.concat(['--system-prompt-preset', @options.system_prompt.preset]) if @options.system_prompt.preset
+        # Preset activates the default Claude Code system prompt by not passing --system-prompt ""
+        # Only --append-system-prompt is passed if append text is provided
         cmd.concat(['--append-system-prompt', @options.system_prompt.append]) if @options.system_prompt.append
       elsif @options.system_prompt.is_a?(Hash)
         prompt_type = @options.system_prompt[:type] || @options.system_prompt['type']
         if prompt_type == 'preset'
-          preset = @options.system_prompt[:preset] || @options.system_prompt['preset']
           append = @options.system_prompt[:append] || @options.system_prompt['append']
-          cmd.concat(['--system-prompt-preset', preset]) if preset
+          # Preset activates the default Claude Code system prompt by not passing --system-prompt ""
           cmd.concat(['--append-system-prompt', append]) if append
         end
       end
@@ -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
@@ -146,7 +107,7 @@ module ClaudeAgentSDK
       thinking_tokens = resolve_thinking_tokens
       cmd.concat(['--max-thinking-tokens', thinking_tokens.to_s]) unless thinking_tokens.nil?
 
-      # Effort level
+      # Effort level (valid values: low, medium, high, max)
       cmd.concat(['--effort', @options.effort.to_s]) if @options.effort
 
       # Betas option for enabling experimental features
@@ -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

@@ -212,12 +212,44 @@ module ClaudeAgentSDK
     end
   end
 
-  # Rate limit event emitted by Claude Code CLI when API rate limits are hit
+  # Type constants for rate limit statuses
+  RATE_LIMIT_STATUSES = %w[allowed allowed_warning rejected].freeze
+
+  # Type constants for rate limit types
+  RATE_LIMIT_TYPES = %w[five_hour seven_day seven_day_opus seven_day_sonnet overage].freeze
+
+  # Rate limit info with typed fields
+  class RateLimitInfo
+    attr_accessor :status, :resets_at, :rate_limit_type, :utilization,
+                  :overage_status, :overage_resets_at, :overage_disabled_reason, :raw
+
+    def initialize(status:, resets_at: nil, rate_limit_type: nil, utilization: nil,
+                   overage_status: nil, overage_resets_at: nil, overage_disabled_reason: nil, raw: {})
+      @status = status
+      @resets_at = resets_at
+      @rate_limit_type = rate_limit_type
+      @utilization = utilization
+      @overage_status = overage_status
+      @overage_resets_at = overage_resets_at
+      @overage_disabled_reason = overage_disabled_reason
+      @raw = raw
+    end
+  end
+
+  # Rate limit event emitted when rate limit info changes
   class RateLimitEvent
-    attr_accessor :data
+    attr_accessor :rate_limit_info, :uuid, :session_id
 
-    def initialize(data:)
-      @data = data
+    def initialize(rate_limit_info:, uuid:, session_id:, raw_data: nil)
+      @rate_limit_info = rate_limit_info
+      @uuid = uuid
+      @session_id = session_id
+      @raw_data = raw_data
+    end
+
+    # Backward-compatible accessor returning the full raw event payload
+    def data
+      @raw_data || {}
     end
   end
 
@@ -753,6 +785,37 @@ module ClaudeAgentSDK
     end
   end
 
+  # Output-only serializable version of McpSdkServerConfig (without live instance)
+  # Returned in MCP status responses
+  class McpSdkServerConfigStatus
+    attr_accessor :type, :name
+
+    def initialize(type: 'sdk', name:)
+      @type = type
+      @name = name
+    end
+
+    def to_h
+      { type: @type, name: @name }
+    end
+  end
+
+  # Claude.ai proxy MCP server config
+  # Output-only type that appears in status responses for servers proxied through Claude.ai
+  class McpClaudeAIProxyServerConfig
+    attr_accessor :type, :url, :id
+
+    def initialize(type: 'claudeai-proxy', url:, id:)
+      @type = type
+      @url = url
+      @id = id
+    end
+
+    def to_h
+      { type: @type, url: @url, id: @id }
+    end
+  end
+
   # Status of a single MCP server connection
   class McpServerStatus
     attr_accessor :name, :status, :server_info, :error, :config, :scope, :tools
@@ -770,17 +833,31 @@ module ClaudeAgentSDK
     def self.parse(data)
       server_info = (McpServerInfo.new(name: data[:serverInfo][:name], version: data[:serverInfo][:version]) if data[:serverInfo])
       tools = data[:tools]&.map { |t| McpToolInfo.parse(t) }
+      config = parse_config(data[:config])
 
       new(
         name: data[:name],
         status: data[:status],
         server_info: server_info,
         error: data[:error],
-        config: data[:config],
+        config: config,
         scope: data[:scope],
         tools: tools
       )
     end
+
+    def self.parse_config(config)
+      return config unless config.is_a?(Hash) && config[:type]
+
+      case config[:type]
+      when 'claudeai-proxy'
+        McpClaudeAIProxyServerConfig.new(url: config[:url], id: config[:id])
+      when 'sdk'
+        McpSdkServerConfigStatus.new(name: config[:name])
+      else
+        config
+      end
+    end
   end
 
   # Response from get_mcp_status containing all server statuses
@@ -866,8 +943,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.9.0'
 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.9.0
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2026-03-05 00:00:00.000000000 Z
+date: 2026-03-12 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