claude-agent-sdk 0.33.1 → 0.35.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` 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.
 
@@ -67,7 +118,9 @@ With `:inline`, every user callback — message blocks, hooks, permission callba
 - 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.
+- A cooperative deadline bounds the cancellation *request*, not the callback's completion: the cancellation is delivered once, and whatever the callback's `ensure` does afterwards runs unbounded on the reactor fiber. Fiber-aware cleanup delays only that callback (and the CLI waiting on its reply); scheduler-opaque cleanup — a file `fsync`, a non-fiber-aware driver, a GVL-holding C extension — stalls every job on the reactor for as long as it takes, and no deadline can interrupt it. Keep inline cleanup fiber-aware, or stay on `:thread` scheduling when you need a hard bound on the whole invocation.
 - The CLI's cancellation of an in-flight callback (e.g. permission prompt superseded) can now actually interrupt it at a suspension point.
+- Calling `client.disconnect` from inside an inline **control-request callback** (a hook, `can_use_tool`, or an SDK MCP handler) works, with one difference from `:thread` mode: the callback's own task is a child of the read task that `disconnect` stops, so after the teardown has completed (transport closed, pending control waiters released) the deferred `Async::Stop` unwinds the callback — `disconnect` raises there instead of returning. Put cleanup in `ensure`; a `rescue StandardError` will not see it (it is not a `StandardError`). In `:thread` mode `disconnect` returns normally on the worker thread and the callback's return value is simply dropped. Either way the callback's response is never sent — the session is gone. Message blocks and observers run on the caller's task, not under the read task, so a `disconnect` from one of those returns normally in both modes; a streaming-input enumerator that calls `disconnect` unwinds with `Async::Stop` in both modes.
 
 The one real risk: **scheduler-opaque blocking stalls the whole reactor.** CPU-bound work or a GVL-holding C extension inside an inline callback blocks every job on that worker, not just yours. Blocking that releases the GVL and pure-Ruby CPU work can be moved onto a thread explicitly:
 
@@ -94,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:
@@ -136,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
@@ -158,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
@@ -174,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
 ```
 
@@ -248,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/docs/sessions.md

@@ -2,7 +2,7 @@
 
 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.
 
-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.
+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.
 
 ## Listing Sessions
 
@@ -25,6 +25,8 @@ 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).
+
 ## Reading Session Messages
 
 ```ruby
@@ -125,7 +127,7 @@ 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` uses `O_CREAT | O_EXCL` to prevent race conditions.
+> 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.
 
 ## Resuming at a Specific Message
 
@@ -210,18 +212,45 @@ ClaudeAgentSDK.query(
 ```
 
 Relevant options: `session_store`, `session_store_flush` (`"batched"` default, or
-`"eager"` to flush after every frame), and `load_timeout_ms` (per store call
-during resume materialization, default `60_000`).
-
-> **Store-backed resume runs against a bare temp `CLAUDE_CONFIG_DIR`.** Only the
-> transcript plus `.credentials.json` (redacted) and `.claude.json` are
-> materialized into it — user-scope `settings.json` (hooks, `permissions`),
-> user `CLAUDE.md`, `agents/`, `skills/`, and `plugins/` from your real config
-> dir are **not** visible to the subprocess, so a store-backed resume can
-> behave differently from a plain `resume:` of the same session. Project-level
-> `.claude/*` still applies (it resolves from `cwd`), and hooks/options passed
-> programmatically via `ClaudeAgentOptions` are unaffected. This matches the
-> Python and TypeScript SDKs.
+`"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
+store never accumulates one background task per frame), and `load_timeout_ms`
+(per store call during resume materialization, default `60_000`).
+
+Resume materialization re-serializes each loaded entry to JSONL. An entry that
+cannot be serialized (NaN/Infinity, invalid UTF-8, circular nesting), an
+unserializable subagent metadata sidecar, or a subkey that is not a safe
+relative String path is skipped with a warning on stderr (naming the entry's
+`uuid` when it has one) rather than aborting the resume. A session left with
+no usable entries is treated like an empty one: `resume:` falls through to the
+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`):
+>
+> - `.credentials.json`, with the OAuth `refreshToken` removed so the resumed
+>   subprocess can't consume it. On macOS with the default config dir and 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).
+> - `.claude.json` (from `$CLAUDE_CONFIG_DIR/.claude.json` when set, else
+>   `~/.claude.json`).
+> - User `settings.json` and `cowork_settings.json` — so `apiKeyHelper`, `env`,
+>   hooks and `permissions` still apply — minus `enabledPlugins`,
+>   `extraKnownMarketplaces` and `env.CLAUDE_CONFIG_DIR`, which would misbehave
+>   under the redirected config dir (plugin declarations would re-install every
+>   declared marketplace on each resume).
+>
+> 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.
+> 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
+> skipped.
 >
 > The temp dir is deleted at disconnect — **unless the mirror dropped batches**
 > (terminal append failures — timeouts immediately, other failures after up to
@@ -235,6 +264,13 @@ during resume materialization, default `60_000`).
 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
+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
+caller's `agent_id`, which the SDK first restricts to `[A-Za-z0-9._-]+`
+(never `.`/`..`), so a path- or prefix-keyed adapter cannot be re-routed by it.
 Validate your adapter with the shipped, framework-agnostic conformance harness:
 
 ```ruby
@@ -282,6 +318,16 @@ Declaring `:inline` means the calls run in place on the reactor fiber under a
   The drop is surfaced like every dropped batch — `MirrorErrorMessage` on
   the stream, `batches_dropped?` on the batcher — and the local transcript
   remains the source of truth, so nothing is lost from the session itself.
+- The timeout bounds the cancellation **request**, not the call's
+  completion: the cancellation is delivered once, at the next suspension
+  point, and the adapter's `ensure` / rescue cleanup then runs unbounded on
+  the reactor fiber before the timeout is reported. Fiber-aware cleanup
+  (closing an async client, releasing an async lock) delays only that call;
+  scheduler-opaque cleanup — an `fsync`, a non-fiber-aware driver's
+  disconnect, a GVL-holding C extension — stalls the whole reactor for its
+  duration, and no deadline can interrupt it. Keep inline cleanup
+  fiber-aware, or leave the adapter on the default thread hop when a hard
+  bound on the whole call matters more than fiber affinity.
 
 Anything other than `:thread`/`:inline` raises `ArgumentError` when the
 session is set up; without a reactor the hard thread-hop bound still applies
@@ -308,7 +354,12 @@ The browsing/mutation helpers above have store-backed counterparts that take a
   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`.
+  `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.
 

data/lib/claude_agent_sdk/cli_installer.rb

@@ -26,7 +26,9 @@ module ClaudeAgentSDK
   # Stdlib only (net/http, json, digest, fileutils, rbconfig) — the gem gains
   # no runtime dependency for this.
   #
-  # @example Pin a version in bin/setup or a Dockerfile build step
+  # @example Install the gem's tested version in bin/setup or a Dockerfile build step
+  #   ClaudeAgentSDK::CLIInstaller.install_pinned
+  # @example Pin a version of your own
   #   ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')
   module CLIInstaller
     BASE_URL = 'https://downloads.claude.ai/claude-code-releases'
@@ -39,6 +41,13 @@ module ClaudeAgentSDK
     # path — silently installing something other than the pinned version.
     VERSION_PATTERN = /\A\d+\.\d+\.\d+(-[A-Za-z0-9.-]+)?\z/
     CHECKSUM_PATTERN = /\A[0-9a-f]{64}\z/
+    # The CLI version this gem release is developed and tested against — the
+    # Ruby equivalent of the Python SDK's bundled-CLI pin (_cli_version.py),
+    # except nothing is shipped inside the gem; +install_pinned+ downloads it.
+    # Single source of truth: bumped here (and only here) by
+    # .github/workflows/cli-pin-bump.yml or a Python-sync release, so a
+    # Dependabot bump of the gem carries the CLI forward with it.
+    PINNED_CLI_VERSION = '2.1.280'
     BINARY_NAME = 'claude'
     VERSION_FILE = 'VERSION'
     LOCK_FILE = '.install.lock'
@@ -263,34 +272,33 @@ module ClaudeAgentSDK
       end
     end
 
-    # The VERSION file: line 1 the installed version, line 2 the SHA-256 of the
-    # binary that was verified at install time. The checksum is what lets the
-    # idempotency shortcut trust the vendored binary without a network call —
-    # a truncated, swapped or half-written binary no longer looks installed.
-    # An older single-line VERSION file simply reads as "no metadata", which
-    # triggers a clean reinstall.
+    # The VERSION file: version, verified SHA-256, and target platform, one
+    # per line. Both platform and checksum must match before trusting a cached
+    # binary offline: a cache copied between OS/CPU/libc targets is not usable.
+    # Older one- or two-line files lack that proof and trigger a clean reinstall.
     module Metadata
       class << self
         def read(dir)
           path = File.join(dir, VERSION_FILE)
           return nil unless File.file?(path)
 
-          version, checksum = File.read(path, METADATA_READ_LIMIT).to_s.split("\n", 3)
+          version, checksum, platform = File.read(path, METADATA_READ_LIMIT).to_s.split("\n", 4)
           version = version.to_s.strip
           checksum = checksum.to_s.strip.downcase
-          return nil unless version.match?(VERSION_PATTERN) && checksum.match?(CHECKSUM_PATTERN)
+          platform = platform.to_s.strip
+          return nil unless version.match?(VERSION_PATTERN) && checksum.match?(CHECKSUM_PATTERN) && !platform.empty?
 
-          { version: version, checksum: checksum }
+          { version: version, checksum: checksum, platform: platform }
         end
 
         # Atomic: an unpredictable temp name opened O_EXCL, then renamed over
         # the old file. Without this a reader could observe a half-written
         # VERSION, or (worse) the previous version paired with a new binary.
-        def write(dir, version, checksum)
+        def write(dir, version, checksum, platform)
           tmp = File.join(dir, "#{VERSION_FILE}.#{SecureRandom.hex(8)}.tmp")
           begin
             File.open(tmp, File::WRONLY | File::CREAT | File::EXCL, 0o644) do |file|
-              file.write("#{version}\n#{checksum}\n")
+              file.write("#{version}\n#{checksum}\n#{platform}\n")
             end
             File.rename(tmp, File.join(dir, VERSION_FILE))
           ensure
@@ -334,9 +342,9 @@ module ClaudeAgentSDK
         with_install_lock(dir) do
           sweep_stale_temp_files(dir)
           resolved = Release.resolve_version(requested)
-          next binary if installed?(dir, resolved)
-
           platform = Platform.detect
+          next binary if installed?(dir, resolved, platform)
+
           publish(dir, binary, resolved, platform, Release.platform_entry(resolved, platform))
           binary
         end
@@ -349,6 +357,14 @@ module ClaudeAgentSDK
         raise CLIInstallError, "Failed to install the Claude Code CLI into #{dir}: #{e.class}: #{e.message}"
       end
 
+      # Install PINNED_CLI_VERSION — the version this gem release was tested
+      # against. The Dockerfile / bin/setup form of "pin the tested pair":
+      # bumping the gem moves the CLI with it, with no version literal in the
+      # caller to keep in sync.
+      def install_pinned(dir: nil)
+        install(version: PINNED_CLI_VERSION, dir: dir)
+      end
+
       # Path of an already-installed binary, or nil.
       #
       # Deliberately lock-free, because #publish makes the lock unnecessary
@@ -400,13 +416,13 @@ module ClaudeAgentSDK
       end
 
       # True only when the vendored binary is byte-for-byte the one recorded
-      # by a previous install of this exact version. No network access.
-      def installed?(dir, version)
+      # by a previous install of this exact version and platform. No network access.
+      def installed?(dir, version, platform)
         binary = installed_path(dir: dir)
         return false unless binary
 
         recorded = Metadata.read(dir)
-        return false unless recorded && recorded[:version] == version
+        return false unless recorded && recorded[:version] == version && recorded[:platform] == platform
 
         Digest::SHA256.file(binary).hexdigest == recorded[:checksum]
       rescue SystemCallError
@@ -434,7 +450,7 @@ module ClaudeAgentSDK
         tmp = "#{binary}.download.#{SecureRandom.hex(8)}"
         begin
           fetch_verified(version, platform, entry, tmp)
-          Metadata.write(dir, version, entry[:checksum])
+          Metadata.write(dir, version, entry[:checksum], platform)
           File.rename(tmp, binary)
         ensure
           FileUtils.rm_f(tmp)

data/lib/claude_agent_sdk/command_builder.rb

@@ -373,7 +373,7 @@ module ClaudeAgentSDK
     end
 
     # `--thinking-display` toggles between `"summarized"` (visible thinking
-    # text) and `"omitted"` (empty thinking, signature only). Opus 4.7 defaults
+    # text) and `"omitted"` (empty thinking, signature only). Current models default
     # to `"omitted"`, so pass `display: "summarized"` to see reasoning.
     def append_thinking_display(cmd, display)
       return if display.nil?
@@ -444,8 +444,12 @@ module ClaudeAgentSDK
           # Typed Mcp*ServerConfig objects serialize via their wire hash —
           # without this they'd JSON-stringify as "#<...>" via to_s.
           config = config.to_h if config.is_a?(Type)
-          servers_for_cli[name] = if config.is_a?(Hash) && config[:type] == "sdk"
-                                    config.except(:instance)
+          # Same recognition rule as ClaudeAgentSDK.extract_sdk_mcp_servers:
+          # either key style (and a Symbol :sdk type). The live instance is
+          # never serialized — JSON.generate would raise on it or leak its
+          # #to_s onto the command line.
+          servers_for_cli[name] = if config.is_a?(Hash) && (config[:type] || config["type"]).to_s == "sdk"
+                                    config.except(:instance, "instance")
                                   else
                                     config
                                   end
@@ -506,6 +510,10 @@ module ClaudeAgentSDK
     end
 
     def load_settings_file(path)
+      # Match the CLI's path resolution when --settings is passed through
+      # without a sandbox merge: the subprocess runs in options.cwd.
+      # Do not expand lexically: symlink/.. must resolve through the filesystem.
+      path = File.join(@options.cwd&.to_s || Dir.pwd, path) unless File.absolute_path?(path)
       # Missing file: warn and continue with sandbox-only settings (Python
       # parity: logger.warning("Settings file not found: ...") and an empty
       # settings object). Raising here turned a misconfiguration the CLI

data/lib/claude_agent_sdk/configuration.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# default_options= copies through Type.deep_dup_for_options: keep this file
+# loadable on its own (require 'claude_agent_sdk/configuration').
+require_relative 'types'
+
 module ClaudeAgentSDK
   # Configuration class for setting default options
   #
@@ -28,11 +32,59 @@ module ClaudeAgentSDK
   #     prompt: "Hello!",
   #     options: ClaudeAgentOptions.new(model: 'opus')  # overrides default
   #   )
+  #
+  # Assignment stores a frozen deep copy of the Hash (containers, typed
+  # option values such as SandboxSettings, and mutable Strings are copied;
+  # procs, observers, SDK MCP server instances and store adapters keep
+  # identity). To change the defaults, assign a new Hash — in-place mutation
+  # of the stored one (including `<<` on one of its Strings) raises
+  # FrozenError, and later changes to the Hash or Strings you passed in have
+  # no effect.
   class Configuration
-    attr_accessor :default_options
+    # The configured defaults: a frozen snapshot (see class docs).
+    #
+    # @return [Hash]
+    attr_reader :default_options
+
+    EMPTY_DEFAULTS = {}.freeze
+    private_constant :EMPTY_DEFAULTS
 
     def initialize
-      @default_options = {}
+      @default_options = EMPTY_DEFAULTS
+    end
+
+    # The defaults are read at request time by every ClaudeAgentOptions.new
+    # (merge_with_defaults) with no lock, possibly from many threads at once.
+    # A live, caller-owned Hash made that a race: an in-place write from one
+    # thread while another iterated the merge raised "can't add a new key
+    # into hash during iteration" or tore the read. Storing a private frozen
+    # snapshot removes the shared mutable state instead of guarding it — the
+    # ivar swap is atomic, a reader only ever sees a complete Hash, and an
+    # in-place write fails loudly. Only the copy is frozen: the caller's
+    # Hash and objects, and identity leaves, are left untouched.
+    #
+    # @param value [Hash, nil] nil clears the defaults
+    def default_options=(value)
+      @default_options = value.nil? ? EMPTY_DEFAULTS : deep_freeze(Type.deep_dup_for_options(value))
+    end
+
+    private
+
+    # Mirrors Type.deep_dup_for_options' recursion: freeze the containers,
+    # option value copies and String copies it produced (and their nested
+    # state), never a leaf it returned by identity — freezing an
+    # SdkMcpServer or a store adapter would break it. A String reaching here
+    # is either the copier's own copy or was already frozen, so freezing it
+    # never touches a caller's mutable String.
+    def deep_freeze(value)
+      case value
+      when Hash then value.each_value { |v| deep_freeze(v) }
+      when Array then value.each { |v| deep_freeze(v) }
+      when Type::OptionValue then value.instance_variables.each { |ivar| deep_freeze(value.instance_variable_get(ivar)) }
+      when String then nil # nothing nested; fall through to freeze the copy
+      else return value
+      end
+      value.freeze
     end
   end
 

data/lib/claude_agent_sdk/errors.rb

@@ -129,6 +129,15 @@ module ClaudeAgentSDK
 
         data.key?(key) ? data[key] : data[key.to_s]
       end
+
+      # The +api_error_status+ field narrowed to Integer-or-nil — the one
+      # narrowing both #api_error_status and .error_text read, so a "500"
+      # String can neither show up in the message nor go missing from the
+      # accessor on its own.
+      def api_error_status(data)
+        status = field(data, :api_error_status)
+        status.is_a?(Integer) ? status : nil
+      end
     end
     private_constant :Payload
 
@@ -158,7 +167,7 @@ module ClaudeAgentSDK
       subtype = Payload.field(data, :subtype)
       return subtype if subtype.is_a?(String) && !subtype.empty? && subtype != 'success'
 
-      status = Payload.field(data, :api_error_status)
+      status = Payload.api_error_status(data)
       return "API error (HTTP #{status})" unless status.nil?
 
       'unknown error'
@@ -174,8 +183,7 @@ module ClaudeAgentSDK
       @errors = Payload.normalize_errors(Payload.field(data, :errors))
       result = Payload.field(data, :result)
       @result = result.is_a?(String) ? result : nil
-      status = Payload.field(data, :api_error_status)
-      @api_error_status = status.is_a?(Integer) ? status : nil
+      @api_error_status = Payload.api_error_status(data)
       reason = Payload.field(data, :terminal_reason)
       @terminal_reason = reason.is_a?(String) ? reason : nil
       session_id = Payload.field(data, :session_id)