claude-agent-sdk 0.2.1 → 0.4.0

data/README.md

@@ -1,19 +1,39 @@
 # 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)
+- [Structured Output](#structured-output)
+- [Budget Control](#budget-control)
+- [Fallback Model](#fallback-model)
+- [Beta Features](#beta-features)
+- [Tools Configuration](#tools-configuration)
+- [Sandbox Settings](#sandbox-settings)
+- [File Checkpointing & Rewind](#file-checkpointing--rewind)
+- [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.4.0'
 ```
 
 And then execute:
@@ -45,7 +65,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 +153,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.
 
-See [lib/claude_agent_sdk.rb](lib/claude_agent_sdk.rb) for implementation details.
+### Basic Client Usage
+
+```ruby
+require 'claude_agent_sdk'
+require 'async'
 
-### Custom Tools (SDK MCP Servers)
+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
+
+  # Send interrupt signal
+  client.interrupt
+
+  # 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 +220,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 +255,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 +263,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 +293,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 )
 ```
 
-#### Mixed Server Support
+### Mixed Server Support
 
 You can use both SDK and external MCP servers together:
 
@@ -236,7 +309,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 +359,13 @@ server = ClaudeAgentSDK.create_sdk_mcp_server(
 )
 ```
 
-For complete examples, see [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
-```
+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).
 
-### 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 +421,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,41 +478,419 @@ Async do
 end.wait
 ```
 
-### Advanced Client Features
+For more examples, see [examples/permission_callback_example.rb](examples/permission_callback_example.rb).
+
+## Structured Output
 
-The Client class supports several advanced features:
+Use `output_format` to get validated JSON responses matching a schema. The Claude CLI returns structured output via a `StructuredOutput` tool use block.
 
 ```ruby
+require 'claude_agent_sdk'
+require 'json'
+
+# Define a JSON schema
+schema = {
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    age: { type: 'integer' },
+    skills: { type: 'array', items: { type: 'string' } }
+  },
+  required: %w[name age skills]
+}
+
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  output_format: { type: 'json_schema', schema: schema },
+  max_turns: 3
+)
+
+structured_data = nil
+
+ClaudeAgentSDK.query(
+  prompt: "Create a profile for a software engineer",
+  options: options
+) do |message|
+  if message.is_a?(ClaudeAgentSDK::AssistantMessage)
+    message.content.each do |block|
+      # Structured output comes via StructuredOutput tool use
+      if block.is_a?(ClaudeAgentSDK::ToolUseBlock) && block.name == 'StructuredOutput'
+        structured_data = block.input
+      end
+    end
+  end
+end
+
+if structured_data
+  puts "Name: #{structured_data[:name]}"
+  puts "Age: #{structured_data[:age]}"
+  puts "Skills: #{structured_data[:skills].join(', ')}"
+end
+```
+
+For complete examples, see [examples/structured_output_example.rb](examples/structured_output_example.rb).
+
+## Budget Control
+
+Use `max_budget_usd` to set a spending cap for your queries:
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  max_budget_usd: 0.10,  # Cap at $0.10
+  max_turns: 3
+)
+
+ClaudeAgentSDK.query(prompt: "Explain recursion", options: options) do |message|
+  if message.is_a?(ClaudeAgentSDK::ResultMessage)
+    puts "Cost: $#{message.total_cost_usd}"
+  end
+end
+```
+
+For complete examples, see [examples/budget_control_example.rb](examples/budget_control_example.rb).
+
+## Fallback Model
+
+Use `fallback_model` to specify a backup model if the primary is unavailable:
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  model: 'claude-sonnet-4-20250514',
+  fallback_model: 'claude-3-5-haiku-20241022'
+)
+
+ClaudeAgentSDK.query(prompt: "Hello", options: options) do |message|
+  if message.is_a?(ClaudeAgentSDK::AssistantMessage)
+    puts "Model used: #{message.model}"
+  end
+end
+```
+
+For complete examples, see [examples/fallback_model_example.rb](examples/fallback_model_example.rb).
+
+## Beta Features
+
+Enable experimental features using the `betas` option:
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  betas: ['context-1m-2025-08-07']  # Extended context window
+)
+
+ClaudeAgentSDK.query(prompt: "Analyze this large document...", options: options) do |message|
+  puts message
+end
+```
+
+Available beta features are listed in the `SDK_BETAS` constant.
+
+## Tools Configuration
+
+Configure base tools separately from allowed tools:
+
+```ruby
+# Using an array of tool names
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  tools: ['Read', 'Edit', 'Bash']  # Base tools available
+)
+
+# Using a preset
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  tools: ClaudeAgentSDK::ToolsPreset.new(preset: 'claude_code')
+)
+
+# Appending to allowed tools
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  append_allowed_tools: ['Write', 'Bash']
+)
+```
+
+## Sandbox Settings
+
+Run commands in an isolated sandbox for additional security:
+
+```ruby
+sandbox = ClaudeAgentSDK::SandboxSettings.new(
+  enabled: true,
+  auto_allow_bash_if_sandboxed: true,
+  network: ClaudeAgentSDK::SandboxNetworkConfig.new(
+    allow_local_binding: true
+  )
+)
+
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  sandbox: sandbox,
+  permission_mode: 'acceptEdits'
+)
+
+ClaudeAgentSDK.query(prompt: "Run some commands", options: options) do |message|
+  puts message
+end
+```
+
+## File Checkpointing & Rewind
+
+Enable file checkpointing to revert file changes to a previous state:
+
+```ruby
+require 'async'
+
 Async do
-  client = ClaudeAgentSDK::Client.new
-  client.connect
+  options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+    enable_file_checkpointing: true,
+    permission_mode: 'acceptEdits'
+  )
 
-  # Send interrupt signal
-  client.interrupt
+  client = ClaudeAgentSDK::Client.new(options: options)
+  client.connect
 
-  # Change permission mode during conversation
-  client.set_permission_mode('acceptEdits')
+  # Track user message UUIDs for potential rewind
+  user_message_uuids = []
+
+  # First query - create a file
+  client.query("Create a test.rb file with some code")
+  client.receive_response do |message|
+    # Process all message types as needed
+    case message
+    when ClaudeAgentSDK::UserMessage
+      # Capture UUID for rewind capability
+      user_message_uuids << message.uuid if message.uuid
+    when ClaudeAgentSDK::AssistantMessage
+      # Handle assistant responses
+      message.content.each do |block|
+        puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
+      end
+    when ClaudeAgentSDK::ResultMessage
+      puts "Query completed (cost: $#{message.total_cost_usd})"
+    end
+  end
 
-  # Change AI model during conversation
-  client.set_model('claude-sonnet-4-5')
+  # Second query - modify the file
+  client.query("Modify the test.rb file to add error handling")
+  client.receive_response do |message|
+    user_message_uuids << message.uuid if message.is_a?(ClaudeAgentSDK::UserMessage) && message.uuid
+  end
 
-  # Get server initialization info
-  info = client.server_info
-  puts "Available commands: #{info}"
+  # Rewind to the first checkpoint (undoes the second query's changes)
+  if user_message_uuids.first
+    puts "Rewinding to checkpoint: #{user_message_uuids.first}"
+    client.rewind_files(user_message_uuids.first)
+  end
 
   client.disconnect
-end.wait
+end
 ```
 
+> **Note:** The `uuid` field on `UserMessage` is populated by the CLI and represents checkpoint identifiers. Rewinding to a UUID restores file state to what it was at that point in the conversation.
+
 ## Types
 
-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
+See [lib/claude_agent_sdk/types.rb](lib/claude_agent_sdk/types.rb) for complete type definitions.
+
+### Message Types
+
+```ruby
+# Union type of all possible messages
+Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage
+```
+
+#### UserMessage
+
+User input message.
+
+```ruby
+class UserMessage
+  attr_accessor :content,           # String | Array<ContentBlock>
+                :uuid,              # String | nil - Unique ID for rewind support
+                :parent_tool_use_id # String | nil
+end
+```
+
+#### AssistantMessage
+
+Assistant response message with content blocks.
+
+```ruby
+class AssistantMessage
+  attr_accessor :content,           # Array<ContentBlock>
+                :model,             # String
+                :parent_tool_use_id,# String | nil
+                :error              # String | nil ('authentication_failed', 'billing_error', 'rate_limit', 'invalid_request', 'server_error', 'unknown')
+end
+```
+
+#### SystemMessage
+
+System message with metadata.
+
+```ruby
+class SystemMessage
+  attr_accessor :subtype,  # String ('init', etc.)
+                :data      # Hash
+end
+```
+
+#### ResultMessage
+
+Final result message with cost and usage information.
+
+```ruby
+class ResultMessage
+  attr_accessor :subtype,           # String
+                :duration_ms,       # Integer
+                :duration_api_ms,   # Integer
+                :is_error,          # Boolean
+                :num_turns,         # Integer
+                :session_id,        # String
+                :total_cost_usd,    # Float | nil
+                :usage,             # Hash | nil
+                :result,            # String | nil (final text result)
+                :structured_output  # Hash | nil (when using output_format)
+end
+```
+
+### Content Block Types
+
+```ruby
+# Union type of all content blocks
+ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
+```
+
+#### TextBlock
+
+Text content block.
+
+```ruby
+class TextBlock
+  attr_accessor :text  # String
+end
+```
+
+#### ThinkingBlock
+
+Thinking content block (for models with extended thinking capability).
+
+```ruby
+class ThinkingBlock
+  attr_accessor :thinking,  # String
+                :signature  # String
+end
+```
+
+#### ToolUseBlock
+
+Tool use request block.
+
+```ruby
+class ToolUseBlock
+  attr_accessor :id,    # String
+                :name,  # String
+                :input  # Hash
+end
+```
+
+#### ToolResultBlock
+
+Tool execution result block.
+
+```ruby
+class ToolResultBlock
+  attr_accessor :tool_use_id,  # String
+                :content,      # String | Array<Hash> | nil
+                :is_error      # Boolean | nil
+end
+```
+
+### Error Types
+
+```ruby
+# Base exception class for all SDK errors
+class ClaudeSDKError < StandardError; end
+
+# Raised when Claude Code CLI is not found
+class CLINotFoundError < CLIConnectionError
+  # @param message [String] Error message (default: "Claude Code not found")
+  # @param cli_path [String, nil] Optional path to the CLI that was not found
+end
+
+# Raised when connection to Claude Code fails
+class CLIConnectionError < ClaudeSDKError; end
+
+# Raised when the Claude Code process fails
+class ProcessError < ClaudeSDKError
+  attr_reader :exit_code,  # Integer | nil
+              :stderr      # String | nil
+end
+
+# Raised when JSON parsing fails
+class CLIJSONDecodeError < ClaudeSDKError
+  attr_reader :line,           # String - The line that failed to parse
+              :original_error  # Exception - The original JSON decode exception
+end
+
+# Raised when message parsing fails
+class MessageParseError < ClaudeSDKError
+  attr_reader :data  # Hash | nil
+end
+```
+
+### Configuration Types
+
+| Type | Description |
+|------|-------------|
+| `ClaudeAgentOptions` | Main configuration for queries and clients |
+| `HookMatcher` | Hook configuration with matcher pattern and timeout |
+| `PermissionResultAllow` | Permission callback result to allow tool use |
+| `PermissionResultDeny` | Permission callback result to deny tool use |
+| `AgentDefinition` | Agent definition with description, prompt, tools, model |
+| `McpStdioServerConfig` | MCP server config for stdio transport |
+| `McpSSEServerConfig` | MCP server config for SSE transport |
+| `McpHttpServerConfig` | MCP server config for HTTP transport |
+| `SdkPluginConfig` | SDK plugin configuration |
+| `SandboxSettings` | Sandbox settings for isolated command execution |
+| `SandboxNetworkConfig` | Network configuration for sandbox |
+| `SandboxIgnoreViolations` | Configure which sandbox violations to ignore |
+| `SystemPromptPreset` | System prompt preset configuration |
+| `ToolsPreset` | Tools preset configuration for base tools selection |
+
+### Constants
+
+| Constant | Description |
+|----------|-------------|
+| `SDK_BETAS` | Available beta features (e.g., `"context-1m-2025-08-07"`) |
+| `PERMISSION_MODES` | Available permission modes |
+| `SETTING_SOURCES` | Available setting sources |
+| `HOOK_EVENTS` | Available hook events |
+| `ASSISTANT_MESSAGE_ERRORS` | Possible error types in AssistantMessage |
 
 ## Error Handling
 
+### AssistantMessage Errors
+
+`AssistantMessage` includes an `error` field for API-level errors:
+
+```ruby
+ClaudeAgentSDK.query(prompt: "Hello") do |message|
+  if message.is_a?(ClaudeAgentSDK::AssistantMessage) && message.error
+    case message.error
+    when 'rate_limit'
+      puts "Rate limited - retry after delay"
+    when 'authentication_failed'
+      puts "Check your API key"
+    when 'billing_error'
+      puts "Check your billing status"
+    when 'invalid_request'
+      puts "Invalid request format"
+    when 'server_error'
+      puts "Server error - retry later"
+    end
+  end
+end
+```
+
+For complete examples, see [examples/error_handling_example.rb](examples/error_handling_example.rb).
+
+### Exception Handling
+
 ```ruby
 require 'claude_agent_sdk'
 
@@ -491,13 +907,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 +926,21 @@ 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 |
+| [examples/structured_output_example.rb](examples/structured_output_example.rb) | JSON schema structured output |
+| [examples/budget_control_example.rb](examples/budget_control_example.rb) | Budget control with `max_budget_usd` |
+| [examples/fallback_model_example.rb](examples/fallback_model_example.rb) | Fallback model configuration |
+| [examples/advanced_hooks_example.rb](examples/advanced_hooks_example.rb) | Typed hook inputs/outputs |
+| [examples/error_handling_example.rb](examples/error_handling_example.rb) | Error handling with `AssistantMessage.error` |
+| [examples/extended_thinking_example.rb](examples/extended_thinking_example.rb) | Extended thinking (API parity) |
 
 ## Development