claude-agent-sdk 0.35.0 → 0.37.0

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
 
@@ -38,7 +40,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` (raw API hash).
+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)).
 
 ## Reading Subagent Transcripts
 
@@ -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
@@ -278,6 +292,65 @@ require 'claude_agent_sdk/testing/session_store_conformance'
 ClaudeAgentSDK::Testing.run_session_store_conformance(-> { MyStore.new(...) })
 ```
 
+Keys and entries cross the adapter boundary with **String** keys (see
+[Hash keys](types.md#hash-keys)): a key is `{ 'project_key' => ..., 'session_id' => ... }`,
+plus `'subpath'` for a subagent transcript, and entries are the raw JSONL
+objects. Persist entries verbatim and treat `entry['uuid']` as an idempotency
+key, since a retried or re-imported batch can repeat earlier writes.
+
+#### Helpers for adapter authors
+
+`ClaudeAgentSDK.project_key_for_directory(directory = nil)` returns the
+`project_key` the SDK uses for a directory (a String or Pathname; `nil` means
+the current working directory). It applies the CLI's project-directory naming
+(realpath, Unicode NFC, then the CLI's sanitization), so a key you build
+matches the keys of live-mirrored transcripts:
+
+```ruby
+key = { 'project_key' => ClaudeAgentSDK.project_key_for_directory('/path/to/project'),
+        'session_id' => '550e8400-e29b-41d4-a716-446655440000' }
+store.load(key)
+```
+
+`ClaudeAgentSDK.fold_session_summary(prev, key, entries)` maintains a
+per-session summary incrementally, so an adapter can implement
+`#list_session_summaries` and `list_sessions(session_store:)` can read every
+session's metadata in one call instead of one `#load` per session. Call it
+from `#append`:
+
+```ruby
+def append(key, entries)
+  return if entries.nil? || entries.empty?
+
+  write_entries(key, entries)
+  return unless key['subpath'].nil? # subagent transcripts never feed the summary
+
+  summary = ClaudeAgentSDK.fold_session_summary(read_summary(key), key, entries)
+  summary['mtime'] = write_time_ms # the clock #list_sessions reports
+  write_summary(key, summary)
+end
+
+def list_session_summaries(project_key)
+  read_summaries(project_key) # => [{ 'session_id' => ..., 'mtime' => ..., 'data' => {...} }, ...]
+end
+```
+
+- `prev` is the summary you stored for the same key on the previous append,
+  or `nil` on the first one. `entries` are the entries being appended.
+- It returns a new `{ 'session_id', 'mtime', 'data' }` Hash and leaves `prev`
+  unchanged. Every derived field is set-once or last-wins, so the fold never
+  needs earlier entries again.
+- Only call it for main-transcript keys (no `'subpath'`).
+- It does not set `mtime`: it carries `prev`'s value, or `0` for a new
+  session. Stamp it after persisting, from the same clock as the `mtime`
+  your `#list_sessions` returns. When the store also implements
+  `#list_sessions`, a summary whose `mtime` is older than the listed one is
+  treated as stale and the SDK re-derives it from the transcript.
+- `data` is opaque. Store it as returned; its String keys survive a JSON
+  round-trip (JSONB, Redis).
+
+`InMemorySessionStore#append` is a working reference.
+
 Copy-in reference adapters for **S3, Redis, and Postgres** live in
 [`examples/session_stores/`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_stores/README.md), each with a
 production checklist.
@@ -340,30 +413,72 @@ 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:
+
+```ruby
+ClaudeAgentSDK.import_session_to_store(
+  session_id: '550e8400-...',
+  session_store: store,
+  directory: '/path/to/project', # optional; nil searches every project
+  include_subagents: true,       # default
+  batch_size: 500                # default
+)
+```
+
+It streams the transcript and calls `store.append` once per batch. A batch ends
+at `batch_size` entries (default **500**; `nil` or a non-positive value also
+means 500) or at about 1 MiB of JSONL, whichever comes first. Entries are
+keyed under the on-disk project directory name, so the imported session can
+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.
+
+> **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/docs/types.md

@@ -1,6 +1,81 @@
 # Types Reference
 
-See [lib/claude_agent_sdk/types.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/lib/claude_agent_sdk/types.rb) for complete type definitions.
+See [lib/claude_agent_sdk/types/](https://github.com/ya-luotao/claude-agent-sdk-ruby/tree/main/lib/claude_agent_sdk/types) for complete type definitions (one file per area; `types.rb` loads them all).
+
+## Hash keys
+
+Where the SDK hands you a plain Hash rather than a typed object, its key form
+depends on where the data came from. One rule covers every case:
+
+| Source | Key form | Examples |
+|--------|----------|----------|
+| The CLI's live stream-JSON, passed through as-is | **Symbols**, spelled exactly as on the wire | `UserMessage#origin`, `ResultMessage#origin`, `AssistantMessage#usage`, `ResultMessage#usage`, `ResultMessage#model_usage`, `ResultMessage#structured_output`, `UserMessage#tool_use_result`, `SystemMessage#data`, hook `tool_input`, the `can_use_tool` `input`, SDK MCP tool and prompt `args`, `Client#mcp_status`, `Client#context_usage` |
+| Transcripts read from disk or a `SessionStore` | **Strings**, spelled as in the JSONL | `SessionMessage#message`, `get_subagent_metadata`, `SessionStore` keys and entries, `fold_session_summary` input and output |
+
+"As on the wire" means the SDK does not rewrite key names. Structures the CLI
+generates use camelCase (`origin[:fromSession]`, `model_usage` values'
+`:inputTokens` / `:costUSD`, `client.mcp_status[:mcpServers]`), while objects
+the CLI relays from the API keep their snake_case (`usage[:input_tokens]`).
+Nesting follows the same rule all the way down, including keys that are data
+rather than field names: `model_usage` is keyed by model-name Symbols
+(`result.model_usage.each { |model, u| puts "#{model}: $#{u[:costUSD]}" }`).
+
+The wrong key form reads as `nil` rather than raising, so look up the source
+before indexing: `tool_input['command']` on a hook input, or
+`meta[:toolUseId]` on subagent metadata, silently returns `nil`. The Python
+SDK uses String keys everywhere; do not port its lookups literally.
+
+The Symbol side of the rule relies on the transport parsing each line with
+`JSON.parse(line, symbolize_names: true)`. The built-in
+`SubprocessCLITransport` does; a [custom transport](client.md#custom-transport)
+must too.
+
+## Reading and writing attributes
+
+The SDK's typed objects (messages, content blocks, hook inputs and outputs,
+option objects: everything built on `ClaudeAgentSDK::Type`) accept the same
+attribute name in several spellings. These accessors are public API:
+
+```ruby
+msg.session_id          # the attr_accessor
+msg[:session_id]        # Symbol or String, snake_case or camelCase:
+msg['session_id']       #   all four read the same attribute
+msg[:sessionId]
+msg['sessionId']
+msg.sessionId           # camelCase reader (also answers respond_to?)
+```
+
+`#[]` returns `nil` for a name the type does not define, while a misspelled
+method call such as `msg.nope` raises `NoMethodError`. These accessors reach a type's
+**attributes** only; any other method reached this way warns in 0.37 and stops
+working in 1.0 — see [Attributes Only](#attributes-only).
+
+`#[]=` assigns through the attribute's setter, with the same name
+normalization, and returns the assigned value:
+
+```ruby
+msg[:result] = 'edited' # same as msg.result = 'edited'
+```
+
+- It **changes the object you received**. Messages are not frozen or copied
+  on delivery, so a change is visible to anything else holding the same
+  object (for example an observer that received it before your block did).
+  Copy first if you need the original.
+- A name the type does not define is ignored on the types the SDK parses from
+  CLI output. `ClaudeAgentOptions` raises `ArgumentError` for an unknown key (as
+  its constructor and `dup_with` do), and the value types you build and pass in
+  warn once and will raise in 1.0 — see [Unknown Keys](#unknown-keys).
+- Discriminator fields (`type` on the MCP server and system-prompt configs,
+  `behavior` on `PermissionResultAllow` / `PermissionResultDeny`,
+  `hook_event_name` on hook inputs and outputs) are read-only, so
+  assigning them has no effect.
+
+Constructors accept the same spellings: `ResultMessage.new('sessionId' => 'abc')`
+is equivalent to `ResultMessage.new(session_id: 'abc')`.
+
+`SDKSessionInfo` and `SessionMessage` (returned by the session functions) are
+currently plain classes, not `Type`s: use their snake_case accessors
+(`info.session_id`); they have no `#[]`, `#[]=` or camelCase readers.
 
 ## Message Types
 
@@ -134,8 +209,9 @@ turn was cancelled via `Client#interrupt`. `nil` when the CLI did not report
 one (older CLIs, or a result that bypassed the query loop such as a local
 slash command).
 
-`model_usage` values are passed through verbatim from the CLI, so their keys
-are camelCase (the TypeScript/Python SDKs' `ModelUsage` shape): `inputTokens`,
+`model_usage` is passed through verbatim from the CLI (see [Hash keys](#hash-keys)):
+it is keyed by model-name Symbols (`:"claude-sonnet-4-5"`), and each value's
+keys are camelCase Symbols (the TypeScript/Python SDKs' `ModelUsage` shape): `inputTokens`,
 `outputTokens`, `cacheReadInputTokens`, `cacheCreationInputTokens`,
 `webSearchRequests`, `costUSD`, `contextWindow`, `maxOutputTokens`, plus
 optional `canonicalModel` (canonical id used for the pricing lookup, which can
@@ -287,7 +363,7 @@ end
 | `McpHttpServerConfig` | MCP server config for HTTP transport |
 | `SdkPluginConfig` | SDK plugin configuration |
 | `McpServerStatus` | Status of a single MCP server connection (with `.parse`) |
-| `McpStatusResponse` | Response from `get_mcp_status` containing all server statuses (with `.parse`) |
+| `McpStatusResponse` | Typed view of the `Client#mcp_status` / `#get_mcp_status` Hash: `McpStatusResponse.parse(client.mcp_status).mcp_servers` is an Array of `McpServerStatus`. The client itself returns the raw Hash (see [client.md](client.md#mcp-status-and-context-usage-return-hashes)) |
 | `McpServerInfo` | MCP server name and version |
 | `McpToolInfo` | MCP tool name, description, and annotations |
 | `McpToolAnnotations` | MCP tool annotation hints (`read_only`, `destructive`, `open_world`) |
@@ -302,6 +378,32 @@ end
 | `SystemPromptFile` | System prompt loaded from a file path |
 | `ToolsPreset` | Tools preset configuration for base tools selection |
 
+### Unknown Keys
+
+`ClaudeAgentOptions` raises `ArgumentError` on an unknown key. The value types you build and pass *in* used to drop a misspelled key silently; they now print a warning, once per class and key, pointing at your call:
+
+```
+app/agents/reviewer.rb:12: warning: ClaudeAgentSDK::HookMatcher: unknown attribute :matchr ignored; this will raise ArgumentError in 1.0 (known: hooks, matcher, timeout)
+```
+
+**In 1.0 the same call raises `ArgumentError`.** This covers `.new` and `#[]=` on:
+
+- option values: `AgentDefinition`, `SandboxSettings`, `SandboxNetworkConfig`, `SandboxFilesystemConfig`, `ThinkingConfigAdaptive` / `Enabled` / `Disabled`, `TaskBudget`, `SystemPromptPreset` / `Custom` / `File`, `ToolsPreset`, `SdkPluginConfig`, `McpStdioServerConfig`, `McpSSEServerConfig`, `McpHttpServerConfig`, `McpSdkServerConfig`
+- `HookMatcher` and hook outputs: `SyncHookJSONOutput`, `AsyncHookJSONOutput`, every `*HookSpecificOutput`
+- `PermissionResultAllow`, `PermissionResultDeny`, `PermissionUpdate`, `PermissionRuleValue`
+
+Accepted without a warning: Symbol or String keys, snake_case or camelCase spellings, and the fixed discriminator a type sets itself (`type`, `hook_event_name`, `behavior`), so `klass.new(value.to_h)` round-trips. Types the SDK parses from CLI output (messages, content blocks, hook inputs, `ToolPermissionContext`, the MCP status types) stay lenient, so a field added by a newer CLI never warns, and so does every construction through `.from_hash` or `.wrap`. The warning goes through `Kernel#warn`, so `-W0` or `$VERBOSE = nil` silences it.
+
+### Attributes Only
+
+`#[]`, `#[]=` and the camelCase readers (`msg[:session_id]`, `msg['sessionId']`, `msg.sessionId`) are public API for a type's **attributes**: the fields it declares, plus predicates such as `options.forkSession?`. Methods your own code adds to a subclass (an `attr_accessor`, a hand-written reader or setter, a mixin's accessors, a singleton method) count as attributes too. Until now they reached any public method, so `msg[:to_h]` returned a Hash, `msg['freeze']` froze the message and `msg.toH` worked. Such a call still works in 0.37 but warns once per class and name:
+
+```
+app/jobs/sync.rb:8: warning: ClaudeAgentSDK::ResultMessage#[]: :to_h is not an attribute; Type#[] will only read attributes in 1.0
+```
+
+**In 1.0 a name that is not an attribute behaves like an undefined one:** `#[]` returns `nil`, `#[]=` ignores it (on the strict types above it raises `ArgumentError`), and a camelCase call raises `NoMethodError`. Call the method directly instead (`msg.to_h`). Undefined names already behave that way today and do not warn. `UserMessage#text` and `AssistantMessage#text` are convenience methods, not attributes.
+
 ## Constants
 
 | Constant | Description |

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

@@ -30,16 +30,22 @@ module ClaudeAgentSDK
   #   ClaudeAgentSDK::CLIInstaller.install_pinned
   # @example Pin a version of your own
   #   ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')
-  module CLIInstaller
+  module CLIInstaller # rubocop:disable Metrics/ModuleLength -- Http/Platform/Release/Metadata submodules in one file
+    # @api private
     BASE_URL = 'https://downloads.claude.ai/claude-code-releases'
     # Dist-tags resolved through a GET to BASE_URL/<tag>.
+    #
+    # @api private
     DIST_TAGS = %w[stable latest].freeze
     # Concrete version, optionally with a pre-release suffix (e.g. 2.1.220-rc1).
     # The suffix is restricted to the semver pre-release character set: every
     # accepted version is interpolated straight into a download URL, and a
     # laxer `\S+` would let "2.1.220-x/../2.1.221" traverse out of the release
     # path — silently installing something other than the pinned version.
+    #
+    # @api private
     VERSION_PATTERN = /\A\d+\.\d+\.\d+(-[A-Za-z0-9.-]+)?\z/
+    # @api private
     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),
@@ -48,23 +54,35 @@ module ClaudeAgentSDK
     # .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'
+    # @api private
     BINARY_NAME = 'claude'
+    # @api private
     VERSION_FILE = 'VERSION'
+    # @api private
     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).
+    #
+    # @api private
     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
     # something to buffer in memory. (The binary itself streams to disk.)
+    #
+    # @api private
     VERSION_RESPONSE_LIMIT = 1024
+    # @api private
     MANIFEST_RESPONSE_LIMIT = 5 * 1024 * 1024
+    # @api private
     METADATA_READ_LIMIT = 4096
 
     # Maps the running Ruby to a release-manifest platform key
     # (darwin-arm64, darwin-x64, linux-x64, linux-arm64, and the -musl
     # variants). Windows is not supported by this gem.
+    #
+    # @api private
     module Platform
       class << self
         def detect
@@ -122,6 +140,8 @@ module ClaudeAgentSDK
     # and chunked streaming for the binary. Knows nothing about releases; the
     # specs stub .fetch_text / .download_to wholesale so no HTTP stubbing
     # library is needed.
+    #
+    # @api private
     module Http
       MAX_REDIRECTS = 5
       OPEN_TIMEOUT_SECONDS = 10
@@ -154,7 +174,9 @@ module ClaudeAgentSDK
             File.open(path, File::WRONLY | File::CREAT | File::EXCL | File::BINARY, 0o600) do |file|
               response.read_body do |chunk|
                 written += chunk.bytesize
-                raise CLIInstallError, "Download from #{url} exceeds the expected #{max_bytes} bytes" if over?(written, max_bytes)
+                if over?(written, max_bytes)
+                  raise CLIInstallError, "Download from #{url} exceeds the expected #{max_bytes} bytes"
+                end
 
                 file.write(chunk)
               end
@@ -191,19 +213,21 @@ 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
 
     # Talks to the release service: dist-tag resolution, manifest lookup and
     # URL construction. Pure remote reads — no filesystem, no state.
+    #
+    # @api private
     module Release
       class << self
         # Local, network-free check of what the caller asked for. Returns the
@@ -238,7 +262,9 @@ module ClaudeAgentSDK
           end
 
           checksum = entry['checksum'].to_s.downcase
-          raise CLIInstallError, "#{url} has no valid sha256 checksum for #{platform}" unless checksum.match?(CHECKSUM_PATTERN)
+          unless checksum.match?(CHECKSUM_PATTERN)
+            raise CLIInstallError, "#{url} has no valid sha256 checksum for #{platform}"
+          end
 
           size = entry['size']
           { checksum: checksum, size: size.is_a?(Integer) && size.positive? ? size : nil }
@@ -276,6 +302,8 @@ module ClaudeAgentSDK
     # 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.
+    #
+    # @api private
     module Metadata
       class << self
         def read(dir)
@@ -309,10 +337,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.