claude-agent-sdk 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dea2034cc231692b028b6bbd97c42a9ee0b940cb90ac88a17d52fcea14c116f6
-  data.tar.gz: 54820d9a71cd55ce3e6d0e370b6f4aaa536054caf2b7369452cfc2788db4a610
+  metadata.gz: f58f68ab3fa3b156f329c2f1757840166e449cb74f0a8513522e7fddaa177daa
+  data.tar.gz: 4d2c107fce9aa21978c983b264799a0a795e2cc58bcac615a0a9786f982221d9
 SHA512:
-  metadata.gz: 3a82f9b4e5dfe224110676b4e37c803d9e60054bea6dc463e91133cb1591b3075a19bda8471cd3b1034548b8f3737f3726f4e634ef4d509499fd389db936451e
-  data.tar.gz: 351038143982dc2b621e138f90d9fff65f8ed0ce5eab25aa7eaa214563336a2070375c9a92be9cfb3ed79d419e12a5c149dde2e3a46cc96c83992fe94eefef82
+  metadata.gz: 656e3dc5eacd58edb5da35a0055771674e09fcff5a7754a79ab5fae4346ba34e4000e61d31d25743cf244cdb6241907b84696bd16ea63411af7dee70d9bc46af
+  data.tar.gz: 5da72d45e25794e720b011f19de10de076d1927e50863b13b1aa4ccde801dd6b697073e82025c281963752cb8408c1a0267cbe2ea7a9a233f3bee4c07e636b9e

data/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.13.0] - 2026-04-03
+
+### Added
+
+#### Observer Interface
+- `Observer` module with `on_user_prompt`, `on_message`, `on_error`, `on_close` — all with no-op defaults
+- `observers` option on `ClaudeAgentOptions` (default `[]`) — register observers for both `query()` and `Client`
+- `resolve_observers` supports callable factories (lambdas) for thread-safe global defaults in Rails/Puma/Sidekiq
+- `notify_observers` rescues per-observer errors so observers never crash the main pipeline
+
+#### OpenTelemetry Instrumentation
+- `ClaudeAgentSDK::Instrumentation::OTelObserver` — emits spans using `gen_ai.*` and OpenInference semantic conventions
+- Span tree: `claude_agent.session` (root) → `claude_agent.generation` + `claude_agent.tool.*` (children)
+- `langfuse.observation.type` set on all spans (`agent`/`generation`/`tool`) to enable Langfuse trace flow diagram
+- `input.value`/`output.value` (OpenInference) for Langfuse Preview Input/Output fields
+- `llm.token_count.*`, `llm.cost.total`, `llm.model_name` for full Langfuse cost/usage tracking
+- `openinference.span.kind` (`AGENT`/`LLM`/`TOOL`) on all spans
+- Events: `api_retry`, `rate_limit`, `tool_progress` recorded on root span
+- Lazy `require 'opentelemetry'` — zero cost for users who don't use it
+
+#### Examples
+- `otel_langfuse_example.rb` — Langfuse-via-OTel setup with OTLP exporter
+- `test_langfuse_otel.rb` — multi-tool integration test (Bash tool calls)
+
+### Changed
+- README: added Observability section with Langfuse setup guide, span attribute reference, custom observer example, Rails initializer patterns
+- README: split sandbox into CLI settings vs sandbox-runtime rows in comparison table
+- README: updated recommended gem version to `~> 0.13.0`
+- CLAUDE.md: documented observer/instrumentation architecture
+
 ## [0.12.0] - 2026-04-01
 
 Full Claude Code parity release — cross-referenced against the Claude Code source (`coreSchemas.ts`) and TypeScript SDK to bring every message type, hook event, and sandbox setting into the Ruby SDK.

data/README.md

@@ -27,19 +27,19 @@ All three SDKs share the same underlying mechanism: they spawn the `claude` CLI
 | Permission callbacks | ✅ | ✅ | ✅ |
 | Structured output | ✅ | ✅ | ✅ |
 | All 24 message types | ✅ | partial | ✅ |
-| Full sandbox settings | ✅ | partial | ✅ |
+| [Sandbox](https://github.com/anthropic-experimental/sandbox-runtime) settings | ✅ | partial | ✅ |
 | Bare mode (`--bare`) | ✅ | ✅ | ✅ |
 | File checkpointing & rewind | ✅ | ✅ | ✅ |
 | Session browsing & mutations | ✅ | ✅ | ✅ |
 | Programmatic subagents | ✅ | ✅ | ✅ |
 | Bundled CLI binary | ✅ | ✅ | — (install `claude` separately) |
+| Observability (OTel / Langfuse) | via [Arize](https://github.com/Arize-ai/openinference) | — | ✅ (built-in) |
 | Custom transport (pluggable I/O) | — | — | ✅ |
 | Rails integration | — | — | ✅ |
-| Global config defaults | — | — | ✅ |
 
-**Where Ruby goes further:** Custom transport support lets you swap the subprocess for any I/O layer (e.g., connect to a remote Claude Code instance over SSH or a container). Rails integration provides a `configure` block for initializers and plays well with ActionCable for real-time streaming. The Ruby SDK also has full typed coverage for all 24 CLI message types and all 27 hook events — some of which the Python SDK hasn't typed yet (falling through to generic `SystemMessage`).
+**Where Ruby goes further:** Built-in OpenTelemetry observer with Langfuse flow diagram support — no third-party instrumentation library needed. Custom transport support lets you swap the subprocess for any I/O layer (e.g., connect to a remote Claude Code instance over SSH or a container). Rails integration provides a `configure` block for initializers with thread-safe observer factories, and plays well with ActionCable for real-time streaming. Full typed coverage for all 24 CLI message types and all 27 hook events — some of which the Python SDK hasn't typed yet.
 
-**What's missing:** The Ruby gem does not bundle the `claude` CLI binary. You need to install Claude Code separately (`npm install -g @anthropic-ai/claude-code`).
+**What's missing:** The Ruby gem does not bundle the `claude` CLI binary (`npm install -g @anthropic-ai/claude-code`).
 
 <details>
 <summary><strong>Implementation differences from the official SDKs</strong></summary>
@@ -89,6 +89,7 @@ All three SDKs spawn `claude` CLI as a subprocess with stream-JSON over stdin/st
 - [File Checkpointing & Rewind](#file-checkpointing--rewind)
 - [Session Browsing](#session-browsing)
 - [Session Mutations](#session-mutations)
+- [Observability (OpenTelemetry / Langfuse)](#observability-opentelemetry--langfuse)
 - [Rails Integration](#rails-integration)
 - [Types](#types)
 - [Error Handling](#error-handling)
@@ -105,7 +106,7 @@ Add this line to your application's Gemfile:
 gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
 
 # Or use a stable version from RubyGems
-gem 'claude-agent-sdk', '~> 0.11.0'
+gem 'claude-agent-sdk', '~> 0.13.0'
 ```
 
 And then execute:
@@ -822,7 +823,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 
 ## Sandbox Settings
 
-Run commands in an isolated sandbox for additional security:
+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(
@@ -1006,6 +1007,137 @@ ClaudeAgentSDK.tag_session(
 
 > **Note:** 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.
 
+## 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|
+  if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
+    msg.content.each do |block|
+      puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
+    end
+  end
+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])
+```
+
+For a complete multi-tool example, see [examples/otel_langfuse_example.rb](examples/otel_langfuse_example.rb).
+
 ## Rails Integration
 
 The SDK integrates well with Rails applications. Here are common patterns:
@@ -1153,6 +1285,55 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 )
 ```
 
+### 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.
+
 For complete examples, see:
 - [examples/rails_actioncable_example.rb](examples/rails_actioncable_example.rb)
 - [examples/rails_background_job_example.rb](examples/rails_background_job_example.rb)
@@ -1499,6 +1680,12 @@ See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-co
 | [examples/fallback_model_example.rb](examples/fallback_model_example.rb) | Fallback model configuration |
 | [examples/extended_thinking_example.rb](examples/extended_thinking_example.rb) | Extended thinking (API parity) |
 
+### Observability
+
+| Example | Description |
+|---------|-------------|
+| [examples/otel_langfuse_example.rb](examples/otel_langfuse_example.rb) | OpenTelemetry tracing with Langfuse backend |
+
 ### Rails Integration
 
 | Example | Description |

data/lib/claude_agent_sdk/instrumentation/otel.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../observer'
+
+module ClaudeAgentSDK
+  module Instrumentation
+    # OpenTelemetry observer that emits spans for Claude Agent SDK messages.
+    #
+    # Uses standard gen_ai.* semantic conventions recognized by Langfuse, Datadog,
+    # Jaeger, and other OTel-compatible backends.
+    #
+    # Requires the `opentelemetry-api` gem at runtime. Users must configure
+    # `opentelemetry-sdk` and an exporter (e.g., `opentelemetry-exporter-otlp`)
+    # themselves before creating this observer.
+    #
+    # @example With Langfuse via OTLP
+    #   require 'opentelemetry/sdk'
+    #   require 'opentelemetry/exporter/otlp'
+    #   require 'claude_agent_sdk/instrumentation'
+    #
+    #   OpenTelemetry::SDK.configure do |c|
+    #     c.service_name = 'my-app'
+    #     c.add_span_processor(
+    #       OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+    #         OpenTelemetry::Exporter::OTLP::Exporter.new(
+    #           endpoint: 'https://cloud.langfuse.com/api/public/otel/v1/traces',
+    #           headers: { 'Authorization' => "Basic #{auth}" }
+    #         )
+    #       )
+    #     )
+    #   end
+    #
+    #   observer = ClaudeAgentSDK::Instrumentation::OTelObserver.new
+    #   options = ClaudeAgentSDK::ClaudeAgentOptions.new(observers: [observer])
+    #   ClaudeAgentSDK.query(prompt: "Hello", options: options) { |msg| ... }
+    class OTelObserver
+      include ClaudeAgentSDK::Observer
+
+      TRACER_NAME = 'claude_agent_sdk'
+      MAX_ATTRIBUTE_LENGTH = 4096
+
+      def initialize(tracer_name: TRACER_NAME, **default_attributes)
+        require 'opentelemetry'
+        @tracer = OpenTelemetry.tracer_provider.tracer(
+          tracer_name,
+          defined?(ClaudeAgentSDK::VERSION) ? ClaudeAgentSDK::VERSION : '0.0.0'
+        )
+        @default_attributes = default_attributes
+        @root_span = nil
+        @root_context = nil
+        @tool_spans = {} # tool_use_id => span
+        @first_user_input = nil # capture first user prompt for trace input
+        @last_assistant_text = nil # capture last assistant text for trace output
+      end
+
+      def on_user_prompt(prompt)
+        return if @first_user_input # only capture the first prompt
+
+        @first_user_input = prompt.to_s
+        # If root span already exists, set immediately; otherwise start_trace will apply it
+        @root_span&.set_attribute('input.value', truncate(@first_user_input)) unless @first_user_input.empty?
+      end
+
+      def on_message(message)
+        case message
+        when ClaudeAgentSDK::InitMessage
+          start_trace(message)
+        when ClaudeAgentSDK::AssistantMessage
+          handle_assistant(message)
+        when ClaudeAgentSDK::UserMessage
+          handle_user(message)
+        when ClaudeAgentSDK::ResultMessage
+          end_trace(message)
+        when ClaudeAgentSDK::APIRetryMessage
+          record_retry_event(message)
+        when ClaudeAgentSDK::RateLimitEvent
+          record_rate_limit_event(message)
+        when ClaudeAgentSDK::ToolProgressMessage
+          record_tool_progress_event(message)
+        end
+      end
+
+      def on_error(error)
+        return unless @root_span
+
+        @root_span.record_exception(error)
+        @root_span.status = OpenTelemetry::Trace::Status.error(error.message)
+      end
+
+      def on_close
+        @tool_spans.each_value(&:finish)
+        @tool_spans.clear
+        @root_span&.finish
+        @root_span = nil
+        @root_context = nil
+      end
+
+      private
+
+      def start_trace(message)
+        attrs = {
+          # gen_ai semantic conventions (recognized by Langfuse, Datadog, etc.)
+          'gen_ai.system' => 'anthropic',
+          'gen_ai.request.model' => message.model,
+          # OpenInference conventions (recognized by Langfuse, Arize)
+          'openinference.span.kind' => 'AGENT',
+          'llm.model_name' => message.model,
+          'input.mime_type' => 'text/plain',
+          'output.mime_type' => 'text/plain',
+          # Langfuse: 'agent' type triggers the trace flow diagram (DAG graph)
+          'langfuse.observation.type' => 'agent',
+          # Session tracking
+          'session.id' => message.session_id
+        }.merge(@default_attributes)
+
+        attrs['claude_code.version'] = message.claude_code_version if message.respond_to?(:claude_code_version) && message.claude_code_version
+        attrs['claude_code.cwd'] = message.cwd if message.respond_to?(:cwd) && message.cwd
+        attrs['claude_code.permission_mode'] = message.permission_mode if message.respond_to?(:permission_mode) && message.permission_mode
+
+        @root_span = @tracer.start_span('claude_agent.session', attributes: compact_attrs(attrs))
+        @root_context = OpenTelemetry::Trace.context_with_span(@root_span)
+
+        # Apply buffered prompt if on_user_prompt was called before InitMessage arrived
+        @root_span.set_attribute('input.value', truncate(@first_user_input)) if @first_user_input && !@first_user_input.empty?
+      end
+
+      def handle_assistant(message)
+        return unless @root_context
+
+        # Extract text content for gen_ai.completion
+        text_parts = []
+        tool_use_blocks = []
+
+        (message.content || []).each do |block|
+          case block
+          when ClaudeAgentSDK::TextBlock
+            text_parts << block.text
+          when ClaudeAgentSDK::ToolUseBlock
+            tool_use_blocks << block
+          end
+        end
+
+        # Track last assistant text for trace output
+        combined_text = text_parts.join("\n")
+        @last_assistant_text = combined_text unless combined_text.empty?
+
+        # Create generation span
+        usage = message.usage || {}
+        input_tokens = usage[:input_tokens] || usage['input_tokens']
+        output_tokens = usage[:output_tokens] || usage['output_tokens']
+        attrs = {
+          'openinference.span.kind' => 'LLM',
+          'langfuse.observation.type' => 'generation',
+          'gen_ai.response.model' => message.model,
+          'llm.model_name' => message.model,
+          'gen_ai.usage.input_tokens' => input_tokens,
+          'gen_ai.usage.output_tokens' => output_tokens,
+          'gen_ai.completion' => truncate(combined_text),
+          # OpenInference: Langfuse maps output.value to the Preview Output field
+          'output.value' => truncate(combined_text)
+        }
+
+        OpenTelemetry::Context.with_current(@root_context) do
+          span = @tracer.start_span('claude_agent.generation', attributes: compact_attrs(attrs))
+          span.finish
+        end
+
+        # Start tool spans for any ToolUseBlocks
+        tool_use_blocks.each { |block| start_tool_span(block) }
+      end
+
+      def handle_user(message)
+        return unless @root_context
+
+        content = message.content
+        return unless content.is_a?(Array)
+
+        content.each do |block|
+          case block
+          when ClaudeAgentSDK::ToolResultBlock
+            end_tool_span(block)
+          end
+        end
+      end
+
+      def end_trace(message)
+        return unless @root_span
+
+        usage = message.usage || {}
+        input_tokens = usage[:input_tokens] || usage['input_tokens']
+        output_tokens = usage[:output_tokens] || usage['output_tokens']
+        total_tokens = (input_tokens || 0) + (output_tokens || 0) if input_tokens || output_tokens
+
+        # Set trace output (last assistant response — shown in Langfuse UI)
+        # ResultMessage.result has the final text; fall back to last tracked assistant text
+        trace_output = message.result || @last_assistant_text
+
+        attrs = {
+          # gen_ai conventions
+          'gen_ai.usage.cost' => message.total_cost_usd,
+          'gen_ai.usage.input_tokens' => input_tokens,
+          'gen_ai.usage.output_tokens' => output_tokens,
+          # OpenInference conventions (Langfuse maps these to usage/cost)
+          'llm.token_count.prompt' => input_tokens,
+          'llm.token_count.completion' => output_tokens,
+          'llm.token_count.total' => total_tokens,
+          'llm.cost.total' => message.total_cost_usd,
+          # Trace output (Langfuse shows this in the trace detail view)
+          'output.value' => truncate(trace_output),
+          # Session metadata
+          'claude_agent.duration_ms' => message.duration_ms,
+          'claude_agent.duration_api_ms' => message.duration_api_ms,
+          'claude_agent.num_turns' => message.num_turns,
+          'claude_agent.stop_reason' => message.stop_reason
+        }
+
+        @root_span.status = OpenTelemetry::Trace::Status.error(message.stop_reason || 'error') if message.is_error
+
+        @root_span.add_attributes(compact_attrs(attrs))
+        @root_span.finish
+        @root_span = nil
+        @root_context = nil
+      end
+
+      def start_tool_span(block)
+        return unless @root_context
+
+        input_json = truncate(safe_json(block.input))
+        attrs = {
+          'openinference.span.kind' => 'TOOL',
+          'langfuse.observation.type' => 'tool',
+          'tool.name' => block.name,
+          # OpenInference: Langfuse maps these to the Preview Input/Output fields
+          'input.value' => input_json,
+          'input.mime_type' => 'application/json'
+        }
+
+        OpenTelemetry::Context.with_current(@root_context) do
+          span = @tracer.start_span("claude_agent.tool.#{block.name}", attributes: compact_attrs(attrs))
+          @tool_spans[block.id] = span
+        end
+      end
+
+      def end_tool_span(block)
+        span = @tool_spans.delete(block.tool_use_id)
+        return unless span
+
+        # OpenInference: Langfuse maps output.value to the Preview Output field
+        span.set_attribute('output.value', truncate(block.content.to_s))
+        span.status = OpenTelemetry::Trace::Status.error('tool error') if block.is_error
+        span.finish
+      end
+
+      def record_retry_event(message)
+        return unless @root_span
+
+        @root_span.add_event('api_retry', attributes: compact_attrs(
+          'attempt' => message.attempt,
+          'max_retries' => message.max_retries,
+          'retry_delay_ms' => message.retry_delay_ms,
+          'error_status' => message.error_status,
+          'error' => message.error
+        ))
+      end
+
+      def record_rate_limit_event(message)
+        return unless @root_span
+
+        info = message.rate_limit_info
+        attrs = {}
+        if info
+          attrs['status'] = info.status if info.respond_to?(:status)
+          attrs['rate_limit_type'] = info.rate_limit_type if info.respond_to?(:rate_limit_type)
+        end
+        @root_span.add_event('rate_limit', attributes: compact_attrs(attrs))
+      end
+
+      def record_tool_progress_event(message)
+        return unless @root_span
+
+        @root_span.add_event('tool_progress', attributes: compact_attrs(
+          'tool_name' => message.tool_name,
+          'tool_use_id' => message.tool_use_id,
+          'elapsed_time_seconds' => message.elapsed_time_seconds
+        ))
+      end
+
+      # Remove nil values from attributes hash (OTel rejects nil attribute values)
+      def compact_attrs(attrs)
+        attrs.compact
+      end
+
+      def truncate(str)
+        return nil unless str
+
+        str.length > MAX_ATTRIBUTE_LENGTH ? str[0...MAX_ATTRIBUTE_LENGTH] : str
+      end
+
+      def safe_json(obj)
+        JSON.generate(obj)
+      rescue StandardError
+        obj.to_s
+      end
+    end
+  end
+end

data/lib/claude_agent_sdk/instrumentation.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Instrumentation adapters for ClaudeAgentSDK.
+# Each adapter lazy-requires its external gem, so loading this file has zero cost
+# unless you instantiate a specific observer.
+require_relative 'instrumentation/otel'

data/lib/claude_agent_sdk/observer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ClaudeAgentSDK
+  # Base module for message observers.
+  #
+  # Include this module and override the methods you care about.
+  # All methods have no-op defaults so observers only need to implement
+  # the callbacks relevant to their use case.
+  #
+  # Observers are registered via ClaudeAgentOptions#observers and are called
+  # for every parsed message in both query() and Client#receive_messages.
+  # Observer errors are rescued so they never crash the main message pipeline.
+  #
+  # @example Custom logging observer
+  #   class LoggingObserver
+  #     include ClaudeAgentSDK::Observer
+  #
+  #     def on_message(message)
+  #       puts "[#{message.class.name}] received"
+  #     end
+  #   end
+  module Observer
+    # Called with the user's prompt text (not echoed back by CLI in streaming mode).
+    # @param prompt [String] The user's prompt string
+    def on_user_prompt(prompt); end
+
+    # Called for every parsed message (typed object from MessageParser).
+    # @param message [Object] A typed message (AssistantMessage, ResultMessage, etc.)
+    def on_message(message); end
+
+    # Called when a transport or parse error occurs.
+    # @param error [Exception] The error that occurred
+    def on_error(error); end
+
+    # Called when the query or client disconnects. Use this to flush buffers.
+    def on_close; end
+  end
+end

data/lib/claude_agent_sdk/types.rb

@@ -1720,7 +1720,7 @@ module ClaudeAgentSDK
                   :output_format, :max_budget_usd, :max_thinking_tokens,
                   :fallback_model, :plugins, :debug_stderr,
                   :betas, :tools, :sandbox, :enable_file_checkpointing, :append_allowed_tools,
-                  :thinking, :effort, :bare
+                  :thinking, :effort, :bare, :observers
 
     # Non-nil defaults for options that need them.
     # Keys absent from here default to nil.
@@ -1728,7 +1728,8 @@ module ClaudeAgentSDK
       allowed_tools: [], disallowed_tools: [], add_dirs: [],
       mcp_servers: {}, env: {}, extra_args: {},
       continue_conversation: false, include_partial_messages: false,
-      fork_session: false, enable_file_checkpointing: false
+      fork_session: false, enable_file_checkpointing: false,
+      observers: []
     }.freeze
 
     # Valid option names derived from attr_accessor declarations.

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -4,6 +4,7 @@ require_relative 'claude_agent_sdk/version'
 require_relative 'claude_agent_sdk/errors'
 require_relative 'claude_agent_sdk/configuration'
 require_relative 'claude_agent_sdk/types'
+require_relative 'claude_agent_sdk/observer'
 require_relative 'claude_agent_sdk/transport'
 require_relative 'claude_agent_sdk/subprocess_cli_transport'
 require_relative 'claude_agent_sdk/message_parser'
@@ -17,6 +18,24 @@ require 'securerandom'
 
 # Claude Agent SDK for Ruby
 module ClaudeAgentSDK
+  # Resolve observers array: callables (Proc/lambda) are invoked to produce
+  # a fresh instance per query/session (thread-safe); plain objects are used as-is.
+  # Array() guards against nil (e.g., when observers: nil is passed explicitly).
+  def self.resolve_observers(observers)
+    Array(observers).map do |obs|
+      obs.respond_to?(:call) ? obs.call : obs
+    end
+  end
+
+  # Safely call a method on each observer, suppressing any errors.
+  def self.notify_observers(observers, method, *args)
+    observers.each do |obs|
+      obs.send(method, *args)
+    rescue StandardError
+      nil
+    end
+  end
+
   # Look up a value in a hash that may use symbol or string keys in camelCase or snake_case.
   # Returns the first non-nil value found, preserving false as a meaningful value.
   def self.flexible_fetch(hash, camel_key, snake_key)
@@ -120,6 +139,9 @@ module ClaudeAgentSDK
       configured_options = options.dup_with(permission_prompt_tool_name: 'stdio')
     end
 
+    # Resolve callable observers into fresh instances (thread-safe for global defaults)
+    resolved_observers = ClaudeAgentSDK.resolve_observers(configured_options.observers)
+
     Async do
       # Always use streaming mode with control protocol (matches Python SDK).
       # This sends agents via initialize request instead of CLI args,
@@ -174,6 +196,7 @@ module ClaudeAgentSDK
 
         # Send prompt(s) as user messages, then close stdin
         if prompt.is_a?(String)
+          ClaudeAgentSDK.notify_observers(resolved_observers, :on_user_prompt, prompt)
           message = {
             type: 'user',
             message: { role: 'user', content: prompt },
@@ -191,9 +214,13 @@ module ClaudeAgentSDK
         # Read and yield messages from the query handler (filters out control messages)
         query_handler.receive_messages do |data|
           message = MessageParser.parse(data)
-          block.call(message) if message
+          if message
+            ClaudeAgentSDK.notify_observers(resolved_observers, :on_message, message)
+            block.call(message)
+          end
         end
       ensure
+        ClaudeAgentSDK.notify_observers(resolved_observers, :on_close)
         # query_handler.close stops the background read task and closes the transport
         if query_handler
           query_handler.close
@@ -308,6 +335,9 @@ module ClaudeAgentSDK
       @query_handler.start
       @query_handler.initialize_protocol
 
+      # Resolve callable observers into fresh instances (thread-safe for global defaults)
+      @resolved_observers = ClaudeAgentSDK.resolve_observers(@options.observers)
+
       @connected = true
 
       # Optionally send initial prompt/messages after connection is ready.
@@ -331,6 +361,7 @@ module ClaudeAgentSDK
     def query(prompt, session_id: 'default')
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
 
+      ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, prompt)
       message = {
         type: 'user',
         message: { role: 'user', content: prompt },
@@ -349,7 +380,10 @@ module ClaudeAgentSDK
 
       @query_handler.receive_messages do |data|
         message = MessageParser.parse(data)
-        block.call(message) if message
+        if message
+          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_message, message)
+          block.call(message)
+        end
       end
     end
 
@@ -439,6 +473,7 @@ module ClaudeAgentSDK
     def disconnect
       return unless @connected
 
+      ClaudeAgentSDK.notify_observers(@resolved_observers || [], :on_close)
       @query_handler&.close
       @query_handler = nil
       @transport = nil

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2026-04-01 00:00:00.000000000 Z
+date: 2026-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -106,7 +106,10 @@ files:
 - lib/claude_agent_sdk.rb
 - lib/claude_agent_sdk/configuration.rb
 - lib/claude_agent_sdk/errors.rb
+- lib/claude_agent_sdk/instrumentation.rb
+- lib/claude_agent_sdk/instrumentation/otel.rb
 - lib/claude_agent_sdk/message_parser.rb
+- lib/claude_agent_sdk/observer.rb
 - lib/claude_agent_sdk/query.rb
 - lib/claude_agent_sdk/sdk_mcp_server.rb
 - lib/claude_agent_sdk/session_mutations.rb