claude-agent-sdk 0.34.0 → 0.36.0

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`. That holds whatever the process's working directory is (a daemonized worker, a job runner started elsewhere): the Railtie points `ClaudeAgentSDK::CLIInstaller.root` at `Rails.root` during boot, before `config/initializers` run, so an initializer can still set a different root, and a root already set in `config/application.rb` is kept. 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`. For the same reason the task never sees a root set in `config/initializers`; if you move the CLI elsewhere, set `CLIInstaller.root` in `config/application.rb`, which both the task and discovery honour. 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
 
@@ -10,8 +53,7 @@ You do **not** need to think about this. By default (`callback_scheduling: :thre
 
 ```ruby
 tool = ClaudeAgentSDK.create_tool('lookup_user', 'Look up a user', { id: Integer }) do |args|
-  user = User.find(args[:id])                # just works
-  { content: [{ type: 'text', text: user.name }] }
+  User.find(args[:id]).name                  # just works
 end
 
 ClaudeAgentSDK.query(prompt: '...') do |message|
@@ -23,17 +65,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.
 
@@ -76,7 +126,7 @@ The one real risk: **scheduler-opaque blocking stalls the whole reactor.** CPU-b
 ```ruby
 tool = ClaudeAgentSDK.create_tool('lookup', 'Query legacy DB', { id: String }) do |args|
   row = ClaudeAgentSDK.offload { legacy_client.fetch(args[:id]) }  # plain thread
-  { content: [{ type: 'text', text: row.to_json }] }
+  row.to_json
 end
 ```
 
@@ -96,38 +146,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 +183,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 +199,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 +213,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 +287,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/docs/sessions.md

@@ -1,8 +1,8 @@
 # Session Browsing & Mutations
 
-Browse, read, mutate, fork, and resume Claude Code sessions directly from Ruby — no CLI subprocess required. 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.
+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.
+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.
 
 ## Listing Sessions
 
@@ -25,7 +25,9 @@ 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 (a blank `cwd` falls back to the project path).
+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.
+
+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).
 
 ## Reading Session Messages
 
@@ -49,7 +51,7 @@ ids = ClaudeAgentSDK.list_subagents(session_id: "uuid-here", directory: "/path/t
 messages = ClaudeAgentSDK.get_subagent_messages(session_id: "uuid-here", agent_id: ids.first, limit: 50)
 ```
 
-With `directory:` given, only that project and its git worktrees are searched (no global fallback). Store-backed counterparts: `list_subagents_from_store` / `get_subagent_messages_from_store`.
+With `directory:` given, only that project and its git worktrees are searched (no global fallback). Pass `session_store:` to read the subagents mirrored into a store instead.
 
 > Each returned `SessionMessage` carries `parent_tool_use_id` — the id of the Agent `tool_use` block in the parent session that spawned this subagent — and `parent_agent_id`, the spawning subagent's id for nested subagents. Both are read from the `agent-<id>.meta.json` sidecar beside the transcript (or the `agent_metadata` entry in a `SessionStore`), and are `nil` when it is missing or unusable.
 
@@ -57,8 +59,8 @@ With `directory:` given, only that project and its git worktrees are searched (n
 
 ```ruby
 meta = ClaudeAgentSDK.get_subagent_metadata(session_id: session_id, agent_id: agent_id, directory: project)
-meta = ClaudeAgentSDK.get_subagent_metadata_from_store(
-  session_store: store, session_id: session_id, agent_id: agent_id, directory: project
+meta = ClaudeAgentSDK.get_subagent_metadata(
+  session_id: session_id, agent_id: agent_id, directory: project, session_store: store
 )
 meta&.dig('toolUseId')    # spawning Agent tool call; not task_id
 meta&.dig('parentAgentId')
@@ -211,6 +213,14 @@ ClaudeAgentSDK.query(
 ) { |message| }
 ```
 
+The mirror maps each transcript file the CLI reports to a store key relative to
+the subprocess's projects dir: `CLAUDE_CONFIG_DIR` from `options.env` (else
+`ENV`), else `~/.claude` under the `HOME` the subprocess sees (`options.env`'s
+`HOME` when it sets one). When neither exists — no `CLAUDE_CONFIG_DIR` and no
+usable home — the session still runs, but nothing is mirrored: each unmappable
+batch is reported as a `MirrorErrorMessage` (with a `nil` key) telling you to
+set `CLAUDE_CONFIG_DIR`.
+
 Relevant options: `session_store`, `session_store_flush` (`"batched"` default, or
 `"eager"` to flush each frame as soon as the store is free — frames arriving
 while an append is in flight are coalesced into the next append, so a slow
@@ -228,7 +238,8 @@ normal spawn path and `continue_conversation` moves on to the next candidate.
 > **Store-backed resume runs against a temp `CLAUDE_CONFIG_DIR`.** The SDK
 > materializes the session transcript (plus subagent transcripts, when the
 > store implements `#list_subkeys`) into it and seeds it from your real config
-> dir (`CLAUDE_CONFIG_DIR` from `options.env`/`ENV`, else `~/.claude`):
+> dir (`CLAUDE_CONFIG_DIR` from `options.env`/`ENV`, else `~/.claude` under the
+> `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
@@ -264,8 +275,11 @@ normal spawn path and `continue_conversation` moves on to the next candidate.
 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?`.
-Report `mtime` as epoch milliseconds; the SDK also orders numeric-string and
-ISO-8601-string mtimes correctly, but anything else sorts as oldest. Subagent
+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
+reads as `0`. `continue_conversation` picks the newest candidate by the same
+rule as the listings (equal mtimes: lowest `session_id`). Subagent
 transcripts arrive under a `subpath` key such as `subagents/agent-<agent_id>`
 (or nested `subagents/workflows/<runId>/agent-<agent_id>`); on a store without
 `#list_subkeys` the subagent readers build `subagents/agent-<agent_id>` from the
@@ -340,30 +354,52 @@ thread for default adapters, inside the cooperative timeout for inline
 declarers (the cancellation passes through the wrapper un-swallowed and the
 wrapper's `ensure` runs at cancellation).
 
-### Store-backed helpers
-
-The browsing/mutation helpers above have store-backed counterparts that take a
-`session_store:` and operate on the store instead of local disk:
-
-- Reads: `list_sessions_from_store`, `get_session_info_from_store`,
-  `get_session_messages_from_store`, `list_subagents_from_store`,
-  `get_subagent_messages_from_store`. Unlike the disk readers (where a nil
-  `directory:` searches every project directory), the store helpers key every
-  read by `project_key` and a nil `directory:` defaults to the **current
-  working directory** — the `SessionStore` interface has no way to enumerate
-  project keys (parity with the Python SDK).
-- Mutations: `rename_session_via_store`, `tag_session_via_store`,
-  `delete_session_via_store` (a no-op on append-only stores without `#delete`),
-  `fork_session_via_store`. Like their disk counterparts, rename, tag, and fork
-  raise `Errno::ENOENT` for a session the store has never seen (`#load`
-  returns nil or `[]`) instead of appending to — and so creating — a phantom
-  session. Rename/tag probe with one `#load` before appending; the probe is
-  check-then-act, so a session deleted concurrently between the probe and the
-  append can still be recreated by that append.
-- Migration: `import_session_to_store` replays a local on-disk session (and its
-  subagents) into a store.
+### Store-backed sessions
+
+Every browsing/mutation function above takes an optional `session_store:`.
+Omitted (or `nil`), it works on local disk as described above; given a store,
+it operates on the store instead, with the same arguments:
 
 ```ruby
-ClaudeAgentSDK.rename_session_via_store(session_store: store, session_id: '550e8400-...', title: 'Renamed')
-forked = ClaudeAgentSDK.fork_session_via_store(session_store: store, session_id: '550e8400-...')
+ClaudeAgentSDK.list_sessions(session_store: store, limit: 10)
+ClaudeAgentSDK.get_session_messages(session_id: '550e8400-...', session_store: store)
+ClaudeAgentSDK.rename_session(session_id: '550e8400-...', title: 'Renamed', session_store: store)
+forked = ClaudeAgentSDK.fork_session(session_id: '550e8400-...', session_store: store)
 ```
+
+Where the store path differs from the disk path:
+
+- **`directory: nil` means the current working directory.** The disk readers
+  search every project directory when `directory:` is nil; a store keys every
+  read and write by `project_key` and has no way to enumerate project keys
+  (parity with the Python SDK).
+- **`include_worktrees:` is disk-only.** A store has no worktrees, so with
+  `session_store:` only the default `true` is accepted; `false` or `nil`
+  raises `ArgumentError` rather than being silently ignored.
+- `list_sessions` uses the store's `#list_session_summaries` when implemented,
+  else `#list_sessions` plus one `#load` per listed session; a store with
+  neither raises `ArgumentError`. `list_subagents` requires `#list_subkeys`.
+- Rename, tag, and fork raise `Errno::ENOENT` for a session the store has
+  never seen (`#load` returns nil or `[]`) instead of appending to — and so
+  creating — a phantom session, like their disk counterparts. Rename/tag probe
+  with one `#load` before appending; the probe is check-then-act, so a session
+  deleted concurrently between the probe and the append can still be
+  recreated by that append. The appended entries carry a fresh `uuid` and
+  `timestamp`, so adapters that dedupe by `uuid` treat them correctly.
+- `delete_session` is a no-op on append-only stores without `#delete` (the
+  disk path raises `Errno::ENOENT` for an unknown session); whether subagent
+  entries are removed too depends on the store's delete cascade.
+
+To migrate, `import_session_to_store` replays a local on-disk session (and its
+subagents) into a store.
+
+> **Deprecated:** the separate store functions (`list_sessions_from_store`,
+> `get_session_info_from_store`, `get_session_messages_from_store`,
+> `list_subagents_from_store`, `get_subagent_metadata_from_store`,
+> `get_subagent_messages_from_store`, `rename_session_via_store`,
+> `tag_session_via_store`, `delete_session_via_store`,
+> `fork_session_via_store`) still work unchanged but print a one-time
+> deprecation warning and will be removed in 1.0. Replace
+> `ClaudeAgentSDK.x_from_store(session_store: store, ...)` or
+> `x_via_store(session_store: store, ...)` with
+> `ClaudeAgentSDK.x(..., session_store: store)`.

data/lib/claude_agent_sdk/cancellation_signal.rb

@@ -20,7 +20,8 @@ module ClaudeAgentSDK
       cancelled?
     end
 
-    # @api private Called by the SDK when the request is no longer actionable.
+    # Called by the SDK when the request is no longer actionable.
+    # @api private
     def cancel
       @queue.close
     end

data/lib/claude_agent_sdk/cli_installer.rb

@@ -51,9 +51,10 @@ module ClaudeAgentSDK
     BINARY_NAME = 'claude'
     VERSION_FILE = 'VERSION'
     LOCK_FILE = '.install.lock'
-    # Relative to Dir.pwd, resolved at CALL time by .default_dir — an absolute
-    # constant would freeze the working directory as of require time, which is
-    # wrong for anything that chdirs (Rake tasks, bin/setup, test suites).
+    # Relative to .root (Dir.pwd when unset), resolved at CALL time by
+    # .default_dir — an absolute constant would freeze the working directory
+    # as of require time, which is wrong for anything that chdirs (Rake
+    # tasks, bin/setup, test suites).
     DEFAULT_DIR = File.join('vendor', 'claude')
     # Response caps. The dist-tag endpoints return a bare version string and
     # manifests are a few KB; anything larger is a misrouted response, not
@@ -191,13 +192,13 @@ module ClaudeAgentSDK
           raise CLIInstallError, "Failed to fetch #{url}: #{e.class}: #{e.message}"
         end
 
-        def follow_redirect(uri, response, redirects_left, &block)
+        def follow_redirect(uri, response, redirects_left, &)
           raise CLIInstallError, "Too many redirects while fetching #{uri}" if redirects_left <= 0
 
           location = response['location'].to_s
           raise CLIInstallError, "Redirect from #{uri} is missing a Location header" if location.empty?
 
-          with_response(URI.join(uri.to_s, location), redirects_left - 1, &block)
+          with_response(URI.join(uri.to_s, location), redirects_left - 1, &)
         end
       end
     end
@@ -309,10 +310,39 @@ module ClaudeAgentSDK
     end
 
     class << self
-      # Absolute path of the default install directory, resolved against the
-      # current working directory each time it is asked for.
+      # The directory DEFAULT_DIR is resolved against, or nil (the default)
+      # for the current working directory at call time.
+      #
+      # Set it when the process cwd is not the project root — a daemonized
+      # worker, a job runner started from /, a systemd unit without
+      # WorkingDirectory — so .default_dir, and with it .installed_path and
+      # SubprocessCLITransport's discovery of the vendored binary, still
+      # point at <root>/vendor/claude. The Rails Railtie sets it to
+      # Rails.root unless something already has.
+      #
+      # Safe to read from any thread without a lock: the value is a single
+      # frozen String reference (or nil), replaced whole by .root=, so a
+      # reader sees either the old root or the new one, never a partial one.
+      #
+      # @return [String, nil] an absolute path, or nil
+      attr_reader :root
+
+      # @param path [String, Pathname, nil] the project root. A relative path
+      #   is absolutized against the working directory NOW, once, so a later
+      #   chdir cannot move it. nil restores the Dir.pwd default.
+      # @raise [ArgumentError] for an empty path (which would silently pin
+      #   the current working directory)
+      def root=(path)
+        raise ArgumentError, 'CLIInstaller.root must be a non-empty path or nil' if path&.to_s&.empty?
+
+        @root = path && File.expand_path(path).freeze
+      end
+
+      # Absolute path of the default install directory: vendor/claude under
+      # .root, or under the current working directory (resolved each time it
+      # is asked for) while .root is unset.
       def default_dir
-        File.expand_path(DEFAULT_DIR, Dir.pwd)
+        File.expand_path(DEFAULT_DIR, root || Dir.pwd)
       end
 
       # Install the CLI into +dir+ and return the absolute path of the binary.

data/lib/claude_agent_sdk/deprecation.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ClaudeAgentSDK
+  # One-time deprecation warnings for public API slated for removal in the
+  # next major release (see the deprecation policy in issue #126).
+  #
+  # Emitted with plain Kernel#warn, deliberately NOT `category: :deprecated`:
+  # Ruby hides that category unless Warning[:deprecated] is enabled (off by
+  # default since 2.7.2, still off on 3.2-3.4), so a category-tagged warning
+  # would reach almost nobody before the removal. Plain warn is visible by
+  # default and still silenced by `-W0` / `$VERBOSE = nil`.
+  #
+  # @api private
+  module Deprecation
+    @warned = Set.new
+    @mutex = Mutex.new
+
+    class << self
+      # Warn once per process that ClaudeAgentSDK.+name+ is deprecated.
+      #
+      # Must be called directly from the deprecated method: `uplevel: 2`
+      # skips this frame and the deprecated method's, so the warning names
+      # the caller's file:line.
+      #
+      # Best-effort like OptionWarnings#emit: a closed or broken $stderr must
+      # not turn a still-supported call into an IOError. The name stays
+      # recorded either way (once per process means once).
+      #
+      # @param name [Symbol] the deprecated ClaudeAgentSDK module method
+      # @param replacement [String] the call to use instead, without the
+      #   ClaudeAgentSDK. prefix
+      # @return [void]
+      def warn_once(name, replacement)
+        first = @mutex.synchronize { @warned.add?(name) }
+        return unless first
+
+        begin
+          warn("ClaudeAgentSDK.#{name} is deprecated and will be removed in 1.0; " \
+               "use ClaudeAgentSDK.#{replacement}", uplevel: 2)
+        rescue StandardError
+          nil
+        end
+      end
+
+      # Test hook: forget which deprecations were already reported.
+      def reset!
+        @mutex.synchronize { @warned.clear }
+      end
+    end
+  end
+end

data/lib/claude_agent_sdk/errors.rb

@@ -23,6 +23,14 @@ module ClaudeAgentSDK
   # missing manifest entry, checksum mismatch).
   class CLIInstallError < ClaudeSDKError; end
 
+  # Raised by the local-disk session APIs (list_sessions, get_session_*,
+  # rename/tag/delete/fork_session, import_session_to_store) when the Claude
+  # config directory cannot be located: CLAUDE_CONFIG_DIR is unset and there
+  # is no usable home directory for the default ~/.claude (HOME unset with no
+  # passwd entry, as under `docker --user` in a minimal image, or an empty or
+  # relative HOME). Set CLAUDE_CONFIG_DIR to fix it.
+  class ConfigDirError < ClaudeSDKError; end
+
   # Raised when the CLI process fails
   class ProcessError < ClaudeSDKError
     attr_reader :exit_code, :stderr