claude-agent-sdk 1.1.0 → 1.2.0

data/docs/configuration.md

@@ -35,6 +35,8 @@ ClaudeAgentSDK.query(prompt: "Create a profile for a software engineer", options
 end
 ```
 
+In the `output_format` Hash, `type` may be a String or a Symbol (`type: :json_schema`), and the keys Symbols or Strings.
+
 See [examples/structured_output_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/structured_output_example.rb).
 
 ## Thinking Configuration
@@ -96,6 +98,8 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 )
 ```
 
+In a Hash form, `type` may be a String or a Symbol (`type: :preset`).
+
 `snapshot` is sent on the control-protocol `initialize` request (never as a CLI flag), so it applies to both `query()` and `Client`. When omitted it acts as `true`, except in bare mode (`bare: true`), where it acts as `false`. A `SystemPromptFile` has no `snapshot`.
 
 Requires Claude Code CLI 2.1.257 or later. Before 2.1.265, a session with an `append` or custom prompt recorded it only when `snapshot` was `true`. See [Modifying system prompts](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session) for details.
@@ -177,10 +181,18 @@ Available beta features are listed in the `SDK_BETAS` constant.
 # Array of tool names
 options = ClaudeAgentSDK::ClaudeAgentOptions.new(tools: ['Read', 'Edit', 'Bash'])
 
+# The same names as one String, in the comma-separated form of the CLI's --tools flag
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(tools: 'Read,Edit,Bash')
+
 # Preset
 options = ClaudeAgentSDK::ClaudeAgentOptions.new(tools: ClaudeAgentSDK::ToolsPreset.new(preset: 'claude_code'))
+
+# The preset as a Hash
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(tools: { type: 'preset', preset: 'claude_code' })
 ```
 
+A String is passed to the CLI as written. In the Hash form, `type` may be a String or a Symbol (`type: :preset`).
+
 ## Skills
 
 `skills` is the single place to enable skills for the main session — it auto-allows the `Skill` tool and defaults `setting_sources` to `['user', 'project']` (when unset) so skill files are discovered:
@@ -195,9 +207,15 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(skills: %w[pdf docx])
 
 Semantics: `nil` (default) leaves CLI defaults untouched; `[]` hides every skill from the listing; an Array adds `Skill(name)` allow-rules per entry (use `plugin:skill` for plugin-qualified names). An explicitly set `setting_sources` (including `[]`) is never overridden. This is a context filter, not a sandbox — skill files remain readable on disk.
 
+If you also give `tools` as a list of names, put `'Skill'` in it. `skills` adds the `Skill` tool to the *allowed* tools, while `tools` decides which tools the session has at all: with `tools: ['Read'], skills: 'all'` there is no `Skill` tool, and no skill can run. Leaving `tools` unset keeps it.
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(tools: %w[Read Skill], skills: %w[pdf docx])
+```
+
 ## 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`.
+Configure [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime) restrictions (network policy, filesystem access) with the `sandbox` option. The SDK sends it to the CLI as the `sandbox` key of the `--settings` argument, merged into your `settings:` when you pass both; there is no separate sandbox flag. The CLI handles OS-level process isolation using `srt`.
 
 ```ruby
 sandbox = ClaudeAgentSDK::SandboxSettings.new(
@@ -212,8 +230,40 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 )
 ```
 
+`sandbox` also takes a Hash, and so do `network` and `filesystem`, inside that Hash or inside a `SandboxSettings`. A Hash may spell the fields of `SandboxSettings`, `SandboxNetworkConfig` and `SandboxFilesystemConfig` as the classes do (`denied_domains`) or as the CLI does (`deniedDomains`), with Symbol or String keys:
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  sandbox: {
+    enabled: true,
+    network: { denied_domains: ['evil.example'] },
+    filesystem: { deny_read: ['~/.ssh'] }
+  }
+)
+```
+
+- Any other key is sent as written. That is how to pass a sandbox setting the classes have no attribute for (`allowAppleEvents`, `strictAllowlist` inside `network`): spell it as the CLI does.
+- A snake_case key is sent under the CLI's name only when its value has the shape the CLI accepts for that key: `true` or `false` for a switch, an Array of Strings for a list, a port number (an Integer from 0 to 65535) for a proxy port, a Hash of String Arrays for `ignore_violations`. With a value of any other shape (`denied_domains: 'evil.example'`, a String where an Array belongs) the key is sent as written, and the CLI ignores a key it does not know.
+- A field holding `nil` is left out, in either spelling, as a `nil` attribute of the typed classes is.
+
+The second rule exists because of how the CLI validates these settings (observed with CLI 2.1.287). When one sandbox value fails its settings schema, the CLI discards the **whole** `--settings` value: the sandbox, and everything you passed in `settings:` next to it, `permissions` rules included. The CLI reports the failure in the `errors` of its `get_settings` control response, and the SDK does not surface that: `connect` succeeds, nothing appears on stderr, and the session runs unsandboxed. That applies to a value written under the CLI's own name (`excludedCommands: 'docker'`) and to the typed classes, which send each value as you gave it: `SandboxSettings.new(excluded_commands: 'docker')` leaves the session without a sandbox.
+
+`enabled: true` asks for a sandbox. It does not make one a requirement. When the sandbox cannot start on the host (missing dependencies, an unsupported platform), the CLI carries on without it. Its settings schema describes the setting that decides this, `failIfUnavailable`, as follows (CLI 2.1.287):
+
+> Exit with an error at startup if sandbox.enabled is true but the sandbox cannot start (missing dependencies or unsupported platform). When false (default), a warning is shown and commands run unsandboxed.
+
+The SDK sends your sandbox settings as you wrote them and does not add this one. If commands must never run unsandboxed, set it yourself:
+
+```ruby
+sandbox = ClaudeAgentSDK::SandboxSettings.new(enabled: true, fail_if_unavailable: true)
+```
+
+Without it, the sign is the CLI's warning on stderr ("Sandbox disabled: ... Commands will run WITHOUT sandboxing. Network and filesystem restrictions will NOT be enforced."), and stderr reaches your code only through the `stderr` (or `debug_stderr`) option. This is the CLI's own description of its behavior: the fallback has not been reproduced in this SDK's testing, where the sandbox was always available.
+
 See [examples/sandbox_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/sandbox_example.rb).
 
+When the `sandbox:` option enabled the sandbox and the CLI reports `Sandbox disabled: …` on its stderr, the SDK repeats that line as a Ruby warning prefixed `[claude-agent-sdk]`, once per session, whether or not you set `stderr:`.
+
 ## 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.
@@ -287,6 +337,119 @@ and `Client#query`.
 
 Matches the Python SDK's `verbatim_prompts`.
 
+## Session Isolation
+
+Claude Code keeps an **auto-memory** for each project: Markdown notes and an
+index file, `<config dir>/projects/<project key>/memory/MEMORY.md`. It is a
+CLI feature, it is on by default, and SDK sessions take part in it. If one
+process runs sessions for more than one user or tenant, three things follow:
+
+- **Every session reads the index.** The CLI puts `MEMORY.md` into the context
+  of every session of that project, under the same heading as `CLAUDE.md` (in
+  CLI 2.1.287: "IMPORTANT: These instructions OVERRIDE any default behavior
+  and you MUST follow them exactly as written"). That holds with the SDK's
+  default (empty) system prompt and with `tools: []`. `setting_sources: []`
+  does not change it either: that option selects the user, project and local
+  sources (their settings files and their `CLAUDE.md` files), and the
+  auto-memory is not one of them.
+- **A session on the `claude_code` preset also writes it.** The preset system
+  prompt includes instructions for keeping memories, so a message such as
+  "remember that ..." makes the model save a note and update the index with
+  its file tools. The CLI allows those writes by itself: in testing (CLI
+  2.1.286) they succeeded in the default permission mode with no
+  `can_use_tool` callback, no hook and no allow rule. Do not count on your
+  permission setup to stop them. With the SDK's default system prompt the
+  sessions tested only read the index: asked to remember something, they
+  wrote nothing (an observation, not a guarantee).
+- **The memory belongs to the project, not to the session.** The project key
+  is the root of the git repository that contains the working directory, so
+  every subdirectory and every git worktree of one repository shares one
+  memory directory. Outside a repository the key is the working directory
+  itself.
+
+So on a server that runs every user's session from one checkout and one config
+directory with the `claude_code` preset, what one user asks the agent to
+remember can be saved without a permission check and then reach every later
+session as an instruction. With the default system prompt the exposure is the
+read side: whatever memory already exists for that project and config
+directory, a developer's own for instance, is in every session's context.
+
+### Turning auto-memory off
+
+Servers and multi-tenant hosts should switch it off. Both forms work with
+`query()` and `Client`:
+
+```ruby
+# An environment variable for the CLI process
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  env: { 'CLAUDE_CODE_DISABLE_AUTO_MEMORY' => '1' }
+)
+
+# Or the CLI setting
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  settings: { autoMemoryEnabled: false }
+)
+```
+
+To apply it to every session, set it as a default (a per-call `env` Hash is
+merged into the configured one):
+
+```ruby
+ClaudeAgentSDK.configure do |config|
+  config.default_options = { env: { 'CLAUDE_CODE_DISABLE_AUTO_MEMORY' => '1' } }
+end
+```
+
+- The variable must be `'1'`. `'0'` and `'false'` do not mean "the default":
+  they force auto-memory **on** and override `autoMemoryEnabled: false`.
+- `bare: true` turns auto-memory off as well, but bare mode never reads an
+  OAuth login or the keychain: it authenticates with `ANTHROPIC_API_KEY` (or
+  an `apiKeyHelper` setting) only. See [Bare Mode](#bare-mode).
+- Both switches reach the CLI that `query()` and `Client` start themselves,
+  through the default `SubprocessCLITransport`: it puts `env` into the CLI's
+  environment and `settings` on its command line (`--settings`).
+- A [custom transport](client.md#custom-transport) starts the CLI its own way,
+  so neither switch reaches that CLI unless the transport passes it through:
+  `env` into the environment it gives the CLI, `settings` onto the command
+  line (a transport that builds its command line with `CommandBuilder` gets
+  `--settings` from it; one that does not, has to add it). Until then the
+  session is not isolated.
+
+### What does not isolate sessions
+
+- **A different `cwd`** separates the memory only when the two directories
+  are not in the same git repository.
+- **A different `CLAUDE_CONFIG_DIR`** separates it only when the two config
+  directories do not share `projects/` (a `projects/` that is a symlink to
+  another config directory's is shared). A new config directory also has no
+  login, so give the CLI `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN`
+  (in the process environment or in `env`).
+- **`setting_sources: []`** keeps the user, project and local settings and
+  `CLAUDE.md` files out of a session. The auto-memory index still loads. So
+  do the MCP servers connected to the claude.ai account the CLI is logged in
+  with: `strict_mcp_config: true` is what limits a session to the servers in
+  `mcp_servers` (see the [options reference](options.md#strict_mcp_config)).
+
+"One working directory per tenant" is therefore not enough on its own. Use the
+switch.
+
+### Checking what a session loaded
+
+`Client#context_usage` reports the files in a session's context without a
+model call. The auto-memory index is the entry whose `:type` is `"AutoMem"`:
+
+```ruby
+ClaudeAgentSDK::Client.open(options: options) do |client|
+  client.context_usage.fetch(:memoryFiles, []).each do |file|
+    puts "#{file[:type]} #{file[:path]} (#{file[:tokens]} tokens)"
+  end
+end
+# AutoMem /home/app/.claude/projects/-srv-app/memory/MEMORY.md (27 tokens)
+```
+
+With auto-memory off the list has no `AutoMem` entry. `query()` has no
+equivalent; run the check through a `Client` with the same options.
+
 ## Forwarding Subagent Text
 
 By default only `tool_use` / `tool_result` blocks from subagents (spawned via

data/docs/errors.md

@@ -87,6 +87,30 @@ initial handshake that was still in flight when the CLI exited. Match on
 `Resume rejected by --resume-drops-turn:` in the message and treat it as
 deterministic: clear the fork target and resume plainly rather than retrying.
 
+## Errors from Client Control Methods
+
+`Client#interrupt`, `#set_model`, `#set_permission_mode`, `#rewind_files`, `#reconnect_mcp_server`, `#toggle_mcp_server`, `#stop_task` and the other control methods (the Ruby-style `model=` and `permission_mode=` included) send a request to the CLI and wait for its answer. They can fail in three ways:
+
+| What happened | Raised |
+|---------------|--------|
+| The client is not connected, or the connection ended while the request was waiting | `CLIConnectionError` |
+| The CLI did not answer in time | `ControlRequestTimeoutError` |
+| The CLI answered with an error: an MCP server name it does not know, a rewind without `enable_file_checkpointing`, a permission mode it does not accept | a plain `StandardError` whose message is the CLI's text |
+
+The third is **not** a `ClaudeSDKError`, so `rescue ClaudeAgentSDK::ClaudeSDKError` does not catch it:
+
+```ruby
+begin
+  client.reconnect_mcp_server('my-server')
+rescue ClaudeAgentSDK::ClaudeSDKError => e
+  puts "Connection lost or timed out: #{e.message}"
+rescue StandardError => e
+  puts "The CLI refused: #{e.message}" # e.g. "Server not found: my-server"
+end
+```
+
+Rescue `StandardError` for it, and do not test for the exact class.
+
 ## Configuring Timeout
 
 The control request timeout defaults to **1200 seconds** (20 minutes) to accommodate long-running agent sessions. Override it via environment variable:
@@ -98,7 +122,7 @@ export CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS=300  # 5 minutes
 ## Error Type Reference
 
 ```ruby
-# Base exception class for all SDK errors
+# Base class of the SDK's error classes (all the ones below)
 class ClaudeSDKError < StandardError; end
 
 # Raised when connection to Claude Code fails
@@ -113,6 +137,11 @@ class CLINotFoundError < CLIConnectionError
   # @param cli_path [String, nil] Optional path to the CLI that was not found
 end
 
+# Raised by CLIInstaller.install / .install_pinned (and the
+# claude_agent_sdk:install_cli rake task) when the CLI cannot be installed.
+# Never raised by query, ask or Client
+class CLIInstallError < ClaudeSDKError; end
+
 # Raised by the local-disk session APIs when CLAUDE_CONFIG_DIR is unset and
 # no usable home directory exists for the default ~/.claude
 class ConfigDirError < ClaudeSDKError; end
@@ -155,10 +184,11 @@ end
 
 | Error | Description |
 |-------|-------------|
-| `ClaudeSDKError` | Base error for all SDK errors |
+| `ClaudeSDKError` | Base class of every error class in this table. One failure is not a `ClaudeSDKError`: a control request the CLI rejects, see [Errors from Client Control Methods](#errors-from-client-control-methods) |
 | `CLIConnectionError` | Connection issues — including every write after a stdin write was cancelled mid-frame (the connection is unusable from then on — reconnect), and `ClaudeAgentSDK.ask` when the stream ends without a `ResultMessage` |
 | `ControlRequestTimeoutError` | Control protocol timeout (configurable via env var) |
 | `CLINotFoundError` | Claude Code not installed |
+| `CLIInstallError` | `CLIInstaller.install` / `install_pinned` (or the `claude_agent_sdk:install_cli` rake task) could not install the CLI: unsupported platform, invalid version, HTTP error, a response or download over its size limit, checksum mismatch, or a filesystem error. A wrapped failure keeps the original exception in `#cause`. This is the error a deploy or `bin/setup` script rescues; a failed install leaves a previously installed binary in place. See [CLI installer](cli-installer.md) |
 | `ConfigDirError` | A local-disk session API (`list_sessions`, `get_session_*`, `rename_session`, ...) could not locate the Claude config directory: `CLAUDE_CONFIG_DIR` is unset and there is no usable home directory (`HOME` unset with no passwd entry, as under `docker --user` in a minimal image, or an empty/relative `HOME`). Set `CLAUDE_CONFIG_DIR` |
 | `SessionStoreError` | Resuming from `session_store:` failed: a store call (`#load`, `#list_sessions`, `#list_subkeys`) raised or exceeded `load_timeout_ms` while the SDK materialized the transcript, before the CLI started. The message names the call; `#cause` is the adapter's exception. Before 1.0 this was a bare `RuntimeError` — see [Sessions](sessions.md#mirroring-to-a-sessionstore) |
 | `ProcessError` | Process failed (includes `exit_code` and `stderr`) — also raised when the CLI is still running 5s after closing stdout and the SDK had to terminate it |

data/docs/hooks-and-permissions.md

@@ -69,16 +69,34 @@ Async do
     }
   )
 
-  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
+  ClaudeAgentSDK::Client.open(options: options) do |client|
+    client.query("Run the bash command: ./foo.sh --help")
+    client.receive_response { |msg| puts msg }
+  end
 end.wait
 ```
 
 See [examples/hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/hooks_example.rb), [examples/advanced_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/advanced_hooks_example.rb), and [examples/lifecycle_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb).
 
+### Hook output
+
+A callback returns a typed output (`AsyncHookJSONOutput`, or `SyncHookJSONOutput`, which can hold a `*HookSpecificOutput`), a Hash, or `nil` (the same as `{}`). A Hash stands for the typed output with the same fields. Its keys may be Symbols or Strings, and each field may be spelled as the typed class's attribute (`permission_decision`) or as the CLI reads it (`permissionDecision`), at the top level and inside `hook_specific_output`. The deny in the example above can also be written as:
+
+```ruby
+{
+  hook_specific_output: {
+    hook_event_name: 'PreToolUse', # a typed output sets this itself; a Hash has to carry it
+    permission_decision: 'deny',
+    permission_decision_reason: "Command contains forbidden pattern: #{pattern}"
+  }
+}
+```
+
+- `continue_` and `async_` stand for `continue` and `async`.
+- A key the typed classes do not have is sent as written, so a CLI field the SDK does not model has to be spelled the way the CLI spells it.
+- The keys inside `updated_input`, `updated_tool_output`, `updated_mcp_tool_output` and a `PermissionRequest` `decision` are not renamed: those are the tool's own payloads (for `decision`, the CLI's), so spell them as the tool or the CLI does.
+- If one Hash spells the same field both ways, the CLI's spelling is the one sent (`permissionDecision` over `permission_decision`, `continue` over `continue_`).
+
 ### Hook cancellation
 
 Dispatched hooks receive `HookContext#request_id` and `HookContext#signal`, using
@@ -123,11 +141,10 @@ Async do
     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
+  ClaudeAgentSDK::Client.open(options: options) do |client|
+    client.query("Create a file called test.txt with content 'Hello'")
+    client.receive_response { |msg| puts msg }
+  end
 end.wait
 ```
 
@@ -202,6 +219,9 @@ An exception raised inside a hook or a `can_use_tool` callback fails that
 control request: the CLI receives an error response carrying the exception
 message, and the session carries on with later requests. The request's
 cancellation signal is invalidated, as for any other callback failure.
+`NotImplementedError`, `LoadError`, `SystemStackError` and `SecurityError` are
+answered the same way, although they are not `StandardError`s. Bytes of the
+message that are not valid UTF-8 are replaced with U+FFFD.
 
 `exit`, `Interrupt` and other signal exceptions are never swallowed. If one
 is raised while a callback runs (by the callback itself, or a real Ctrl-C /

data/docs/mcp-servers.md

@@ -8,7 +8,6 @@ A **custom tool** is a Ruby proc/lambda that you can offer to Claude, for Claude
 
 ```ruby
 require 'claude_agent_sdk'
-require 'async'
 
 greet_tool = ClaudeAgentSDK.create_tool(
   'greet', 'Greet a user', { name: :string },
@@ -28,13 +27,10 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
   allowed_tools: ['mcp__tools__greet']
 )
 
-Async do
-  client = ClaudeAgentSDK::Client.new(options: options)
-  client.connect
+ClaudeAgentSDK::Client.open(options: options) do |client|
   client.query("Greet Alice")
   client.receive_response { |msg| puts msg }
-  client.disconnect
-end.wait
+end
 ```
 
 ## Handler Return Values
@@ -56,7 +52,28 @@ ClaudeAgentSDK.create_tool('lookup_order', 'Look up an order', { id: :string })
 end
 ```
 
-Any other return value (`nil`, an Integer, an Array, ...) is reported to Claude as an `isError: true` result saying the tool must return a hash with a `:content` key.
+Any other return value (`nil`, an Integer, an Array, ...) is reported to Claude as an `isError: true` result saying the tool must return a hash with a `:content` key. So is a Hash whose `:content` is not an Array — `{ content: 'text' }`, or a single block Hash — with a message saying `:content` must be an Array of content blocks; return the String itself, or wrap the block in an Array.
+
+## Shorthand Input Schemas
+
+`{ name: :string }` is shorthand for a JSON Schema object in which every listed parameter is required. Each value names a type, as a Ruby class or as a Symbol:
+
+| Shorthand | JSON Schema type | The handler receives |
+| --- | --- | --- |
+| `String`, `:string` | `string` | a String |
+| `Integer`, `:integer` | `integer` | an Integer |
+| `Float`, `:float`, `:number` | `number` | an Integer or a Float |
+| `TrueClass`, `FalseClass`, `:boolean` | `boolean` | `true` or `false` |
+| `Array`, `:array` | `array` | an Array, with elements of any type |
+| `Hash`, `:object` | `object` | a Hash with Symbol keys |
+
+```ruby
+ClaudeAgentSDK.create_tool('tag_order', 'Tag an order', { order_id: Integer, tags: Array }) do |args|
+  "Tagged order #{args[:order_id]} with #{args[:tags].join(', ')}"
+end
+```
+
+Arguments are validated against these types before the handler runs. For an optional parameter, the type of an Array's elements, an enum or a per-parameter description, pass a full JSON Schema instead (next section).
 
 ## Pre-built JSON Schemas
 
@@ -125,12 +142,14 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 
 An exception raised inside a handler is returned to the model as an
 `isError: true` result carrying the exception message, so it can self-correct.
+That holds for `NotImplementedError`, `LoadError`, `SystemStackError` and
+`SecurityError` as well, although they are not `StandardError`s.
 `exit`, `Interrupt` and other signal exceptions are never swallowed: the CLI
 first gets an `isError` result naming the exception class
 (`"SystemExit: exit"`), so it is not left waiting on the tool call, and then
 the exception propagates as Ruby normally would (`exit` ends the process,
 Ctrl-C interrupts it). Called directly, without a session,
-`SdkMcpServer#call_tool` simply lets such exceptions propagate. Cancellation of the tool call itself still propagates.
+`SdkMcpServer#call_tool` simply lets `exit` and signal exceptions propagate. Cancellation of the tool call itself still propagates.
 
 ## Mixed Server Support
 
@@ -196,7 +215,9 @@ server = ClaudeAgentSDK.create_sdk_mcp_server(
 ```
 
 An exception raised inside a resource reader or prompt generator is answered
-with a JSON-RPC internal error (`-32603`) carrying the exception message. For
+with a JSON-RPC internal error (`-32603`) carrying the exception message;
+`NotImplementedError`, `LoadError`, `SystemStackError` and `SecurityError`
+are covered here too. For
 `exit`, `Interrupt` and other signal exceptions the CLI gets that error first,
 naming the exception class, and then the exception propagates as Ruby normally
 would.

data/docs/observability.md

@@ -1,6 +1,6 @@
 # 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.
+The SDK includes a built-in **observer interface** and an **OpenTelemetry observer** for tracing agent sessions. Span attributes follow the Langfuse and OpenInference conventions, plus a subset of the OTel `gen_ai.*` attributes. Any OTel backend (Jaeger, Datadog, ...) can store and display the spans; one that interprets attributes by the OTel GenAI semantic conventions reads only part of them, as [Span Attributes](#span-attributes) explains.
 
 ## Distributed Trace Context (W3C)
 
@@ -18,13 +18,15 @@ In `Client` mode, call `disconnect` (ideally in an `ensure` block) so `on_close`
 
 ```
 claude_agent.session            (root span — one per query/session)
-├── claude_agent.generation     (per AssistantMessage, with model + token usage)
+├── claude_agent.generation     (per AssistantMessage, with model; token usage once per API response)
 ├── claude_agent.tool.Bash      (per tool call, open on ToolUseBlock, close on ToolResultBlock)
 ├── claude_agent.tool.Read
 ├── claude_agent.generation
 └── ...
 ```
 
+A session that fails before its first `InitMessage` (the CLI cannot be found or started, or the `initialize` handshake fails or times out) still leaves a span. `OTelObserver` emits a `claude_agent.session` span that records the exception and has error status, and ends it at once, so it is exported even when no `on_close` follows: a `Client#connect` that fails before the handshake never calls it. The span carries the observer's default attributes and, if a prompt had already been sent, `input.value`. It has no model, `session.id` or `claude_code.*` attributes, because the CLI never reported them. Once a trace has started, an error is recorded on its session span instead, and an error that arrives after the trace ended adds no span: the usual one is the `ResultError` raised when the CLI exits non-zero after an error result, which that trace already reports.
+
 ## Setup with Langfuse
 
 **1. Install the OTel gems** (not bundled with the SDK — you choose your exporter):
@@ -38,6 +40,7 @@ Or add to your Gemfile:
 ```ruby
 gem 'opentelemetry-sdk', '~> 1.4'
 gem 'opentelemetry-exporter-otlp', '~> 0.28'
+gem 'base64' # the snippet below requires it; under Bundler, Ruby 3.4+ needs it listed
 ```
 
 **2. Configure the OTel SDK** to export to your Langfuse instance:
@@ -110,19 +113,67 @@ See [docs/rails.md](rails.md) for the Rails-specific pattern.
 
 ## 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`, `gen_ai.usage.cache_creation_input_tokens`, `gen_ai.usage.cache_read_input_tokens`, `llm.token_count.prompt_details.cache_read`, `llm.token_count.prompt_details.cache_write` |
-| `claude_agent.generation` | `generation` | `gen_ai.response.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.usage.cache_creation_input_tokens`, `gen_ai.usage.cache_read_input_tokens`, `output.value` |
-| `claude_agent.tool.*` | `tool` | `tool.name`, `input.value`, `output.value` |
+Attribute names follow the Langfuse and OpenInference conventions, plus a subset of the OTel `gen_ai.*` attributes. The tables below list every attribute the observer sets. An attribute whose value the CLI did not report is left out, and `input.value`, `output.value` and `gen_ai.completion` are cut at 4,096 characters.
+
+**`claude_agent.session`**
+
+| Attribute | Value |
+|-----------|-------|
+| `gen_ai.system` | `anthropic` |
+| `gen_ai.request.model`, `llm.model_name` | The model named by the `InitMessage` |
+| `session.id` | The CLI session ID |
+| `openinference.span.kind` | `AGENT` |
+| `langfuse.observation.type` | `agent` |
+| `input.mime_type`, `output.mime_type` | `text/plain` |
+| `claude_code.version`, `claude_code.cwd`, `claude_code.permission_mode` | From the `InitMessage` |
+| Your default attributes | Whatever you passed to `OTelObserver.new`. They are set on this span only |
+| `input.value` | The prompt of the trace |
+| `output.value` | `ResultMessage#result`, or the last assistant text when the result has none |
+| `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.usage.cache_creation_input_tokens`, `gen_ai.usage.cache_read_input_tokens` | The four counts of `ResultMessage#usage` as the API reports them, so `input_tokens` leaves cache tokens out |
+| `llm.token_count.prompt` | Input, cache-creation and cache-read tokens added up |
+| `llm.token_count.completion` | Output tokens |
+| `llm.token_count.total` | `llm.token_count.prompt` plus `llm.token_count.completion` |
+| `llm.token_count.prompt_details.cache_read`, `llm.token_count.prompt_details.cache_write` | Cache-read and cache-creation tokens |
+| `gen_ai.usage.cost`, `llm.cost.total` | The cost increase since the previous result (see below) |
+| `claude_agent.duration_ms`, `claude_agent.duration_api_ms`, `claude_agent.num_turns`, `claude_agent.stop_reason` | From the `ResultMessage` |
+
+The span status is error when the `ResultMessage` has `is_error` (the description is its stop reason) or when `on_error` recorded an exception, which also adds an `exception` event. Three more events are recorded on this span: `api_retry` (`attempt`, `max_retries`, `retry_delay_ms`, `error_status`, `error`), `rate_limit` (`status`, `rate_limit_type`) and `tool_progress` (`tool_name`, `tool_use_id`, `elapsed_time_seconds`).
+
+**`claude_agent.generation`**
+
+| Attribute | Value |
+|-----------|-------|
+| `openinference.span.kind` | `LLM` |
+| `langfuse.observation.type` | `generation` |
+| `gen_ai.response.model`, `llm.model_name` | The model named by the `AssistantMessage` |
+| `gen_ai.completion`, `output.value` | The text blocks of the message joined by newlines; an empty string when it has none (a thinking or tool-call message) |
+| `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.usage.cache_creation_input_tokens`, `gen_ai.usage.cache_read_input_tokens` | The usage of the API response, on the first span of each `message_id` only (see below) |
+
+**`claude_agent.tool.<tool name>`**
+
+| Attribute | Value |
+|-----------|-------|
+| `openinference.span.kind` | `TOOL` |
+| `langfuse.observation.type` | `tool` |
+| `tool.name` | The name of the tool |
+| `input.value`, `input.mime_type` | The tool input as JSON, and `application/json` |
+| `output.value`, `output.mime_type` | The tool result: a String as it is (`text/plain`), structured content as JSON (`application/json`). Both are left out when the result has no content |
+
+The span status is error when the tool result has `is_error`.
+
+**Token usage on generation spans.** The CLI sends one `AssistantMessage` per content block, so an API response with a thinking block and a tool call produces two `claude_agent.generation` spans, and both messages repeat the response's `message_id` and `usage`. The observer sets the four `gen_ai.usage.*` token attributes on the first generation span of each `message_id` and on none of that response's other spans, so a sum over generation spans counts every response once. A message without a `message_id` keeps its usage. That usage is the snapshot taken when the response started: the input, cache-read and cache-creation counts are final, but `gen_ai.usage.output_tokens` holds only the few tokens generated by then, and the response's final output count never reaches the message stream. For authoritative totals, output tokens included, read the session span, which takes them from `ResultMessage#usage`.
 
 `gen_ai.usage.cost` and `llm.cost.total` record the **increase** since the last observed `ResultMessage.total_cost_usd` in the connected session, rather than repeating that cumulative total on every turn's span. The baseline survives per-turn span resets and resets on close, a changed session ID (such as `/clear`), or a decreased counter. The original `ResultMessage` is unchanged.
 
 Missing costs omit both attributes without discarding the last known total; the next reported increment can therefore include an unreported or interrupted turn. The first observation uses the CLI's reported total. If a newer CLI restores historical spend on resume, that first span also includes it: a fresh observer cannot separate spend it never observed. These are CLI cost estimates, not billing records.
 
-Events (`api_retry`, `rate_limit`, `tool_progress`) are recorded on the root span.
+**How this compares with the OTel GenAI semantic conventions.** Nine of the attributes above are `gen_ai.*` names. Three are used as the conventions define them: `gen_ai.request.model`, `gen_ai.response.model`, and `gen_ai.usage.output_tokens` on the session span. The other six are deprecated, removed, not defined or defined differently there, and the observer keeps them for the Langfuse mappings they were added for:
+
+- `gen_ai.system` is deprecated in favor of `gen_ai.provider.name`, and `gen_ai.completion` has been removed.
+- `gen_ai.usage.cache_creation_input_tokens`, `gen_ai.usage.cache_read_input_tokens` and `gen_ai.usage.cost` are not names the conventions define. The two cache names are the Anthropic API's field names.
+- `gen_ai.usage.input_tokens` is the API's `input_tokens`, which leaves cache tokens out, while the conventions say the value should include them. A backend that follows the conventions therefore sees only part of the input of a cached turn: 18 tokens for a recorded turn that consumed 49,974. The inclusive count is `llm.token_count.prompt` on the session span.
+
+The observer sets neither `gen_ai.operation.name` nor `gen_ai.provider.name`. This comparison was made against `opentelemetry-semantic_conventions` 1.43.0; the GenAI conventions are still marked as in development.
 
 The `langfuse.observation.type` attribute is set on each span (`agent`/`generation`/`tool`) to enable Langfuse's **trace flow diagram** (DAG graph visualization).