claude-agent-sdk 1.1.0 → 1.2.0

data/docs/rails.md

@@ -16,7 +16,7 @@ The gem ships a Railtie, an install generator and a rake task for vendoring the
    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`.
+   This writes `config/initializers/claude_agent_sdk.rb` — a `ClaudeAgentSDK.configure` block with commented defaults (model, permission mode, CLI path, [per-user isolation](#per-user-isolation), 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:
 
@@ -33,7 +33,10 @@ The gem ships a Railtie, an install generator and a rake task for vendoring the
    # 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
+       options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+         tools: [], max_turns: 1,                            # text only, no built-in tools
+         env: { 'CLAUDE_CODE_DISABLE_AUTO_MEMORY' => '1' }   # see "Per-user isolation"
+       )
        prompt = "Summarize this support ticket in two sentences:\n\n#{ticket.body}"
 
        ClaudeAgentSDK.query(prompt: prompt, options: options) do |message|
@@ -43,24 +46,26 @@ The gem ships a Railtie, an install generator and a rake task for vendoring the
    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.
+   The block runs on a plain thread (see the next section), so ActiveRecord calls inside it are safe. It is a thread of its own, though: the job's `Current` attributes, time zone, log tags and database role or shard are not set there — see [Request state does not follow into callbacks](#request-state-does-not-follow-into-callbacks). For multi-turn sessions and mid-session control (interrupt, model switching) use `ClaudeAgentSDK::Client.open` — see [ActionCable streaming](#actioncable-streaming) below. Hooks and custom tools work with `ClaudeAgentSDK.query` too.
 
 ## Thread-keyed libraries are safe inside SDK callbacks
 
 The SDK depends on [`async`](https://github.com/socketry/async), which installs a Fiber scheduler that multiplexes fibers onto a single OS thread and intercepts IO so blocking calls yield to siblings. Most mature Ruby libraries are thread-safe but not fiber-safe — they key state (checked-out DB connections, per-thread caches, request stores) on `Thread.current`. When the scheduler interleaves two fibers on one thread, those fibers share the same state slot, and interleaved IO on a shared connection silently corrupts wire protocols. This affects every DB driver keyed by thread (`pg`, `mysql2`, `sqlite3`), ActiveRecord's connection pool, and HTTP/cache clients pooled per thread.
 
-You do **not** need to think about this. By default (`callback_scheduling: :thread`; see the fiber-workers section below for the opt-in alternative) the SDK hops to a plain thread at every user-callback boundary — message blocks given to `query` / `Client`, SDK MCP tool handlers, hooks, permission callbacks, and observer methods — so your code runs with no Fiber scheduler active and inherits the ordinary thread-keyed assumptions every Rails / Sidekiq / Kamal app already makes:
+The SDK keeps your callbacks out of this. By default (`callback_scheduling: :thread`; see the fiber-workers section below for the opt-in alternative) it hops to a plain thread at every user-callback boundary — message blocks given to `query` / `Client`, SDK MCP tool handlers, hooks, permission callbacks, and observer methods — so your code runs with no Fiber scheduler active, and thread-keyed libraries behave there as they do on any other thread:
 
 ```ruby
 tool = ClaudeAgentSDK.create_tool('lookup_user', 'Look up a user', { id: Integer }) do |args|
-  User.find(args[:id]).name                  # just works
+  User.find(args[:id]).name                  # a connection of this thread's own: safe
 end
 
 ClaudeAgentSDK.query(prompt: '...') do |message|
-  Message.create!(role: 'assistant', body: message.to_s)   # just works
+  Message.create!(role: 'assistant', body: message.to_s)   # likewise
 end
 ```
 
+That thread is a new one, not the thread that called the SDK. The connection pool does not mind; everything Rails keeps for the current request or job does — `Current` attributes, `Time.zone`, log tags, the database role and shard are all back at their defaults inside a callback, and the callback is outside the caller's transaction. Read [Request state does not follow into callbacks](#request-state-does-not-follow-into-callbacks) and [Transactions and the connection pool](#transactions-and-the-connection-pool) before a callback touches anything scoped to the request.
+
 The trade-off: because callbacks run on a plain thread rather than inside an `Async::Task`, fiber-specific primitives aren't available to them — `Async::Task.current` will raise "No async task available". If a callback wants cooperative concurrency it should open its own `Async { }` block. In practice, callbacks typically do some Ruby work, call external services, and return — so this rarely matters. If you wrap your own call site in an outer `Async { }` block, the scheduler is visible to your code again; you've opted in, and whatever fiber-safety rules your app uses apply there.
 
 ### Rails executor around callbacks: `callback_wrapper`
@@ -75,20 +80,233 @@ ClaudeAgentSDK.configure do |config|
 end
 ```
 
-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:
+It runs each callback inside the Rails executor — 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.
+- **Already inside the executor** — a callback that runs on the caller's own fiber, which under `:inline` scheduling is a `Client`'s message block and observers: it runs straight through, leaving cleanup to the enclosing executor. The other `:inline` callbacks run on fibers of their own, where under fiber isolation the executor is not active; they take one of the other paths.
+
+Everywhere else — production, with no reloading — the callback runs inside the executor: its run hooks before the callback and its complete hooks after it, also when the callback raises. The configuration is read per call, so one initializer is correct in every environment.
+
+**Development: an agent run still holds the reload lock.** The helper removes the deadlock, not the wait. A request or in-process job that runs an agent stays inside the executor, with its share of the interlock, until the run returns. Once a file changes — an agent editing your app does that — the next request asks to reload, the reloader waits for that share, and every other request waits behind the reloader. Rails treats any long request this way; it is not specific to the SDK. In development, run agent jobs in a separate process (`bin/jobs`, Sidekiq) rather than in a controller action or the in-process `:async` adapter, and point an agent that edits code at a different checkout than the one the server runs from. To see who is waiting for whom, add `config.middleware.insert_before Rack::Sendfile, ActionDispatch::DebugLocks` and open `/rails/locks`.
+
+**Errors and `Rails.error`.** The wrapper reports nothing to `Rails.error` itself, which is the one difference from `executor.wrap` (that reports whatever passes through it as an unhandled error). What your error tracker sees is therefore decided by where an exception ends up:
+
+- An exception that escapes a callback — one raised in a message block, say — comes out of `query` / `receive_response` on the thread that called the SDK. It is reported there, once, with that thread's context, by whatever runs the code inside the executor: the request middleware for a controller action, ActiveJob for a job a queue worker runs (`perform_later`). A `perform_now` called outside any executor — from a script or a console — raises it to its caller and reports nothing by itself.
+- A failure the SDK handles is not reported: an exception in a hook or `can_use_tool` is answered to the CLI as an error response, one in an SDK MCP tool handler becomes an error result the model sees, one in an observer is swallowed, and a timed-out or cancelled callback is cancellation, not an error. To track these, report them where they happen: `rescue` inside the callback, call `Rails.error.report(e, handled: true)`, and re-raise.
+
+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: the executor 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 are safe, including around a `break` from a message block.
 
-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.
+Beyond the executor, this is a generic hook: APM spans, logging context, per-request state. To combine a wrapper of your own with the Rails one, call the Rails one from yours — and mind which side of that call your code is on. In production `rails.call` enters the Rails executor, and the executor starts every execution from a clean slate: on the way in it resets `CurrentAttributes` and the error context (`Rails.error.set_context`).
+
+```ruby
+rails = ClaudeAgentSDK::Railtie.callback_wrapper
+
+# What only has to surround the callback can stay outside:
+->(invocation) { MyApm.trace('agent.callback') { rails.call(invocation) } }
+
+# State that Rails resets per execution is set inside:
+->(invocation) { rails.call(-> { Current.set(account: account) { invocation.call } }) }
+
+# Not around it. This loses Current.account in every callback, in production only:
+->(invocation) { Current.set(account: account) { rails.call(invocation) } }
+```
 
-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 last form is a trap because it works in development, where the Rails wrapper stays out of the executor (see above), and because the loss looks selective: `Time.zone`, log tags and `connected_to` are not reset by the executor and survive on either side. `Current.set` does not carry the error context either; that needs `ActiveSupport::ExecutionContext.set`. The [recipe below](#carrying-the-callers-state-into-callbacks) puts all of it in the right place, and `spec/rails/callback_wrapper_composition_spec.rb` pins this rule against the executor hooks of both supported Rails versions.
 
 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.
 
 When do you want this vs `callback_scheduling: :inline`? `callback_wrapper` + default `:thread` mode is the right choice for ordinary threaded hosts (Puma, threaded Sidekiq/solid_queue): it fixes connection hygiene without any fiber-isolation precondition. `:inline` is only for hosts that are fiber-isolated end to end (solid_queue fiber workers with `isolation_level = :fiber`); there the wrapper still applies — it simply runs in place on the reactor fiber.
 
+## Request state does not follow into callbacks
+
+A callback is written inside your controller action or job, a few lines below its `Current.set` or `connected_to` block — but it does not run there. It runs on a thread the SDK starts for it (the default `:thread` scheduling) or on a fiber of the SDK's reactor (`:inline`), and Rails keeps what belongs to the current request or job per thread or per fiber. A thread or fiber Rails never set up reads all of it as the default:
+
+| Set on the caller | What a callback sees |
+| --- | --- |
+| `Current.user = alice` (any `ActiveSupport::CurrentAttributes`) | `nil` |
+| `Time.zone = "Tokyo"`, `Time.use_zone` | the application's default zone (`UTC` unless configured) |
+| log tags: `Rails.logger.tagged("req-123")`, the request id, ActiveJob's job id | none |
+| `connected_to(role: :reading)` | `:writing` |
+| `connected_to(shard: :tenant_b)` | `:default` |
+| `connected_to(prevent_writes: true)` | writes allowed |
+| the error context: `Rails.error.set_context`, the controller or job Rails records | empty |
+| `I18n.locale = :de` | depends on the i18n version — see below |
+| the OpenTelemetry context | kept — the SDK carries it across |
+
+This is the same in a message block, an observer, a hook, `can_use_tool` and an SDK MCP tool handler; with and without `Railtie.callback_wrapper`; in development and in production. It is the same under `callback_scheduling: :inline` with fiber isolation, with one exception: there a `Client`'s message block and observers run on the fiber that called the SDK, and see its state. (`ClaudeAgentSDK.query` runs every callback on another fiber, and hooks, `can_use_tool` and tool handlers always do.)
+
+What a callback gets of `I18n.locale` depends on where i18n keeps its configuration:
+
+| i18n | Callback on a thread of its own (`:thread` scheduling) | Callback on another fiber of the caller's thread (`:inline`) |
+| --- | --- | --- |
+| 1.14.7 and earlier: a fiber-local | the default locale | the default locale |
+| 1.14.8: a thread variable | the default locale | `:de` — every fiber of the thread shares one locale |
+| 1.15 and later: fiber storage | `:de` — new threads and fibers inherit it | `:de` |
+
+Nothing raises. The consequences are silent:
+
+- A job inside `connected_to(shard: :tenant_b)` writes its own records to `tenant_b`; the same `create!` in a tool handler or in the message block writes to the **default** shard. Inside `connected_to(role: :reading)` the caller's own write raises `ActiveRecord::ReadOnlyError`; the same write in a callback succeeds, on the primary.
+- A scope or policy that reads `Current.account` runs unscoped. Log lines written by callbacks carry no request id, errors reported from them no controller or job, and times are formatted in the default zone.
+
+### Carrying the caller's state into callbacks
+
+The SDK has no option for this yet. The supported way today is a wrapper of your own that captures the state **on the caller** and restores it **inside** the Rails wrapper, on the callback's thread or fiber:
+
+<!-- spec/rails/request_state_spec.rb runs the next code block verbatim -->
+```ruby
+# app/lib/agent_context.rb
+module AgentContext
+  # A callback_wrapper that runs SDK callbacks under the state of whoever
+  # calls this method. Call it from the request or job, once per SDK call.
+  def self.callback_wrapper
+    rails   = ClaudeAgentSDK::Railtie.callback_wrapper
+    origin  = Fiber.current
+    restore = capture
+
+    lambda do |invocation|
+      # The callback is running on the caller itself: the state is there.
+      next rails.call(invocation) if Fiber.current.equal?(origin)
+
+      # Restore inside the Rails wrapper: the executor it enters starts
+      # every execution from a clean slate.
+      rails.call(-> { restore.call(invocation) })
+    end
+  end
+
+  # Snapshots the caller. Returns a lambda that runs an invocation under
+  # that snapshot, on whatever thread or fiber it is called on.
+  def self.capture
+    attributes = Current.attributes.dup
+    context    = ActiveSupport::ExecutionContext.to_h
+    locale     = I18n.locale
+    zone       = Time.zone
+    tags       = log_tags
+
+    lambda do |invocation|
+      Current.set(attributes) do
+        ActiveSupport::ExecutionContext.set(**context) do
+          I18n.with_locale(locale) do
+            Time.use_zone(zone) do
+              with_log_tags(tags) { invocation.call }
+            end
+          end
+        end
+      end
+    end
+  end
+
+  # The tags of the first tagged logger Rails.logger writes to. Not
+  # Rails.logger.formatter: in a broadcast that can be a plain logger's.
+  def self.log_tags
+    loggers = Rails.logger.respond_to?(:broadcasts) ? Rails.logger.broadcasts : [Rails.logger]
+    formatter = loggers.map { |logger| logger.formatter if logger.respond_to?(:formatter) }
+                       .find { |candidate| candidate.respond_to?(:current_tags) }
+    formatter ? formatter.current_tags.dup : []
+  end
+
+  # push / pop, not `Rails.logger.tagged(*tags) { ... }`: a BroadcastLogger
+  # runs that block once for every tagged logger it broadcasts to.
+  def self.with_log_tags(tags)
+    logger = Rails.logger
+    return yield if tags.empty? || !logger.respond_to?(:push_tags)
+
+    logger.push_tags(*tags)
+    begin
+      yield
+    ensure
+      logger.pop_tags(tags.size)
+    end
+  end
+end
+```
+
+Build the wrapper where the state is set, and pass it in that call's options:
+
+```ruby
+class SummarizeTicketJob < ApplicationJob
+  def perform(ticket)
+    Current.account = ticket.account
+    options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+      callback_wrapper: AgentContext.callback_wrapper,   # replaces the configured Rails wrapper, and calls it
+      tools: [], max_turns: 1,
+      env: { 'CLAUDE_CODE_DISABLE_AUTO_MEMORY' => '1' }
+    )
+
+    ClaudeAgentSDK.query(prompt: "Summarize:\n\n#{ticket.body}", options: options) do |message|
+      # Current.account, the locale, Time.zone, the job's log tags and error context are set here
+      ticket.update!(summary: message.result) if message.is_a?(ClaudeAgentSDK::ResultMessage)
+    end
+  end
+end
+```
+
+What the recipe depends on:
+
+- **One wrapper per call, built on the caller.** `AgentContext.callback_wrapper` snapshots whoever calls it. Call it from the request or job, after its state is set and before `query` / `Client.open` — not inside their blocks, which may already run on another fiber. It cannot go into the initializer: a process-wide wrapper only ever runs at the destination and has no caller to look at. And it must not outlive the call: a wrapper is fixed for the lifetime of the session it was passed to, so one built when a long-lived `Client` connects makes every later turn run its callbacks as the **first** caller — another user's turn would read and write under the first user's account and shard. Open a session per request or job and resume it by id, as the examples below do, and the capture happens once per call.
+- **The restore happens inside `rails.call`.** In production the Rails wrapper enters the executor, and the executor starts every execution from a clean slate: it resets `Current` and the error context. State set around `rails.call` is wiped on the way in; state set inside it survives.
+- **No restore on the fiber that captured the state.** Under `:inline` scheduling a `Client`'s message block and observers run on the caller itself. The state is already there, and restoring it again would add the log tags a second time.
+- **Log tags are pushed and popped.** `Rails.logger` is an `ActiveSupport::BroadcastLogger`, and `Rails.logger.tagged(*tags) { ... }` runs its block once for every tagged logger in the broadcast, returning an array: with two tagged loggers the callback would run twice. `push_tags` / `pop_tags` reach every tagged logger and run nothing. The tags are read from the first logger in the broadcast that keeps tags rather than from `Rails.logger.formatter`, which is the first logger's on Rails 8.1, tagged or not, and `nil` on 7.1 for a broadcast you built yourself. With no tagged logger at all the recipe carries no tags and still runs.
+- **`ActiveSupport::ExecutionContext` is restored explicitly.** It is where `Rails.error.set_context` and Rails' own controller and job entries live; `Current.set` does not bring it back. Rails has no public reader for it, so recheck this line when you upgrade Rails.
+- **The locale is restored rather than assumed**, because only i18n 1.15 and later hand it to every callback by themselves. The restore is safe wherever a callback has a thread of its own, which is `:thread` scheduling, with any i18n. With i18n 1.14.8 it is only safe there: under `:inline` all fibers of the reactor thread share one locale, so a callback's `I18n.with_locale` changes the locale of every job on that worker while the callback runs, and another job that sets its own locale meanwhile changes the callback's. On a fiber-isolated host, keeping jobs' locales apart takes i18n 1.15 or later: on 1.14.8 the jobs of one worker share a locale among themselves, with or without the SDK. `:thread` scheduling takes the recipe's restore off that shared thread; it does not separate the jobs.
+- **Values travel, containers do not.** The recipe rebuilds the caller's state from values. The objects themselves — `Current.user`, say — are shared with the caller, so treat them as read-only in callbacks. Do not go further and copy thread-local variables wholesale, hand the caller's ActiveRecord connection to a callback, or pass `ActiveRecord::Base.connected_to_stack` across: those are mutable and belong to one thread.
+
+An application with replicas or shards also carries the role, the shard and `prevent_writes`. Capture them in `capture`:
+
+```ruby
+    role, shard    = ApplicationRecord.current_role, ApplicationRecord.current_shard
+    prevent_writes = ApplicationRecord.current_preventing_writes
+```
+
+and re-enter them innermost, in place of `with_log_tags(tags) { invocation.call }`:
+
+```ruby
+              with_log_tags(tags) do
+                ApplicationRecord.connected_to(role: role, shard: shard, prevent_writes: prevent_writes) { invocation.call }
+              end
+```
+
+`connected_to` on `ApplicationRecord` switches the models that inherit from it; an application with several connection classes captures and re-enters each of them.
+
+What is checked: `spec/rails/request_state_spec.rb` boots a Rails application for each combination of production / development, `:thread` / `:inline` scheduling and `ClaudeAgentSDK.query` / `Client.open`. It pins the `Current`, `Time.zone`, log tag and error context rows of the table, the `I18n.locale` cases for whichever i18n the bundle resolves (CI's resolve 1.15 or later; the 1.14.7 and 1.14.8 rows were run against those releases), and runs the `AgentContext` block exactly as printed above through all five kinds of callback — also with two tagged loggers in the `Rails.logger` broadcast, and with a plain logger ahead of the tagged one. It does not cover the three `connected_to` rows or the role / shard lines — the gem's Rails test bundles carry no ActiveRecord; those were measured in a Rails 8.1 application with ActiveRecord and SQLite.
+
+## Transactions and the connection pool
+
+For the same reason — another thread — a callback is outside the caller's database transaction, on a connection of its own. Wrapping an SDK call in `transaction` or `with_lock` does not do what it looks like:
+
+```ruby
+ticket.with_lock do                                   # the job's connection holds the row lock
+  ClaudeAgentSDK.query(prompt: prompt) do |message|
+    next unless message.is_a?(ClaudeAgentSDK::ResultMessage)
+
+    ticket.update!(summary: message.result)           # another connection: waits for that lock,
+  end                                                 # while the job waits for this block
+end
+```
+
+- A callback does not see rows the caller has not committed.
+- What a callback writes is committed on its own connection. Rolling the caller's transaction back does not undo it.
+- A callback that needs a lock the caller's transaction holds waits for the caller, which is waiting for the callback. SQLite gives up after its busy timeout (`database is locked`); a server database keeps the callback waiting for as long as its lock timeout allows, which for PostgreSQL is forever by default. No database can detect the cycle, because half of it is in your process.
+
+So finish the transaction **before** you call the SDK, and hand the callbacks what they need explicitly — ids rather than records in an unsaved state:
+
+```ruby
+ticket.update!(state: 'summarizing')                  # committed before the agent starts
+ticket_id = ticket.id
+
+ClaudeAgentSDK.query(prompt: prompt) do |message|
+  next unless message.is_a?(ClaudeAgentSDK::ResultMessage)
+
+  Ticket.find(ticket_id).update!(summary: message.result, state: 'summarized')   # commits here, independently
+end
+```
+
+**Pool size.** A callback that uses the database needs a connection while the caller may still be holding one: inside a transaction, under an explicit lease, and for the whole request or job on Rails 7.1, where a connection stays with its thread until the request ends. And one session can have several callbacks in the database at the same moment — the SDK answers the CLI's hook, permission and tool requests concurrently, so two parallel tool calls mean two hooks running at once. Size the pool for the caller's connection **plus the peak number of callback invocations that use the database at the same time**, summed over the sessions a process runs concurrently — not for one extra connection per session. With a pool of one and the caller inside a transaction, the first query in a callback raises `ActiveRecord::ConnectionTimeoutError`.
+
+Under `callback_scheduling: :inline` with fiber isolation all of this applies to every callback that runs on a fiber other than the caller's: hooks, permission callbacks, tool handlers, and everything under `ClaudeAgentSDK.query`. Only a `Client`'s message block and observers share the caller's connection and transaction there.
+
+(Measured with ActiveRecord 8.1 on SQLite; the PostgreSQL and MySQL lock waits follow from how those databases wait for row locks and were not measured.)
+
 ## Fiber workers (solid_queue) and `callback_scheduling: :inline`
 
 [solid_queue 728](https://github.com/rails/solid_queue/pull/728) added a fiber-based worker mode: workers configured with `fibers: N` run claimed jobs as fibers on one async reactor thread — built for exactly the long-lived, I/O-bound "LLM streaming" jobs this SDK produces. It requires the app to be fiber-isolated end to end:
@@ -111,9 +329,13 @@ ClaudeAgentSDK.configure do |config|
 end
 ```
 
-With `:inline`, every user callback — message blocks, hooks, permission callbacks, SDK MCP handlers, observers — runs in place on the reactor fiber of the job. This is the same execution model as the Python SDK (async callbacks run natively on the event loop). Concretely:
+With `:inline`, no user callback leaves the job's reactor: message blocks, hooks, permission callbacks, SDK MCP handlers and observers all run in place, on a fiber of that reactor. This is the same execution model as the Python SDK (async callbacks run natively on the event loop).
 
-- `Fiber.scheduler` is live inside callbacks; reactor primitives work directly. DB access goes through the Rails 7.2+ fiber-aware pool under the same assumptions as the rest of your fiber-worker jobs.
+In place on the reactor is not the same as on the job's own fiber, and under fiber isolation the fiber is what Rails keys the job's state on. A `Client`'s message block and observers run on the fiber that called the SDK. Hooks, permission callbacks and SDK MCP handlers run on child fibers of the session's read task, and `ClaudeAgentSDK.query` runs its whole body, message block included, on a fiber of its own. On those fibers `Current`, `Time.zone`, the log tags and the database role and shard start from their defaults, exactly as on a callback thread — see [Request state does not follow into callbacks](#request-state-does-not-follow-into-callbacks).
+
+Concretely:
+
+- `Fiber.scheduler` is live inside callbacks; reactor primitives work directly. DB access goes through the Rails 7.2+ fiber-aware pool, as in the rest of your fiber-worker jobs.
 - No per-call threads exist, so nothing can strand an AR connection.
 - The whole SDK session can live directly on the job fiber — no bridge threads. `Client#connect` already requires an Async context, and the transport's pipe I/O is scheduler-aware.
 - Hook timeouts become **cooperative**: a timed-out inline hook is cancelled at its next suspension point (its `ensure` blocks run), instead of being abandoned on a worker thread. A CPU-stuck hook cannot be timed out.
@@ -148,7 +370,8 @@ class ChatAgentJob < ApplicationJob
   def perform(chat_id, message_content)
     options = ClaudeAgentSDK::ClaudeAgentOptions.new(
       system_prompt: { type: 'preset', preset: 'claude_code' },
-      permission_mode: 'bypassPermissions'
+      permission_mode: 'bypassPermissions',
+      env: { 'CLAUDE_CODE_DISABLE_AUTO_MEMORY' => '1' }   # one job class serves every chat: see "Per-user isolation"
     )
 
     ClaudeAgentSDK::Client.open(options: options) do |client|
@@ -173,6 +396,18 @@ 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.
 
+### Per-user isolation
+
+One job class serves every chat here, from one working directory — and the CLI keeps an auto-memory per *project directory*, not per session or per user:
+
+- Every SDK session reads that project's memory index. The CLI injects it next to the `CLAUDE.md` instructions, under the same "these instructions override default behavior" header.
+- A session on the `claude_code` preset also **writes** it when a user asks it to remember something, and that write passes no permission check: no `permission_mode`, `can_use_tool` callback or hook is consulted.
+- `setting_sources: []` isolates settings files. It does not turn this off.
+
+So in a multi-user app one user's "remember that…" becomes part of every other user's context. `env: { 'CLAUDE_CODE_DISABLE_AUTO_MEMORY' => '1' }` turns auto-memory off for the session. Every set of options built on this page carries it (`spec/rails/session_isolation_spec.rb` checks each one). Set it for every session a multi-user app runs — per call, as here, or once for the whole process by uncommenting the line the generated initializer carries; defaults merge per key, so a per-call `env:` keeps it, and the short snippets on this page that pass no options get it too. The value has to be `'1'`: the CLI reads `'0'` or `'false'` as "force auto-memory on", which overrides even `autoMemoryEnabled: false` in settings. To see what a session loaded, call `client.context_usage[:memoryFiles]` (an entry with `type: "AutoMem"` is the memory index); it costs no model call.
+
+What else isolates sessions, and what only appears to, is covered in [Session isolation](configuration.md#session-isolation).
+
 ## Session Resumption
 
 Persist Claude sessions for multi-turn conversations:
@@ -195,8 +430,12 @@ class ChatSession < ApplicationRecord
   private
 
   def build_options
-    opts = { permission_mode: 'bypassPermissions', setting_sources: [] }
-    opts[:resume] = claude_session_id if claude_session_id.present?
+    opts = {
+      permission_mode: 'bypassPermissions',
+      setting_sources: [],                                  # isolates settings files, not the CLI's auto-memory:
+      env: { 'CLAUDE_CODE_DISABLE_AUTO_MEMORY' => '1' },    # this does (see "Per-user isolation")
+      resume: claude_session_id.presence                    # nil for the first message: a new session
+    }
     ClaudeAgentSDK::ClaudeAgentOptions.new(**opts)
   end
 end
@@ -214,7 +453,12 @@ class ClaudeAgentJob < ApplicationJob
   def perform(task_id)
     task = Task.find(task_id)
 
-    ClaudeAgentSDK::Client.open(options: ClaudeAgentSDK::ClaudeAgentOptions.new(max_turns: 10)) do |client|
+    options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+      max_turns: 10,
+      env: { 'CLAUDE_CODE_DISABLE_AUTO_MEMORY' => '1' }   # see "Per-user isolation"
+    )
+
+    ClaudeAgentSDK::Client.open(options: options) do |client|
       client.query(task.prompt)
       client.receive_response do |message|
         task.update!(status: 'done', result: message.result) if message.is_a?(ClaudeAgentSDK::ResultMessage)
@@ -241,7 +485,8 @@ mcp_servers = {
 
 options = ClaudeAgentSDK::ClaudeAgentOptions.new(
   mcp_servers: mcp_servers,
-  permission_mode: 'bypassPermissions'
+  permission_mode: 'bypassPermissions',
+  env: { 'CLAUDE_CODE_DISABLE_AUTO_MEMORY' => '1' }   # see "Per-user isolation"
 )
 ```
 
@@ -251,7 +496,7 @@ Add OpenTelemetry tracing to your Rails app with a single initializer:
 
 ```ruby
 # config/initializers/opentelemetry.rb
-require 'base64'
+require 'base64'   # a bundled gem since Ruby 3.4 — no Gemfile entry needed: Active Support 7.1+ depends on it
 require 'opentelemetry/sdk'
 require 'opentelemetry/exporter/otlp'
 

data/docs/sessions.md

@@ -2,7 +2,7 @@
 
 Browse, read, mutate, fork, and resume Claude Code sessions directly from Ruby — no CLI subprocess required. By default these APIs read and write `~/.claude/projects/` JSONL files directly, respecting the `CLAUDE_CONFIG_DIR` environment variable (an empty value is treated as unset, falling back to `~/.claude`) and auto-detecting git worktrees. On a host with no usable home directory (`HOME` unset with no passwd entry — e.g. `docker --user` in a minimal image — or an empty/relative `HOME`) and no `CLAUDE_CONFIG_DIR`, the local-disk path raises `ClaudeAgentSDK::ConfigDirError`; set `CLAUDE_CONFIG_DIR` there. Every one of them also takes an optional `session_store:` to operate on a [`SessionStore`](#mirroring-to-a-sessionstore) instead (see [Store-backed sessions](#store-backed-sessions)).
 
-Not-found semantics: the read APIs return `[]`/`nil` for unknown sessions and for directories that do not exist or have no recorded sessions. An explicit `directory:` strictly scopes the search to that project and its git worktrees — there is no cross-project fallback (pass `directory: nil` to search all projects). 0-byte transcript stubs are skipped during session-file resolution. Ids are validated at the boundary: a `session_id` that is not a UUID String, or an `agent_id` that is not a String of `[A-Za-z0-9._-]` characters (or is `.`/`..`), gets the same `[]`/`nil` as an unknown session (`import_session_to_store` raises `ArgumentError`), on the disk and store readers alike. The mutations (`rename_session`, `tag_session`, `delete_session`, `fork_session`, with or without `session_store:`) apply the same check to `session_id` and `up_to_message_id` and raise `ArgumentError` (`Invalid session_id: ...`) for anything that is not a UUID String.
+Not-found semantics: the read APIs return `[]`/`nil` for unknown sessions and for directories that do not exist or have no recorded sessions. A `directory:` that was removed after its sessions were recorded (a deleted worktree) still names its project: the path is resolved as far as it exists, so those sessions can be listed, read, renamed, tagged, forked and deleted through it. An explicit `directory:` strictly scopes the search to that project and its git worktrees — there is no cross-project fallback (pass `directory: nil` to search all projects). 0-byte transcript stubs are skipped during session-file resolution. Ids are validated at the boundary: a `session_id` that is not a UUID String, or an `agent_id` that is not a String of `[A-Za-z0-9._-]` characters (or is `.`/`..`), gets the same `[]`/`nil` as an unknown session (`import_session_to_store` raises `ArgumentError`), on the disk and store readers alike. The mutations (`rename_session`, `tag_session`, `delete_session`, `fork_session`, with or without `session_store:`) apply the same check to `session_id` and `up_to_message_id` and raise `ArgumentError` (`Invalid session_id: ...`) for anything that is not a UUID String. `rename_session` raises `ArgumentError` for a `title:` that is blank or not a usable String (`nil`, another type, invalidly encoded — a binary String, such as `File.binread` returns, is read as UTF-8), and `tag_session` for such a `tag:` — except `nil`, which clears the tag.
 
 ## Listing Sessions
 
@@ -25,9 +25,16 @@ ClaudeAgentSDK.list_sessions(directory: '.', include_worktrees: true)
 
 Each `SDKSessionInfo` includes: `session_id`, `summary`, `last_modified`, `file_size`, `custom_title`, `first_prompt`, `git_branch`, `cwd`, `tag`, `created_at`.
 
-Listings are newest first; sessions with the same `last_modified` are ordered by `session_id`, so `offset:`/`limit:` pages are stable across calls and the disk and store listings order identically. Blank (empty or whitespace-only) custom/AI titles, last-prompt and summary entries, `git_branch`, `cwd`, and `tag` values read as absent on both paths. `cwd` is the first non-blank top-level `cwd` in the transcript (a key nested in a tool input doesn't count), falling back to the project path; `first_prompt` is `nil` when the session has no usable prompt. `last_modified` is always Integer epoch milliseconds — the file mtime on disk, the adapter's `mtime` coerced as described under [Implementing an adapter](#implementing-an-adapter) on the store paths.
+Listings are newest first; sessions with the same `last_modified` are ordered by `session_id`, so `offset:`/`limit:` pages are stable across calls and the disk and store listings order identically. Blank (empty or whitespace-only) custom/AI titles, last-prompt and summary entries, `git_branch`, `cwd`, and `tag` values read as absent on both paths. `cwd` is the first non-blank top-level `cwd` in the transcript (a key nested in a tool input doesn't count), falling back to the project path; `first_prompt` is `nil` when the session has no usable prompt; `created_at` is the first top-level `timestamp`. `last_modified` is always Integer epoch milliseconds — the file mtime on disk, the adapter's `mtime` coerced as described under [Implementing an adapter](#implementing-an-adapter) on the store paths (`get_session_info` takes it from the store's `list_sessions`, or else `list_session_summaries`, row for the session — one extra adapter call; a store that implements neither reports the timestamp of the session's last entry instead, `0` when no entry has one).
 
-When `list_sessions` finds the same session in several project directories (copied config dirs, worktrees), it keeps one copy: the newest `last_modified`; on equal mtimes the larger file (the more complete copy); then the copy in the project directory whose name sorts first (worktree listings: the worktree `git worktree list` reports first, i.e. the main worktree).
+The disk path does not read whole transcripts to list them: it looks at the first and the last 64 KiB of each file, and for `first_prompt` and `created_at` at up to the first 1 MiB when those first 64 KiB hold none (a large hook attachment, or a long prompt, often comes first). The store paths fold every entry. The two report the same values unless the entry that decides a field lies outside what the disk path reads:
+
+- a custom title or tag appended while the session was still running stops being seen once more than 64 KiB of transcript follows it (`custom_title` falls back to the AI title or `nil`, `summary` to the next source, `tag` to `nil`) until the CLI resumes the session, which re-appends them at the end;
+- a last-prompt entry that is only at the start of the file is not used for `summary`;
+- `cwd` comes from the first 64 KiB: a first entry larger than that leaves it at the project path;
+- a first prompt whose transcript line ends beyond the first 1 MiB is not found: `first_prompt` is the name of a slash command seen before it, or `nil` — and a session with neither that nor a title or last-prompt entry in its last 64 KiB is not listed from disk at all. Likewise `created_at` is `nil` when no line ending within the first 1 MiB carries a timestamp of its own.
+
+When `list_sessions` finds the same session in several project directories (copied config dirs, worktrees), it keeps one copy: the newest `last_modified`; on equal mtimes the larger file (the more complete copy); then the copy in the project directory whose name sorts first (`directory:` listings: the directory's own copy, then the worktrees in the order `git worktree list` reports them, main worktree first).
 
 ## Reading Session Messages
 
@@ -40,7 +47,7 @@ messages.each { |msg| puts "[#{msg.type}] #{msg.message}" }
 ClaudeAgentSDK.get_session_messages(session_id: 'abc-123-...', offset: 10, limit: 20)
 ```
 
-Each `SessionMessage` includes `type` (`"user"` or `"assistant"`), `uuid`, `session_id`, and `message` (the raw API message Hash, read from the transcript, so its keys are Strings: `msg.message['content']`; see [Hash keys](types.md#hash-keys)).
+Each `SessionMessage` includes `type` (`"user"` or `"assistant"`), `uuid`, `session_id`, and `message` (the raw API message Hash, read from the transcript, so its keys are Strings: `msg.message['content']`; see [Hash keys](types.md#hash-keys)). Messages come back in conversation order. The CLI writes one entry per content block, so an assistant turn with several tool calls comes back as several `assistant` messages and one `user` message per `tool_result`; every result follows the `tool_use` it answers and precedes the next assistant turn. Transcripts are read as UTF-8 whatever the process locale is; a line that does not parse (the last line of a session whose CLI was killed mid-write) is skipped, and bytes that are not valid UTF-8 inside a line that does parse come back as U+FFFD.
 
 ## Reading Subagent Transcripts
 
@@ -112,6 +119,8 @@ ClaudeAgentSDK.delete_session(
 )
 ```
 
+Delete only sessions whose CLI process has exited. A CLI that is still running the session does not notice the deletion: its next write recreates the file with only the entries it writes from then on, so the session comes back in listings holding just the later part of the conversation.
+
 ## Forking a Session
 
 ```ruby
@@ -129,7 +138,9 @@ ClaudeAgentSDK.fork_session(
 )
 ```
 
-> Session mutations use append-only JSONL writes with `O_WRONLY | O_APPEND` (no `O_CREAT`) for TOCTOU safety. They are safe to call while the session is open in a CLI process. `fork_session` writes and closes a private staging file before atomically publishing it with a hard link, so partial forks are not discoverable and existing sessions are never overwritten. The project filesystem must support hard links; publication failures leave the source and any existing destination untouched.
+Without `title:` the fork is named after its source, `<title> (fork)`: the title the listing shows for the source (its custom title, else its AI title), else its first prompt, else `Forked session`. The disk and the store path use the same rule.
+
+> `rename_session` and `tag_session` use append-only JSONL writes with `O_WRONLY | O_APPEND` (no `O_CREAT`) for TOCTOU safety. They, and `fork_session`, are safe to call while the session is open in a CLI process; `delete_session` is not (see [Deleting a Session](#deleting-a-session)). `fork_session` writes and closes a private staging file before atomically publishing it with a hard link, so partial forks are not discoverable and existing sessions are never overwritten. The project filesystem must support hard links; publication failures leave the source and any existing destination untouched.
 
 ## Resuming at a Specific Message
 
@@ -261,10 +272,11 @@ normal spawn path and `continue_conversation` moves on to the next candidate.
 > `HOME` the subprocess will see — `options.env`'s `HOME` when it sets one):
 >
 > - `.credentials.json`, with the OAuth `refreshToken` removed so the resumed
->   subprocess can't consume it. On macOS with the default config dir and no
+>   subprocess can't consume it. On macOS with no
 >   `ANTHROPIC_API_KEY`/`CLAUDE_CODE_OAUTH_TOKEN`, the credentials come from
->   the Keychain entry when one exists (the redirected config dir would
->   otherwise miss it).
+>   the CLI's Keychain entry for your config dir when one exists (the
+>   redirected config dir would otherwise miss it) — with a custom
+>   `CLAUDE_CONFIG_DIR`, only when that directory has no `.credentials.json`.
 > - `.claude.json` (from `$CLAUDE_CONFIG_DIR/.claude.json` when set, else
 >   `~/.claude.json`).
 > - User `settings.json` and `cowork_settings.json` — so `apiKeyHelper`, `env`,
@@ -276,7 +288,10 @@ normal spawn path and `continue_conversation` moves on to the next candidate.
 > Everything else in your config dir is **not** visible to the subprocess —
 > notably user `CLAUDE.md`, `agents/`, `skills/`, and `plugins/` (so, with the
 > plugin keys stripped, user plugins are off) — so a store-backed resume can
-> still behave differently from a plain `resume:` of the same session.
+> still behave differently from a plain `resume:` of the same session. The
+> project's auto-memory is part of that: the temp config dir has no
+> `projects/<key>/memory/`, so a store-backed resume neither loads the memory
+> you already have nor keeps what the session writes to it.
 > Project-level `.claude/*` still applies (it resolves from `cwd`), and
 > hooks/options passed programmatically via `ClaudeAgentOptions` are unaffected.
 > Seeded files are written owner-only (`0600`); a missing source file is simply
@@ -286,14 +301,26 @@ normal spawn path and `continue_conversation` moves on to the next candidate.
 > (terminal append failures — timeouts immediately, other failures after up to
 > three attempts — surfaced as `MirrorErrorMessage`):
 > the store copy is then incomplete and the temp dir holds the only copy of the
-> dropped turns, so the SDK scrubs the credential copies, keeps the transcripts,
-> and warns with the preserved path so you can import them into the store.
+> dropped turns, so the SDK moves it into a fresh private directory next to it
+> (`claude-preserved-resume-*`), keeps the transcripts (`projects/`) there,
+> deletes everything else — the seeded credential and settings copies and
+> whatever the CLI wrote beside them, such as its `backups/` copy of
+> `.claude.json` — and warns with the new path so you can import them into the
+> store. If what it moved is not the directory the SDK created (the path had
+> been replaced, for instance by a symlink), or it cannot be moved, the SDK
+> deletes nothing and the warning says the scrub was skipped and why; if an
+> entry cannot be removed, the warning says the scrub failed and names what is
+> left.
 
 ### Implementing an adapter
 
 Subclass `ClaudeAgentSDK::SessionStore` (or duck-type it). Only `#append` and
 `#load` are required; `#list_sessions`, `#delete`, `#list_subkeys`, and
 `#list_session_summaries` are optional and probed via `SessionStore.implements?`.
+An optional method that raises `NotImplementedError` when called counts as not
+implemented too (the stub a delegating wrapper inherits, or an adapter declining
+it at run time): the SDK takes the same fallback, and the conformance suite
+skips that method's contracts.
 Report `mtime` as epoch milliseconds; the SDK also accepts numeric-string,
 ISO-8601-string and `Time` mtimes (ordering them correctly and reporting them
 as Integer epoch ms in `last_modified`), but anything else sorts as oldest and
@@ -489,7 +516,8 @@ be resumed with `session_store:` + `resume:` from the original directory.
 Re-importing appends the entries again, so adapters should dedupe by
 `entry['uuid']`. It raises `ArgumentError` for an invalid `session_id` and
 `Errno::ENOENT` when the transcript cannot be found; an unparseable line is
-skipped with a warning.
+skipped with a warning, and bytes that are not valid UTF-8 inside a line that
+does parse are stored as U+FFFD (an adapter could not serialize them).
 
 > **Deprecated:** the separate store functions (`list_sessions_from_store`,
 > `get_session_info_from_store`, `get_session_messages_from_store`,

data/docs/subagents.md

@@ -158,7 +158,7 @@ See [hook fields and permission cancellation](hooks-and-permissions.md).
 
 ## Minimal example
 
-[`examples/subagent_status_example.rb`](../examples/subagent_status_example.rb)
+[`examples/subagent_status_example.rb`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/subagent_status_example.rb)
 defines a tool-free reviewer, registers lifecycle hooks, reads metadata, and
 prints task events and forwarded child text without building a status model: