claude-agent-sdk 0.33.1 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6994a2674fc098001857cff72a21c3d804744c6fa25cb866f2a133ee1a2ec876
-  data.tar.gz: 349b7ce2314eac4c315e3c3d03ef0e466926fe3abb0f8823d1780f1486a8ce0d
+  metadata.gz: a2976dae089e4ccc32b7974b646cb9e543c4dcdfd6bfb35eeccf6b3c4ef5e6ed
+  data.tar.gz: 89ec51407ce6f25c962982078b3fe8301bfda9be4e57bf4a03593e9818d5913a
 SHA512:
-  metadata.gz: 0442feb3be095e8be7903e55e51f5620607b682cb0ed57f1ded989f01f6bf04bf22cee36556b52fd8cb4072d2e3bf4a2400c459b8cad231a83590d75b1010403
-  data.tar.gz: e287cd5825a5e16f1c8d7ce8295d0f3fba07ee15c5e4502be2dbfefcd223cf061c6e20afe5e5e6349e7ee2729c8c70e77aea152c6b95dc997978bc5ef358f68e
+  metadata.gz: 4784c6381acbfedd9a921a852329dfdd64257aa60b25bf51b0f4278b5fe6ce4913b1f719941a0fece9ac818342e5129c0ffd481159bf731ee6930ecf4902b632
+  data.tar.gz: cee7e96d3ef502138189a114716db3862d10d2ff10411e04bf0db8bc654511c547397164c7640c590eed166d11556c26b5d4e6de744f3a6ac396cdb15e40bad3

data/CHANGELOG.md

@@ -7,6 +7,99 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.35.0] - 2026-09-23
+
+First-class Rails integration and a first-impressions pass. **Rails users:** if your initializer uses the previously documented `->(inv) { Rails.application.executor.wrap { inv.call } }` callback wrapper, switch to `ClaudeAgentSDK::Railtie.callback_wrapper` — the bare form can deadlock in development (see **Fixed**).
+
+### Added
+- **Rails integration: `ClaudeAgentSDK::Railtie`**, loaded only when Rails is (`require_relative 'claude_agent_sdk/railtie' if defined?(Rails::Railtie)`, which Bundler.require satisfies in a Rails app); non-Rails processes load nothing new. It contributes a rake task and installs nothing into callback dispatch.
+- **`bin/rails generate claude_agent_sdk:install`** — writes `config/initializers/claude_agent_sdk.rb` (commented `model` / `permission_mode` / `cli_path` / OpenTelemetry defaults, `callback_wrapper: ClaudeAgentSDK::Railtie.callback_wrapper` enabled), appends `/vendor/claude/` to `.gitignore` once (any existing spelling counts), and prints the next steps.
+- **`claude_agent_sdk:install_cli` rake task** — `CLIInstaller.install_pinned` into `Rails.root/vendor/claude`, or `install(version:)` with `CLAUDE_CLI_VERSION=x.y.z|stable|latest`; prints the installed path. It does not boot the app, so it runs in a Docker build step. Outside Rails, `require 'claude_agent_sdk/tasks'` in a Rakefile provides the same task (loading only `CLIInstaller`), installing under the working directory.
+- **`ClaudeAgentSDK::Railtie.callback_wrapper`** — a `callback_wrapper` that runs SDK callbacks in `Rails.application.executor` (so ActiveRecord connections check back in), except where that deadlocks: with code reloading enabled or `config.allow_concurrency = false` it calls the callback outside the executor and releases the thread's ActiveRecord connections itself; when the executor is already active on the callback's context (`:inline` scheduling) it calls straight through. Supports Rails 7.1+.
+- CI: a `rails` job runs the Rails integration specs (`spec/rails`, in their own process via `rspec --options spec/rails/.rspec`) against Rails 7.1 on Ruby 3.2 and the latest Rails 8 on Ruby 3.4 (`gemfiles/rails_7_1.gemfile`, `gemfiles/rails_8.gemfile`). The default `bundle exec rspec` run excludes `spec/rails`.
+- **Every SDK type now prints its fields.** `Type#inspect` lists the non-nil attributes (`#<ClaudeAgentSDK::ResultMessage subtype="success" num_turns=3 total_cost_usd=0.012 ...>`) instead of a bare object address, and `#to_s` falls back to it, so the README's `puts message` is readable for every message type. The output is bounded for logging: Strings past 80 characters are truncated with a count of what was cut, Arrays and Hashes show their first five entries plus a count of the rest, nesting past two levels (and any reference cycle) collapses to a placeholder, and objects that only have `Kernel#inspect` (SDK MCP server instances, store adapters, observers) show as `#<ClassName>` rather than dumping their state. Callbacks (`can_use_tool`, hooks, `callback_wrapper`, ...) render from their source location, e.g. `#<Proc(lambda) permissions.rb:17>`, never through their own `#inspect`, so a raising or oversized override cannot break or flood a log line.
+- **One-line `to_s` for results and system messages.** `ResultMessage#to_s` prints `[result: success, 3 turns, 4.2s, $0.0120]` (missing fields omitted; an error result appends its `errors`), `SystemMessage#to_s` prints `[system: init]`, and `TextBlock#to_s` returns its text. `UserMessage` / `AssistantMessage` keep printing their text.
+
+### Changed
+- `docs/rails.md` opens with a getting-started path (gem → generator → `install_cli` → first job), and its ActionCable, session-resumption and background-job examples use `ClaudeAgentSDK::Client.open` instead of hand-rolled `Async { connect … ensure disconnect }.wait`. README and gemspec description lead with the Rails integration.
+- **`#inspect` filters credential-bearing attributes** to `"[FILTERED]"` (Hash keys stay visible): `ClaudeAgentOptions#env` (usually carries `ANTHROPIC_API_KEY`), `McpStdioServerConfig#env`, and `McpHttpServerConfig` / `McpSSEServerConfig#headers`, since these objects end up in logs. The objects are not modified. Type subclasses declare such attributes with `inspect_filtered :name`. Typed `SystemMessage` subclasses (`InitMessage`, ...) leave the raw `@data` frame out of `#inspect`, since it repeats their attributes; a bare `SystemMessage` keeps it. Nothing sent to the CLI changes: wire output still goes through `#to_h`.
+- The README's `Client` section and the basic example in `docs/client.md` now lead with `Client.open`, which creates the reactor and always disconnects, instead of the `Async do … begin … ensure client.disconnect end.wait` boilerplate. The manual `connect` / `disconnect` form is still shown for code already running inside an `Async` reactor. No API changes.
+- The bundled `claude-agent-ruby` skill recommends `Client.open` and documents the install generator, the `install_cli` task and `Railtie.callback_wrapper`.
+- **Gem metadata names its maintainer** (`authors: ["ya-luotao"]`, with a contact email) instead of "Community Contributors". The stale `IMPLEMENTATION.md` is removed, and the past audit reports move from the repository root to `docs/history/`, which is not packaged with the gem.
+
+### Fixed
+- **The Rails `callback_wrapper` previously recommended in docs/rails.md, `->(inv) { Rails.application.executor.wrap { inv.call } }`, can deadlock in development.** With code reloading enabled, the request or job calling the SDK holds a share of the reload interlock while it waits for a callback running on its own thread (the default `:thread` scheduling); if a reload is requested meanwhile — e.g. after the agent edits an app file — the reloader queues for the exclusive lock and the callback's `executor.wrap` queues behind it, forever. With `config.allow_concurrency = false` the same wrapper blocks on the executor's monitor every time. The guide (and the `callback_wrapper` API docs and skill reference) now recommend `ClaudeAgentSDK::Railtie.callback_wrapper`; replace the bare lambda with it in existing initializers.
+
+## [0.34.0] - 2026-09-23
+
+The September 2026 audit campaign: 17 fixes from the final audit pass plus the 28 AUDIT-2026-09-22 issues (#66–#93). A few fixes tighten behaviour that was silently wrong — read **Changed** before upgrading.
+
+### Added
+- **`CLIInstaller::PINNED_CLI_VERSION`** (`'2.1.280'`, the CLI Python SDK 0.2.158 bundles) — the CLI version this gem release is developed and tested against; the Ruby equivalent of the Python SDK's bundled-CLI pin (`_cli_version.py`), except nothing is shipped inside the gem. Single source of truth: this constant is the only place the pin lives — docs and the transport's guidance reference it rather than repeating the literal.
+- **`CLIInstaller.install_pinned(dir: nil)`** — installs exactly `PINNED_CLI_VERSION`. The Dockerfile / `bin/setup` form of "pin the tested pair": a deploy that calls it gets the SDK+CLI combination this release was tested with, and a Dependabot bump of the gem carries the CLI forward with it — no version literal in the caller to keep in sync. `install`'s default is unchanged (`'stable'` dist-tag), and explicit `version:` pins behave exactly as before.
+- **`.github/workflows/cli-pin-bump.yml`** — scheduled (and manually dispatchable) workflow that reads the Python SDK's `_cli_version.py` on `main` and opens a PR moving `PINNED_CLI_VERSION` when it changes. It touches only that one line; cutting the follow-up patch release stays a human decision.
+
+### Changed
+- **Runtime dependency floors now name versions that actually work: `async >= 2.10, < 3` and `mcp >= 0.22, < 2`** (were `~> 2.0` / `>= 0.20`). A new CI leg runs the suite against exactly these floors: async 2.0.x cannot run on Ruby 3.2+ at all, releases before 2.6.4 break hook timeouts and control-request error delivery, and 2.10 is the first with `Task#defer_stop`, which `Query#close` now relies on. `mcp` 0.20/0.21 fail every `tools/call` of a tool whose schema uses `$ref` into `$defs`. Only bundles pinned below these floors are affected. (#87)
+- **`config.default_options = {...}` stores a frozen deep copy.** Change defaults by assigning a new Hash; in-place mutation of the stored defaults (`config.default_options[:model] = 'x'`, `merge!`, including on the initial empty Hash) now raises `FrozenError`, and later changes to the Hash you passed have no effect. The snapshot's Strings are frozen too: a session built from configured defaults shares them, so reassign (`options.model = 'opus'`) rather than mutate in place. Your own Hash and objects, and identity-bearing values such as SDK MCP server instances, are never frozen. (#92)
+- **`rename_session_via_store` / `tag_session_via_store` raise `Errno::ENOENT` for a session the store has never seen** (`#load` returns nil or `[]`), like their disk counterparts and `fork_session_via_store`, instead of appending — and so creating — a phantom session that could never be deleted on append-only stores. Deliberately stricter than the Python SDK's store helpers. (#85)
+- **`exit`, `Interrupt` and signal exceptions raised inside an SDK MCP tool handler are reported in-band** as an `isError: true` result, so the `tools/call` control response is always written; previously they escaped dispatch (and in the default `:thread` scheduling `exit` tore down the session). Cancellation still propagates. A `callback_wrapper` now observes a `RuntimeError` whose `#cause` is the original exception. Hooks and `can_use_tool` are tracked in #119. (#77)
+- **Transcript mirror `eager` mode no longer guarantees one `SessionStore#append` per frame.** At most one background drain runs at a time; frames arriving while an append is in flight are coalesced, in order, into the next one (see Fixed, #84). Adapters must not assume one frame per call.
+- **Subagent readers only accept `agent_id`s matching `[A-Za-z0-9._-]+`** (never `.` or `..`); anything else returns `[]` / `nil` without calling the adapter, so a path- or prefix-keyed `SessionStore` can't be re-routed through the synthesized `subagents/agent-<agent_id>` subpath (now documented in the adapter contract). (#79)
+- **Blank session metadata reads the same on disk and in a store:** whitespace-only `git_branch` / `tag` are `nil` and a blank `cwd` falls back to the project path on the disk path too. (#67)
+- **S3 reference adapter (`examples/session_stores/s3_session_store.rb`)** reserves each part number through a per-transcript `.sequence` object with conditional writes, so appends stay ordered across adapter instances and clock skew. Requires an S3-compatible endpoint with strong consistency and conditional `PUT`; stop old writers before upgrading (mixed old/new writers are unsupported), and quiesce writers before deleting sessions. Each uncontended append costs two extra requests.
+- **`CLIInstaller`'s `VERSION` file records the target platform** (OS, architecture, libc) alongside version and checksum, and the offline shortcut requires all three to match, so a cache copied from another platform is reinstalled instead of trusted. Older one- or two-line metadata needs one online reinstall, then works offline again.
+- **SDK MCP servers reject a tool whose input schema declares a top-level `server_context` property** at registration (the `mcp` gem would silently overwrite it with its own context), and a call that passes one to a composed/referenced/free-form schema gets an actionable `isError` result without invoking the handler.
+- The transport's "Claude Code not found" guidance, `docs/cli-installer.md` and the skill references now point at `install_pinned` (interpolating the constant) instead of a hardcoded example version that went stale with every CLI release.
+- Docs, examples and the bundled `claude-agent-ruby` skill now use current model IDs (`claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5`) and recommend adaptive thinking plus `effort:`; `ThinkingConfigEnabled(budget_tokens:)` is described as the older-model path. `examples/extended_thinking_example.rb` no longer teaches the deprecated `max_thinking_tokens`. No API changes.
+
+### Fixed
+
+**Subprocess transport and teardown**
+- **A stdin write cancelled mid-frame now poisons the transport instead of corrupting the session.** An `Async::Stop`, inline cooperative timeout or deadline landing while a large frame was parked on a full pipe left `ready?` true, so the next frame was appended to the partial one and every later message was invalid JSON. The original cancellation still propagates; every later write raises `CLIConnectionError` ("possible partial frame"). Recovery is a new session. (#80)
+- **`close` and `end_input` no longer hang or strand a writer parked on a full stdin pipe.** A reactor fiber parked in the write is woken with the documented `CLIConnectionError`, and on Ruby 3.3+ a reactor-side close no longer hangs the whole reactor while a FiberBoundary worker thread is parked in the write. (#80)
+- **`read_messages` no longer waits forever for a CLI that closes stdout and then hangs.** After stdout EOF the SDK waits 5 s, then TERM, then KILL, and raises `ProcessError` ("did not exit within 5s of closing stdout", negative-signal `exit_code`). (#73)
+- **A truncated final stdout frame is reported** as `CLIJSONDecodeError` (`line` holds the partial frame) instead of the stream silently ending without its `ResultMessage`. Whitespace-only tails and reads cut short by `close` stay silent. (#89)
+- **`Client#disconnect` called from inside an inline control-request callback, or from a streaming-input enumerator, now finishes the teardown before the caller unwinds.** The callback's task belongs to the tree the close stops, and the cascading `Async::Stop` used to interrupt `Query#close` before the transport and the close watcher were closed (a bare `Query#close` leaked the CLI process). The stop is now deferred through the teardown; the caller then unwinds with `Async::Stop` (use `ensure`, not `rescue StandardError`). A teardown error superseded by that Stop is warned on stderr. `:thread` mode, message blocks and observers are unchanged: `disconnect` returns normally there. (#81)
+- **An outer `Async` timeout during `close` no longer makes the transport forget a still-live CLI process**: the timeout propagates and the TERM/KILL fallback keeps ownership. A cancelled close's background fallback releases the process from the at-exit registry only once it has actually been reaped.
+- **Control requests fail promptly when the stream ends**: a clean read EOF broadcasts a terminal error to every waiting control request (they used to sit out the 1200 s timeout), and requests issued after EOF are rejected before writing. A control request's serialization, write and wait now share one deadline and one cleanup scope, so a failed or cancelled send never leaks its waiter and backpressure can't block past the configured timeout.
+- **CLI stderr is scrubbed to valid UTF-8** for the `stderr` callback, `debug_stderr` and `ProcessError#stderr`, like stdout frames. (#90)
+- **CLI discovery no longer accepts a non-executable file at a well-known install location** — a stray 0644 `~/.claude/local/claude` now ends in `CLINotFoundError` with install instructions instead of a raw `Errno::EACCES` at spawn. (#72)
+- **Store-backed resume and CLI discovery work on hosts without a usable home directory** (`HOME` unset with no passwd entry, e.g. `docker --user` in a minimal image, or an empty/relative `HOME`): home-relative auth seeds and install locations are skipped instead of raising `ArgumentError`. `Sessions.config_dir` / `projects_dir` are tracked in #120. (#82)
+- **Sandbox settings merging resolves a relative settings file against the CLI's `cwd`**, not the Ruby process's working directory.
+- **`FiberBoundary` worker threads disable `report_on_exception` before the callback runs**, so a fast-failing callback is no longer also dumped to stderr. (#93)
+
+**Options and configuration**
+- **Typed option values are no longer shared by reference between sessions.** `SandboxSettings` (and its network/filesystem configs), `SystemPromptPreset` / `Custom` / `File`, `ToolsPreset`, `AgentDefinition`, `HookMatcher`, thinking configs, `TaskBudget`, `Mcp*ServerConfig` and `SdkPluginConfig` placed in `ClaudeAgentSDK.configure` defaults, or copied by `ClaudeAgentOptions#dup_with` (including values nested in `agents`, `hooks`, `mcp_servers`, `plugins`), are copied per instance via the new `Type#dup_for_options` hook — a per-session change to sandbox rules or a system prompt can no longer silently change what every other session sends to the CLI. Unfrozen Strings are copied too. Procs, observers and factories, SDK MCP server instances, session-store adapters and `callback_wrapper` keep their identity; CLI arguments are unchanged. (#69, #70)
+- **`Configuration#default_options` is no longer a live Hash read without synchronization**: request-time merges read a private frozen snapshot, so a concurrent in-place write can no longer raise `can't add a new key into hash during iteration` or tear a merge. (#92)
+- **String-keyed SDK MCP server configs are recognized** (`{ 'tools' => { 'type' => 'sdk', 'instance' => server } }`, and `type: :sdk`): the instance is registered in-process, stdin stays open for its tool calls, and it is never serialized into `--mcp-config`. (#68)
+- **`Client` normalizes input like `query()`**: a bare Hash prompt is rejected before anything is spawned (it used to stream Ruby inspection strings), and `nil` / empty hook lists are accepted instead of crashing `connect`.
+- **Class-valued shorthand tool schemas work**: the documented `{ id: Integer }` advertises and accepts an integer (it advertised a string and rejected integers); `Float`, `TrueClass` and `FalseClass` likewise.
+- **`ResultError`'s message and `#api_error_status` share one Integer narrowing**, so a non-Integer status (e.g. `"500"`) no longer appears as `API error (HTTP 500)` while the accessor returns `nil`. (#76)
+
+**Sessions and SessionStore**
+- **A single unserializable store entry no longer aborts a store-backed resume.** Entries (and subagent metadata sidecars) that JSON can't encode — NaN/Infinity, invalid UTF-8, circular or over-deep nesting — are skipped with a warning naming the entry's `uuid`; well-formed entries are written byte-for-byte as before. A session with no usable entries behaves like an empty one, and `--continue` classifies sidechains from the first surviving entry. (#83)
+- **Non-String subkeys from a `SessionStore` are rejected** like any other unsafe subkey instead of raising `NoMethodError` and aborting the resume. (#91)
+- **Store-backed listings coerce adapter `mtime` values** (ISO-8601 or numeric strings, e.g. SQL timestamps through JSON): they list newest first — they came back oldest first, so `limit:` cut off the newest sessions — and mixed Integer/String mtimes no longer raise. (#66)
+- **Session listings break equal-mtime ties by `session_id`**, so `offset:` / `limit:` pages are stable across calls and never skip or repeat sessions, and disk and store listings order identical input identically. (#78)
+- **Disk and store paths agree on sidechain classification and blank summaries**: a corrupt, blank, non-object or invalidly encoded first transcript line no longer makes one path list a session the other hides (the disk reader now classifies from the first parseable entry, as the store path did), and whitespace-only (or invalidly encoded) summaries/titles are blank on both. (#67, #75)
+- **Session read APIs validate ids at the boundary**: a non-String or invalidly encoded `session_id` / `agent_id` gets the same `nil` / `[]` as a malformed id (and `import_session_to_store` raises `ArgumentError`) instead of a deep `NoMethodError` / `ArgumentError`. (#74)
+- **The transcript mirror no longer piles up background tasks when the `SessionStore` is slower than the CLI's frame rate**: at most one drain task runs, and later frames are buffered and coalesced in order, without ever slowing the read loop. (#84)
+- **Rename and tag no longer corrupt a transcript whose last record lacks a trailing newline**: the metadata record is written on its own line.
+- **Forked sessions are published atomically**: the fork is written to a private temporary file and hard-linked into place, so a failed fork never leaves a partial session under its final id (filesystems without hard links fail safely).
+- **An explicitly cleared custom or AI title at the end of a long transcript stays cleared** on the disk path (it resurrected an older title from the file head).
+- **`InMemorySessionStore` deep-copies entries and summaries** across `append` / `load` / summary boundaries, so callers can no longer mutate stored transcripts through the objects they passed in or got back.
+- **The SessionStore conformance kit checks summary content** (latest title, first timestamp, first prompt, sidechain classification across appends and refolds), so an adapter returning empty or stale summaries now fails it.
+- Docs and the bundled skill describe what store-backed resume really seeds (`settings.json` / `cowork_settings.json` included since 0.31). (#86)
+
+**Observability**
+- **`OTelObserver` records per-turn cost increments** for `gen_ai.usage.cost` / `llm.cost.total`; the CLI reports cumulative `total_cost_usd`, so summing spans used to double-count earlier turns.
+- **OpenTelemetry parent context is preserved across the SDK's fibers and threads** (`query()` / `Client.open` reactors, Query's background tasks, FiberBoundary worker dispatch), so observer and callback spans attach to the caller's trace instead of starting detached.
+
+**Examples and tooling**
+- `examples/error_handling_example.rb`'s retry helper now retries what the SDK raises: `ResultError` only for transient API statuses (429, 529, other 5xx), then bare `ProcessError` with bounded backoff. (#88)
+- CI runs the suite against the newest allowed majors (json 3.x, mcp 1.x) and the declared dependency floors. The git-less gemspec fallback packages the same files git would; `docs/errors.md` lists `ResultError`; flaky ordering sleeps in specs are gone. (#87, #93)
+
 ## [0.33.1] - 2026-09-21
 
 Compatibility with `json` 3.x and `mcp` 1.x. Upgrade if your bundle resolves `json` 3.x — `rename_session` / `tag_session` raise on 0.33.0.

data/README.md

@@ -8,26 +8,28 @@
 [![Docs](https://img.shields.io/badge/docs-rubydoc.info-blue)](https://rubydoc.info/gems/claude-agent-sdk)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-A Ruby SDK for the [Claude Code](https://docs.claude.com/en/docs/claude-code-overview) agent runtime. Build AI agents, automate coding workflows, and integrate Claude into Rails and other Ruby applications with the same capabilities as the official [TypeScript](https://github.com/anthropics/claude-agent-sdk-typescript) and [Python](https://github.com/anthropics/claude-agent-sdk-python) SDKs.
+A Ruby SDK for the [Claude Code](https://docs.claude.com/en/docs/claude-code-overview) agent runtime, built for running agents in production Ruby and Rails apps. It has the same capabilities as the official [TypeScript](https://github.com/anthropics/claude-agent-sdk-typescript) and [Python](https://github.com/anthropics/claude-agent-sdk-python) SDKs, plus what a Rails deploy needs around them: a generator and CLI-vendoring rake task, callbacks that are safe to touch ActiveRecord from, a pinned CLI binary, built-in OpenTelemetry tracing, and transcript mirroring to your own storage.
 
 > **Unofficial and community-maintained.** This project is not affiliated with or supported by Anthropic. It tracks the official SDKs release by release; see the [CHANGELOG](CHANGELOG.md) for the currently synced version.
 
 ## Highlights
 
+- **Rails integration.** `bin/rails generate claude_agent_sdk:install` writes the initializer and `bin/rails claude_agent_sdk:install_cli` vendors the CLI; [docs/rails.md](docs/rails.md) covers jobs, ActionCable streaming, session resumption, and solid_queue fiber workers (`callback_scheduling: :inline`).
+- **Callbacks that are safe around ActiveRecord.** Tool handlers, hooks, permission callbacks, and message blocks run on a plain thread by default, outside the SDK's fiber scheduler, so thread-keyed libraries (ActiveRecord, `pg`, per-thread caches) behave as they do everywhere else in your app. `ClaudeAgentSDK::Railtie.callback_wrapper` runs them in the Rails executor so connections go back to the pool, without deadlocking development code reloading.
+- **Hermetic deploys.** `CLIInstaller` vendors a checksum-verified CLI binary, pinned to the version each gem release is tested with, so production never depends on a global `npm install`.
+- **Built-in OpenTelemetry observer** with Langfuse support; no third-party instrumentation library required.
+- **Transcript mirroring.** A `SessionStore` adapter mirrors session transcripts to your own storage (reference adapters for Postgres, Redis, and S3, plus a conformance suite), and sessions can be resumed from it on another host.
 - **Same wire protocol as the official SDKs.** Spawns the `claude` CLI as a subprocess and speaks stream-JSON over stdin/stdout, so every feature of the runtime is available: sessions, subagents, sandboxing, structured output, file checkpointing and rewind.
 - **`query()` for one-shot calls, `Client` for bidirectional sessions** with interrupts, mid-session model switching, and streaming input from any `Enumerator`.
 - **In-process custom tools.** Define tools as Ruby blocks; they run inside your process with direct access to your app state (SDK MCP servers), with JSON-Schema-validated arguments.
 - **All 27 hook events and permission callbacks** with typed inputs, so you can gate, audit, or rewrite every tool call.
-- **Rails-ready.** Fiber-safe callback dispatch, an initializer-style `configure` block, ActionCable streaming, background-job session resumption, and a `callback_scheduling: :inline` mode for fiber workers.
-- **Built-in OpenTelemetry observer** with Langfuse support; no third-party instrumentation library required.
 - **Pluggable transport** to run the CLI somewhere else (an E2B microVM, a container, over SSH).
-- **Hermetic deploys.** `CLIInstaller` vendors a checksum-verified, pinned CLI binary into your project so production never depends on a global `npm install`.
 
 ## Installation
 
 ```ruby
 # Gemfile
-gem 'claude-agent-sdk', '~> 0.33.1'
+gem 'claude-agent-sdk', '~> 0.35.0'
 ```
 
 Then `bundle install`, or install directly with `gem install claude-agent-sdk`. To track unreleased changes, point the Gemfile at GitHub: `gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'`.
@@ -44,6 +46,30 @@ ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')  # => "/app/vendor/clau
 
 The vendored binary is found ahead of `PATH`, installs are idempotent and concurrency-safe, and a failed upgrade never breaks a working install. See [docs/cli-installer.md](docs/cli-installer.md) for the full behaviour, supported platforms, and the CLI discovery order.
 
+### Rails in a minute
+
+```bash
+bundle add claude-agent-sdk
+bin/rails generate claude_agent_sdk:install   # config/initializers/claude_agent_sdk.rb + .gitignore entry
+bin/rails claude_agent_sdk:install_cli        # the tested CLI into vendor/claude (also a Docker build step)
+```
+
+```ruby
+# app/jobs/summarize_ticket_job.rb
+class SummarizeTicketJob < ApplicationJob
+  def perform(ticket)
+    options = ClaudeAgentSDK::ClaudeAgentOptions.new(tools: [], max_turns: 1)
+    prompt = "Summarize this support ticket in two sentences:\n\n#{ticket.body}"
+
+    ClaudeAgentSDK.query(prompt: prompt, options: options) do |message|
+      ticket.update!(summary: message.result) if message.is_a?(ClaudeAgentSDK::ResultMessage)
+    end
+  end
+end
+```
+
+The block runs on a plain thread, so ActiveRecord calls inside it just work. [docs/rails.md](docs/rails.md) continues with multi-turn sessions, ActionCable streaming, and fiber workers.
+
 ## Quick Start
 
 ```ruby
@@ -84,23 +110,31 @@ end
 
 ### `Client` — bidirectional sessions
 
-`Client` keeps a session open so you can send follow-up queries, interrupt, switch models, and use hooks, permission callbacks, and custom tools. It runs inside an [`async`](https://github.com/socketry/async) block; blocking calls yield automatically, no `await` needed.
+`Client` keeps a session open so you can send follow-up queries, interrupt, switch models, and use hooks, permission callbacks, and custom tools. `Client.open` connects, yields the client, and always disconnects when the block exits, even on an exception. It returns the block's value.
 
 ```ruby
 require 'claude_agent_sdk'
-require 'async'
 
-Async do
-  client = ClaudeAgentSDK::Client.new
+ClaudeAgentSDK::Client.open do |client|
+  client.query("What is the capital of France?")
+  client.receive_response { |msg| puts msg }
 
-  begin
-    client.connect
-    client.query("What is the capital of France?")
-    client.receive_response { |msg| puts msg }
-  ensure
-    client.disconnect
-  end
-end.wait
+  client.query("And of Germany?")
+  client.receive_response { |msg| puts msg }
+end
+```
+
+`Client.open` creates an [`async`](https://github.com/socketry/async) reactor when there isn't one; blocking calls yield automatically, no `await` needed. Called outside a reactor, `break` inside the block raises `LocalJumpError` (the client still disconnects), so return a value instead. Code that is already running inside an `Async` reactor can also manage the lifecycle by hand:
+
+```ruby
+client = ClaudeAgentSDK::Client.new
+begin
+  client.connect
+  client.query("What is the capital of France?")
+  client.receive_response { |msg| puts msg }
+ensure
+  client.disconnect
+end
 ```
 
 See [docs/client.md](docs/client.md) for `interrupt`, mid-session model and permission switching, MCP status, and custom transports.
@@ -148,7 +182,7 @@ See [docs/hooks-and-permissions.md](docs/hooks-and-permissions.md) for the full
 | Session listing, reading, renaming, tagging, forking, resume-at-message | [docs/sessions.md](docs/sessions.md) |
 | Subagent capabilities, event contracts, and minimal example | [docs/subagents.md](docs/subagents.md) |
 | OpenTelemetry tracing, Langfuse, custom observers | [docs/observability.md](docs/observability.md) |
-| Rails: fiber safety, solid_queue fiber workers, ActionCable, jobs, initializer | [docs/rails.md](docs/rails.md) |
+| Rails: generator, `install_cli` task, callback wrapper, fiber safety, solid_queue fiber workers, ActionCable, jobs | [docs/rails.md](docs/rails.md) |
 | Vendoring a pinned CLI binary and CLI discovery order | [docs/cli-installer.md](docs/cli-installer.md) |
 | Message, content block, and configuration type reference | [docs/types.md](docs/types.md) |
 | Error handling, exception hierarchy, timeouts | [docs/errors.md](docs/errors.md) |
@@ -210,9 +244,10 @@ bundle install
 bundle exec rspec                    # unit suite
 bundle exec rubocop                  # lint
 RUN_INTEGRATION=1 bundle exec rspec  # also run the real-CLI integration suite (needs `claude` and ANTHROPIC_API_KEY)
+BUNDLE_GEMFILE=gemfiles/rails_8.gemfile bundle exec rspec --options spec/rails/.rspec  # Rails integration specs
 ```
 
-CI runs the suite and RuboCop on Ruby 3.2, 3.3, and 3.4. See [spec/README.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/spec/README.md) for the test layout.
+CI runs the suite and RuboCop on Ruby 3.2, 3.3, and 3.4, and the Rails specs against Rails 7.1 and 8. See [spec/README.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/spec/README.md) for the test layout.
 
 ## Contributing
 

data/docs/cli-installer.md

@@ -7,11 +7,18 @@ The SDK runs the `claude` CLI as a subprocess, so a deploy is only reproducible
 ```ruby
 require 'claude_agent_sdk'
 
-# 'stable' (default), 'latest', or a concrete version — pin it in production.
-ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')
+# Install the CLI version this gem release was tested against
+# (CLIInstaller::PINNED_CLI_VERSION) — recommended: bumping the gem
+# then carries the CLI forward with it, e.g. via Dependabot.
+ClaudeAgentSDK::CLIInstaller.install_pinned
 # => "/app/vendor/claude/claude"
 
-ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220', dir: '/opt/claude')
+# Or pin a concrete version of your own:
+ClaudeAgentSDK::CLIInstaller.install(version: 'x.y.z', dir: '/opt/claude')
+
+# 'stable' (the default) and 'latest' are floating dist-tags, not pins:
+# they re-resolve on every call, so a rebuild may install a newer CLI.
+ClaudeAgentSDK::CLIInstaller.install(version: 'stable')
 
 # nil unless a binary is already installed there
 ClaudeAgentSDK::CLIInstaller.installed_path
@@ -19,7 +26,7 @@ ClaudeAgentSDK::CLIInstaller.installed_path
 
 `install` is idempotent and safe to run concurrently, so it fits `bin/setup`, a cached Docker layer, and every process of a multi-process boot:
 
-- The install directory's `VERSION` file records the installed version **and** the SHA-256 that was verified at download time. The shortcut re-hashes the vendored binary (~0.1s for the real 245MB binary) and only skips the download when both match — a truncated, swapped or half-written binary is reinstalled instead of trusted. It makes **no network request**, so repeat boots work offline — with a pinned concrete version; `'stable'`/`'latest'` must always re-resolve through the endpoint, which is one more reason to pin in production.
+- The install directory's `VERSION` file records the installed version, verified SHA-256, and target platform (OS, architecture, libc). The shortcut re-hashes the vendored binary (~0.1s for the real 245MB binary) and only skips the download when all three match — a truncated binary or a cache copied from another platform is reinstalled instead of trusted. It makes **no network request**, so same-platform repeat boots work offline — with a pinned concrete version; `'stable'`/`'latest'` must always re-resolve through the endpoint, which is one more reason to pin in production. Older one- or two-line metadata lacks a platform and requires one online reinstall to migrate; subsequent pinned installs work offline again.
 - An exclusive `flock` on `<dir>/.install.lock` covers the whole check → download → place → record sequence, so parallel installs into one directory don't race; the loser simply observes the finished install.
 
 Failures (unsupported platform, invalid version, HTTP error, response-size cap, oversized download, checksum mismatch, filesystem errors) raise `ClaudeAgentSDK::CLIInstallError`.
@@ -31,18 +38,42 @@ Failures (unsupported platform, invalid version, HTTP error, response-size cap,
 ## Docker and `bin/setup`
 
 ```dockerfile
-# Dockerfile — pin the CLI in its own cached layer
+# Dockerfile — the gem's pinned CLI version in its own cached layer
 RUN bundle exec ruby -e "require 'claude_agent_sdk'; \
-    ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')"
+    ClaudeAgentSDK::CLIInstaller.install_pinned"
 ```
 
 ```ruby
 #!/usr/bin/env ruby
-# bin/setup
+# bin/setup — gem's pin by default, overridable per developer
 require 'claude_agent_sdk'
-puts ClaudeAgentSDK::CLIInstaller.install(version: ENV.fetch('CLAUDE_CLI_VERSION', 'stable'))
+version = ENV.fetch('CLAUDE_CLI_VERSION', ClaudeAgentSDK::CLIInstaller::PINNED_CLI_VERSION)
+puts ClaudeAgentSDK::CLIInstaller.install(version: version)
 ```
 
+## Rake task
+
+Rails apps get `claude_agent_sdk:install_cli` from the gem's Railtie; any other project can load it from its `Rakefile`:
+
+```ruby
+# Rakefile (non-Rails)
+require 'claude_agent_sdk/tasks'   # loads only CLIInstaller, not the whole SDK
+```
+
+```bash
+bin/rails claude_agent_sdk:install_cli                 # Rails: installs PINNED_CLI_VERSION into Rails.root/vendor/claude
+rake claude_agent_sdk:install_cli                      # elsewhere: into vendor/claude under the working directory
+rake claude_agent_sdk:install_cli CLAUDE_CLI_VERSION=x.y.z   # a version of your own, or 'stable' / 'latest'
+```
+
+The task calls `install_pinned` (or `install(version:)` when `CLAUDE_CLI_VERSION` is set — the same variable the `bin/setup` example above reads), prints the installed path, and doesn't boot the Rails app, so it runs in a Docker build without a database or credentials:
+
+```dockerfile
+RUN bin/rails claude_agent_sdk:install_cli
+```
+
+The variable is deliberately not rake's conventional `VERSION`, which Rails' `db:migrate` uses and build environments often export for an app version or git SHA. An empty `CLAUDE_CLI_VERSION` means the gem's pin.
+
 ## Supported platforms
 
 `darwin-arm64`, `darwin-x64` (Rosetta 2 gets the arm64 build), `linux-x64`, `linux-arm64`, and the `-musl` variants. Windows is not supported.
@@ -54,4 +85,4 @@ With no explicit `cli_path:` in `ClaudeAgentOptions`, the transport probes in th
 1. `CLAUDE_CLI_PATH` — an explicit path to an executable, no discovery at all (a relative value is resolved against the process's working directory, not `cwd:`)
 2. The vendored binary (`CLIInstaller.installed_path`) — deliberately ahead of `PATH`, so a pinned install beats whatever is installed globally
 3. `which claude`
-4. Common install locations (`~/.claude/local/claude`, `/usr/local/bin/claude`, …)
+4. Common install locations (`~/.claude/local/claude`, `/usr/local/bin/claude`, …) — only an executable regular file counts, and the `~` ones are skipped when there is no usable home directory (HOME unset with no passwd entry, or a non-absolute HOME)

data/docs/client.md

@@ -4,29 +4,38 @@
 
 ## Basic Usage
 
+`Client.open` connects, yields the client, and always disconnects when the block exits (exceptions propagate after the disconnect). It returns the block's value, and creates an `async` reactor if it isn't already running inside one.
+
 ```ruby
 require 'claude_agent_sdk'
-require 'async'
 
-Async do
-  client = ClaudeAgentSDK::Client.new
+ClaudeAgentSDK::Client.open do |client|
+  client.query("What is the capital of France?")
 
-  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
+  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
-  ensure
-    client.disconnect
   end
-end.wait
+end
+```
+
+Called outside a reactor, `break` inside the `Client.open` block raises `LocalJumpError` (the client still disconnects), so return a value from the block instead. `break` inside `receive_response` / `receive_messages` is fine. It stops the iteration.
+
+If your code already runs inside an `Async` reactor and you want to manage the connection yourself, call `connect` and `disconnect` directly:
+
+```ruby
+client = ClaudeAgentSDK::Client.new
+begin
+  client.connect
+  client.query("What is the capital of France?")
+  client.receive_response { |msg| puts msg }
+ensure
+  client.disconnect
+end
 ```
 
 ## Advanced Features
@@ -38,7 +47,7 @@ Async do
 
   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
+  client.set_model('claude-sonnet-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

data/docs/configuration.md

@@ -58,7 +58,7 @@ Use the `effort` option to control the model's effort level:
 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`).
+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 later models, 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 (e.g. 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`.
 
@@ -119,8 +119,8 @@ See [examples/budget_control_example.rb](https://github.com/ya-luotao/claude-age
 
 ```ruby
 options = ClaudeAgentSDK::ClaudeAgentOptions.new(
-  model: 'claude-sonnet-4-20250514',
-  fallback_model: 'claude-3-5-haiku-20241022'
+  model: 'claude-sonnet-5',
+  fallback_model: 'claude-haiku-4-5'
 )
 ```
 
@@ -135,8 +135,8 @@ receives the full conversation.
 
 ```ruby
 options = ClaudeAgentSDK::ClaudeAgentOptions.new(
-  model: 'haiku',
-  advisor_model: 'opus'  # alias or full model ID, e.g. 'claude-opus-4-8'
+  model: 'claude-haiku-4-5',
+  advisor_model: 'claude-opus-5'  # full model ID, or an alias such as 'opus'
 )
 ```
 

data/docs/errors.md

@@ -138,11 +138,12 @@ end
 | Error | Description |
 |-------|-------------|
 | `ClaudeSDKError` | Base error for all SDK errors |
-| `CLIConnectionError` | Connection issues |
+| `CLIConnectionError` | Connection issues — including every write after a stdin write was cancelled mid-frame (the connection is unusable from then on — reconnect) |
 | `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 |
+| `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 |
+| `ResultError` | Run ended on a terminal error result (subclasses `ProcessError`; adds `subtype`, `errors`, `api_error_status`, `terminal_reason`, ...) — rescue it first |
+| `CLIJSONDecodeError` | JSON parsing issues — including stdout ending mid-frame (a truncated final message; `line` holds the partial frame) |
 | `MessageParseError` | Message parsing issues |
 
 See [lib/claude_agent_sdk/errors.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/lib/claude_agent_sdk/errors.rb) for all error types.

data/docs/mcp-servers.md

@@ -41,6 +41,17 @@ end.wait
 
 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:
 
+**Reserved argument name:** do not use `server_context` as a top-level tool
+argument. The underlying MCP gem uses that keyword for injected request context
+and would overwrite the user value before your handler runs. Registering a tool
+whose root `properties` declare it raises `ArgumentError`, for both shorthand and
+pre-built schemas (including directly constructed `SdkMcpTool` objects). For
+composed, referenced, or free-form schemas, actual MCP calls containing this
+top-level key return an actionable `isError: true` tool result before the handler
+runs. This runtime guard remains active even if schema validation falls back to
+a permissive schema. Rename the argument to something like `request_context`.
+Nested object properties named `server_context` are safe and remain supported.
+
 ```ruby
 # Symbol keys (standard Ruby)
 ClaudeAgentSDK.create_tool('save', 'Save a fact', {
@@ -92,6 +103,12 @@ 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.
+This includes `exit`, `Interrupt` and other signal exceptions: they are reported
+the same way instead of escaping the session and leaving the CLI waiting on the
+tool call. Cancellation of the tool call itself still propagates.
+
 ## Mixed Server Support
 
 You can use both SDK and external MCP servers together:
@@ -108,6 +125,11 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 )
 ```
 
+A hand-written SDK entry may use String or Symbol keys:
+`{ 'type' => 'sdk', 'name' => 'calc', 'instance' => server }` behaves exactly like
+the Hash `create_sdk_mcp_server` returns. The instance is registered in-process
+and is never sent to the CLI.
+
 ## MCP Resources and Prompts
 
 SDK MCP servers can also expose **resources** (data sources) and **prompts** (reusable templates):

data/docs/observability.md

@@ -6,6 +6,8 @@ The SDK includes a built-in **observer interface** and an **OpenTelemetry observ
 
 When `connect` spawns the CLI and there is an active OTel span, the SDK injects `TRACEPARENT`/`TRACESTATE` (and any other propagator carrier keys, e.g. `BAGGAGE` — which may carry user-defined key/values — uppercased) into the subprocess environment so CLI-side telemetry (`CLAUDE_CODE_ENABLE_TELEMETRY=1`) joins the caller's distributed trace. This requires the `opentelemetry` gem to be loaded with a configured propagator — there is no hard dependency, and it is a no-op otherwise. Explicit `ClaudeAgentOptions#env` keys always win; stale inherited `TRACEPARENT`/`TRACESTATE` is replaced (or unset) only when an active span supersedes it. This works independently of `OTelObserver`: the CLI parents under the caller's surrounding span, not under `claude_agent.session` (which starts at InitMessage, after spawn).
 
+The SDK also carries the active OTel context (including baggage) into the reactor fibers created by `query()` and standalone `Client.open`, their background input/control tasks, and callback worker-thread hops. `OTelObserver` session spans therefore keep the surrounding caller span as their parent in both default `:thread` and opt-in `:inline` mode. For `Client`, keep the intended parent active while connecting and receiving messages: background control callbacks inherit the connection's context, while message observers use the receiving operation's context. Context is captured per operation/task, not when an observer is constructed, so sequential observer reuse does not retain an earlier caller's parent. This uses OTel's scoped context API only when loaded; it does not copy application thread-local state or change callback scheduling.
+
 ## How It Works
 
 Register observers via `ClaudeAgentOptions`. The SDK calls `on_user_prompt` when a prompt is sent — the verbatim string for String prompts (`query()` / `Client#query`), and once per `type: 'user'` message with extractable text for Enumerator/streaming input (`query()` stream path and `Client#connect` with an initial enumerable). It calls `on_message` for every parsed message, `on_error` once per error that surfaces to your code (before `on_close` where both fire), and `on_close` when the session ends. Observer errors are silently rescued so they never crash your application.
@@ -116,6 +118,10 @@ The OTel observer sets attributes using both `gen_ai.*` (OTel GenAI) and OpenInf
 | `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` |
 
+`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.
 
 The `langfuse.observation.type` attribute is set on each span (`agent`/`generation`/`tool`) to enable Langfuse's **trace flow diagram** (DAG graph visualization).