claude-agent-sdk 0.16.7 → 0.16.9

data/docs/client.md

@@ -0,0 +1,157 @@
+# Client & Custom Transport
+
+`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.
+
+## Basic Usage
+
+```ruby
+require 'claude_agent_sdk'
+require 'async'
+
+Async do
+  client = ClaudeAgentSDK::Client.new
+
+  begin
+    client.connect
+    client.query("What is the capital of France?")
+
+    client.receive_response do |msg|
+      case msg
+      when ClaudeAgentSDK::AssistantMessage
+        puts msg.text
+      when ClaudeAgentSDK::ResultMessage
+        puts "Cost: $#{msg.total_cost_usd}" if msg.total_cost_usd
+      end
+    end
+  ensure
+    client.disconnect
+  end
+end.wait
+```
+
+## Advanced Features
+
+```ruby
+Async do
+  client = ClaudeAgentSDK::Client.new
+  client.connect
+
+  client.interrupt                              # Send interrupt signal
+  client.set_permission_mode('acceptEdits')     # Change permission mode mid-conversation
+  client.set_model('claude-sonnet-4-5')         # Switch model mid-conversation
+  status = client.get_mcp_status                # Inspect MCP server status
+  info   = client.get_server_info               # Inspect server init info
+  client.reconnect_mcp_server('my-server')      # Reconnect a failed MCP server
+  client.toggle_mcp_server('my-server', false)  # Enable/disable an MCP server
+  client.stop_task('task_abc123')               # Stop a running background task
+
+  client.disconnect
+end.wait
+```
+
+## Custom Transport
+
+By default, `Client` uses `SubprocessCLITransport` to spawn the Claude Code CLI locally. You can provide a custom transport class to connect via other channels (e.g., remote SSH, WebSocket, or a sandbox VM).
+
+A transport must implement six methods:
+
+| Method | Purpose |
+|---|---|
+| `connect` | Establish the connection / spawn the remote CLI |
+| `write(data)` | Send raw JSON-line bytes to stdin |
+| `read_messages { \|hash\| ... }` | Yield parsed JSON messages from stdout; block until the stream closes |
+| `end_input` | Signal EOF on stdin |
+| `close` | Terminate and clean up |
+| `ready?` | Report whether the transport can accept I/O |
+
+Then plug it into `Client` via `transport_class:` / `transport_args:`. All connect orchestration (option transforms, MCP extraction, hook conversion, Query lifecycle) is handled for you.
+
+```ruby
+client = ClaudeAgentSDK::Client.new(
+  options: options,
+  transport_class: MyTransport,
+  transport_args: { foo: 'bar' } # forwarded to MyTransport.new(options, **transport_args)
+)
+```
+
+### Reference: running `claude` inside an E2B sandbox
+
+[`examples/e2b_transport_example.rb`](../examples/e2b_transport_example.rb) is a working transport that runs the Claude Code CLI inside an [E2B](https://e2b.dev) Firecracker microVM instead of on your host. The wire protocol stays identical — only the I/O layer changes:
+
+```
+ClaudeAgentSDK::Client (host)
+    │  JSON-lines
+    ▼
+E2BCliTransport (host)
+    │  send_stdin / commands.run(background:) / CommandHandle#each
+    ▼
+E2B envd RPC (HTTP/2)
+    │
+    ▼
+/usr/local/bin/claude (in-VM subprocess)
+```
+
+The example reuses the SDK's `CommandBuilder` to produce the exact same argv that `SubprocessCLITransport` would build (including SDK MCP server `:instance` field stripping), shell-escapes it for E2B's `/bin/bash -l -c` execution path, and streams stdout/stderr back through `CommandHandle#each`.
+
+Sketch (full file is ~250 lines):
+
+```ruby
+require 'claude_agent_sdk'
+require 'e2b'
+
+class E2BCliTransport < ClaudeAgentSDK::Transport
+  def initialize(options, sandbox:, cli_path: '/usr/local/bin/claude')
+    @options, @sandbox, @cli_path = options, sandbox, cli_path
+  end
+
+  def connect
+    argv = ClaudeAgentSDK::CommandBuilder.new(@cli_path, @options).build
+    cmd = argv.map { |a| Shellwords.shellescape(a.to_s) }.join(' ')
+    @handle = @sandbox.commands.run(cmd, background: true, stdin: true,
+                                    cwd: @options.cwd&.to_s, envs: build_env)
+    @pid = @handle.pid
+    @ready = true
+  end
+
+  def write(data)         = @sandbox.commands.send_stdin(@pid, data)
+  def end_input           = @sandbox.commands.close_stdin(@pid)
+  def close               = @handle&.kill
+  def ready?              = @ready
+
+  def read_messages(&block)
+    buf = +''
+    @handle.each do |stdout, stderr, _pty|
+      next if stderr && !stderr.empty?
+      stdout.each_line do |line|
+        buf << line.strip
+        begin
+          yield JSON.parse(buf, symbolize_names: true)
+          buf.clear
+        rescue JSON::ParserError
+          # JSON line split across reads — keep buffering
+        end
+      end
+    end
+    @handle.wait # raises E2B::CommandExitError on non-zero exit
+  end
+end
+
+sandbox = E2B::Sandbox.create(template: 'base', timeout: 600)
+Async do
+  client = ClaudeAgentSDK::Client.new(
+    options: options,
+    transport_class: E2BCliTransport,
+    transport_args: { sandbox: sandbox }
+  )
+  client.connect
+  client.query('Hello from the sandbox!')
+  client.receive_response { |msg| puts msg }
+  client.disconnect
+ensure
+  sandbox.kill
+end.wait
+```
+
+**Why use a remote transport?** Untrusted code execution, multi-tenant agent runs that can't share a host, environments without local Node.js, or simply isolating filesystem/network blast radius. The Firecracker VM gives you a fresh `/home/user` per session and is killable without touching the host.
+
+**Production hardening** (intentionally omitted from the example for clarity): inactivity watchdog, keepalive heartbeat, stream reconnect on transient SSL/EOF errors, host env-var blocklist, MCP server filtering for sandbox compatibility. See the example file's header comments for what to add and why.

data/docs/configuration.md

@@ -0,0 +1,215 @@
+# Configuration & Features
+
+Reference for advanced `ClaudeAgentOptions` features.
+
+## 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'
+
+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_data = block.input if block.is_a?(ClaudeAgentSDK::ToolUseBlock) && block.name == 'StructuredOutput'
+    end
+  end
+end
+```
+
+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 — CLI dynamically adjusts budget based on task complexity
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(thinking: ClaudeAgentSDK::ThinkingConfigAdaptive.new)
+
+# Enabled with explicit token budget
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(thinking: ClaudeAgentSDK::ThinkingConfigEnabled.new(budget_tokens: 50_000))
+
+# Explicitly disabled
+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: 'xhigh')
+```
+
+Valid levels live in `ClaudeAgentSDK::EFFORT_LEVELS` (`low`, `medium`, `high`, `xhigh`, `max`). The set of *supported* levels is model-dependent — `xhigh` is available on Opus 4.7 and the CLI falls back to the highest supported level at or below the one you set (e.g. `xhigh` → `high` on Opus 4.6). When `effort` is `nil`, the CLI picks a model-native default (Opus 4.7 → `xhigh`).
+
+> **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`.
+
+### Cross-User Prompt Caching
+
+When running a multi-user fleet with shared preset prompts, enable `exclude_dynamic_sections` to make the system prompt byte-identical across users for prompt-caching hits:
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  system_prompt: ClaudeAgentSDK::SystemPromptPreset.new(
+    preset: 'claude_code',
+    append: '...your shared domain instructions...',
+    exclude_dynamic_sections: true
+  )
+)
+```
+
+When set, the CLI strips per-user dynamic sections (working directory, auto-memory, git status) from the system prompt and re-injects them into the first user message instead. Older CLIs silently ignore this option.
+
+## Budget Control
+
+```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|
+  puts "Cost: $#{message.total_cost_usd}" if message.is_a?(ClaudeAgentSDK::ResultMessage)
+end
+```
+
+See [examples/budget_control_example.rb](../examples/budget_control_example.rb).
+
+## Fallback Model
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  model: 'claude-sonnet-4-20250514',
+  fallback_model: 'claude-3-5-haiku-20241022'
+)
+```
+
+See [examples/fallback_model_example.rb](../examples/fallback_model_example.rb).
+
+## Beta Features
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  betas: ['context-1m-2025-08-07']  # Extended context window
+)
+```
+
+Available beta features are listed in the `SDK_BETAS` constant.
+
+## Tools Configuration
+
+```ruby
+# Array of tool names
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(tools: ['Read', 'Edit', 'Bash'])
+
+# Preset
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(tools: ClaudeAgentSDK::ToolsPreset.new(preset: 'claude_code'))
+
+# Append to allowed tools
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(append_allowed_tools: ['Write', 'Bash'])
+```
+
+## Sandbox Settings
+
+Configure [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime) restrictions (network policy, filesystem access) via the CLI's `--sandbox` flag. The CLI handles OS-level process isolation using `srt`.
+
+```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'
+)
+```
+
+See [examples/sandbox_example.rb](../examples/sandbox_example.rb).
+
+## Bare Mode
+
+Bare mode (`--bare`) is a minimal startup mode that skips hooks, LSP, plugin sync, attribution, auto-memory, background prefetches, keychain reads, and CLAUDE.md auto-discovery. It sets `CLAUDE_CODE_SIMPLE=1` internally. Useful for scripted/programmatic usage where you want fast startup and full control over what's loaded.
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  bare: true,
+  system_prompt: 'You are a code reviewer.',
+  permission_mode: 'bypassPermissions'
+)
+```
+
+In bare mode, explicitly provide any context you need:
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  bare: true,
+  system_prompt: 'You are a helpful assistant.',
+  add_dirs: ['/path/to/project'],       # CLAUDE.md directories (auto-discovery is off)
+  setting_sources: ['project'],          # load .claude/settings.json
+  allowed_tools: ['Read', 'Grep', 'Glob'],
+  permission_mode: 'bypassPermissions'
+)
+```
+
+**What bare mode skips:** hooks, LSP, plugin sync, attribution, auto-memory, background prefetches, keychain reads, CLAUDE.md auto-discovery, teammate snapshots, release notes.
+
+**What still works:** skills (via `/skill-name`), explicit `--add-dir` CLAUDE.md, `--settings`, `--mcp-config`, `--agents`, `--plugin-dir`, API key from `ANTHROPIC_API_KEY` env var.
+
+See [examples/bare_mode_example.rb](../examples/bare_mode_example.rb).
+
+## 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
+
+  user_message_uuids = []
+
+  client.query("Create a test.rb file with some code")
+  client.receive_response do |message|
+    user_message_uuids << message.uuid if message.is_a?(ClaudeAgentSDK::UserMessage) && message.uuid
+  end
+
+  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)
+  client.rewind_files(user_message_uuids.first) if user_message_uuids.first
+
+  client.disconnect
+end.wait
+```
+
+> **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.

data/docs/errors.md

@@ -0,0 +1,95 @@
+# 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'            then puts "Rate limited - retry after delay"
+    when 'authentication_failed' then puts "Check your API key"
+    when 'billing_error'         then puts "Check your billing status"
+    when 'invalid_request'       then puts "Invalid request format"
+    when 'server_error'          then puts "Server error - retry later"
+    end
+  end
+end
+```
+
+See [examples/error_handling_example.rb](../examples/error_handling_example.rb).
+
+## Exception Handling
+
+```ruby
+require 'claude_agent_sdk'
+
+begin
+  ClaudeAgentSDK.query(prompt: "Hello") { |message| puts message }
+rescue ClaudeAgentSDK::ControlRequestTimeoutError
+  puts "Control protocol timed out — consider increasing the timeout"
+rescue ClaudeAgentSDK::CLINotFoundError
+  puts "Please install Claude Code"
+rescue ClaudeAgentSDK::ProcessError => e
+  puts "Process failed with exit code: #{e.exit_code}"
+rescue ClaudeAgentSDK::CLIJSONDecodeError => e
+  puts "Failed to parse response: #{e}"
+end
+```
+
+## Configuring Timeout
+
+The control request timeout defaults to **1200 seconds** (20 minutes) to accommodate long-running agent sessions. Override it via environment variable:
+
+```bash
+export CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS=300  # 5 minutes
+```
+
+## Error Type Reference
+
+```ruby
+# Base exception class for all SDK errors
+class ClaudeSDKError < StandardError; end
+
+# Raised when connection to Claude Code fails
+class CLIConnectionError < ClaudeSDKError; end
+
+# Raised when the control protocol does not respond in time
+class ControlRequestTimeoutError < CLIConnectionError; 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 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
+```
+
+| Error | Description |
+|-------|-------------|
+| `ClaudeSDKError` | Base error for all SDK errors |
+| `CLIConnectionError` | Connection issues |
+| `ControlRequestTimeoutError` | Control protocol timeout (configurable via env var) |
+| `CLINotFoundError` | Claude Code not installed |
+| `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.

data/docs/hooks-and-permissions.md

@@ -0,0 +1,110 @@
+# Hooks & Permission Callbacks
+
+## 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 provide deterministic processing and automated feedback for Claude. Read more in [Claude Code Hooks Reference](https://docs.anthropic.com/en/docs/claude-code/hooks).
+
+### Supported Events
+
+All hook input objects include common fields like `session_id`, `transcript_path`, `cwd`, and `permission_mode`.
+
+- `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`)
+- `SubagentStop` → `SubagentStopHookInput` (`stop_hook_active`, `agent_id`, `agent_transcript_path`, `agent_type`)
+- `PreCompact` → `PreCompactHookInput` (`trigger`, `custom_instructions`)
+- `Notification` → `NotificationHookInput` (`message`, `title`, `notification_type`)
+- `SubagentStart` → `SubagentStartHookInput` (`agent_id`, `agent_type`)
+- `PermissionRequest` → `PermissionRequestHookInput` (`tool_name`, `tool_input`, `permission_suggestions`)
+
+All 27 hook events have typed input classes. See [`ClaudeAgentSDK::HOOK_EVENTS`](../lib/claude_agent_sdk/types.rb) and [examples/lifecycle_hooks_example.rb](../examples/lifecycle_hooks_example.rb).
+
+### Example: Blocking Dangerous Commands
+
+```ruby
+require 'claude_agent_sdk'
+require 'async'
+
+Async do
+  bash_hook = lambda do |input, _tool_use_id, _context|
+    return {} unless input.respond_to?(:tool_name) && input.tool_name == 'Bash'
+
+    tool_input = input.tool_input || {}
+    command = tool_input[:command] || tool_input['command'] || ''
+    block_patterns = ['rm -rf', 'foo.sh']
+
+    block_patterns.each do |pattern|
+      if command.include?(pattern)
+        return {
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: "Command contains forbidden pattern: #{pattern}"
+          }
+        }
+      end
+    end
+
+    {}
+  end
+
+  options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+    allowed_tools: ['Bash'],
+    hooks: {
+      'PreToolUse' => [
+        ClaudeAgentSDK::HookMatcher.new(matcher: 'Bash', hooks: [bash_hook])
+      ]
+    }
+  )
+
+  client = ClaudeAgentSDK::Client.new(options: options)
+  client.connect
+  client.query("Run the bash command: ./foo.sh --help")
+  client.receive_response { |msg| puts msg }
+  client.disconnect
+end.wait
+```
+
+See [examples/hooks_example.rb](../examples/hooks_example.rb), [examples/advanced_hooks_example.rb](../examples/advanced_hooks_example.rb), and [examples/lifecycle_hooks_example.rb](../examples/lifecycle_hooks_example.rb).
+
+## Permission Callbacks
+
+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.
+
+```ruby
+require 'claude_agent_sdk'
+require 'async'
+
+Async do
+  permission_callback = lambda do |tool_name, input, context|
+    return ClaudeAgentSDK::PermissionResultAllow.new if tool_name == 'Read'
+
+    if tool_name == 'Write'
+      file_path = input[:file_path] || input['file_path']
+      if file_path && file_path.include?('/etc/')
+        return ClaudeAgentSDK::PermissionResultDeny.new(
+          message: 'Cannot write to sensitive system files',
+          interrupt: false
+        )
+      end
+    end
+
+    ClaudeAgentSDK::PermissionResultAllow.new
+  end
+
+  options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+    allowed_tools: ['Read', 'Write', 'Bash'],
+    can_use_tool: permission_callback
+  )
+
+  client = ClaudeAgentSDK::Client.new(options: options)
+  client.connect
+  client.query("Create a file called test.txt with content 'Hello'")
+  client.receive_response { |msg| puts msg }
+  client.disconnect
+end.wait
+```
+
+See [examples/permission_callback_example.rb](../examples/permission_callback_example.rb).