claude-agent-sdk 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1d1549408835720ec2fefea719ca9ccb948b0010bae0bbeb2955ac5e461fd8c
-  data.tar.gz: 2b65f85b5ce0dec97e03395652ffeeadf6af4465a5346fc45d587ac20ac93642
+  metadata.gz: d4b8c3f8f0eefdfe38747d264f5d89148e1e589f12c200796dd2c37e821b3f61
+  data.tar.gz: 60252ef9c5f8679526a1f76b1be4216138e8bc7d91deb7bc1235b94d04a8481d
 SHA512:
-  metadata.gz: 1de77e6f190cc6d474232801b53db8abdf8c239832266b304f6f48399317ab31f8b9298f8ed8af554d142d878476ba81ad712832a117fd01f8abffb798d50be1
-  data.tar.gz: 9f9c6ad3bef6990c9e9efaea2f0b49c120b703508a74aaf152836032521b92143d07129f4930569a3bb5de97db1abac7f5d6e1868d9bcfb9bcf9a9fead5e1064
+  metadata.gz: a95797df469fa0acede9c2187d0e8dd9420582e856853552dcc4b0c09b7e4564ca7371478624a904090366d06880a2e7457f71910b88e815fbbe12d8f210f255
+  data.tar.gz: 77354e6852d2f86b060ac0e4948006ed1c28311f7481e4efa7cdc2f57864448ab0d656244559da43094cde1ac409ae25fd4aad13228640001b0e453d7d9fc753

data/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.4.0] - 2026-01-06
+
+### Added
+
+#### File Checkpointing & Rewind
+- `enable_file_checkpointing` option in `ClaudeAgentOptions` for enabling file state checkpointing
+- `rewind_files(user_message_uuid)` method on `Query` and `Client` classes
+- `uuid` field on `UserMessage` for tracking message identifiers for rewind support
+
+#### Beta Features Support
+- `SDK_BETAS` constant with available beta features (e.g., `"context-1m-2025-08-07"`)
+- `betas` option in `ClaudeAgentOptions` for enabling beta features
+
+#### Tools Configuration
+- `tools` option for base tools selection (separate from `allowed_tools`)
+- Supports array of tool names, empty array `[]`, or `ToolsPreset` object
+- `ToolsPreset` class for preset-based tool configuration
+- `append_allowed_tools` option to append tools to the allowed list
+
+#### Sandbox Settings
+- `SandboxSettings` class for isolated command execution configuration
+- `SandboxNetworkConfig` class for network isolation settings
+- `SandboxIgnoreViolations` class for configuring violation handling
+- `sandbox` option in `ClaudeAgentOptions` for sandbox configuration
+- Automatic merging of sandbox settings into the main settings JSON
+
+#### Additional Types
+- `SystemPromptPreset` class for preset-based system prompts
+
+### Technical Details
+- All new CLI flags properly passed to Claude Code subprocess
+- Sandbox settings merged into `--settings` JSON for CLI compatibility
+- UserMessage UUID parsed from CLI output for rewind support
+
 ## [0.2.0] - 2025-10-17
 
 ### Changed

data/README.md

@@ -15,6 +15,13 @@
 - [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)
@@ -26,7 +33,7 @@
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'claude-agent-sdk', '~> 0.2.1'
+gem 'claude-agent-sdk', '~> 0.4.0'
 ```
 
 And then execute:
@@ -473,40 +480,417 @@ end.wait
 
 For more examples, see [examples/permission_callback_example.rb](examples/permission_callback_example.rb).
 
+## Structured Output
+
+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
+  options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+    enable_file_checkpointing: true,
+    permission_mode: 'acceptEdits'
+  )
+
+  client = ClaudeAgentSDK::Client.new(options: options)
+  client.connect
+
+  # 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
+
+  # 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
+
+  # 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
+```
+
+> **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:
+See [lib/claude_agent_sdk/types.rb](lib/claude_agent_sdk/types.rb) for complete type definitions.
 
 ### Message Types
 
-| 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 |
+```ruby
+# Union type of all possible messages
+Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage
+```
 
-### Content Blocks
+#### UserMessage
 
-| 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 |
+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
 
-### Configuration
+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 |
+| `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'
 
@@ -551,6 +935,12 @@ See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-co
 | [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
 

data/lib/claude_agent_sdk/message_parser.rb

@@ -32,6 +32,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
       message_data = data[:message]
       raise MessageParseError.new("Missing message field in user message", data: data) unless message_data
 
@@ -40,9 +41,9 @@ module ClaudeAgentSDK
 
       if content.is_a?(Array)
         content_blocks = content.map { |block| parse_content_block(block) }
-        UserMessage.new(content: content_blocks, parent_tool_use_id: parent_tool_use_id)
+        UserMessage.new(content: content_blocks, uuid: uuid, parent_tool_use_id: parent_tool_use_id)
       else
-        UserMessage.new(content: content, parent_tool_use_id: parent_tool_use_id)
+        UserMessage.new(content: content, uuid: uuid, parent_tool_use_id: parent_tool_use_id)
       end
     end
 

data/lib/claude_agent_sdk/query.rb

@@ -551,6 +551,17 @@ module ClaudeAgentSDK
                            })
     end
 
+    # Rewind files to a previous checkpoint (v0.1.15+)
+    # Restores file state to what it was at the given user message
+    # Requires enable_file_checkpointing to be true in options
+    # @param user_message_uuid [String] The UUID of the UserMessage to rewind to
+    def rewind_files(user_message_uuid)
+      send_control_request({
+                             subtype: 'rewind_files',
+                             userMessageUuid: user_message_uuid
+                           })
+    end
+
     # Stream input messages to transport
     def stream_input(stream)
       stream.each do |message|

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -80,12 +80,77 @@ module ClaudeAgentSDK
       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
+      # 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
+
+      # 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
 
+      # Betas option for enabling experimental features
+      if @options.betas && !@options.betas.empty?
+        cmd.concat(['--betas', @options.betas.join(',')])
+      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
+
+      # 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: {...} }

data/lib/claude_agent_sdk/types.rb

@@ -19,6 +19,10 @@ module ClaudeAgentSDK
   # Type constants for assistant message errors
   ASSISTANT_MESSAGE_ERRORS = %w[authentication_failed billing_error rate_limit invalid_request server_error unknown].freeze
 
+  # Type constants for SDK beta features
+  # Available beta features that can be enabled via the betas option
+  SDK_BETAS = %w[context-1m-2025-08-07].freeze
+
   # Content Blocks
 
   # Text content block
@@ -66,10 +70,11 @@ module ClaudeAgentSDK
 
   # User message
   class UserMessage
-    attr_accessor :content, :parent_tool_use_id
+    attr_accessor :content, :uuid, :parent_tool_use_id
 
-    def initialize(content:, parent_tool_use_id: nil)
+    def initialize(content:, uuid: nil, parent_tool_use_id: nil)
       @content = content
+      @uuid = uuid # Unique identifier for rewind support
       @parent_tool_use_id = parent_tool_use_id
     end
   end
@@ -512,6 +517,125 @@ module ClaudeAgentSDK
     end
   end
 
+  # Sandbox network configuration
+  class SandboxNetworkConfig
+    attr_accessor :allow_unix_sockets, :allow_all_unix_sockets, :allow_local_binding,
+                  :http_proxy_port, :socks_proxy_port
+
+    def initialize(
+      allow_unix_sockets: nil,
+      allow_all_unix_sockets: nil,
+      allow_local_binding: nil,
+      http_proxy_port: nil,
+      socks_proxy_port: nil
+    )
+      @allow_unix_sockets = allow_unix_sockets
+      @allow_all_unix_sockets = allow_all_unix_sockets
+      @allow_local_binding = allow_local_binding
+      @http_proxy_port = http_proxy_port
+      @socks_proxy_port = socks_proxy_port
+    end
+
+    def to_h
+      result = {}
+      result[:allowUnixSockets] = @allow_unix_sockets unless @allow_unix_sockets.nil?
+      result[:allowAllUnixSockets] = @allow_all_unix_sockets unless @allow_all_unix_sockets.nil?
+      result[:allowLocalBinding] = @allow_local_binding unless @allow_local_binding.nil?
+      result[:httpProxyPort] = @http_proxy_port if @http_proxy_port
+      result[:socksProxyPort] = @socks_proxy_port if @socks_proxy_port
+      result
+    end
+  end
+
+  # Sandbox ignore violations configuration
+  class SandboxIgnoreViolations
+    attr_accessor :file, :network
+
+    def initialize(file: nil, network: nil)
+      @file = file # Array of file paths to ignore
+      @network = network # Array of network patterns to ignore
+    end
+
+    def to_h
+      result = {}
+      result[:file] = @file if @file
+      result[:network] = @network if @network
+      result
+    end
+  end
+
+  # Sandbox settings for isolated command execution
+  class SandboxSettings
+    attr_accessor :enabled, :auto_allow_bash_if_sandboxed, :excluded_commands,
+                  :allow_unsandboxed_commands, :network, :ignore_violations,
+                  :enable_weaker_nested_sandbox
+
+    def initialize(
+      enabled: nil,
+      auto_allow_bash_if_sandboxed: nil,
+      excluded_commands: nil,
+      allow_unsandboxed_commands: nil,
+      network: nil,
+      ignore_violations: nil,
+      enable_weaker_nested_sandbox: nil
+    )
+      @enabled = enabled
+      @auto_allow_bash_if_sandboxed = auto_allow_bash_if_sandboxed
+      @excluded_commands = excluded_commands # Array of commands to exclude
+      @allow_unsandboxed_commands = allow_unsandboxed_commands
+      @network = network # SandboxNetworkConfig instance
+      @ignore_violations = ignore_violations # SandboxIgnoreViolations instance
+      @enable_weaker_nested_sandbox = enable_weaker_nested_sandbox
+    end
+
+    def to_h
+      result = {}
+      result[:enabled] = @enabled unless @enabled.nil?
+      result[:autoAllowBashIfSandboxed] = @auto_allow_bash_if_sandboxed unless @auto_allow_bash_if_sandboxed.nil?
+      result[:excludedCommands] = @excluded_commands if @excluded_commands
+      result[:allowUnsandboxedCommands] = @allow_unsandboxed_commands unless @allow_unsandboxed_commands.nil?
+      if @network
+        result[:network] = @network.is_a?(SandboxNetworkConfig) ? @network.to_h : @network
+      end
+      if @ignore_violations
+        result[:ignoreViolations] = @ignore_violations.is_a?(SandboxIgnoreViolations) ? @ignore_violations.to_h : @ignore_violations
+      end
+      result[:enableWeakerNestedSandbox] = @enable_weaker_nested_sandbox unless @enable_weaker_nested_sandbox.nil?
+      result
+    end
+  end
+
+  # System prompt preset configuration
+  class SystemPromptPreset
+    attr_accessor :type, :preset, :append
+
+    def initialize(preset:, append: nil)
+      @type = 'preset'
+      @preset = preset
+      @append = append
+    end
+
+    def to_h
+      result = { type: @type, preset: @preset }
+      result[:append] = @append if @append
+      result
+    end
+  end
+
+  # Tools preset configuration
+  class ToolsPreset
+    attr_accessor :type, :preset
+
+    def initialize(preset:)
+      @type = 'preset'
+      @preset = preset
+    end
+
+    def to_h
+      { type: @type, preset: @preset }
+    end
+  end
+
   # Claude Agent Options for configuring queries
   class ClaudeAgentOptions
     attr_accessor :allowed_tools, :system_prompt, :mcp_servers, :permission_mode,
@@ -520,9 +644,9 @@ module ClaudeAgentSDK
                   :add_dirs, :env, :extra_args, :max_buffer_size, :stderr,
                   :can_use_tool, :hooks, :user, :include_partial_messages,
                   :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
+                  :fallback_model, :plugins, :debug_stderr,
+                  :betas, :tools, :sandbox, :enable_file_checkpointing, :append_allowed_tools
 
     def initialize(
       allowed_tools: [],
@@ -550,13 +674,17 @@ module ClaudeAgentSDK
       fork_session: false,
       agents: 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
+      debug_stderr: nil,
+      betas: nil,
+      tools: nil,
+      sandbox: nil,
+      enable_file_checkpointing: false,
+      append_allowed_tools: nil
     )
       @allowed_tools = allowed_tools
       @system_prompt = system_prompt
@@ -583,13 +711,17 @@ 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
+      @betas = betas # Array of beta feature strings (e.g., ["context-1m-2025-08-07"])
+      @tools = tools # Base tools selection: Array, empty array [], or ToolsPreset
+      @sandbox = sandbox # SandboxSettings instance for isolated command execution
+      @enable_file_checkpointing = enable_file_checkpointing # Enable file checkpointing for rewind support
+      @append_allowed_tools = append_allowed_tools # Array of tools to append to allowed_tools
     end
 
     def dup_with(**changes)

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -244,6 +244,15 @@ module ClaudeAgentSDK
       @query_handler.set_model(model)
     end
 
+    # Rewind files to a previous checkpoint (v0.1.15+)
+    # Restores file state to what it was at the given user message
+    # Requires enable_file_checkpointing to be true in options
+    # @param user_message_uuid [String] The UUID of the UserMessage to rewind to
+    def rewind_files(user_message_uuid)
+      raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+      @query_handler.rewind_files(user_message_uuid)
+    end
+
     # Get server initialization info
     # @return [Hash, nil] Server info or nil
     def server_info

metadata

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