claude-agent-sdk 0.34.0 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff96202bf91fc547d93ae77a7b022fb83a0651574fcb1aae5e521531e33ea9e7
-  data.tar.gz: 6956e7943d0856d9ac5975a7ba01e779159df1193301199dc0f082bf80835d88
+  metadata.gz: a2976dae089e4ccc32b7974b646cb9e543c4dcdfd6bfb35eeccf6b3c4ef5e6ed
+  data.tar.gz: 89ec51407ce6f25c962982078b3fe8301bfda9be4e57bf4a03593e9818d5913a
 SHA512:
-  metadata.gz: 9e64d2bf6a83ae79b2f77007baad0d9ff340e4ff0b264d1acc066660860e57e329af84406bc041d39af73c1030afebf96d9f2a7894038354fdf6ce9847447e6c
-  data.tar.gz: 8e0e4e08914e30d812094a7a7cbfe4c0f128f7f83b3856a5947149b84566fd9ec72c8c9c3477778e3c196aba6694fb3524e84b3d4d1c1a919f1683aa545a271a
+  metadata.gz: 4784c6381acbfedd9a921a852329dfdd64257aa60b25bf51b0f4278b5fe6ce4913b1f719941a0fece9ac818342e5129c0ffd481159bf731ee6930ecf4902b632
+  data.tar.gz: cee7e96d3ef502138189a114716db3862d10d2ff10411e04bf0db8bc654511c547397164c7640c590eed166d11556c26b5d4e6de744f3a6ac396cdb15e40bad3

data/CHANGELOG.md

@@ -7,6 +7,29 @@ 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.

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.34.0'
+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

@@ -51,6 +51,29 @@ version = ENV.fetch('CLAUDE_CLI_VERSION', ClaudeAgentSDK::CLIInstaller::PINNED_C
 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.

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

data/docs/rails.md

@@ -1,6 +1,49 @@
 # Rails Integration
 
-The SDK integrates well with Rails applications. Below are the common patterns.
+The gem ships a Railtie, an install generator and a rake task for vendoring the CLI; the rest of this page covers how SDK callbacks interact with Rails' threading, executor and fiber workers, and the common job / ActionCable patterns.
+
+## Getting started
+
+1. Add the gem:
+
+   ```bash
+   bundle add claude-agent-sdk
+   ```
+
+2. Generate the initializer:
+
+   ```bash
+   bin/rails generate claude_agent_sdk:install
+   ```
+
+   This writes `config/initializers/claude_agent_sdk.rb` — a `ClaudeAgentSDK.configure` block with commented defaults (model, permission mode, CLI path, OpenTelemetry) and the Rails callback wrapper [described below](#rails-executor-around-callbacks-callback_wrapper) switched on — and adds `/vendor/claude/` to `.gitignore`.
+
+3. Vendor the Claude Code CLI:
+
+   ```bash
+   bin/rails claude_agent_sdk:install_cli                  # the version this gem release is tested with
+   bin/rails claude_agent_sdk:install_cli CLAUDE_CLI_VERSION=x.y.z    # or a version of your own ('stable' / 'latest' float)
+   ```
+
+   The binary lands in `Rails.root/vendor/claude`, where the SDK finds it ahead of any `claude` on `PATH` whenever the process runs from the app root, as `bin/rails`, Puma and most job runners do (otherwise set `cli_path:`; the initializer has it commented). The task does not boot the app (no database or credentials needed), so the same line works as a cached Docker build step: `RUN bin/rails claude_agent_sdk:install_cli`. Installs are checksum-verified and idempotent — see [docs/cli-installer.md](cli-installer.md). The CLI authenticates from the environment, e.g. `ANTHROPIC_API_KEY`.
+
+4. Run an agent from a job:
+
+   ```ruby
+   # app/jobs/summarize_ticket_job.rb
+   class SummarizeTicketJob < ApplicationJob
+     def perform(ticket)
+       options = ClaudeAgentSDK::ClaudeAgentOptions.new(tools: [], max_turns: 1)  # text only, no built-in tools
+       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 (see the next section), so ActiveRecord calls inside it just work. For multi-turn sessions, hooks, custom tools and interrupts use `ClaudeAgentSDK::Client.open` — see [ActionCable streaming](#actioncable-streaming) below.
 
 ## Thread-keyed libraries are safe inside SDK callbacks
 
@@ -23,17 +66,25 @@ The trade-off: because callbacks run on a plain thread rather than inside an `As
 
 ### Rails executor around callbacks: `callback_wrapper`
 
-One consequence of the thread hop: an ActiveRecord connection implicitly checked out inside a callback belongs to that throwaway thread and stays stranded until the pool reaper reclaims it. Rails' own answer to "code running on a thread Rails didn't create" is the executor — and `callback_wrapper` lets you install it around every user-callback dispatch:
+One consequence of the thread hop: an ActiveRecord connection implicitly checked out inside a callback belongs to that throwaway thread and stays stranded until the pool reaper reclaims it. Rails' own answer to "code running on a thread Rails didn't create" is the executor — and `callback_wrapper` lets you install it around every user-callback dispatch. Use the SDK's Rails-aware wrapper (the generated initializer already does):
 
 ```ruby
 ClaudeAgentSDK.configure do |config|
   config.default_options = {
-    callback_wrapper: ->(invocation) { Rails.application.executor.wrap { invocation.call } }
+    callback_wrapper: ClaudeAgentSDK::Railtie.callback_wrapper
   }
 end
 ```
 
-The wrapper is a callable receiving a zero-arg `invocation`; it must call it and return its value. It runs on the **same execution context as the callback** — inside the worker thread in `:thread` mode, which is the whole point: `executor.wrap` runs on the thread that touches ActiveRecord, so connections check back in when the callback ends. Exceptions from the callback propagate through the wrapper unchanged (don't rescue them); `ensure`-based wrappers like `executor.wrap` are safe, including around a `break` from a message block. Beyond the executor, this is a generic hook for APM span propagation, `CurrentAttributes`/logging context, etc.
+It runs each callback inside `Rails.application.executor.wrap` — except where that would deadlock, which is why it replaces the bare `->(invocation) { Rails.application.executor.wrap { invocation.call } }` this guide used to recommend:
+
+- **Development (code reloading enabled).** Every executor then holds a share of the code-reload interlock. The request or job calling the SDK is already inside the executor, and in `:thread` mode it waits for the callback's thread. If a reload is requested meanwhile (say, another request arrives after the agent edited an app file), the reloader queues for the exclusive unload lock, and a callback thread entering `executor.wrap` queues behind it for a fresh share — which the reloader can never let through while the waiting caller holds its own. Everything hangs. The helper instead runs the callback without entering the executor (the caller's share still keeps code from being unloaded under it) and returns the thread's ActiveRecord connections to the pool when the callback finishes. The executor's other per-run hooks (query cache, `CurrentAttributes` reset) do not run for callbacks in this case.
+- **`config.allow_concurrency = false`.** The executor holds a process-wide monitor that the calling thread already owns, so a callback thread's `executor.wrap` would block every time; same treatment.
+- **Already inside the executor** (`:inline` scheduling on a job's own fiber): the callback runs straight through, leaving cleanup to the enclosing executor.
+
+Everywhere else — production, with no reloading — it is exactly `executor.wrap`. The configuration is read per call, so one initializer is correct in every environment.
+
+Writing your own wrapper: it is a callable receiving a zero-arg `invocation`; it must call it and return its value. It runs on the **same execution context as the callback** — inside the worker thread in `:thread` mode, which is the whole point: `executor.wrap` runs on the thread that touches ActiveRecord, so connections check back in when the callback ends. Exceptions from the callback propagate through the wrapper unchanged (don't rescue them); `ensure`-based wrappers like `executor.wrap` are safe, including around a `break` from a message block. Beyond the executor, this is a generic hook for APM span propagation, `CurrentAttributes`/logging context, etc. — to combine one with the Rails wrapper, call it from yours: `rails = ClaudeAgentSDK::Railtie.callback_wrapper` then `->(inv) { MyApm.trace { rails.call(inv) } }`.
 
 The wrapper also composes around every timeout-bounded `SessionStore` adapter call (mirror-batcher appends, resume-materialization loads and listings), inside the timeout bound — so an ActiveRecord-backed store adapter gets the same connection hygiene as your callbacks.
 
@@ -96,38 +147,33 @@ class ChatAgentJob < ApplicationJob
   queue_as :claude_agents
 
   def perform(chat_id, message_content)
-    Async do
-      options = ClaudeAgentSDK::ClaudeAgentOptions.new(
-        system_prompt: { type: 'preset', preset: 'claude_code' },
-        permission_mode: 'bypassPermissions'
-      )
+    options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+      system_prompt: { type: 'preset', preset: 'claude_code' },
+      permission_mode: 'bypassPermissions'
+    )
 
-      client = ClaudeAgentSDK::Client.new(options: options)
-
-      begin
-        client.connect
-        client.query(message_content)
-
-        client.receive_response do |message|
-          case message
-          when ClaudeAgentSDK::AssistantMessage
-            ChatChannel.broadcast_to(chat_id, { type: 'chunk', content: message.text })
-          when ClaudeAgentSDK::ResultMessage
-            ChatChannel.broadcast_to(chat_id, {
-              type: 'complete',
-              content: message.result,
-              cost: message.total_cost_usd
-            })
-          end
+    ClaudeAgentSDK::Client.open(options: options) do |client|
+      client.query(message_content)
+
+      client.receive_response do |message|
+        case message
+        when ClaudeAgentSDK::AssistantMessage
+          ChatChannel.broadcast_to(chat_id, { type: 'chunk', content: message.text })
+        when ClaudeAgentSDK::ResultMessage
+          ChatChannel.broadcast_to(chat_id, {
+            type: 'complete',
+            content: message.result,
+            cost: message.total_cost_usd
+          })
         end
-      ensure
-        client.disconnect
       end
-    end.wait
+    end
   end
 end
 ```
 
+`Client.open` connects, yields the client, and always disconnects — also when the block raises, so the job's error handling sees the original exception. It runs inside an existing reactor or starts its own, so a job needs no `Async { }.wait` wrapper. Its return value is the block's; to leave the block early use `next`, not `break` (outside an `Async` block, `break` raises `LocalJumpError`, though the session is still torn down). `break` inside `receive_response` itself is fine.
+
 ## Session Resumption
 
 Persist Claude sessions for multi-turn conversations:
@@ -138,19 +184,13 @@ class ChatSession < ApplicationRecord
   # Columns: id, claude_session_id, user_id, created_at, updated_at
 
   def send_message(content)
-    options = build_options
-    client = ClaudeAgentSDK::Client.new(options: options)
-
-    Async do
-      client.connect
-      client.query(content, session_id: claude_session_id ? nil : generate_session_id)
+    ClaudeAgentSDK::Client.open(options: build_options) do |client|
+      client.query(content)
 
       client.receive_response do |message|
         update!(claude_session_id: message.session_id) if message.is_a?(ClaudeAgentSDK::ResultMessage)
       end
-    ensure
-      client.disconnect
-    end.wait
+    end
   end
 
   private
@@ -160,13 +200,11 @@ class ChatSession < ApplicationRecord
     opts[:resume] = claude_session_id if claude_session_id.present?
     ClaudeAgentSDK::ClaudeAgentOptions.new(**opts)
   end
-
-  def generate_session_id
-    "chat_#{id}_#{Time.current.to_i}"
-  end
 end
 ```
 
+The first message starts a new session; every later one resumes it by the ID the previous `ResultMessage` reported.
+
 ## Background Jobs with Error Handling
 
 ```ruby
@@ -176,17 +214,17 @@ class ClaudeAgentJob < ApplicationJob
 
   def perform(task_id)
     task = Task.find(task_id)
-    Async { execute_agent(task) }.wait
+
+    ClaudeAgentSDK::Client.open(options: ClaudeAgentSDK::ClaudeAgentOptions.new(max_turns: 10)) do |client|
+      client.query(task.prompt)
+      client.receive_response do |message|
+        task.update!(status: 'done', result: message.result) if message.is_a?(ClaudeAgentSDK::ResultMessage)
+      end
+    end
   rescue ClaudeAgentSDK::CLINotFoundError
-    task.update!(status: 'failed', error: 'Claude CLI not installed')
+    task.update!(status: 'failed', error: 'Claude CLI not installed (bin/rails claude_agent_sdk:install_cli)')
     raise
   end
-
-  private
-
-  def execute_agent(task)
-    # ... agent execution
-  end
 end
 ```
 
@@ -250,7 +288,8 @@ ClaudeAgentSDK.configure do |config|
       # 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 }
-    ] : []
+    ] : [],
+    callback_wrapper: ClaudeAgentSDK::Railtie.callback_wrapper
   }
 end
 ```

data/lib/claude_agent_sdk/railtie.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ClaudeAgentSDK
+  # Rails integration. Loaded by lib/claude_agent_sdk.rb only when
+  # Rails::Railtie is already defined (Bundler.require runs after
+  # `require 'rails'`), so non-Rails processes never see it.
+  #
+  # Deliberately minimal: it contributes the `claude_agent_sdk:*` rake tasks
+  # and nothing else. It installs nothing into callback dispatch — the
+  # generated initializer (`bin/rails g claude_agent_sdk:install`) opts in
+  # to {.callback_wrapper} explicitly, where it is visible and removable.
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load File.expand_path('tasks/claude_agent_sdk.rake', __dir__)
+    end
+
+    # A `callback_wrapper` (see ClaudeAgentOptions#callback_wrapper) that
+    # gives SDK callbacks Rails' connection hygiene without deadlocking
+    # development code reloading.
+    #
+    # The obvious wrapper, `->(inv) { Rails.application.executor.wrap { inv.call } }`,
+    # deadlocks whenever the executor carries a process-wide lock:
+    #
+    # - With code reloading enabled, every executor holds a share of the
+    #   ActiveSupport::Dependencies interlock. In the default `:thread`
+    #   scheduling the request/job thread (already inside the executor, so
+    #   already holding a share) blocks on the FiberBoundary thread running
+    #   the callback. If a reload starts meanwhile (another request after the
+    #   agent edited an app file), the reloader queues for the exclusive
+    #   unload lock, and the callback thread's own `executor.wrap` then waits
+    #   behind it for a new share — which the reloader can never get while
+    #   the parent's share is held. Three-way deadlock.
+    # - With `config.allow_concurrency = false`, the executor holds a
+    #   process-wide monitor that the parent thread already owns, so the
+    #   callback thread's `executor.wrap` blocks every time.
+    #
+    # So, per invocation:
+    #
+    # 1. Executor already active on this execution context (`:inline`
+    #    scheduling, or a callback running on the caller's own thread) —
+    #    call straight through; the enclosing executor already owns cleanup.
+    # 2. Executor carries a lock (the two cases above, mirroring railties'
+    #    `configure_executor_for_concurrency`) — call WITHOUT entering the
+    #    executor, then return this thread's ActiveRecord connections to the
+    #    pool. The caller's executor still covers the callback: its share of
+    #    the interlock keeps a reload from unloading code under it until the
+    #    whole SDK call returns.
+    # 3. Otherwise (production: no reloading, concurrency allowed) — run the
+    #    callback inside `Rails.application.executor.wrap`.
+    #
+    # The configuration is read on every call, so the same wrapper is correct
+    # in every environment.
+    #
+    # @return [Proc] a callable suitable for `callback_wrapper:`
+    # @example config/initializers/claude_agent_sdk.rb
+    #   ClaudeAgentSDK.configure do |config|
+    #     config.default_options = { callback_wrapper: ClaudeAgentSDK::Railtie.callback_wrapper }
+    #   end
+    def self.callback_wrapper
+      lambda do |invocation|
+        app = ::Rails.application
+        next invocation.call if app.nil? || app.executor.active?
+        next app.executor.wrap { invocation.call } unless executor_locks?(app.config)
+
+        begin
+          invocation.call
+        ensure
+          release_active_record_connections
+        end
+      end
+    end
+
+    # Whether railties registered a process-wide lock hook on the executor
+    # (Rails::Application::Finisher, initializer
+    # :configure_executor_for_concurrency).
+    def self.executor_locks?(config)
+      return true if config.allow_concurrency == false
+      return false if config.allow_concurrency == :unsafe
+
+      config.reloading_enabled?
+    end
+    private_class_method :executor_locks?
+
+    # What the executor's ActiveRecord completion hook does for a callback
+    # that ran on a thread of its own. Explicit :all — the no-argument form
+    # is deprecated on Rails 7.1.
+    def self.release_active_record_connections
+      return unless defined?(::ActiveRecord::Base)
+
+      ::ActiveRecord::Base.connection_handler.clear_active_connections!(:all)
+    end
+    private_class_method :release_active_record_connections
+  end
+end

data/lib/claude_agent_sdk/tasks/claude_agent_sdk.rake

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# claude_agent_sdk:* tasks. Loaded by ClaudeAgentSDK::Railtie in Rails apps
+# and by `require 'claude_agent_sdk/tasks'` from a plain Rakefile. Guarded
+# because Rake appends the actions of a task defined twice — an app that
+# does both would otherwise install twice.
+unless Rake::Task.task_defined?('claude_agent_sdk:install_cli')
+  namespace :claude_agent_sdk do
+    desc 'Install the Claude Code CLI into vendor/claude: the version this gem is tested with, ' \
+         'or CLAUDE_CLI_VERSION=x.y.z / stable / latest'
+    task :install_cli do
+      # Under Rails, anchor to the app root instead of the process cwd (the
+      # app is not booted: no :environment dependency, so this runs in a
+      # Docker build without credentials). Resolved when the task runs.
+      root = Rails.root if defined?(Rails) && Rails.respond_to?(:root)
+      dir = root&.join('vendor', 'claude')&.to_s
+      # Not the conventional rake `VERSION`: Rails' own db:migrate uses it and
+      # build environments often export it for the app's version or git SHA.
+      version = ENV.fetch('CLAUDE_CLI_VERSION', '').strip
+
+      path = if version.empty?
+               ClaudeAgentSDK::CLIInstaller.install_pinned(dir: dir)
+             else
+               ClaudeAgentSDK::CLIInstaller.install(version: version, dir: dir)
+             end
+      label = version.empty? ? ClaudeAgentSDK::CLIInstaller::PINNED_CLI_VERSION : version
+      puts "Claude Code CLI (#{label}) installed at #{path}"
+    end
+  end
+end

data/lib/claude_agent_sdk/tasks.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Rake tasks for apps that don't use Rails (where the Railtie loads them).
+# From a plain Rakefile:
+#
+#   require 'claude_agent_sdk/tasks'
+#
+# then `rake claude_agent_sdk:install_cli` (e.g. in a Dockerfile). Only the
+# stdlib-only CLIInstaller is loaded, not the whole SDK.
+require 'rake'
+require_relative 'cli_installer'
+
+load File.expand_path('tasks/claude_agent_sdk.rake', __dir__)

data/lib/claude_agent_sdk/types.rb

@@ -157,8 +157,178 @@ module ClaudeAgentSDK
     end
     private_class_method :option_hash_key
 
+    # Bounded, human-oriented #inspect listing the non-nil instance variables
+    # in definition order:
+    #
+    #   #<ClaudeAgentSDK::ResultMessage subtype="success" num_turns=3 ...>
+    #
+    # Messages carry whole transcripts, tool payloads and usage maps, so the
+    # output is bounded rather than faithful: long Strings are truncated,
+    # long Arrays/Hashes abbreviated, and nesting past INSPECT_MAX_DEPTH (or
+    # a reference cycle) collapses to a placeholder. Other objects keep their
+    # own #inspect (truncated) unless they only have Kernel#inspect, which
+    # dumps every ivar recursively — those (SDK MCP server instances, store
+    # adapters, observers) show as `#<ClassName>`. For display only: nothing
+    # sent to the CLI goes through #inspect or #to_s (wire output uses #to_h).
+    def inspect
+      inspect_with(0, {}.compare_by_identity)
+    end
+
+    # Object#to_s ignores instance variables, so `puts message` would print
+    # only a class name and an address. Types with a natural textual form
+    # (UserMessage, AssistantMessage, TextBlock, ResultMessage, SystemMessage)
+    # override this.
+    def to_s
+      inspect
+    end
+
+    # Declares attributes that carry credentials (env vars, auth headers).
+    # Objects get logged, so #inspect shows them filtered; #to_h and
+    # everything sent to the CLI are unaffected. Inherited by subclasses.
+    def self.inspect_filtered(*names)
+      @inspect_filtered_attributes = (inspect_filtered_attributes + names.map(&:to_s)).uniq.freeze
+    end
+
+    def self.inspect_filtered_attributes
+      @inspect_filtered_attributes || (superclass <= Type ? superclass.inspect_filtered_attributes : [].freeze)
+    end
+
+    INSPECT_MAX_STRING = 80
+    INSPECT_MAX_ITEMS = 5
+    INSPECT_MAX_DEPTH = 2
+    private_constant :INSPECT_MAX_STRING, :INSPECT_MAX_ITEMS, :INSPECT_MAX_DEPTH
+
+    protected
+
+    # `seen` holds the Types/containers on the current rendering path (not
+    # every one rendered so far), so a shared-but-acyclic value still renders
+    # in full wherever it appears.
+    def inspect_with(depth, seen)
+      return "#<#{inspect_class_name} …>" if depth > INSPECT_MAX_DEPTH || seen.key?(self)
+
+      seen[self] = true
+      begin
+        attributes = inspect_attributes.map do |name, value|
+          " #{name}=#{inspect_bounded(value, depth + 1, seen)}"
+        end
+        "#<#{inspect_class_name}#{attributes.join}>"
+      ensure
+        seen.delete(self)
+      end
+    end
+
     private
 
+    # [name, value] pairs rendered by #inspect. Subclasses override to hide
+    # redundant state or redact secrets — never by mutating the object.
+    def inspect_attributes
+      filtered = self.class.inspect_filtered_attributes
+      instance_variables.filter_map do |ivar|
+        value = instance_variable_get(ivar)
+        next if value.nil?
+
+        name = ivar.to_s.delete_prefix('@')
+        [name, filtered.include?(name) ? inspect_filter(value) : value]
+      end
+    end
+
+    # A credential-bearing Hash keeps its keys (useful when debugging which
+    # variables are set) with every value replaced; anything else is replaced
+    # outright. Builds a new Hash; the object itself is never touched.
+    def inspect_filter(value)
+      value.respond_to?(:each_key) ? value.each_key.to_h { |key| [key, '[FILTERED]'] } : '[FILTERED]'
+    end
+
+    def inspect_class_name
+      self.class.name || self.class.inspect
+    end
+
+    def inspect_bounded(value, depth, seen)
+      case value
+      when Type then value.inspect_with(depth, seen)
+      when String then inspect_truncated(value)
+      when Array then inspect_container(value, '[', ']', depth, seen) { |item| inspect_bounded(item, depth + 1, seen) }
+      when Hash
+        inspect_container(value, '{', '}', depth, seen) do |key, item|
+          "#{inspect_hash_key(key, depth + 1, seen)}#{inspect_bounded(item, depth + 1, seen)}"
+        end
+      when Proc, Method, UnboundMethod then inspect_callable(value)
+      else inspect_leaf(value)
+      end
+    end
+
+    def inspect_container(value, open, close, depth, seen, &render)
+      return "#{open}#{close}" if value.empty?
+      return "#{open}…(#{value.size})#{close}" if depth > INSPECT_MAX_DEPTH || seen.key?(value)
+
+      seen[value] = true
+      begin
+        parts = value.first(INSPECT_MAX_ITEMS).map(&render)
+        parts << "…(+#{value.size - INSPECT_MAX_ITEMS} more)" if value.size > INSPECT_MAX_ITEMS
+        "#{open}#{parts.join(', ')}#{close}"
+      ensure
+        seen.delete(value)
+      end
+    end
+
+    # Rendered by hand rather than via Hash#inspect, whose format differs
+    # between Ruby 3.3 (`{:a=>1}`) and 3.4 (`{a: 1}`).
+    def inspect_hash_key(key, depth, seen)
+      return "#{key.name}: " if key.is_a?(Symbol) && key.inspect.match?(/\A:\w+[?!]?\z/)
+
+      "#{inspect_bounded(key, depth, seen)} => "
+    end
+
+    def inspect_truncated(string)
+      return string.inspect if string.length <= INSPECT_MAX_STRING
+
+      "#{string[0, INSPECT_MAX_STRING].inspect}…(+#{string.length - INSPECT_MAX_STRING} chars)"
+    end
+
+    # Callbacks (can_use_tool, hooks, callback_wrapper, ...) are user-supplied:
+    # render them from source_location rather than their own #inspect, which
+    # a subclass may override (and raise from) and which embeds an absolute
+    # path — `#<Proc(lambda) permissions.rb:17>`, `#<Method Policy#call>`.
+    def inspect_callable(value)
+      label = if value.is_a?(Proc)
+                value.lambda? ? 'Proc(lambda)' : 'Proc'
+              else
+                "#{value.class.name} #{value.owner.name || value.owner.inspect}##{value.name}"
+              end
+      file, line = value.source_location
+      rendered = file ? "#<#{label} #{File.basename(file)}:#{line}>" : "#<#{label}>"
+      inspect_truncated_text(rendered)
+    rescue StandardError
+      inspect_leaf(value)
+    end
+
+    def inspect_truncated_text(rendered)
+      return rendered if rendered.length <= INSPECT_MAX_STRING
+
+      "#{rendered[0, INSPECT_MAX_STRING]}…(+#{rendered.length - INSPECT_MAX_STRING} chars)"
+    end
+
+    # Printing must never raise (it runs inside loggers and `puts`), so an
+    # object whose #inspect raises, or a BasicObject without one, falls back
+    # to a placeholder.
+    def inspect_leaf(value)
+      return "#<#{value.class}>" if kernel_inspect_only?(value)
+
+      inspect_truncated_text(value.inspect)
+    rescue StandardError
+      begin
+        "#<#{value.class}>"
+      rescue StandardError
+        '#<?>'
+      end
+    end
+
+    def kernel_inspect_only?(value)
+      Kernel.instance_method(:method).bind_call(value, :inspect).owner == Kernel
+    rescue TypeError # not a Kernel object: BasicObject, Delegator
+      false
+    end
+
     # Allow camelCase attribute access
     def method_missing(method_name, ...)
       normalized = normalize_name(method_name)
@@ -230,6 +400,10 @@ module ClaudeAgentSDK
   # Text content block
   class TextBlock < Type
     attr_accessor :text
+
+    def to_s
+      text.to_s
+    end
   end
 
   # Thinking content block
@@ -375,6 +549,22 @@ module ClaudeAgentSDK
       super
       @data ||= attributes if attributes.is_a?(Hash)
     end
+
+    def to_s
+      subtype.nil? ? '[system]' : "[system: #{subtype}]"
+    end
+
+    private
+
+    # A typed subclass (InitMessage, TaskStartedMessage, ...) already exposes
+    # the fields of its raw frame as attributes; repeating @data would double
+    # the output. A bare SystemMessage (unrecognized subtype) keeps it, since
+    # @data is the only place its payload lives.
+    def inspect_attributes
+      return super if instance_of?(SystemMessage)
+
+      super.reject { |pair| pair.first == 'data' }
+    end
   end
 
   # Init system message (emitted at session start and after /clear)
@@ -755,6 +945,19 @@ module ClaudeAgentSDK
     # @return [Hash{Symbol => Object}, nil]
     # @see UserMessage#origin
     attr_accessor :origin
+
+    # One human-readable line, e.g. `[result: success, 3 turns, 4.2s, $0.0120]`
+    # (parts the CLI did not report are left out). An error result appends its
+    # `errors`. Use #inspect for every field.
+    def to_s
+      parts = [subtype].compact
+      parts << "#{num_turns} #{num_turns == 1 ? 'turn' : 'turns'}" unless num_turns.nil?
+      parts << format('%.1fs', duration_ms / 1000.0) if duration_ms.is_a?(Numeric)
+      parts << format('$%.4f', total_cost_usd) if total_cost_usd.is_a?(Numeric)
+      line = parts.empty? ? '[result]' : "[result: #{parts.join(', ')}]"
+      line += " - #{Array(errors).join('; ')}" if is_error && !Array(errors).empty?
+      line
+    end
   end
 
   # Stream event for partial message updates
@@ -1723,6 +1926,8 @@ module ClaudeAgentSDK
     attr_accessor :command, :args, :env
     attr_reader :type
 
+    inspect_filtered :env
+
     def initialize(attributes = {})
       super
       @type = 'stdio'
@@ -1742,6 +1947,8 @@ module ClaudeAgentSDK
     attr_accessor :url, :headers
     attr_reader :type
 
+    inspect_filtered :headers
+
     def initialize(attributes = {})
       super
       @type = 'sse'
@@ -1760,6 +1967,8 @@ module ClaudeAgentSDK
     attr_accessor :url, :headers
     attr_reader :type
 
+    inspect_filtered :headers
+
     def initialize(attributes = {})
       super
       @type = 'http'
@@ -1980,6 +2189,9 @@ module ClaudeAgentSDK
 
   # Claude Agent Options for configuring queries
   class ClaudeAgentOptions < Type
+    # `env` routinely carries credentials (ANTHROPIC_API_KEY, ...).
+    inspect_filtered :env
+
     attr_accessor :allowed_tools, :system_prompt, :mcp_servers, :permission_mode,
                   :resume, :resume_session_at, :session_id, :max_turns, :disallowed_tools,
                   :model, :permission_prompt_tool_name, :cwd, :cli_path, :settings,
@@ -2226,13 +2438,17 @@ module ClaudeAgentSDK
     # A callable receiving a zero-arg invocation; it MUST call it and
     # return its value:
     #
-    #   callback_wrapper: ->(invocation) { Rails.application.executor.wrap { invocation.call } }
+    #   callback_wrapper: ->(invocation) { MyApm.trace('agent.callback') { invocation.call } }
     #
     # The wrapper runs on the same execution context as the callback —
-    # inside the worker thread in :thread mode (so executor.wrap checks AR
-    # connections back in when the callback ends), in place on the reactor
+    # inside the worker thread in :thread mode, in place on the reactor
     # fiber in :inline mode. Exceptions propagate through it unchanged; it
     # must not swallow them. Default nil (no wrapping).
+    #
+    # Rails apps: use ClaudeAgentSDK::Railtie.callback_wrapper, which runs
+    # callbacks in the Rails executor (AR connections check back in when the
+    # callback ends). A bare `Rails.application.executor.wrap` deadlocks
+    # under development code reloading in :thread mode.
     def callback_wrapper=(value)
       raise ArgumentError, "callback_wrapper must be a callable or nil (got #{value.inspect})" unless value.nil? || value.respond_to?(:call)
 

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -20,6 +20,10 @@ require_relative 'claude_agent_sdk/session_resume'
 require_relative 'claude_agent_sdk/session_mutations'
 require_relative 'claude_agent_sdk/fiber_boundary'
 require_relative 'claude_agent_sdk/option_warnings'
+# Rails apps only: Bundler.require runs after `require 'rails'`, so the
+# Railtie (rake tasks; the generator lives under lib/generators) is picked up
+# there and nowhere else.
+require_relative 'claude_agent_sdk/railtie' if defined?(Rails::Railtie)
 require 'async'
 require 'securerandom'
 

data/lib/generators/claude_agent_sdk/install/install_generator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module ClaudeAgentSDK
+  module Generators
+    # `bin/rails generate claude_agent_sdk:install` — writes the initializer,
+    # ignores the vendored CLI, and prints the next steps. Lives under
+    # lib/generators/ so Rails' generator lookup finds it by namespace.
+    class InstallGenerator < ::Rails::Generators::Base
+      # Explicit: Thor derives the namespace by snake-casing the class path,
+      # which turns ClaudeAgentSDK into "claude_agent_s_d_k".
+      namespace 'claude_agent_sdk:install'
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates config/initializers/claude_agent_sdk.rb and git-ignores the vendored Claude Code CLI.'
+
+      GITIGNORE_ENTRY = '/vendor/claude/'
+      # Spellings that already ignore the vendored CLI directory.
+      GITIGNORE_PATTERN = %r{\A/?vendor/claude/?\z}
+
+      def create_initializer
+        template 'claude_agent_sdk.rb.tt', 'config/initializers/claude_agent_sdk.rb'
+      end
+
+      def ignore_vendored_cli
+        path = File.join(destination_root, '.gitignore')
+        entry = "# Claude Code CLI vendored by `bin/rails claude_agent_sdk:install_cli`\n#{GITIGNORE_ENTRY}\n"
+        return create_file('.gitignore', entry) unless File.exist?(path)
+
+        content = File.read(path)
+        if content.each_line.any? { |line| line.strip.match?(GITIGNORE_PATTERN) }
+          say_status :identical, '.gitignore (already ignores vendor/claude)', :blue
+        else
+          append_to_file '.gitignore', gitignore_separator(content) + entry
+        end
+      end
+
+      def show_next_steps
+        say <<~MSG
+
+          Next steps:
+            1. Install the Claude Code CLI this gem is tested with into vendor/claude
+               (run it in your Dockerfile / bin/setup as well):
+                 bin/rails claude_agent_sdk:install_cli
+            2. Provide credentials to the CLI, e.g. ANTHROPIC_API_KEY in the environment.
+            3. Review config/initializers/claude_agent_sdk.rb.
+
+          Rails guide: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/rails.md
+        MSG
+      end
+
+      private
+
+      # Start the appended block on its own line, after a blank one.
+      def gitignore_separator(content)
+        return '' if content.empty?
+
+        content.end_with?("\n") ? "\n" : "\n\n"
+      end
+    end
+  end
+end

data/lib/generators/claude_agent_sdk/install/templates/claude_agent_sdk.rb.tt

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Claude Agent SDK defaults, merged into every ClaudeAgentSDK.query and
+# ClaudeAgentSDK::Client session; per-call ClaudeAgentOptions override them.
+# Guide: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/rails.md
+
+# Uncomment together with `observers:` below (needs the opentelemetry-sdk gem).
+# require 'claude_agent_sdk/instrumentation'
+
+ClaudeAgentSDK.configure do |config|
+  config.default_options = {
+    # Model: full ID or alias ('opus', 'sonnet', 'haiku'). Unset, the CLI picks.
+    # model: 'claude-sonnet-5',
+    # model: 'claude-opus-5',
+    # model: 'claude-haiku-4-5',
+
+    # Tool permissions: 'default', 'acceptEdits', 'plan', 'dontAsk',
+    # 'bypassPermissions' (unattended jobs in a sandbox only), or 'auto'.
+    # permission_mode: 'default',
+
+    # The CLI is found in vendor/claude relative to the process cwd (Rails.root
+    # under bin/rails, Puma and most job runners). Pin it for other launchers:
+    # cli_path: Rails.root.join('vendor', 'claude', 'claude').to_s,
+
+    # OpenTelemetry tracing (Langfuse, Honeycomb, ...). A factory lambda gives
+    # every query/session its own observer — safe under Puma and job threads.
+    # observers: [-> { ClaudeAgentSDK::Instrumentation::OTelObserver.new }],
+
+    # Wraps every SDK callback (tool handlers, hooks, permission callbacks,
+    # message blocks, observers) so ActiveRecord connections go back to the
+    # pool. Not a bare `Rails.application.executor.wrap`: that deadlocks with
+    # development code reloading. See docs/rails.md ("callback_wrapper").
+    callback_wrapper: ClaudeAgentSDK::Railtie.callback_wrapper
+  }
+end

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 0.35.0
 platform: ruby
 authors:
-- Community Contributors
+- ya-luotao
 autorequire:
 bindir: bin
 cert_chain: []
@@ -106,9 +106,14 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.87.0
-description: Unofficial Ruby SDK for interacting with Claude Code, supporting bidirectional
-  conversations, custom tools, and hooks. Not officially maintained by Anthropic.
-email: []
+description: 'Unofficial Ruby SDK for the Claude Code agent runtime: one-shot queries
+  and bidirectional sessions, in-process custom tools, hooks and permission callbacks.
+  Includes Rails integration (Railtie, install generator, CLI-vendoring rake task,
+  executor-aware callback wrapper), a pinned CLI installer, OpenTelemetry tracing,
+  and session transcript mirroring. Not affiliated with or officially maintained by
+  Anthropic.'
+email:
+- luotao@hey.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -141,6 +146,7 @@ files:
 - lib/claude_agent_sdk/observer.rb
 - lib/claude_agent_sdk/option_warnings.rb
 - lib/claude_agent_sdk/query.rb
+- lib/claude_agent_sdk/railtie.rb
 - lib/claude_agent_sdk/sdk_mcp_server.rb
 - lib/claude_agent_sdk/session_mutations.rb
 - lib/claude_agent_sdk/session_resume.rb
@@ -149,11 +155,15 @@ files:
 - lib/claude_agent_sdk/sessions.rb
 - lib/claude_agent_sdk/streaming.rb
 - lib/claude_agent_sdk/subprocess_cli_transport.rb
+- lib/claude_agent_sdk/tasks.rb
+- lib/claude_agent_sdk/tasks/claude_agent_sdk.rake
 - lib/claude_agent_sdk/testing/session_store_conformance.rb
 - lib/claude_agent_sdk/transcript_mirror_batcher.rb
 - lib/claude_agent_sdk/transport.rb
 - lib/claude_agent_sdk/types.rb
 - lib/claude_agent_sdk/version.rb
+- lib/generators/claude_agent_sdk/install/install_generator.rb
+- lib/generators/claude_agent_sdk/install/templates/claude_agent_sdk.rb.tt
 homepage: https://github.com/ya-luotao/claude-agent-sdk-ruby
 licenses:
 - MIT
@@ -181,5 +191,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: Unofficial Ruby SDK for Claude Agent
+summary: Unofficial Ruby SDK for Claude Agent, with Rails integration
 test_files: []