claude-agent-sdk 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8044b53b9c1c89e75c789b94a1ca000bb4a4a6e94d380bef3ded209585517b29
-  data.tar.gz: a3effbef7a3cbf1faed47cecb6f69df37e17266eabae7e56a556855b85707c4f
+  metadata.gz: de5807b36fd822ee89e4a793a536b4ba8804c168259d17cc1a03974425f128ea
+  data.tar.gz: c40d5dad151728b8b2e131ad96da616bd03b4972f6d5807d5375ea24d499ceb6
 SHA512:
-  metadata.gz: 3c9360caa6e3fc1ffa7d359e4d2195aecf003e1fc37655bfe15355efc2dce3cfd896f30a0b7bdc504a88d90056bab05b7ad2a90c33f0ad03867abcaf0ccb16a7
-  data.tar.gz: 68059199d80d3f10ff03b18b6fbb505348070f8a1a53d8d00cd56550fdfe7c337a4b53d39d7e41d0238c954dd2106656c6f8eaf6e39b5ac516278ac4c7c57ff4
+  metadata.gz: f34dc590db10f0f4ebe1360a5318617fd0b7c6299fcf83d45438d1bb1a9a106734e06268f7d4361bbdf575d660afa63b97586c56235fa9d617a6b891a0e1e158
+  data.tar.gz: e6548661fbcd10c96b5b64b4efc6676d5ad47f28435a23e4b8045a590df107bedea2ee8d089a230c32aaa84dafdbb0239bbeffb1b7b7aba255196d2ded16903e

data/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.7.0] - 2026-02-20
+
+### Added
+
+#### Thinking Configuration
+- `ThinkingConfigAdaptive`, `ThinkingConfigEnabled`, `ThinkingConfigDisabled` classes for structured thinking control
+- `thinking` option on `ClaudeAgentOptions` — takes precedence over deprecated `max_thinking_tokens`
+  - `ThinkingConfigAdaptive` → 32,000 token default budget
+  - `ThinkingConfigEnabled(budget_tokens:)` → explicit budget
+  - `ThinkingConfigDisabled` → 0 tokens (thinking off)
+- `effort` option on `ClaudeAgentOptions` — maps to `--effort` CLI flag (`'low'`, `'medium'`, `'high'`)
+
+#### Tool Annotations
+- `annotations` attribute on `SdkMcpTool` for MCP tool annotations (e.g., `readOnlyHint`, `title`)
+- `annotations:` keyword on `ClaudeAgentSDK.create_tool`
+- Annotations included in `SdkMcpServer#list_tools` responses
+
+#### Hook Enhancements
+- `tool_use_id` attribute on `PreToolUseHookInput` and `PostToolUseHookInput`
+- `additional_context` attribute on `PreToolUseHookSpecificOutput`
+
+#### Message Enhancements
+- `tool_use_result` attribute on `UserMessage` for tool response data
+- `MessageParser` populates `tool_use_result` from CLI output
+
+### Changed
+
+#### Architecture: Always Streaming Mode (BREAKING for internal API)
+- **`SubprocessCLITransport`** now always uses `--input-format stream-json` — removed `--print` mode and `--agents` CLI flag
+- **`SubprocessCLITransport.new`** still accepts `(prompt, options)` for compatibility but ignores the prompt argument (always uses streaming mode)
+- **`query()`** now uses the full control protocol internally (Query handler + initialize handshake), matching the Python SDK
+- **Agents** are sent via the `initialize` control request over stdin instead of CLI `--agents` flag, avoiding OS ARG_MAX limits
+- **`query()`** now supports SDK MCP servers and `can_use_tool` callbacks (previously Client-only)
+
+#### Empty System Prompt
+- When `system_prompt` is `nil`, passes `--system-prompt ""` to CLI for predictable behavior without the default Claude Code system prompt
+
+## [0.6.3] - 2026-02-18
+
+### Fixed
+- **ProcessError stderr:** Real stderr output is now included in `ProcessError` exceptions (was always "No stderr output captured")
+- **Rate limit events:** Added `RateLimitEvent` type and `rate_limit_event` message parsing support
+
 ## [0.6.2] - 2026-02-17
 
 ### Fixed

data/README.md

@@ -16,6 +16,7 @@
 - [Hooks](#hooks)
 - [Permission Callbacks](#permission-callbacks)
 - [Structured Output](#structured-output)
+- [Thinking Configuration](#thinking-configuration)
 - [Budget Control](#budget-control)
 - [Fallback Model](#fallback-model)
 - [Beta Features](#beta-features)
@@ -38,7 +39,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.6.0'
+gem 'claude-agent-sdk', '~> 0.7.0'
 ```
 
 And then execute:
@@ -249,8 +250,11 @@ Custom tools are implemented as in-process MCP servers that run directly within
 require 'claude_agent_sdk'
 require 'async'
 
-# Define a tool using create_tool
-greet_tool = ClaudeAgentSDK.create_tool('greet', 'Greet a user', { name: :string }) do |args|
+# Define a tool using create_tool (with optional annotations)
+greet_tool = ClaudeAgentSDK.create_tool(
+  'greet', 'Greet a user', { name: :string },
+  annotations: { title: 'Greeter', readOnlyHint: true }
+) do |args|
   { content: [{ type: 'text', text: "Hello, #{args[:name]}!" }] }
 end
 
@@ -392,8 +396,8 @@ A **hook** is a Ruby proc/lambda that the Claude Code *application* (*not* Claud
 
 All hook input objects include common fields like `session_id`, `transcript_path`, `cwd`, and `permission_mode`.
 
-- `PreToolUse` → `PreToolUseHookInput` (`tool_name`, `tool_input`)
-- `PostToolUse` → `PostToolUseHookInput` (`tool_name`, `tool_input`, `tool_response`)
+- `PreToolUse` → `PreToolUseHookInput` (`tool_name`, `tool_input`, `tool_use_id`)
+- `PostToolUse` → `PostToolUseHookInput` (`tool_name`, `tool_input`, `tool_response`, `tool_use_id`)
 - `PostToolUseFailure` → `PostToolUseFailureHookInput` (`tool_name`, `tool_input`, `tool_use_id`, `error`, `is_interrupt`)
 - `UserPromptSubmit` → `UserPromptSubmitHookInput` (`prompt`)
 - `Stop` → `StopHookInput` (`stop_hook_active`)
@@ -566,6 +570,37 @@ end
 
 For complete examples, see [examples/structured_output_example.rb](examples/structured_output_example.rb).
 
+## Thinking Configuration
+
+Control extended thinking behavior with typed configuration objects. The `thinking` option takes precedence over the deprecated `max_thinking_tokens`.
+
+```ruby
+# Adaptive thinking — uses a default budget of 32,000 tokens
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  thinking: ClaudeAgentSDK::ThinkingConfigAdaptive.new
+)
+
+# Enabled thinking with custom budget
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  thinking: ClaudeAgentSDK::ThinkingConfigEnabled.new(budget_tokens: 50_000)
+)
+
+# Explicitly disabled thinking
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  thinking: ClaudeAgentSDK::ThinkingConfigDisabled.new
+)
+```
+
+Use the `effort` option to control the model's effort level:
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  effort: 'high'  # 'low', 'medium', or 'high'
+)
+```
+
+> **Note:** When `system_prompt` is `nil` (the default), the SDK passes `--system-prompt ""` to the CLI, which suppresses the default Claude Code system prompt. To use the default system prompt, use a `SystemPromptPreset`.
+
 ## Budget Control
 
 Use `max_budget_usd` to set a spending cap for your queries:
@@ -891,7 +926,8 @@ User input message.
 class UserMessage
   attr_accessor :content,           # String | Array<ContentBlock>
                 :uuid,              # String | nil - Unique ID for rewind support
-                :parent_tool_use_id # String | nil
+                :parent_tool_use_id, # String | nil
+                :tool_use_result    # Hash | nil - Tool result data when message is a tool response
 end
 ```
 
@@ -1036,6 +1072,10 @@ end
 | `PermissionResultAllow` | Permission callback result to allow tool use |
 | `PermissionResultDeny` | Permission callback result to deny tool use |
 | `AgentDefinition` | Agent definition with description, prompt, tools, model |
+| `ThinkingConfigAdaptive` | Adaptive thinking mode (32,000 token default budget) |
+| `ThinkingConfigEnabled` | Enabled thinking with explicit `budget_tokens` |
+| `ThinkingConfigDisabled` | Disabled thinking (0 tokens) |
+| `SdkMcpTool` | SDK MCP tool definition with name, description, input_schema, handler, annotations |
 | `McpStdioServerConfig` | MCP server config for stdio transport |
 | `McpSSEServerConfig` | MCP server config for SSE transport |
 | `McpHttpServerConfig` | MCP server config for HTTP transport |

data/lib/claude_agent_sdk/message_parser.rb

@@ -23,6 +23,8 @@ module ClaudeAgentSDK
         parse_result_message(data)
       when 'stream_event'
         parse_stream_event(data)
+      when 'rate_limit_event'
+        parse_rate_limit_event(data)
       else
         raise MessageParseError.new("Unknown message type: #{message_type}", data: data)
       end
@@ -33,6 +35,7 @@ module ClaudeAgentSDK
     def self.parse_user_message(data)
       parent_tool_use_id = data[:parent_tool_use_id]
       uuid = data[:uuid] # UUID for rewind support
+      tool_use_result = data[:tool_use_result]
       message_data = data[:message]
       raise MessageParseError.new("Missing message field in user message", data: data) unless message_data
 
@@ -41,9 +44,11 @@ module ClaudeAgentSDK
 
       if content.is_a?(Array)
         content_blocks = content.map { |block| parse_content_block(block) }
-        UserMessage.new(content: content_blocks, uuid: uuid, parent_tool_use_id: parent_tool_use_id)
+        UserMessage.new(content: content_blocks, uuid: uuid, parent_tool_use_id: parent_tool_use_id,
+                        tool_use_result: tool_use_result)
       else
-        UserMessage.new(content: content, uuid: uuid, parent_tool_use_id: parent_tool_use_id)
+        UserMessage.new(content: content, uuid: uuid, parent_tool_use_id: parent_tool_use_id,
+                        tool_use_result: tool_use_result)
       end
     end
 
@@ -91,6 +96,10 @@ module ClaudeAgentSDK
       )
     end
 
+    def self.parse_rate_limit_event(data)
+      RateLimitEvent.new(data: data)
+    end
+
     def self.parse_content_block(block)
       case block[:type]
       when 'text'

data/lib/claude_agent_sdk/query.rb

@@ -23,12 +23,13 @@ module ClaudeAgentSDK
     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)
+    def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil, agents: nil)
       @transport = transport
       @is_streaming_mode = is_streaming_mode
       @can_use_tool = can_use_tool
       @hooks = hooks || {}
       @sdk_mcp_servers = sdk_mcp_servers || {}
+      @agents = agents
 
       # Control protocol state
       @pending_control_responses = {}
@@ -76,10 +77,24 @@ module ClaudeAgentSDK
         end
       end
 
+      # Build agents dict for initialization
+      agents_dict = nil
+      if @agents
+        agents_dict = @agents.transform_values do |agent_def|
+          {
+            description: agent_def.description,
+            prompt: agent_def.prompt,
+            tools: agent_def.tools,
+            model: agent_def.model
+          }.compact
+        end
+      end
+
       # Send initialize request
       request = {
         subtype: 'initialize',
-        hooks: hooks_config.empty? ? nil : hooks_config
+        hooks: hooks_config.empty? ? nil : hooks_config,
+        agents: agents_dict
       }
 
       response = send_control_request(request)
@@ -306,6 +321,7 @@ module ClaudeAgentSDK
         PreToolUseHookInput.new(
           tool_name: fetch.call(:tool_name),
           tool_input: fetch.call(:tool_input),
+          tool_use_id: fetch.call(:tool_use_id),
           **base_args
         )
       when 'PostToolUse'
@@ -313,6 +329,7 @@ module ClaudeAgentSDK
           tool_name: fetch.call(:tool_name),
           tool_input: fetch.call(:tool_input),
           tool_response: fetch.call(:tool_response),
+          tool_use_id: fetch.call(:tool_use_id),
           **base_args
         )
       when 'PostToolUseFailure'

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -51,11 +51,13 @@ module ClaudeAgentSDK
     # @return [Array<Hash>] Array of tool definitions
     def list_tools
       @tools.map do |tool|
-        {
+        entry = {
           name: tool.name,
           description: tool.description,
           inputSchema: convert_input_schema(tool.input_schema)
         }
+        entry[:annotations] = tool.annotations if tool.annotations
+        entry
       end
     end
 
@@ -387,14 +389,15 @@ module ClaudeAgentSDK
   #       { content: [{ type: 'text', text: "Result: #{result}" }] }
   #     end
   #   end
-  def self.create_tool(name, description, input_schema, &handler)
+  def self.create_tool(name, description, input_schema, annotations: nil, &handler)
     raise ArgumentError, 'Block required for tool handler' unless handler
 
     SdkMcpTool.new(
       name: name,
       description: description,
       input_schema: input_schema,
-      handler: handler
+      handler: handler,
+      annotations: annotations
     )
   end
 

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -13,15 +13,9 @@ module ClaudeAgentSDK
     DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024 # 1MB buffer limit
     MINIMUM_CLAUDE_CODE_VERSION = '2.0.0'
 
-    # Prompts larger than this are piped via stdin instead of CLI args
-    # to avoid Errno::E2BIG (ARG_MAX is typically 1MB on macOS/Linux,
-    # shared with environment variables).
-    PROMPT_STDIN_THRESHOLD = 200 * 1024 # 200KB
-
-    def initialize(prompt, options)
-      @prompt = prompt
-      @is_streaming = !prompt.is_a?(String)
-      @options = options
+    def initialize(options_or_prompt = nil, options = nil)
+      # Support both new single-arg form and legacy two-arg form
+      @options = options.nil? ? options_or_prompt : options
       @cli_path = options.cli_path || find_cli
       @cwd = options.cwd
       @process = nil
@@ -32,7 +26,8 @@ module ClaudeAgentSDK
       @exit_error = nil
       @max_buffer_size = options.max_buffer_size || DEFAULT_MAX_BUFFER_SIZE
       @stderr_task = nil
-      @pipe_prompt_via_stdin = false
+      @recent_stderr = []
+      @recent_stderr_mutex = Mutex.new
     end
 
     def find_cli
@@ -74,20 +69,21 @@ module ClaudeAgentSDK
       cmd = [@cli_path, '--output-format', 'stream-json', '--verbose']
 
       # System prompt handling
-      if @options.system_prompt
-        if @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
-          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
-            cmd.concat(['--append-system-prompt', append]) if append
-          end
+      # When nil, pass empty string to ensure predictable behavior without default Claude Code system prompt
+      if @options.system_prompt.nil?
+        cmd.concat(['--system-prompt', ''])
+      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
+        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
+          cmd.concat(['--append-system-prompt', append]) if append
         end
       end
 
@@ -145,7 +141,13 @@ module ClaudeAgentSDK
 
       # Budget limit option
       cmd.concat(['--max-budget-usd', @options.max_budget_usd.to_s]) if @options.max_budget_usd
-      # Note: max_thinking_tokens is stored in options but not yet supported by Claude CLI
+
+      # Thinking configuration (takes precedence over deprecated max_thinking_tokens)
+      thinking_tokens = resolve_thinking_tokens
+      cmd.concat(['--max-thinking-tokens', thinking_tokens.to_s]) unless thinking_tokens.nil?
+
+      # Effort level
+      cmd.concat(['--effort', @options.effort.to_s]) if @options.effort
 
       # Betas option for enabling experimental features
       if @options.betas && !@options.betas.empty?
@@ -214,18 +216,8 @@ module ClaudeAgentSDK
       cmd << '--include-partial-messages' if @options.include_partial_messages
       cmd << '--fork-session' if @options.fork_session
 
-      # Agents
-      if @options.agents
-        agents_dict = @options.agents.transform_values do |agent_def|
-          {
-            description: agent_def.description,
-            prompt: agent_def.prompt,
-            tools: agent_def.tools,
-            model: agent_def.model
-          }.compact
-        end
-        cmd.concat(['--agents', JSON.generate(agents_dict)])
-      end
+      # Note: agents are now sent via the initialize control request (not CLI args)
+      # to avoid OS ARG_MAX limits with large agent configurations.
 
       # Plugins
       if @options.plugins && !@options.plugins.empty?
@@ -248,17 +240,10 @@ module ClaudeAgentSDK
         end
       end
 
-      # Prompt handling
-      if @is_streaming
-        cmd.concat(['--input-format', 'stream-json'])
-      elsif @prompt.to_s.bytesize > PROMPT_STDIN_THRESHOLD
-        # Large prompts are piped via stdin to avoid OS argument size limits.
-        # Claude CLI reads from stdin when --print is used without a trailing argument.
-        cmd << '--print'
-        @pipe_prompt_via_stdin = true
-      else
-        cmd.concat(['--print', '--', @prompt.to_s])
-      end
+      # Always use streaming mode for bidirectional control protocol.
+      # Prompts and agents are sent via stdin (initialize + user messages),
+      # which avoids OS ARG_MAX limits for large prompts and agent configurations.
+      cmd.concat(['--input-format', 'stream-json'])
 
       cmd
     end
@@ -273,9 +258,11 @@ module ClaudeAgentSDK
       # Build environment
       # Convert symbol keys to strings for spawn compatibility
       custom_env = @options.env.transform_keys { |k| k.to_s }
-      # 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)
+      # Explicitly unset CLAUDECODE to prevent "nested session" detection when the SDK
+      # launches Claude Code from within an existing Claude Code terminal.
+      # NOTE: Must set to nil (not just omit the key) — Ruby's spawn only overlays
+      # 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['PWD'] = @cwd.to_s if @cwd
 
@@ -292,32 +279,24 @@ module ClaudeAgentSDK
         # Without this, --verbose output fills the OS pipe buffer (~64KB),
         # the subprocess blocks on write, and all pipes stall → EPIPE.
         if @stderr
-          if should_pipe_stderr
+          if should_pipe_stderr # rubocop:disable Style/ConditionalAssignment
             @stderr_task = Thread.new do
               handle_stderr
             rescue StandardError
               # Ignore errors during stderr reading
             end
           else
-            # Silently drain stderr so the subprocess never blocks
+            # Silently drain stderr so the subprocess never blocks,
+            # but still accumulate recent lines for error reporting.
             @stderr_task = Thread.new do
-              @stderr.each_line { |_| } # discard
+              drain_stderr_with_accumulation
             rescue StandardError
               # Ignore — process may have already exited
             end
           end
         end
 
-        # For large prompts, pipe the prompt text to stdin before closing.
-        # This avoids Errno::E2BIG when the prompt exceeds ARG_MAX.
-        if @pipe_prompt_via_stdin && @stdin
-          @stdin.write(@prompt.to_s)
-        end
-
-        # Close stdin for non-streaming mode
-        @stdin.close unless @is_streaming
-        @stdin = nil unless @is_streaming
-
+        # Always keep stdin open — streaming mode uses it for the control protocol
         @ready = true
       rescue Errno::ENOENT => e
         # Check if error is from cwd or CLI
@@ -343,6 +322,12 @@ module ClaudeAgentSDK
         line_str = line.chomp
         next if line_str.empty?
 
+        # Accumulate recent lines for inclusion in ProcessError
+        @recent_stderr_mutex.synchronize do
+          @recent_stderr << line_str
+          @recent_stderr.shift if @recent_stderr.size > 20
+        end
+
         # Call stderr callback if provided
         @options.stderr&.call(line_str)
 
@@ -359,6 +344,20 @@ module ClaudeAgentSDK
       # Ignore errors during stderr reading
     end
 
+    def drain_stderr_with_accumulation
+      return unless @stderr
+
+      @stderr.each_line do |line|
+        line_str = line.chomp
+        next if line_str.empty?
+
+        @recent_stderr_mutex.synchronize do
+          @recent_stderr << line_str
+          @recent_stderr.shift if @recent_stderr.size > 20
+        end
+      end
+    end
+
     def close
       @ready = false
       return unless @process
@@ -511,10 +510,16 @@ module ClaudeAgentSDK
       returncode = status.exitstatus
 
       if returncode && returncode != 0
+        # Wait briefly for stderr thread to finish draining
+        @stderr_task&.join(1)
+
+        stderr_text = @recent_stderr_mutex.synchronize { @recent_stderr.last(10).join("\n") }
+        stderr_text = 'No stderr output captured' if stderr_text.empty?
+
         @exit_error = ProcessError.new(
           "Command failed with exit code #{returncode}",
           exit_code: returncode,
-          stderr: 'Check stderr output for details'
+          stderr: stderr_text
         )
         raise @exit_error
       end
@@ -544,5 +549,24 @@ module ClaudeAgentSDK
     def ready?
       @ready
     end
+
+    DEFAULT_ADAPTIVE_THINKING_TOKENS = 32_000
+
+    private
+
+    def resolve_thinking_tokens
+      if @options.thinking
+        case @options.thinking
+        when ThinkingConfigAdaptive
+          DEFAULT_ADAPTIVE_THINKING_TOKENS
+        when ThinkingConfigEnabled
+          @options.thinking.budget_tokens
+        when ThinkingConfigDisabled
+          0
+        end
+      elsif @options.max_thinking_tokens
+        @options.max_thinking_tokens
+      end
+    end
   end
 end

data/lib/claude_agent_sdk/types.rb

@@ -81,12 +81,13 @@ module ClaudeAgentSDK
 
   # User message
   class UserMessage
-    attr_accessor :content, :uuid, :parent_tool_use_id
+    attr_accessor :content, :uuid, :parent_tool_use_id, :tool_use_result
 
-    def initialize(content:, uuid: nil, parent_tool_use_id: nil)
+    def initialize(content:, uuid: nil, parent_tool_use_id: nil, tool_use_result: nil)
       @content = content
       @uuid = uuid # Unique identifier for rewind support
       @parent_tool_use_id = parent_tool_use_id
+      @tool_use_result = tool_use_result # Tool result data when message is a tool response
     end
   end
 
@@ -144,6 +145,45 @@ module ClaudeAgentSDK
     end
   end
 
+  # Rate limit event emitted by Claude Code CLI when API rate limits are hit
+  class RateLimitEvent
+    attr_accessor :data
+
+    def initialize(data:)
+      @data = data
+    end
+  end
+
+  # Thinking configuration types
+
+  # Adaptive thinking: uses a default budget of 32000 tokens
+  class ThinkingConfigAdaptive
+    attr_accessor :type
+
+    def initialize
+      @type = 'adaptive'
+    end
+  end
+
+  # Enabled thinking: uses a user-specified budget
+  class ThinkingConfigEnabled
+    attr_accessor :type, :budget_tokens
+
+    def initialize(budget_tokens:)
+      @type = 'enabled'
+      @budget_tokens = budget_tokens
+    end
+  end
+
+  # Disabled thinking: sets thinking tokens to 0
+  class ThinkingConfigDisabled
+    attr_accessor :type
+
+    def initialize
+      @type = 'disabled'
+    end
+  end
+
   # Agent definition configuration
   class AgentDefinition
     attr_accessor :description, :prompt, :tools, :model
@@ -269,26 +309,29 @@ module ClaudeAgentSDK
 
   # PreToolUse hook input
   class PreToolUseHookInput < BaseHookInput
-    attr_accessor :hook_event_name, :tool_name, :tool_input
+    attr_accessor :hook_event_name, :tool_name, :tool_input, :tool_use_id
 
-    def initialize(hook_event_name: 'PreToolUse', tool_name: nil, tool_input: nil, **base_args)
+    def initialize(hook_event_name: 'PreToolUse', tool_name: nil, tool_input: nil, tool_use_id: nil, **base_args)
       super(**base_args)
       @hook_event_name = hook_event_name
       @tool_name = tool_name
       @tool_input = tool_input
+      @tool_use_id = tool_use_id
     end
   end
 
   # PostToolUse hook input
   class PostToolUseHookInput < BaseHookInput
-    attr_accessor :hook_event_name, :tool_name, :tool_input, :tool_response
+    attr_accessor :hook_event_name, :tool_name, :tool_input, :tool_response, :tool_use_id
 
-    def initialize(hook_event_name: 'PostToolUse', tool_name: nil, tool_input: nil, tool_response: nil, **base_args)
+    def initialize(hook_event_name: 'PostToolUse', tool_name: nil, tool_input: nil, tool_response: nil,
+                   tool_use_id: nil, **base_args)
       super(**base_args)
       @hook_event_name = hook_event_name
       @tool_name = tool_name
       @tool_input = tool_input
       @tool_response = tool_response
+      @tool_use_id = tool_use_id
     end
   end
 
@@ -398,13 +441,16 @@ module ClaudeAgentSDK
 
   # PreToolUse hook specific output
   class PreToolUseHookSpecificOutput
-    attr_accessor :hook_event_name, :permission_decision, :permission_decision_reason, :updated_input
+    attr_accessor :hook_event_name, :permission_decision, :permission_decision_reason,
+                  :updated_input, :additional_context
 
-    def initialize(permission_decision: nil, permission_decision_reason: nil, updated_input: nil)
+    def initialize(permission_decision: nil, permission_decision_reason: nil, updated_input: nil,
+                   additional_context: nil)
       @hook_event_name = 'PreToolUse'
       @permission_decision = permission_decision # 'allow', 'deny', or 'ask'
       @permission_decision_reason = permission_decision_reason
       @updated_input = updated_input
+      @additional_context = additional_context
     end
 
     def to_h
@@ -412,6 +458,7 @@ module ClaudeAgentSDK
       result[:permissionDecision] = @permission_decision if @permission_decision
       result[:permissionDecisionReason] = @permission_decision_reason if @permission_decision_reason
       result[:updatedInput] = @updated_input if @updated_input
+      result[:additionalContext] = @additional_context if @additional_context
       result
     end
   end
@@ -782,7 +829,8 @@ module ClaudeAgentSDK
                   :fork_session, :agents, :setting_sources,
                   :output_format, :max_budget_usd, :max_thinking_tokens,
                   :fallback_model, :plugins, :debug_stderr,
-                  :betas, :tools, :sandbox, :enable_file_checkpointing, :append_allowed_tools
+                  :betas, :tools, :sandbox, :enable_file_checkpointing, :append_allowed_tools,
+                  :thinking, :effort
 
     # Non-nil defaults for options that need them.
     # Keys absent from here default to nil.
@@ -844,13 +892,14 @@ module ClaudeAgentSDK
 
   # SDK MCP Tool definition
   class SdkMcpTool
-    attr_accessor :name, :description, :input_schema, :handler
+    attr_accessor :name, :description, :input_schema, :handler, :annotations
 
-    def initialize(name:, description:, input_schema:, handler:)
+    def initialize(name:, description:, input_schema:, handler:, annotations: nil)
       @name = name
       @description = description
       @input_schema = input_schema
       @handler = handler
+      @annotations = annotations # MCP tool annotations (e.g., { title: '...', readOnlyHint: true })
     end
   end
 

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -65,12 +65,46 @@ module ClaudeAgentSDK
     options = options.dup_with(env: (options.env || {}).merge('CLAUDE_CODE_ENTRYPOINT' => 'sdk-rb'))
 
     Async do
-      transport = SubprocessCLITransport.new(prompt, options)
+      # 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)
       begin
         transport.connect
 
-        # If prompt is an Enumerator, write each message to stdin
-        if prompt.is_a?(Enumerator) || prompt.respond_to?(:each)
+        # Extract SDK MCP servers
+        sdk_mcp_servers = {}
+        if options.mcp_servers.is_a?(Hash)
+          options.mcp_servers.each do |name, config|
+            sdk_mcp_servers[name] = config[:instance] if config.is_a?(Hash) && config[:type] == 'sdk'
+          end
+        end
+
+        # Create Query handler for control protocol
+        query_handler = Query.new(
+          transport: transport,
+          is_streaming_mode: true,
+          agents: options.agents,
+          sdk_mcp_servers: sdk_mcp_servers
+        )
+
+        # Start reading messages in background
+        query_handler.start
+
+        # Initialize the control protocol (sends agents)
+        query_handler.initialize_protocol
+
+        # Send prompt(s) as user messages, then close stdin
+        if prompt.is_a?(String)
+          message = {
+            type: 'user',
+            message: { role: 'user', content: prompt },
+            parent_tool_use_id: nil,
+            session_id: 'default'
+          }
+          transport.write(JSON.generate(message) + "\n")
+          transport.end_input
+        elsif prompt.is_a?(Enumerator) || prompt.respond_to?(:each)
           Async do
             begin
               prompt.each do |message_json|
@@ -82,13 +116,18 @@ module ClaudeAgentSDK
           end
         end
 
-        # Read and yield messages
-        transport.read_messages do |data|
+        # Read and yield messages from the query handler (filters out control messages)
+        query_handler.receive_messages do |data|
           message = MessageParser.parse(data)
           block.call(message)
         end
       ensure
-        transport.close
+        # query_handler.close stops the background read task and closes the transport
+        if query_handler
+          query_handler.close
+        else
+          transport.close
+        end
       end
     end.wait
   end
@@ -167,7 +206,7 @@ module ClaudeAgentSDK
       )
 
       # Client always uses streaming mode; keep stdin open for bidirectional communication.
-      @transport = SubprocessCLITransport.new([].to_enum, configured_options)
+      @transport = SubprocessCLITransport.new(configured_options)
       @transport.connect
 
       # Extract SDK MCP servers
@@ -187,7 +226,8 @@ module ClaudeAgentSDK
         is_streaming_mode: true,
         can_use_tool: configured_options.can_use_tool,
         hooks: hooks,
-        sdk_mcp_servers: sdk_mcp_servers
+        sdk_mcp_servers: sdk_mcp_servers,
+        agents: configured_options.agents
       )
 
       # Start query handler and initialize

metadata

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