claude-agent-sdk 0.36.0 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aed11255947a3321978d4d9e65cf02ca0d88a6f8b2c9e61afede1de95c247b76
-  data.tar.gz: e5d54c2745b1264198a25569599c4f34ac6817778914f450d7aaca8ddb7e99d5
+  metadata.gz: 7d238195bb7f1725358c2ca33a8396ff1f4ab4121c7cc905e1dc2e1957a4553e
+  data.tar.gz: 480e5d771b68e72b0646bfa102cd921b1797d7134a925c496c5575a5e795c88e
 SHA512:
-  metadata.gz: b5c4ce0e5b2a8594eafd236fcdd4d8592cf0f900b8eede62e7e680b50d3560ea99d04180e3b42550e863a95225e9cac191fe50e8baa7c376413832b051e1900b
-  data.tar.gz: b45fb3972949da75f83f845244e72b74fefcc88acf57c04ed89cbdde896a7e50eda69853a3430db88163259afe88862da0c598083745a3b9778f418ec001bf2d
+  metadata.gz: 91d8f9de96e91aa5297e2342f33a57de100807978ac5c6bb7739927f99e0c41707f335c4e41512c9d843bf19afdc3d30ab97b526319e3cc45d932e5bae2cc761
+  data.tar.gz: e7d2504b2dcda1c0ee5d1d4174d9ece35efc1a53b9832b00595829adacc6039f423d4db4999e1139d1fb6ad93c3b532dad119f9aceb51305328d3d25d847e7f6

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.37.0] - 2026-09-23
+
+The last 0.x release before 1.0 ([roadmap](https://github.com/ya-luotao/claude-agent-sdk-ruby/issues/126)). No runtime behaviour changes — only new warnings for things 1.0 will reject. **Run your suite on 0.37 with warnings visible before moving to 1.0:**
+- A misspelled key on a value type you build (`HookMatcher`, `AgentDefinition`, `SandboxSettings`, MCP server configs, permission results, hook outputs, …) now warns once, pointing at your call; 1.0 raises `ArgumentError`.
+- `msg[:name]` / camelCase readers reaching a non-attribute method (e.g. `msg[:to_h]`) warn once; in 1.0 they only reach attributes.
+- The 1.0 SemVer surface is now visible: SDK internals are tagged `@api private` and hidden from the API docs, and the documented contracts (Hash-key rule, `mcp_status` / `context_usage` return Hashes, `Type#[]`) are written down.
+
+### Changed
+- **Docs: pre-1.0 contracts written down** ([#126](https://github.com/ya-luotao/claude-agent-sdk-ruby/issues/126)). No code changes. `Client#mcp_status` / `#get_mcp_status` and `#context_usage` / `#get_context_usage` return the CLI's raw Hash with camelCase Symbol keys. `docs/types.md` had described `McpStatusResponse` as the response type; it is the optional typed view, via `McpStatusResponse.parse(client.mcp_status)`, and there is no typed context-usage class (`docs/client.md`). A new "Hash keys" section in `docs/types.md` states one rule: Hashes passed through from the live CLI stream (`origin`, `usage`, `model_usage`, hook `tool_input`, `can_use_tool` input, SDK MCP tool args, control responses) have Symbol keys spelled as on the wire, and Hashes read from transcripts or a `SessionStore` (`SessionMessage#message`, `get_subagent_metadata`, store keys and entries) have String keys. The docs, examples and bundled skill drop their `h[:key] || h['key']` fallbacks in favour of the one correct form. `Type#[]`, `#[]=` and the camelCase readers are documented as public API, including that `#[]=` changes the object you received. `docs/sessions.md` documents `ClaudeAgentSDK.project_key_for_directory` and `ClaudeAgentSDK.fold_session_summary` for adapter authors, and `import_session_to_store`'s batching (`batch_size:` defaults to 500 entries, and a batch also ends at about 1 MiB).
+- **SDK internals are now tagged `@api private` and hidden from the YARD docs** ([#126](https://github.com/ya-luotao/claude-agent-sdk-ruby/issues/126)). The tagged namespaces are `Query`, `MessageParser`, `TranscriptMirrorBatcher`, `Sessions`, `SessionMutations`, `SessionResume`, `MaterializedResume`, `SessionSummary`, `SessionStores`, `OptionWarnings` and `FiberBoundary`, including everything nested in them. Some public classes also have internal members, and those are tagged individually: `SubprocessCLITransport`'s methods outside the `Transport` interface and its constants; `CommandBuilder`'s constants (`.new` and `#build` stay public); `CLIInstaller::Http`, `Platform`, `Release` and `Metadata` and the installer's constants other than `PINNED_CLI_VERSION`; `SdkMcpServer#handle_json`, `#handle_message` and `SdkMcpServer::ToolInputSchema`; `Client#query_handler`; and `ClaudeAgentSDK::OBSERVER_INTERFACE`. Their public faces are unchanged: `ClaudeAgentSDK.offload`, `fold_session_summary`, the session functions and `SDKSessionInfo` / `SessionMessage` remain public. Nothing changes at runtime. No method or constant was renamed, removed or made private, so every existing call keeps working. From 1.0, SemVer covers `docs/` and the YARD API without `@api private`; objects tagged `@api private` are not covered and may change in any release. `CONTRIBUTING.md` has a new "What is public API" section.
+- `lib/claude_agent_sdk/types.rb` is split into one file per area under `lib/claude_agent_sdk/types/` (messages, hooks, options, ...). The code moved without edits and `types.rb` still loads every part, so `require 'claude_agent_sdk/types'` and every class and constant are unchanged; no API change ([#126](https://github.com/ya-luotao/claude-agent-sdk-ruby/issues/126)).
+- `Type`'s internal machinery is tagged `@api private` and leaves the rendered docs: `Type#dup_for_options`, `Type.deep_dup_for_options`, `Type::OptionValue`, `Type.inspect_filtered`, `Type.inspect_filtered_attributes`, and the new `Type.strict_attributes` / `.strict_attributes?` / `.declare_attributes` / `.attribute?` / `.attribute_names`. They are not part of the SemVer surface. `Type#[]`, `#[]=`, the camelCase readers, `#to_h`, `.wrap` and `.from_hash` stay public ([#126](https://github.com/ya-luotao/claude-agent-sdk-ruby/issues/126)).
+
+### Deprecated
+- **Unknown keys on user-constructed types.** The value types you build and pass in (option values such as `AgentDefinition`, `SandboxSettings`, the thinking configs and the MCP server configs; `HookMatcher`; hook outputs; `PermissionResultAllow` / `PermissionResultDeny`; `PermissionUpdate`; `PermissionRuleValue`) silently dropped a misspelled key, so `HookMatcher.new(matchr: 'Bash')` quietly built a matcher with no `matcher` set. `.new` and `#[]=` now warn once per class and key, at the caller's line: `ClaudeAgentSDK::HookMatcher: unknown attribute :matchr ignored; this will raise ArgumentError in 1.0 (known: hooks, matcher, timeout)`. **In 1.0 they raise `ArgumentError`**, as `ClaudeAgentOptions` already does. camelCase and String keys and a type's own discriminator (`type`, `hook_event_name`, `behavior`) are accepted, so `klass.new(value.to_h)` round-trips silently. Types parsed from CLI output (messages, content blocks, hook inputs) and every construction through `.from_hash` / `.wrap` stay lenient, so a newer CLI's extra fields never warn; permission suggestions from the CLI are now hydrated through `PermissionUpdate.wrap` for that reason. Full list in `docs/types.md` ([#126](https://github.com/ya-luotao/claude-agent-sdk-ruby/issues/126)).
+- **`Type#[]`, `#[]=` and camelCase methods reaching something other than an attribute.** They are public API for a type's attributes (its `attr_*` fields, the backward-compatible `RateLimitEvent#data`, predicates such as `options.forkSession?`, and any method your own code adds to a subclass, mixin or instance), but they resolved any public method: `msg[:to_h]` returned a Hash, `msg['freeze']` froze the message, `msg.toH` called `#to_h`. Such a call still works but warns once per class and name, e.g. `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 (raises on the types above), a camelCase call raises `NoMethodError`, and `respond_to?` says `false`. Names that are not methods at all keep today's behaviour and do not warn. `UserMessage#text` / `AssistantMessage#text` are convenience methods, not attributes ([#126](https://github.com/ya-luotao/claude-agent-sdk-ruby/issues/126)).
+
 ## [0.36.0] - 2026-09-23
 
 The first step on the [road to 1.0](https://github.com/ya-luotao/claude-agent-sdk-ruby/issues/126): one `session_store:` argument for every session function (the store-specific twins are deprecated), `ClaudeAgentSDK.ask`, String tool results, and the last audit follow-ups (#119–#121). **Read before upgrading:**

data/README.md

@@ -29,7 +29,7 @@ A Ruby SDK for the [Claude Code](https://docs.claude.com/en/docs/claude-code-ove
 
 ```ruby
 # Gemfile
-gem 'claude-agent-sdk', '~> 0.36.0'
+gem 'claude-agent-sdk', '~> 0.37.0'
 ```
 
 Then `bundle install`, or install directly with `gem install claude-agent-sdk`. To track unreleased changes, point the Gemfile at GitHub: `gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'`.
@@ -193,7 +193,7 @@ See [docs/hooks-and-permissions.md](docs/hooks-and-permissions.md) for the full
 | OpenTelemetry tracing, Langfuse, custom observers | [docs/observability.md](docs/observability.md) |
 | Rails: generator, `install_cli` task, callback wrapper, fiber safety, solid_queue fiber workers, ActionCable, jobs | [docs/rails.md](docs/rails.md) |
 | Vendoring a pinned CLI binary and CLI discovery order | [docs/cli-installer.md](docs/cli-installer.md) |
-| Message, content block, and configuration type reference | [docs/types.md](docs/types.md) |
+| Hash-key rule, attribute access, and the message, content block, and configuration type reference | [docs/types.md](docs/types.md) |
 | Error handling, exception hierarchy, timeouts | [docs/errors.md](docs/errors.md) |
 
 API reference: [rubydoc.info/gems/claude-agent-sdk](https://rubydoc.info/gems/claude-agent-sdk). Available built-in tools: [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/settings#tools-available-to-claude).

data/docs/client.md

@@ -77,6 +77,31 @@ The Ruby-style names above sit next to the Python SDK's spellings, and both work
 
 Each Ruby-style method calls its parity counterpart, so both send the same control request and raise `CLIConnectionError` when the client is not connected. The one exception is `server_info`, which reads the cached initialization result and returns `nil` instead of raising before `connect`. As with any Ruby setter, `client.model = 'haiku'` evaluates to `'haiku'`, not to the control response.
 
+### MCP status and context usage return Hashes
+
+`mcp_status` / `get_mcp_status` and `context_usage` / `get_context_usage` return the CLI's control response payload as a plain Hash, unchanged: Symbol keys spelled as on the wire, which for these payloads is camelCase (`:mcpServers`, `:serverInfo`, `:totalTokens`), at every level of nesting (see [Hash keys](types.md#hash-keys)). The SDK does not model or filter the payload, so fields added by newer CLI versions come through. A response without a payload reads as `{}`.
+
+```ruby
+status = client.mcp_status
+status[:mcpServers].each { |s| puts "#{s[:name]}: #{s[:status]}" }
+status.dig(:mcpServers, 0, :serverInfo, :version)
+
+usage = client.context_usage
+puts "#{usage[:totalTokens]} / #{usage[:maxTokens]} tokens"
+```
+
+For a typed view of the MCP status, parse the Hash yourself:
+
+```ruby
+typed = ClaudeAgentSDK::McpStatusResponse.parse(client.mcp_status)
+typed.mcp_servers.each do |server|            # McpServerStatus
+  puts "#{server.name} #{server.status} #{server.server_info&.version}"
+  server.tools&.each { |tool| puts "  #{tool.name} read_only=#{tool.annotations&.read_only}" }
+end
+```
+
+`McpServerStatus#config` is an `McpSdkServerConfigStatus` or `McpClaudeAIProxyServerConfig` for `sdk` and `claudeai-proxy` servers, and the raw Hash for every other server type. There is no typed class for context usage; read the Hash.
+
 ## Custom Transport
 
 By default, `Client` uses `SubprocessCLITransport` to spawn the Claude Code CLI locally. You can provide a custom transport class to connect via other channels (e.g., remote SSH, WebSocket, or a sandbox VM).
@@ -87,7 +112,7 @@ A transport must implement six methods:
 |---|---|
 | `connect` | Establish the connection / spawn the remote CLI |
 | `write(data)` | Send raw JSON-line bytes to stdin |
-| `read_messages { \|hash\| ... }` | Yield parsed JSON messages from stdout; block until the stream closes |
+| `read_messages { \|hash\| ... }` | Yield each stdout line as a Hash parsed with `JSON.parse(line, symbolize_names: true)` (the SDK reads Symbol keys; see [Hash keys](types.md#hash-keys)); block until the stream closes |
 | `end_input` | Signal EOF on stdin |
 | `close` | Terminate and clean up |
 | `ready?` | Report whether the transport can accept I/O |

data/docs/hooks-and-permissions.md

@@ -19,7 +19,9 @@ All hook input objects include common fields like `session_id`, `transcript_path
 - `SubagentStart` → `SubagentStartHookInput` (`agent_id`, `agent_type`)
 - `PermissionRequest` → `PermissionRequestHookInput` (`tool_name`, `tool_input`, `permission_suggestions`)
 
-All 27 hook events have typed input classes. See [`ClaudeAgentSDK::HOOK_EVENTS`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/lib/claude_agent_sdk/types.rb) and [examples/lifecycle_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb).
+`tool_input` (and the `input` a [permission callback](#permission-callbacks) receives) is the CLI's Hash passed through unchanged, so its keys are Symbols spelled as on the wire: `tool_input[:command]`, `input[:file_path]`. See [Hash keys](types.md#hash-keys).
+
+All 27 hook events have typed input classes. See [`ClaudeAgentSDK::HOOK_EVENTS`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/lib/claude_agent_sdk/types/hooks.rb) and [examples/lifecycle_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb).
 
 `background_tasks` and `session_crons` are optional arrays of raw CLI hashes.
 `nil` means the CLI did not provide a snapshot; `[]` means it provided an empty
@@ -40,7 +42,7 @@ Async do
     return {} unless input.respond_to?(:tool_name) && input.tool_name == 'Bash'
 
     tool_input = input.tool_input || {}
-    command = tool_input[:command] || tool_input['command'] || ''
+    command = tool_input[:command] || ''
     block_patterns = ['rm -rf', 'foo.sh']
 
     block_patterns.each do |pattern|
@@ -105,7 +107,7 @@ Async do
     return ClaudeAgentSDK::PermissionResultAllow.new if tool_name == 'Read'
 
     if tool_name == 'Write'
-      file_path = input[:file_path] || input['file_path']
+      file_path = input[:file_path]
       if file_path && file_path.include?('/etc/')
         return ClaudeAgentSDK::PermissionResultDeny.new(
           message: 'Cannot write to sensitive system files',

data/docs/mcp-servers.md

@@ -130,8 +130,7 @@ first gets an `isError` result naming the exception class
 (`"SystemExit: exit"`), so it is not left waiting on the tool call, and then
 the exception propagates as Ruby normally would (`exit` ends the process,
 Ctrl-C interrupts it). Called directly, without a session,
-`SdkMcpServer#call_tool` and `#handle_message` simply let such exceptions
-propagate. Cancellation of the tool call itself still propagates.
+`SdkMcpServer#call_tool` simply lets such exceptions propagate. Cancellation of the tool call itself still propagates.
 
 ## Mixed Server Support
 

data/docs/sessions.md

@@ -40,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
 
@@ -292,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.
@@ -391,7 +450,27 @@ Where the store path differs from the disk path:
   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.
+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`,

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/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,24 +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 .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
@@ -123,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
@@ -155,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
@@ -205,6 +226,8 @@ module ClaudeAgentSDK
 
     # 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
@@ -239,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 }
@@ -277,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)