claude-agent-sdk 0.16.7 → 0.16.9

data/docs/mcp-servers.md

@@ -0,0 +1,153 @@
+# 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. Custom tools are implemented as in-process MCP servers that run directly within your Ruby application, eliminating the need for separate processes that regular MCP servers require.
+
+**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.
+
+## Creating a Simple Tool
+
+```ruby
+require 'claude_agent_sdk'
+require 'async'
+
+greet_tool = ClaudeAgentSDK.create_tool(
+  'greet', 'Greet a user', { name: :string },
+  annotations: { title: 'Greeter', readOnlyHint: true }
+) do |args|
+  { content: [{ type: 'text', text: "Hello, #{args[:name]}!" }] }
+end
+
+server = ClaudeAgentSDK.create_sdk_mcp_server(
+  name: 'my-tools',
+  version: '1.0.0',
+  tools: [greet_tool]
+)
+
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  mcp_servers: { tools: server },
+  allowed_tools: ['mcp__tools__greet']
+)
+
+Async do
+  client = ClaudeAgentSDK::Client.new(options: options)
+  client.connect
+  client.query("Greet Alice")
+  client.receive_response { |msg| puts msg }
+  client.disconnect
+end.wait
+```
+
+## Pre-built JSON Schemas
+
+If your schemas come from another library (e.g., [RubyLLM](https://github.com/crmne/ruby_llm)) that deep-stringifies keys, the SDK handles them transparently — both symbol-keyed and string-keyed schemas are accepted and normalized:
+
+```ruby
+# Symbol keys (standard Ruby)
+ClaudeAgentSDK.create_tool('save', 'Save a fact', {
+  type: 'object',
+  properties: { fact: { type: 'string' } },
+  required: ['fact']
+}) { |args| { content: [{ type: 'text', text: "Saved: #{args[:fact]}" }] } }
+
+# String keys (e.g., from RubyLLM or JSON.parse)
+ClaudeAgentSDK.create_tool('save', 'Save a fact', {
+  'type' => 'object',
+  'properties' => { 'fact' => { 'type' => 'string' } },
+  'required' => ['fact']
+}) { |args| { content: [{ type: 'text', text: "Saved: #{args[:fact]}" }] } }
+```
+
+## Benefits Over External MCP Servers
+
+- **No subprocess management** — runs in the same process as your application
+- **Better performance** — no IPC overhead for tool calls
+- **Simpler deployment** — single Ruby process instead of multiple
+- **Easier debugging** — all code runs in the same process
+- **Direct access** — tools can directly access your application's state
+
+## Calculator Example
+
+```ruby
+add_tool = ClaudeAgentSDK.create_tool('add', 'Add two numbers', { a: :number, b: :number }) do |args|
+  result = args[:a] + args[:b]
+  { content: [{ type: 'text', text: "#{args[:a]} + #{args[:b]} = #{result}" }] }
+end
+
+divide_tool = ClaudeAgentSDK.create_tool('divide', 'Divide numbers', { a: :number, b: :number }) do |args|
+  if args[:b] == 0
+    { content: [{ type: 'text', text: 'Error: Division by zero' }], is_error: true }
+  else
+    { content: [{ type: 'text', text: "Result: #{args[:a] / args[:b]}" }] }
+  end
+end
+
+calculator = ClaudeAgentSDK.create_sdk_mcp_server(
+  name: 'calculator',
+  tools: [add_tool, divide_tool]
+)
+
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  mcp_servers: { calc: calculator },
+  allowed_tools: ['mcp__calc__add', 'mcp__calc__divide']
+)
+```
+
+## Mixed Server Support
+
+You can use both SDK and external MCP servers together:
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  mcp_servers: {
+    internal: sdk_server,      # In-process SDK server
+    external: {                # External subprocess server
+      type: 'stdio',
+      command: 'external-server'
+    }
+  }
+)
+```
+
+## MCP Resources and Prompts
+
+SDK MCP servers can also expose **resources** (data sources) and **prompts** (reusable templates):
+
+```ruby
+config_resource = ClaudeAgentSDK.create_resource(
+  uri: 'config://app/settings',
+  name: 'Application Settings',
+  description: 'Current app configuration',
+  mime_type: 'application/json'
+) do
+  config_data = { app_name: 'MyApp', version: '1.0.0' }
+  {
+    contents: [{
+      uri: 'config://app/settings',
+      mimeType: 'application/json',
+      text: JSON.pretty_generate(config_data)
+    }]
+  }
+end
+
+review_prompt = ClaudeAgentSDK.create_prompt(
+  name: 'code_review',
+  description: 'Review code for best practices',
+  arguments: [{ name: 'code', description: 'Code to review', required: true }]
+) do |args|
+  {
+    messages: [{
+      role: 'user',
+      content: { type: 'text', text: "Review this code: #{args[:code]}" }
+    }]
+  }
+end
+
+server = ClaudeAgentSDK.create_sdk_mcp_server(
+  name: 'dev-tools',
+  tools: [my_tool],
+  resources: [config_resource],
+  prompts: [review_prompt]
+)
+```
+
+See [examples/mcp_calculator.rb](../examples/mcp_calculator.rb) and [examples/mcp_resources_prompts_example.rb](../examples/mcp_resources_prompts_example.rb) for complete examples.

data/docs/observability.md

@@ -0,0 +1,126 @@
+# Observability (OpenTelemetry / Langfuse)
+
+The SDK includes a built-in **observer interface** and an **OpenTelemetry observer** for tracing agent sessions. Traces are emitted using standard `gen_ai.*` semantic conventions, compatible with Langfuse, Jaeger, Datadog, and any OTel backend.
+
+## How It Works
+
+Register observers via `ClaudeAgentOptions`. The SDK calls `on_message` for every parsed message in both `query()` and `Client`, and `on_close` when the session ends. Observer errors are silently rescued so they never crash your application.
+
+```
+claude_agent.session            (root span — one per query/session)
+├── claude_agent.generation     (per AssistantMessage, with model + token usage)
+├── claude_agent.tool.Bash      (per tool call, open on ToolUseBlock, close on ToolResultBlock)
+├── claude_agent.tool.Read
+├── claude_agent.generation
+└── ...
+```
+
+## Setup with Langfuse
+
+**1. Install the OTel gems** (not bundled with the SDK — you choose your exporter):
+
+```bash
+gem install opentelemetry-sdk opentelemetry-exporter-otlp
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'opentelemetry-sdk', '~> 1.4'
+gem 'opentelemetry-exporter-otlp', '~> 0.28'
+```
+
+**2. Configure the OTel SDK** to export to your Langfuse instance:
+
+```ruby
+require 'base64'
+require 'opentelemetry/sdk'
+require 'opentelemetry/exporter/otlp'
+
+# Langfuse authenticates via Basic Auth over OTLP
+public_key = ENV['LANGFUSE_PUBLIC_KEY']
+secret_key = ENV['LANGFUSE_SECRET_KEY']
+auth = Base64.strict_encode64("#{public_key}:#{secret_key}")
+
+# Self-hosted or cloud: https://cloud.langfuse.com (EU) / https://us.cloud.langfuse.com (US)
+langfuse_host = ENV.fetch('LANGFUSE_HOST', 'https://cloud.langfuse.com')
+
+OpenTelemetry::SDK.configure do |c|
+  c.service_name = 'my-agent-app'
+  c.add_span_processor(
+    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+      OpenTelemetry::Exporter::OTLP::Exporter.new(
+        endpoint: "#{langfuse_host}/api/public/otel/v1/traces",
+        headers: {
+          'Authorization' => "Basic #{auth}",
+          'x-langfuse-ingestion-version' => '4'
+        }
+      )
+    )
+  )
+end
+```
+
+**3. Create the observer and run a query:**
+
+```ruby
+require 'claude_agent_sdk'
+require 'claude_agent_sdk/instrumentation'
+
+observer = ClaudeAgentSDK::Instrumentation::OTelObserver.new(
+  'langfuse.session.id' => 'my-session-123',  # optional: group traces by session
+  'user.id' => 'user-42'                      # optional: tag with user ID
+)
+
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  observers: [observer],
+  allowed_tools: ['Bash', 'Read'],
+  permission_mode: 'bypassPermissions'
+)
+
+ClaudeAgentSDK.query(prompt: "List files in /tmp", options: options) do |msg|
+  puts msg.text if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
+end
+
+# For long-running apps, flush before exit:
+# OpenTelemetry.tracer_provider.shutdown
+```
+
+## Span Attributes
+
+The OTel observer sets attributes using both `gen_ai.*` (OTel GenAI) and OpenInference conventions for maximum backend compatibility:
+
+| Span | Type | Key Attributes |
+|------|------|----------------|
+| `claude_agent.session` | `agent` | `gen_ai.system`, `gen_ai.request.model`, `session.id`, `input.value`, `output.value`, `gen_ai.usage.cost`, `llm.cost.total` |
+| `claude_agent.generation` | `generation` | `gen_ai.response.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `output.value` |
+| `claude_agent.tool.*` | `tool` | `tool.name`, `input.value`, `output.value` |
+
+Events (`api_retry`, `rate_limit`, `tool_progress`) are recorded on the root span.
+
+The `langfuse.observation.type` attribute is set on each span (`agent`/`generation`/`tool`) to enable Langfuse's **trace flow diagram** (DAG graph visualization).
+
+## Custom Observers
+
+Implement the `Observer` module to build your own instrumentation:
+
+```ruby
+class MyObserver
+  include ClaudeAgentSDK::Observer
+
+  def on_message(message)
+    case message
+    when ClaudeAgentSDK::ResultMessage
+      puts "Cost: $#{message.total_cost_usd}, Tokens: #{message.usage}"
+    end
+  end
+
+  def on_close
+    puts "Session ended"
+  end
+end
+
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(observers: [MyObserver.new])
+```
+
+See [examples/otel_langfuse_example.rb](../examples/otel_langfuse_example.rb) for a complete multi-tool example.

data/docs/rails.md

@@ -0,0 +1,199 @@
+# Rails Integration
+
+The SDK integrates well with Rails applications. Below are the common patterns.
+
+## Thread-keyed libraries are safe inside SDK callbacks
+
+The SDK depends on [`async`](https://github.com/socketry/async), which installs a Fiber scheduler that multiplexes fibers onto a single OS thread and intercepts IO so blocking calls yield to siblings. Most mature Ruby libraries are thread-safe but not fiber-safe — they key state (checked-out DB connections, per-thread caches, request stores) on `Thread.current`. When the scheduler interleaves two fibers on one thread, those fibers share the same state slot, and interleaved IO on a shared connection silently corrupts wire protocols. This affects every DB driver keyed by thread (`pg`, `mysql2`, `sqlite3`), ActiveRecord's connection pool, and HTTP/cache clients pooled per thread.
+
+You do **not** need to think about this. The SDK hops to a plain thread at every user-callback boundary — message blocks given to `query` / `Client`, SDK MCP tool handlers, hooks, permission callbacks, and observer methods — so your code runs with no Fiber scheduler active and inherits the ordinary thread-keyed assumptions every Rails / Sidekiq / Kamal app already makes:
+
+```ruby
+tool = ClaudeAgentSDK.create_tool('lookup_user', 'Look up a user', { id: Integer }) do |args|
+  user = User.find(args[:id])                # just works
+  { content: [{ type: 'text', text: user.name }] }
+end
+
+ClaudeAgentSDK.query(prompt: '...') do |message|
+  Message.create!(role: 'assistant', body: message.to_s)   # just works
+end
+```
+
+The trade-off: because callbacks run on a plain thread rather than inside an `Async::Task`, fiber-specific primitives aren't available to them — `Async::Task.current` will raise "No async task available". If a callback wants cooperative concurrency it should open its own `Async { }` block. In practice, callbacks typically do some Ruby work, call external services, and return — so this rarely matters. If you wrap your own call site in an outer `Async { }` block, the scheduler is visible to your code again; you've opted in, and whatever fiber-safety rules your app uses apply there.
+
+## ActionCable Streaming
+
+Stream Claude responses to the frontend in real-time:
+
+```ruby
+# app/jobs/chat_agent_job.rb
+class ChatAgentJob < ApplicationJob
+  queue_as :claude_agents
+
+  def perform(chat_id, message_content)
+    Async do
+      options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+        system_prompt: { type: 'preset', preset: 'claude_code' },
+        permission_mode: 'bypassPermissions'
+      )
+
+      client = ClaudeAgentSDK::Client.new(options: options)
+
+      begin
+        client.connect
+        client.query(message_content)
+
+        client.receive_response do |message|
+          case message
+          when ClaudeAgentSDK::AssistantMessage
+            ChatChannel.broadcast_to(chat_id, { type: 'chunk', content: message.text })
+          when ClaudeAgentSDK::ResultMessage
+            ChatChannel.broadcast_to(chat_id, {
+              type: 'complete',
+              content: message.result,
+              cost: message.total_cost_usd
+            })
+          end
+        end
+      ensure
+        client.disconnect
+      end
+    end.wait
+  end
+end
+```
+
+## Session Resumption
+
+Persist Claude sessions for multi-turn conversations:
+
+```ruby
+# app/models/chat_session.rb
+class ChatSession < ApplicationRecord
+  # Columns: id, claude_session_id, user_id, created_at, updated_at
+
+  def send_message(content)
+    options = build_options
+    client = ClaudeAgentSDK::Client.new(options: options)
+
+    Async do
+      client.connect
+      client.query(content, session_id: claude_session_id ? nil : generate_session_id)
+
+      client.receive_response do |message|
+        update!(claude_session_id: message.session_id) if message.is_a?(ClaudeAgentSDK::ResultMessage)
+      end
+    ensure
+      client.disconnect
+    end.wait
+  end
+
+  private
+
+  def build_options
+    opts = { permission_mode: 'bypassPermissions', setting_sources: [] }
+    opts[:resume] = claude_session_id if claude_session_id.present?
+    ClaudeAgentSDK::ClaudeAgentOptions.new(**opts)
+  end
+
+  def generate_session_id
+    "chat_#{id}_#{Time.current.to_i}"
+  end
+end
+```
+
+## Background Jobs with Error Handling
+
+```ruby
+class ClaudeAgentJob < ApplicationJob
+  queue_as :claude_agents
+  retry_on ClaudeAgentSDK::ProcessError, wait: :polynomially_longer, attempts: 3
+
+  def perform(task_id)
+    task = Task.find(task_id)
+    Async { execute_agent(task) }.wait
+  rescue ClaudeAgentSDK::CLINotFoundError
+    task.update!(status: 'failed', error: 'Claude CLI not installed')
+    raise
+  end
+
+  private
+
+  def execute_agent(task)
+    # ... agent execution
+  end
+end
+```
+
+## HTTP MCP Servers
+
+Connect to remote tool services:
+
+```ruby
+mcp_servers = {
+  'api_tools' => ClaudeAgentSDK::McpHttpServerConfig.new(
+    url: ENV['MCP_SERVER_URL'],
+    headers: { 'Authorization' => "Bearer #{ENV['MCP_TOKEN']}" }
+  ).to_h
+}
+
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  mcp_servers: mcp_servers,
+  permission_mode: 'bypassPermissions'
+)
+```
+
+## Observability in Rails
+
+Add OpenTelemetry tracing to your Rails app with a single initializer:
+
+```ruby
+# config/initializers/opentelemetry.rb
+require 'base64'
+require 'opentelemetry/sdk'
+require 'opentelemetry/exporter/otlp'
+
+if ENV['LANGFUSE_PUBLIC_KEY'].present?
+  auth = Base64.strict_encode64("#{ENV['LANGFUSE_PUBLIC_KEY']}:#{ENV['LANGFUSE_SECRET_KEY']}")
+  langfuse_host = ENV.fetch('LANGFUSE_HOST', 'https://cloud.langfuse.com')
+
+  OpenTelemetry::SDK.configure do |c|
+    c.service_name = Rails.application.class.module_parent_name.underscore
+    c.add_span_processor(
+      OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+        OpenTelemetry::Exporter::OTLP::Exporter.new(
+          endpoint: "#{langfuse_host}/api/public/otel/v1/traces",
+          headers: {
+            'Authorization' => "Basic #{auth}",
+            'x-langfuse-ingestion-version' => '4'
+          }
+        )
+      )
+    )
+  end
+end
+```
+
+```ruby
+# config/initializers/claude_agent_sdk.rb
+require 'claude_agent_sdk/instrumentation'
+
+ClaudeAgentSDK.configure do |config|
+  config.default_options = {
+    permission_mode: 'bypassPermissions',
+    observers: ENV['LANGFUSE_PUBLIC_KEY'].present? ? [
+      # Use a lambda so each query gets a fresh observer instance (thread-safe).
+      # A single shared instance would have its span state clobbered by concurrent requests.
+      -> { ClaudeAgentSDK::Instrumentation::OTelObserver.new }
+    ] : []
+  }
+end
+```
+
+Then every `ClaudeAgentSDK.query` and `Client` session automatically gets traced — no per-call wiring needed. The lambda factory ensures each request gets its own observer with isolated span state, safe for concurrent Puma/Sidekiq workers.
+
+See:
+- [examples/rails_actioncable_example.rb](../examples/rails_actioncable_example.rb)
+- [examples/rails_background_job_example.rb](../examples/rails_background_job_example.rb)
+- [examples/session_resumption_example.rb](../examples/session_resumption_example.rb)
+- [examples/http_mcp_server_example.rb](../examples/http_mcp_server_example.rb)

data/docs/sessions.md

@@ -0,0 +1,101 @@
+# Session Browsing & Mutations
+
+Browse, read, mutate, fork, and resume Claude Code sessions directly from Ruby — no CLI subprocess required. These APIs read and write `~/.claude/projects/` JSONL files directly, respecting the `CLAUDE_CONFIG_DIR` environment variable and auto-detecting git worktrees.
+
+## Listing Sessions
+
+```ruby
+# All sessions (sorted by most recent first)
+sessions = ClaudeAgentSDK.list_sessions
+sessions.each do |session|
+  puts "#{session.session_id}: #{session.summary} (#{session.git_branch})"
+end
+
+# For a specific directory
+ClaudeAgentSDK.list_sessions(directory: '/path/to/project', limit: 10)
+
+# Paginate with offset
+ClaudeAgentSDK.list_sessions(directory: '.', limit: 10, offset: 10)
+
+# Include git worktree sessions
+ClaudeAgentSDK.list_sessions(directory: '.', include_worktrees: true)
+```
+
+Each `SDKSessionInfo` includes: `session_id`, `summary`, `last_modified`, `file_size`, `custom_title`, `first_prompt`, `git_branch`, `cwd`.
+
+## Reading Session Messages
+
+```ruby
+# Full conversation
+messages = ClaudeAgentSDK.get_session_messages(session_id: 'abc-123-...')
+messages.each { |msg| puts "[#{msg.type}] #{msg.message}" }
+
+# Paginate
+ClaudeAgentSDK.get_session_messages(session_id: 'abc-123-...', offset: 10, limit: 20)
+```
+
+Each `SessionMessage` includes `type` (`"user"` or `"assistant"`), `uuid`, `session_id`, and `message` (raw API hash).
+
+## Renaming a Session
+
+```ruby
+ClaudeAgentSDK.rename_session(
+  session_id: '550e8400-e29b-41d4-a716-446655440000',
+  title: 'My refactoring session',
+  directory: '/path/to/project'  # optional
+)
+```
+
+## Tagging a Session
+
+```ruby
+ClaudeAgentSDK.tag_session(session_id: '550e8400-...', tag: 'experiment')
+ClaudeAgentSDK.tag_session(session_id: '550e8400-...', tag: nil)  # clear
+```
+
+Tags are Unicode-sanitized before storing.
+
+## Deleting a Session
+
+```ruby
+# Hard-delete (removes the JSONL file permanently)
+ClaudeAgentSDK.delete_session(
+  session_id: '550e8400-...',
+  directory: '/path/to/project'  # optional
+)
+```
+
+## Forking a Session
+
+```ruby
+# Fork into a new branch with fresh UUIDs
+result = ClaudeAgentSDK.fork_session(
+  session_id: '550e8400-...',
+  title: 'Experiment branch'  # optional, auto-generated if omitted
+)
+puts result.session_id  # UUID of the new forked session
+
+# Partial fork — fork up to a specific message
+ClaudeAgentSDK.fork_session(
+  session_id: '550e8400-...',
+  up_to_message_id: 'message-uuid-here'
+)
+```
+
+> Session mutations use append-only JSONL writes with `O_WRONLY | O_APPEND` (no `O_CREAT`) for TOCTOU safety. They are safe to call while the session is open in a CLI process. `fork_session` uses `O_CREAT | O_EXCL` to prevent race conditions.
+
+## Resuming at a Specific Message
+
+`resume_session_at` truncates the resumed conversation to messages up to **and including** the assistant message with the given UUID — useful for rewriting history from a known point or branching exploration without forking the session file. The flag rides on top of `resume`, so the original session ID is preserved; only the in-memory history loaded for the new turn is shortened.
+
+```ruby
+ClaudeAgentSDK.query(
+  prompt: 'Try a different approach',
+  options: ClaudeAgentSDK::ClaudeAgentOptions.new(
+    resume: '550e8400-...',
+    resume_session_at: 'assistant-message-uuid-from-history'
+  )
+) { |message| }
+```
+
+`resume_session_at` requires `resume`; the SDK raises `ArgumentError` from `CommandBuilder` when this constraint is violated, matching the underlying CLI's validation but surfacing it synchronously in the caller's stack.