claude-agent-sdk 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db20a5dbe6ebc51b229f4de595489038a26a47d8109600131c45aa2bf27c6d2e
-  data.tar.gz: 563e16e88a48ce331cd48c6ebce3302f0c57292ee6563ebaec7af02bed29433d
+  metadata.gz: b1d1549408835720ec2fefea719ca9ccb948b0010bae0bbeb2955ac5e461fd8c
+  data.tar.gz: 2b65f85b5ce0dec97e03395652ffeeadf6af4465a5346fc45d587ac20ac93642
 SHA512:
-  metadata.gz: 288868f49db2968d92dc2250fe2ca91b7692431c92dc4fce41b04a35610858c146490da45178290877988a9210d67ebdf8257363f651e058a0bab534d24222fc
-  data.tar.gz: 183224c382c68b916da22c20c64d2f4fd625861baee265611bae8f752c25effcc7de2159a61cc65822cd62f24344f85b485cd1e6005ceff0e88ea2c34be4c30c
+  metadata.gz: 1de77e6f190cc6d474232801b53db8abdf8c239832266b304f6f48399317ab31f8b9298f8ed8af554d142d878476ba81ad712832a117fd01f8abffb798d50be1
+  data.tar.gz: 9f9c6ad3bef6990c9e9efaea2f0b49c120b703508a74aaf152836032521b92143d07129f4930569a3bb5de97db1abac7f5d6e1868d9bcfb9bcf9a9fead5e1064

data/README.md

@@ -1,19 +1,32 @@
 # Claude Agent SDK for Ruby
 
-> **⚠️ DISCLAIMER**: This is an **unofficial, community-maintained** Ruby SDK for Claude Agent. It is not officially supported or maintained by Anthropic. For official SDK support, please refer to the [Python SDK](https://docs.claude.com/en/api/agent-sdk/python).
+> **Disclaimer**: This is an **unofficial, community-maintained** Ruby SDK for Claude Agent. It is not officially supported by Anthropic. For official SDK support, see the [Python SDK](https://docs.claude.com/en/api/agent-sdk/python).
 >
 > This implementation is based on the official Python SDK and aims to provide feature parity for Ruby developers. Use at your own risk.
 
-Ruby SDK for Claude Agent. See the [Claude Agent SDK documentation](https://docs.anthropic.com/en/docs/claude-code/sdk) for more information.
-
 [![Gem Version](https://badge.fury.io/rb/claude-agent-sdk.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/claude-agent-sdk)
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Basic Usage: query()](#basic-usage-query)
+- [Client](#client)
+- [Custom Tools (SDK MCP Servers)](#custom-tools-sdk-mcp-servers)
+- [Hooks](#hooks)
+- [Permission Callbacks](#permission-callbacks)
+- [Types](#types)
+- [Error Handling](#error-handling)
+- [Examples](#examples)
+- [Development](#development)
+- [License](#license)
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'claude-agent-sdk', '~> 0.2.0'
+gem 'claude-agent-sdk', '~> 0.2.1'
 ```
 
 And then execute:
@@ -45,7 +58,7 @@ end
 
 ## Basic Usage: query()
 
-`query()` is a function for querying Claude Code. It yields response messages to a block. See [lib/claude_agent_sdk.rb](lib/claude_agent_sdk.rb).
+`query()` is a function for querying Claude Code. It yields response messages to a block.
 
 ```ruby
 require 'claude_agent_sdk'
@@ -133,11 +146,66 @@ For a complete example, see [examples/streaming_input_example.rb](examples/strea
 
 `ClaudeAgentSDK::Client` supports bidirectional, interactive conversations with Claude Code. Unlike `query()`, `Client` enables **custom tools**, **hooks**, and **permission callbacks**, all of which can be defined as Ruby procs/lambdas.
 
-**The Client class automatically uses streaming mode** for bidirectional communication, allowing you to send multiple queries dynamically during a single session without closing the connection. This matches the Python SDK's `ClaudeSDKClient` behavior.
+**The Client class automatically uses streaming mode** for bidirectional communication, allowing you to send multiple queries dynamically during a single session without closing the connection.
+
+### Basic Client Usage
+
+```ruby
+require 'claude_agent_sdk'
+require 'async'
+
+Async do
+  client = ClaudeAgentSDK::Client.new
+
+  begin
+    # Connect automatically uses streaming mode for bidirectional communication
+    client.connect
+
+    # Send a query
+    client.query("What is the capital of France?")
+
+    # Receive the response
+    client.receive_response do |msg|
+      if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
+        msg.content.each do |block|
+          puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
+        end
+      elsif msg.is_a?(ClaudeAgentSDK::ResultMessage)
+        puts "Cost: $#{msg.total_cost_usd}" if msg.total_cost_usd
+      end
+    end
+
+  ensure
+    client.disconnect
+  end
+end.wait
+```
+
+### Advanced Client Features
+
+```ruby
+Async do
+  client = ClaudeAgentSDK::Client.new
+  client.connect
 
-See [lib/claude_agent_sdk.rb](lib/claude_agent_sdk.rb) for implementation details.
+  # Send interrupt signal
+  client.interrupt
 
-### Custom Tools (SDK MCP Servers)
+  # Change permission mode during conversation
+  client.set_permission_mode('acceptEdits')
+
+  # Change AI model during conversation
+  client.set_model('claude-sonnet-4-5')
+
+  # Get server initialization info
+  info = client.server_info
+  puts "Available commands: #{info}"
+
+  client.disconnect
+end.wait
+```
+
+## Custom Tools (SDK MCP Servers)
 
 A **custom tool** is a Ruby proc/lambda that you can offer to Claude, for Claude to invoke as needed.
 
@@ -145,9 +213,7 @@ Custom tools are implemented as in-process MCP servers that run directly within
 
 **Implementation**: This SDK uses the [official Ruby MCP SDK](https://github.com/modelcontextprotocol/ruby-sdk) (`mcp` gem) internally, providing full protocol compliance while offering a simpler block-based API for tool definition.
 
-For a complete example, see [examples/mcp_calculator.rb](examples/mcp_calculator.rb).
-
-#### Creating a Simple Tool
+### Creating a Simple Tool
 
 ```ruby
 require 'claude_agent_sdk'
@@ -182,7 +248,7 @@ Async do
 end.wait
 ```
 
-#### Benefits Over External MCP Servers
+### Benefits Over External MCP Servers
 
 - **No subprocess management** - Runs in the same process as your application
 - **Better performance** - No IPC overhead for tool calls
@@ -190,7 +256,7 @@ end.wait
 - **Easier debugging** - All code runs in the same process
 - **Direct access** - Tools can directly access your application's state
 
-#### Calculator Example
+### Calculator Example
 
 ```ruby
 # Define calculator tools
@@ -220,7 +286,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 )
 ```
 
-#### Mixed Server Support
+### Mixed Server Support
 
 You can use both SDK and external MCP servers together:
 
@@ -236,7 +302,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 )
 ```
 
-#### MCP Resources and Prompts
+### MCP Resources and Prompts
 
 SDK MCP servers can also expose **resources** (data sources) and **prompts** (reusable templates):
 
@@ -286,48 +352,13 @@ server = ClaudeAgentSDK.create_sdk_mcp_server(
 )
 ```
 
-For complete examples, see [examples/mcp_resources_prompts_example.rb](examples/mcp_resources_prompts_example.rb).
+For complete examples, see [examples/mcp_calculator.rb](examples/mcp_calculator.rb) and [examples/mcp_resources_prompts_example.rb](examples/mcp_resources_prompts_example.rb).
 
-### Basic Client Usage
-
-```ruby
-require 'claude_agent_sdk'
-require 'async'
-
-Async do
-  client = ClaudeAgentSDK::Client.new
-
-  begin
-    # Connect automatically uses streaming mode for bidirectional communication
-    client.connect
-
-    # Send a query
-    client.query("What is the capital of France?")
-
-    # Receive the response
-    client.receive_response do |msg|
-      if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
-        msg.content.each do |block|
-          puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
-        end
-      elsif msg.is_a?(ClaudeAgentSDK::ResultMessage)
-        puts "Cost: $#{msg.total_cost_usd}" if msg.total_cost_usd
-      end
-    end
-
-  ensure
-    client.disconnect
-  end
-end.wait
-```
-
-### Hooks
+## Hooks
 
 A **hook** is a Ruby proc/lambda that the Claude Code *application* (*not* Claude) invokes at specific points of the Claude agent loop. Hooks can provide deterministic processing and automated feedback for Claude. Read more in [Claude Code Hooks Reference](https://docs.anthropic.com/en/docs/claude-code/hooks).
 
-For more examples, see [examples/hooks_example.rb](examples/hooks_example.rb).
-
-#### Example
+### Example
 
 ```ruby
 require 'claude_agent_sdk'
@@ -383,13 +414,13 @@ Async do
 end.wait
 ```
 
-### Permission Callbacks
+For more examples, see [examples/hooks_example.rb](examples/hooks_example.rb).
 
-A **permission callback** is a Ruby proc/lambda that allows you to programmatically control tool execution. This gives you fine-grained control over what tools Claude can use and with what inputs.
+## Permission Callbacks
 
-For more examples, see [examples/permission_callback_example.rb](examples/permission_callback_example.rb).
+A **permission callback** is a Ruby proc/lambda that allows you to programmatically control tool execution. This gives you fine-grained control over what tools Claude can use and with what inputs.
 
-#### Example
+### Example
 
 ```ruby
 require 'claude_agent_sdk'
@@ -440,38 +471,39 @@ Async do
 end.wait
 ```
 
-### Advanced Client Features
-
-The Client class supports several advanced features:
+For more examples, see [examples/permission_callback_example.rb](examples/permission_callback_example.rb).
 
-```ruby
-Async do
-  client = ClaudeAgentSDK::Client.new
-  client.connect
+## Types
 
-  # Send interrupt signal
-  client.interrupt
+See [lib/claude_agent_sdk/types.rb](lib/claude_agent_sdk/types.rb) for complete type definitions:
 
-  # Change permission mode during conversation
-  client.set_permission_mode('acceptEdits')
+### Message Types
 
-  # Change AI model during conversation
-  client.set_model('claude-sonnet-4-5')
+| Type | Description |
+|------|-------------|
+| `AssistantMessage` | Response from Claude with content blocks |
+| `UserMessage` | User input message |
+| `SystemMessage` | System metadata message |
+| `ResultMessage` | Final result with cost and usage information |
+| `StreamEvent` | Partial message updates during streaming |
 
-  # Get server initialization info
-  info = client.server_info
-  puts "Available commands: #{info}"
+### Content Blocks
 
-  client.disconnect
-end.wait
-```
+| Type | Description |
+|------|-------------|
+| `TextBlock` | Text content with `text` attribute |
+| `ThinkingBlock` | Claude's reasoning with `thinking` and `signature` |
+| `ToolUseBlock` | Tool invocation with `id`, `name`, and `input` |
+| `ToolResultBlock` | Tool execution result |
 
-## Types
+### Configuration
 
-See [lib/claude_agent_sdk/types.rb](lib/claude_agent_sdk/types.rb) for complete type definitions:
-- `ClaudeAgentOptions` - Configuration options
-- `AssistantMessage`, `UserMessage`, `SystemMessage`, `ResultMessage` - Message types
-- `TextBlock`, `ToolUseBlock`, `ToolResultBlock` - Content blocks
+| Type | Description |
+|------|-------------|
+| `ClaudeAgentOptions` | Main configuration for queries and clients |
+| `HookMatcher` | Hook configuration with matcher pattern |
+| `PermissionResultAllow` | Permission callback result to allow tool use |
+| `PermissionResultDeny` | Permission callback result to deny tool use |
 
 ## Error Handling
 
@@ -491,13 +523,16 @@ rescue ClaudeAgentSDK::CLIJSONDecodeError => e
 end
 ```
 
-Error types:
-- `ClaudeSDKError` - Base error
-- `CLINotFoundError` - Claude Code not installed
-- `CLIConnectionError` - Connection issues
-- `ProcessError` - Process failed
-- `CLIJSONDecodeError` - JSON parsing issues
-- `MessageParseError` - Message parsing issues
+### Error Types
+
+| Error | Description |
+|-------|-------------|
+| `ClaudeSDKError` | Base error for all SDK errors |
+| `CLINotFoundError` | Claude Code not installed |
+| `CLIConnectionError` | Connection issues |
+| `ProcessError` | Process failed (includes `exit_code` and `stderr`) |
+| `CLIJSONDecodeError` | JSON parsing issues |
+| `MessageParseError` | Message parsing issues |
 
 See [lib/claude_agent_sdk/errors.rb](lib/claude_agent_sdk/errors.rb) for all error types.
 
@@ -507,15 +542,15 @@ See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-co
 
 ## Examples
 
-See the following examples for complete working code:
-
-- [examples/quick_start.rb](examples/quick_start.rb) - Basic `query()` usage with options
-- [examples/client_example.rb](examples/client_example.rb) - Interactive Client usage
-- [examples/streaming_input_example.rb](examples/streaming_input_example.rb) - Streaming input for multi-turn conversations
-- [examples/mcp_calculator.rb](examples/mcp_calculator.rb) - Custom tools with SDK MCP servers
-- [examples/mcp_resources_prompts_example.rb](examples/mcp_resources_prompts_example.rb) - MCP resources and prompts
-- [examples/hooks_example.rb](examples/hooks_example.rb) - Using hooks to control tool execution
-- [examples/permission_callback_example.rb](examples/permission_callback_example.rb) - Dynamic tool permission control
+| Example | Description |
+|---------|-------------|
+| [examples/quick_start.rb](examples/quick_start.rb) | Basic `query()` usage with options |
+| [examples/client_example.rb](examples/client_example.rb) | Interactive Client usage |
+| [examples/streaming_input_example.rb](examples/streaming_input_example.rb) | Streaming input for multi-turn conversations |
+| [examples/mcp_calculator.rb](examples/mcp_calculator.rb) | Custom tools with SDK MCP servers |
+| [examples/mcp_resources_prompts_example.rb](examples/mcp_resources_prompts_example.rb) | MCP resources and prompts |
+| [examples/hooks_example.rb](examples/hooks_example.rb) | Using hooks to control tool execution |
+| [examples/permission_callback_example.rb](examples/permission_callback_example.rb) | Dynamic tool permission control |
 
 ## Development
 

data/lib/claude_agent_sdk/message_parser.rb

@@ -54,7 +54,8 @@ module ClaudeAgentSDK
       AssistantMessage.new(
         content: content_blocks,
         model: data.dig(:message, :model),
-        parent_tool_use_id: data[:parent_tool_use_id]
+        parent_tool_use_id: data[:parent_tool_use_id],
+        error: data[:error] # authentication_failed, billing_error, rate_limit, invalid_request, server_error, unknown
       )
     end
 
@@ -75,7 +76,8 @@ module ClaudeAgentSDK
         session_id: data[:session_id],
         total_cost_usd: data[:total_cost_usd],
         usage: data[:usage],
-        result: data[:result]
+        result: data[:result],
+        structured_output: data[:structured_output] # Structured output when output_format is specified
       )
     end
 

data/lib/claude_agent_sdk/query.rb

@@ -217,16 +217,73 @@ module ClaudeAgentSDK
       callback = @hook_callbacks[callback_id]
       raise "No hook callback found for ID: #{callback_id}" unless callback
 
+      # Parse input data into typed HookInput object
+      input_data = request_data[:input] || {}
+      hook_input = parse_hook_input(input_data)
+
+      # Create typed HookContext
+      context = HookContext.new(signal: nil)
+
       hook_output = callback.call(
-        request_data[:input],
+        hook_input,
         request_data[:tool_use_id],
-        { signal: nil }
+        context
       )
 
       # Convert Ruby-safe field names to CLI-expected names
       convert_hook_output_for_cli(hook_output)
     end
 
+    def parse_hook_input(input_data)
+      event_name = input_data[:hook_event_name] || input_data['hook_event_name']
+      base_args = {
+        session_id: input_data[:session_id],
+        transcript_path: input_data[:transcript_path],
+        cwd: input_data[:cwd],
+        permission_mode: input_data[:permission_mode]
+      }
+
+      case event_name
+      when 'PreToolUse'
+        PreToolUseHookInput.new(
+          tool_name: input_data[:tool_name],
+          tool_input: input_data[:tool_input],
+          **base_args
+        )
+      when 'PostToolUse'
+        PostToolUseHookInput.new(
+          tool_name: input_data[:tool_name],
+          tool_input: input_data[:tool_input],
+          tool_response: input_data[:tool_response],
+          **base_args
+        )
+      when 'UserPromptSubmit'
+        UserPromptSubmitHookInput.new(
+          prompt: input_data[:prompt],
+          **base_args
+        )
+      when 'Stop'
+        StopHookInput.new(
+          stop_hook_active: input_data[:stop_hook_active],
+          **base_args
+        )
+      when 'SubagentStop'
+        SubagentStopHookInput.new(
+          stop_hook_active: input_data[:stop_hook_active],
+          **base_args
+        )
+      when 'PreCompact'
+        PreCompactHookInput.new(
+          trigger: input_data[:trigger],
+          custom_instructions: input_data[:custom_instructions],
+          **base_args
+        )
+      else
+        # Return base input for unknown event types
+        BaseHookInput.new(**base_args)
+      end
+    end
+
     def handle_mcp_message(request_data)
       server_name = request_data[:server_name]
       mcp_message = request_data[:message]
@@ -238,6 +295,13 @@ module ClaudeAgentSDK
     end
 
     def convert_hook_output_for_cli(hook_output)
+      # Handle typed output objects
+      if hook_output.respond_to?(:to_h) && !hook_output.is_a?(Hash)
+        return hook_output.to_h
+      end
+
+      return {} unless hook_output.is_a?(Hash)
+
       # Convert Ruby hash with symbol keys to CLI format
       # Handle special keywords that might be Ruby-safe versions
       converted = {}
@@ -245,9 +309,21 @@ module ClaudeAgentSDK
         converted_key = case key
                         when :async_, 'async_' then 'async'
                         when :continue_, 'continue_' then 'continue'
-                        else key.to_s.gsub('_', '')
+                        when :hook_specific_output then 'hookSpecificOutput'
+                        when :suppress_output then 'suppressOutput'
+                        when :stop_reason then 'stopReason'
+                        when :system_message then 'systemMessage'
+                        when :async_timeout then 'asyncTimeout'
+                        else key.to_s
                         end
-        converted[converted_key] = value
+
+        # Recursively convert nested objects
+        converted_value = if value.respond_to?(:to_h) && !value.is_a?(Hash)
+                            value.to_h
+                          else
+                            value
+                          end
+        converted[converted_key] = converted_value
       end
       converted
     end

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -75,12 +75,33 @@ module ClaudeAgentSDK
       cmd.concat(['--max-turns', @options.max_turns.to_s]) if @options.max_turns
       cmd.concat(['--disallowedTools', @options.disallowed_tools.join(',')]) unless @options.disallowed_tools.empty?
       cmd.concat(['--model', @options.model]) if @options.model
+      cmd.concat(['--fallback-model', @options.fallback_model]) if @options.fallback_model
       cmd.concat(['--permission-prompt-tool', @options.permission_prompt_tool_name]) if @options.permission_prompt_tool_name
       cmd.concat(['--permission-mode', @options.permission_mode]) if @options.permission_mode
       cmd << '--continue' if @options.continue_conversation
       cmd.concat(['--resume', @options.resume]) if @options.resume
       cmd.concat(['--settings', @options.settings]) if @options.settings
 
+      # New options to match Python SDK
+      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
+
+      # 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
+
       # Add directories
       @options.add_dirs.each do |dir|
         cmd.concat(['--add-dir', dir.to_s])
@@ -121,6 +142,14 @@ module ClaudeAgentSDK
         cmd.concat(['--agents', JSON.generate(agents_dict)])
       end
 
+      # 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
+
       # Setting sources
       sources_value = @options.setting_sources ? @options.setting_sources.join(',') : ''
       cmd.concat(['--setting-sources', sources_value])
@@ -159,7 +188,7 @@ module ClaudeAgentSDK
       process_env['PWD'] = @cwd.to_s if @cwd
 
       # Determine stderr handling
-      should_pipe_stderr = @options.stderr || @options.extra_args.key?('debug-to-stderr')
+      should_pipe_stderr = @options.stderr || @options.debug_stderr || @options.extra_args.key?('debug-to-stderr')
 
       begin
         # Start process using Open3
@@ -205,7 +234,17 @@ module ClaudeAgentSDK
         line_str = line.chomp
         next if line_str.empty?
 
+        # Call stderr callback if provided
         @options.stderr&.call(line_str)
+
+        # Write to debug_stderr file/IO if provided
+        if @options.debug_stderr
+          if @options.debug_stderr.respond_to?(:puts)
+            @options.debug_stderr.puts(line_str)
+          elsif @options.debug_stderr.is_a?(String)
+            File.open(@options.debug_stderr, 'a') { |f| f.puts(line_str) }
+          end
+        end
       end
     rescue StandardError
       # Ignore errors during stderr reading

data/lib/claude_agent_sdk/types.rb

@@ -1,6 +1,24 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
+  # Type constants for permission modes
+  PERMISSION_MODES = %w[default acceptEdits plan bypassPermissions].freeze
+
+  # Type constants for setting sources
+  SETTING_SOURCES = %w[user project local].freeze
+
+  # Type constants for permission update destinations
+  PERMISSION_UPDATE_DESTINATIONS = %w[userSettings projectSettings localSettings session].freeze
+
+  # Type constants for permission behaviors
+  PERMISSION_BEHAVIORS = %w[allow deny ask].freeze
+
+  # Type constants for hook events
+  HOOK_EVENTS = %w[PreToolUse PostToolUse UserPromptSubmit Stop SubagentStop PreCompact].freeze
+
+  # Type constants for assistant message errors
+  ASSISTANT_MESSAGE_ERRORS = %w[authentication_failed billing_error rate_limit invalid_request server_error unknown].freeze
+
   # Content Blocks
 
   # Text content block
@@ -58,12 +76,13 @@ module ClaudeAgentSDK
 
   # Assistant message with content blocks
   class AssistantMessage
-    attr_accessor :content, :model, :parent_tool_use_id
+    attr_accessor :content, :model, :parent_tool_use_id, :error
 
-    def initialize(content:, model:, parent_tool_use_id: nil)
+    def initialize(content:, model:, parent_tool_use_id: nil, error: nil)
       @content = content
       @model = model
       @parent_tool_use_id = parent_tool_use_id
+      @error = error # One of: authentication_failed, billing_error, rate_limit, invalid_request, server_error, unknown
     end
   end
 
@@ -80,10 +99,10 @@ module ClaudeAgentSDK
   # Result message with cost and usage information
   class ResultMessage
     attr_accessor :subtype, :duration_ms, :duration_api_ms, :is_error,
-                  :num_turns, :session_id, :total_cost_usd, :usage, :result
+                  :num_turns, :session_id, :total_cost_usd, :usage, :result, :structured_output
 
     def initialize(subtype:, duration_ms:, duration_api_ms:, is_error:,
-                   num_turns:, session_id:, total_cost_usd: nil, usage: nil, result: nil)
+                   num_turns:, session_id:, total_cost_usd: nil, usage: nil, result: nil, structured_output: nil)
       @subtype = subtype
       @duration_ms = duration_ms
       @duration_api_ms = duration_api_ms
@@ -93,6 +112,7 @@ module ClaudeAgentSDK
       @total_cost_usd = total_cost_usd
       @usage = usage
       @result = result
+      @structured_output = structured_output # Structured output when output_format is specified
     end
   end
 
@@ -201,11 +221,215 @@ module ClaudeAgentSDK
 
   # Hook matcher configuration
   class HookMatcher
-    attr_accessor :matcher, :hooks
+    attr_accessor :matcher, :hooks, :timeout
 
-    def initialize(matcher: nil, hooks: [])
+    def initialize(matcher: nil, hooks: [], timeout: nil)
       @matcher = matcher
       @hooks = hooks
+      @timeout = timeout # Timeout in seconds for hook execution
+    end
+  end
+
+  # Hook context passed to hook callbacks
+  class HookContext
+    attr_accessor :signal
+
+    def initialize(signal: nil)
+      @signal = signal
+    end
+  end
+
+  # Base hook input with common fields
+  class BaseHookInput
+    attr_accessor :session_id, :transcript_path, :cwd, :permission_mode
+
+    def initialize(session_id: nil, transcript_path: nil, cwd: nil, permission_mode: nil)
+      @session_id = session_id
+      @transcript_path = transcript_path
+      @cwd = cwd
+      @permission_mode = permission_mode
+    end
+  end
+
+  # PreToolUse hook input
+  class PreToolUseHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :tool_name, :tool_input
+
+    def initialize(hook_event_name: 'PreToolUse', tool_name: nil, tool_input: nil, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @tool_name = tool_name
+      @tool_input = tool_input
+    end
+  end
+
+  # PostToolUse hook input
+  class PostToolUseHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :tool_name, :tool_input, :tool_response
+
+    def initialize(hook_event_name: 'PostToolUse', tool_name: nil, tool_input: nil, tool_response: nil, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @tool_name = tool_name
+      @tool_input = tool_input
+      @tool_response = tool_response
+    end
+  end
+
+  # UserPromptSubmit hook input
+  class UserPromptSubmitHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :prompt
+
+    def initialize(hook_event_name: 'UserPromptSubmit', prompt: nil, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @prompt = prompt
+    end
+  end
+
+  # Stop hook input
+  class StopHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :stop_hook_active
+
+    def initialize(hook_event_name: 'Stop', stop_hook_active: false, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @stop_hook_active = stop_hook_active
+    end
+  end
+
+  # SubagentStop hook input
+  class SubagentStopHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :stop_hook_active
+
+    def initialize(hook_event_name: 'SubagentStop', stop_hook_active: false, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @stop_hook_active = stop_hook_active
+    end
+  end
+
+  # PreCompact hook input
+  class PreCompactHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :trigger, :custom_instructions
+
+    def initialize(hook_event_name: 'PreCompact', trigger: nil, custom_instructions: nil, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @trigger = trigger
+      @custom_instructions = custom_instructions
+    end
+  end
+
+  # PreToolUse hook specific output
+  class PreToolUseHookSpecificOutput
+    attr_accessor :hook_event_name, :permission_decision, :permission_decision_reason, :updated_input
+
+    def initialize(permission_decision: nil, permission_decision_reason: nil, updated_input: nil)
+      @hook_event_name = 'PreToolUse'
+      @permission_decision = permission_decision # 'allow', 'deny', or 'ask'
+      @permission_decision_reason = permission_decision_reason
+      @updated_input = updated_input
+    end
+
+    def to_h
+      result = { hookEventName: @hook_event_name }
+      result[:permissionDecision] = @permission_decision if @permission_decision
+      result[:permissionDecisionReason] = @permission_decision_reason if @permission_decision_reason
+      result[:updatedInput] = @updated_input if @updated_input
+      result
+    end
+  end
+
+  # PostToolUse hook specific output
+  class PostToolUseHookSpecificOutput
+    attr_accessor :hook_event_name, :additional_context
+
+    def initialize(additional_context: nil)
+      @hook_event_name = 'PostToolUse'
+      @additional_context = additional_context
+    end
+
+    def to_h
+      result = { hookEventName: @hook_event_name }
+      result[:additionalContext] = @additional_context if @additional_context
+      result
+    end
+  end
+
+  # UserPromptSubmit hook specific output
+  class UserPromptSubmitHookSpecificOutput
+    attr_accessor :hook_event_name, :additional_context
+
+    def initialize(additional_context: nil)
+      @hook_event_name = 'UserPromptSubmit'
+      @additional_context = additional_context
+    end
+
+    def to_h
+      result = { hookEventName: @hook_event_name }
+      result[:additionalContext] = @additional_context if @additional_context
+      result
+    end
+  end
+
+  # SessionStart hook specific output
+  class SessionStartHookSpecificOutput
+    attr_accessor :hook_event_name, :additional_context
+
+    def initialize(additional_context: nil)
+      @hook_event_name = 'SessionStart'
+      @additional_context = additional_context
+    end
+
+    def to_h
+      result = { hookEventName: @hook_event_name }
+      result[:additionalContext] = @additional_context if @additional_context
+      result
+    end
+  end
+
+  # Async hook JSON output
+  class AsyncHookJSONOutput
+    attr_accessor :async, :async_timeout
+
+    def initialize(async: true, async_timeout: nil)
+      @async = async
+      @async_timeout = async_timeout
+    end
+
+    def to_h
+      result = { async: @async }
+      result[:asyncTimeout] = @async_timeout if @async_timeout
+      result
+    end
+  end
+
+  # Sync hook JSON output
+  class SyncHookJSONOutput
+    attr_accessor :continue, :suppress_output, :stop_reason, :decision,
+                  :system_message, :reason, :hook_specific_output
+
+    def initialize(continue: true, suppress_output: false, stop_reason: nil, decision: nil,
+                   system_message: nil, reason: nil, hook_specific_output: nil)
+      @continue = continue
+      @suppress_output = suppress_output
+      @stop_reason = stop_reason
+      @decision = decision
+      @system_message = system_message
+      @reason = reason
+      @hook_specific_output = hook_specific_output
+    end
+
+    def to_h
+      result = { continue: @continue }
+      result[:suppressOutput] = @suppress_output if @suppress_output
+      result[:stopReason] = @stop_reason if @stop_reason
+      result[:decision] = @decision if @decision
+      result[:systemMessage] = @system_message if @system_message
+      result[:reason] = @reason if @reason
+      result[:hookSpecificOutput] = @hook_specific_output.to_h if @hook_specific_output
+      result
     end
   end
 
@@ -274,6 +498,20 @@ module ClaudeAgentSDK
     end
   end
 
+  # SDK Plugin configuration
+  class SdkPluginConfig
+    attr_accessor :type, :path
+
+    def initialize(path:)
+      @type = 'plugin'
+      @path = path
+    end
+
+    def to_h
+      { type: @type, path: @path }
+    end
+  end
+
   # Claude Agent Options for configuring queries
   class ClaudeAgentOptions
     attr_accessor :allowed_tools, :system_prompt, :mcp_servers, :permission_mode,
@@ -281,7 +519,10 @@ module ClaudeAgentSDK
                   :model, :permission_prompt_tool_name, :cwd, :cli_path, :settings,
                   :add_dirs, :env, :extra_args, :max_buffer_size, :stderr,
                   :can_use_tool, :hooks, :user, :include_partial_messages,
-                  :fork_session, :agents, :setting_sources
+                  :fork_session, :agents, :setting_sources,
+                  # New options added to match Python SDK
+                  :output_format, :max_budget_usd, :max_thinking_tokens,
+                  :fallback_model, :plugins, :debug_stderr
 
     def initialize(
       allowed_tools: [],
@@ -308,7 +549,14 @@ module ClaudeAgentSDK
       include_partial_messages: false,
       fork_session: false,
       agents: nil,
-      setting_sources: nil
+      setting_sources: nil,
+      # New options added to match Python SDK
+      output_format: nil,
+      max_budget_usd: nil,
+      max_thinking_tokens: nil,
+      fallback_model: nil,
+      plugins: nil,
+      debug_stderr: nil
     )
       @allowed_tools = allowed_tools
       @system_prompt = system_prompt
@@ -335,6 +583,13 @@ module ClaudeAgentSDK
       @fork_session = fork_session
       @agents = agents
       @setting_sources = setting_sources
+      # New options added to match Python SDK
+      @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
     end
 
     def dup_with(**changes)

data/lib/claude_agent_sdk/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2025-10-17 00:00:00.000000000 Z
+date: 2025-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async