claude-agent-sdk 0.36.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aed11255947a3321978d4d9e65cf02ca0d88a6f8b2c9e61afede1de95c247b76
-  data.tar.gz: e5d54c2745b1264198a25569599c4f34ac6817778914f450d7aaca8ddb7e99d5
+  metadata.gz: a678100ed5fdb6ba11e9895e534b4a87df8a2b8a57d0a0a459900d81d88bf593
+  data.tar.gz: 8bc65b4056f315abe23a3f1f9089402819137b2abb38cbd1d57afdcfe5366e42
 SHA512:
-  metadata.gz: b5c4ce0e5b2a8594eafd236fcdd4d8592cf0f900b8eede62e7e680b50d3560ea99d04180e3b42550e863a95225e9cac191fe50e8baa7c376413832b051e1900b
-  data.tar.gz: b45fb3972949da75f83f845244e72b74fefcc88acf57c04ed89cbdde896a7e50eda69853a3430db88163259afe88862da0c598083745a3b9778f418ec001bf2d
+  metadata.gz: b7ec8544374217a99458cc3557504777d5ac4e2a66cab706f9322f326f43220b312fc877388983961a688a1e3c55b3493bae1458c4a7ed71a7614bfe2e6bc0aa
+  data.tar.gz: b119e67d145088a4adbf832f611eaf5d7047c255a2037e5a76372f6ac319d8d6d7addaf4af062b58acbb12ba9acf17799027b89175c02498f65471320683533a

data/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-09-23
+
+**1.0 is a stability commitment.** From here on the public API — everything documented in `docs/` plus the YARD docs without `@api private`, now also described by the RBS signatures in `sig/` — follows Semantic Versioning: no breaking changes within 1.x. Upgrading from 0.x? Read [UPGRADING-1.0.md](UPGRADING-1.0.md) and run your suite on 0.37 first.
+
+1.0 ([#126](https://github.com/ya-luotao/claude-agent-sdk-ruby/issues/126)): three breaking changes, the first two of which 0.37 warns about at the call site. **Read [UPGRADING-1.0.md](UPGRADING-1.0.md) before upgrading** and run your suite on 0.37 with warnings visible first: an app that runs on 0.37 without SDK warnings is unaffected by those two, except that `respond_to?` on a camelCase non-attribute (`msg.respond_to?(:toH)`) silently answered `true` on 0.37 and answers `false` now.
+
+### Added
+- **`ClaudeAgentSDK::SessionStoreError`** (a `ClaudeSDKError`), raised by `query`, `ask` and `Client#connect` when resuming from `session_store:` fails: a store call (`#load`, `#list_sessions`, `#list_subkeys`) raised or exceeded `load_timeout_ms` while the SDK materialized the transcript. The message names the store call, and `#cause` holds the adapter's exception (or the timeout). Documented in `docs/errors.md` and `docs/sessions.md`.
+- **RBS signatures for the public API** ([#126](https://github.com/ya-luotao/claude-agent-sdk-ruby/issues/126)). The gem now ships `sig/`, so Steep and other RBS tools type-check code that uses it (through `rbs collection`; `sig/manifest.yaml` declares the one stdlib dependency, `pathname`). The signatures cover the whole public surface (the objects documented in `docs/` and YARD without `@api private`): `ClaudeAgentSDK.query` / `.ask` / `.configure` / `.offload`, the SDK MCP helpers, every session function (including `session_store:` and the deprecated twins), `Client` with its Ruby-style aliases, `ClaudeAgentOptions` (every option as a typed keyword), the message, content-block, hook, permission and MCP types, the error hierarchy, `CLIInstaller`, `Streaming`, `Railtie.callback_wrapper` and the observers. Duck types are interfaces, so any object with the right methods fits: `_Transport`, `_SessionStore` (only `#append` and `#load` are required), and one interface per user callback (`_CanUseTool`, `_HookCallback`, `_ToolHandler`, `_CallbackWrapper`, ...). Hashes follow the documented key rule: `wire_hash` (`Hash[Symbol, untyped]`) for data from the CLI stream, `transcript_hash` (`Hash[String, untyped]`) for transcripts and store data. Internals tagged `@api private` have no signatures. CI validates the signatures (`rake rbs:validate`) and runs the suite under RBS's runtime type checker (`rake rbs:test`), so a signature that disagrees with the code fails the build. `CONTRIBUTING.md` explains how to keep `sig/` in step with API changes.
+
+### Changed
+- **Breaking: unknown keys on user-constructed types raise `ArgumentError`.** `.new` and `#[]=` on the value types you build and pass in (option values such as `AgentDefinition`, `SandboxSettings`, the thinking and MCP server configs; `HookMatcher`; hook outputs; `PermissionResultAllow` / `PermissionResultDeny`; `PermissionUpdate`; `PermissionRuleValue`) raise instead of warning, with a message naming the class, the key and the known keys: `ClaudeAgentSDK::HookMatcher: unknown attribute :matchr (known: hooks, matcher, timeout)`. camelCase and String keys and a type's own discriminator are still accepted; `.from_hash`, `.wrap` and every type parsed from CLI output stay lenient.
+- **Breaking: `Type#[]`, `#[]=` and camelCase methods reach attributes only.** A name that is not an attribute behaves like an undefined one: `msg[:to_h]` is `nil`, `#[]=` ignores it (raises on the strict types above), `msg.toH` raises `NoMethodError` and `respond_to?(:toH)` is `false`. Methods your own code adds to a subclass, mixin or instance still count as attributes.
+- **Breaking: store-backed resume failures raise `SessionStoreError` instead of `RuntimeError`.** The two SDK-raised `RuntimeError`s (store call failed, store call timed out) become `SessionStoreError`, and a `RuntimeError` raised by the adapter itself, which 0.37 let through unwrapped, is now wrapped too, so `rescue ClaudeSDKError` catches every resume-materialization failure. Code that rescued `RuntimeError` there must rescue `SessionStoreError`. The failure message now includes the adapter exception's class (`... failed during resume materialization: IOError: connection reset`).
+- `UPGRADING-1.0.md` ships in the gem and the YARD docs, linked from the README.
+- The deprecation warning printed by the ten `*_from_store` / `*_via_store` session functions, and their YARD and docs, now say they will be removed in **2.0**. 0.36 and 0.37 said 1.0, but they stay, deprecated, for all of 1.x ([#126](https://github.com/ya-luotao/claude-agent-sdk-ruby/issues/126)). Nothing else about them changes: each still works and still warns once per process.
+
+## [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

@@ -12,6 +12,8 @@ A Ruby SDK for the [Claude Code](https://docs.claude.com/en/docs/claude-code-ove
 
 > **Unofficial and community-maintained.** This project is not affiliated with or supported by Anthropic. It tracks the official SDKs release by release; see the [CHANGELOG](CHANGELOG.md) for the currently synced version.
 
+> **Upgrading from 0.x?** 1.0 raises on unknown keys, limits `#[]` to attributes and adds `SessionStoreError`. [UPGRADING-1.0.md](UPGRADING-1.0.md) has the checklist.
+
 ## Highlights
 
 - **Rails integration.** `bin/rails generate claude_agent_sdk:install` writes the initializer and `bin/rails claude_agent_sdk:install_cli` vendors the CLI; [docs/rails.md](docs/rails.md) covers jobs, ActionCable streaming, session resumption, and solid_queue fiber workers (`callback_scheduling: :inline`).
@@ -29,7 +31,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', '~> 1.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 +195,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).
@@ -252,11 +254,13 @@ This repository is also a Claude Code plugin marketplace. The bundled skill teac
 bundle install
 bundle exec rspec                    # unit suite
 bundle exec rubocop                  # lint
+bundle exec rake rbs:validate        # validate the RBS signatures in sig/
+bundle exec rake rbs:test            # the suite under RBS runtime type checking
 RUN_INTEGRATION=1 bundle exec rspec  # also run the real-CLI integration suite (needs `claude` and ANTHROPIC_API_KEY)
 BUNDLE_GEMFILE=gemfiles/rails_8.gemfile bundle exec rspec --options spec/rails/.rspec  # Rails integration specs
 ```
 
-CI runs the suite and RuboCop on Ruby 3.2, 3.3, and 3.4 on Linux, the suite on macOS, and the Rails specs against Rails 7.1 and 8; a weekly job runs the integration suite against the pinned CLI. See [CONTRIBUTING.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/CONTRIBUTING.md) for the development setup and [spec/README.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/spec/README.md) for the test layout.
+CI runs the suite and RuboCop on Ruby 3.2, 3.3, and 3.4 on Linux, the suite on macOS, and the Rails specs against Rails 7.1 and 8, validates the RBS signatures and runs the suite under RBS runtime type checking; a weekly job runs the integration suite against the pinned CLI. The gem ships RBS signatures for its public API in `sig/`, which Steep and other RBS tools pick up through `rbs collection`. See [CONTRIBUTING.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/CONTRIBUTING.md) for the development setup and [spec/README.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/spec/README.md) for the test layout.
 
 ## Contributing
 

data/UPGRADING-1.0.md

@@ -0,0 +1,151 @@
+# Upgrading from 0.37 to 1.0
+
+1.0 is 0.37 plus three breaking changes. 0.37 already warns about each of the
+first two at the exact call site, so **if your app runs on 0.37 without SDK
+warnings, the first two changes will not affect it on 1.0**, with one silent
+exception: `respond_to?` on a camelCase name that is not an attribute
+(`msg.respond_to?(:toH)`) answered `true` on 0.37 without a warning and answers
+`false` on 1.0. The third change is to which exception class you rescue.
+
+| Area | 0.37 | 1.0 |
+|------|------|-----|
+| Unknown key on a type you build (`HookMatcher.new(matchr: ...)`) | warns once, key ignored | raises `ArgumentError` |
+| `#[]` / `#[]=` / camelCase reaching a non-attribute (`msg[:to_h]`, `msg.toH`) | works, warns once | treated as undefined |
+| Store-backed resume failure | bare `RuntimeError` | `ClaudeAgentSDK::SessionStoreError` |
+
+## Checklist
+
+1. Upgrade to 0.37 first: `gem 'claude-agent-sdk', '~> 0.37.0'`, then `bundle update claude-agent-sdk`.
+2. Run your test suite, and exercise a staging boot, with warnings visible and
+   stderr kept: no `-W0`, no `$VERBOSE = nil`, and no stderr filtering.
+   For example, `bundle exec rspec 2> sdk-warnings.log`.
+3. Find the SDK's warnings:
+   ```sh
+   grep -E 'unknown attribute|is not an attribute|is deprecated' sdk-warnings.log
+   ```
+   Each line starts with the `file:line` of your call. Every warning is
+   printed once per process per class and key (or per method), so fix what
+   you find and run again until the output is empty.
+4. Fix each hit as described below.
+5. Around code that resumes from a `session_store:` (`query`, `ask`,
+   `Client#connect`, `Client.open`), search for `rescue RuntimeError` and for
+   rescues of your adapter's own exception classes that inherit from
+   `RuntimeError` (for example `Net::ReadTimeout`, a `Timeout::Error`, which is
+   a `RuntimeError`). In 1.0 these arrive wrapped: rescue
+   `ClaudeAgentSDK::SessionStoreError` and inspect `#cause` for the original.
+6. Upgrade: `gem 'claude-agent-sdk', '~> 1.0'`.
+
+## Unknown keys raise `ArgumentError`
+
+The value types you build and pass *in* now reject a key they do not define,
+as `ClaudeAgentOptions` always has. Before 0.37 the key was silently dropped,
+so a typo such as `matchr:` built a matcher that matched every tool:
+
+```ruby
+ClaudeAgentSDK::HookMatcher.new(matchr: 'Bash', hooks: [check])
+# 0.37: warning: ClaudeAgentSDK::HookMatcher: unknown attribute :matchr ignored; this will raise ArgumentError in 1.0 (known: hooks, matcher, timeout)
+# 1.0:  ArgumentError: ClaudeAgentSDK::HookMatcher: unknown attribute :matchr (known: hooks, matcher, timeout)
+```
+
+This covers `.new` and `#[]=` on the option values (`AgentDefinition`,
+`SandboxSettings` and its network and filesystem configs, the three thinking
+configs, `TaskBudget`, the three system prompt types, `ToolsPreset`,
+`SdkPluginConfig`, the four MCP server configs), `HookMatcher`, the hook
+outputs (`SyncHookJSONOutput`, `AsyncHookJSONOutput`, every
+`*HookSpecificOutput`), `PermissionResultAllow`, `PermissionResultDeny`,
+`PermissionUpdate` and `PermissionRuleValue`. The full list is in
+[docs/types.md](docs/types.md#unknown-keys).
+
+**Fix:** correct the key, or remove it if the type never had it. Symbol and
+String keys, snake_case and camelCase all still work, and so does a type's own
+discriminator (`type`, `hook_event_name`, `behavior`), so on types that define
+their own `#to_h` (the MCP server configs, `SandboxSettings`, the system prompt
+types, the hook outputs, ...) `klass.new(value.to_h)` round-trips. For a Hash you did not write yourself (deserialized from the CLI,
+a queue or a database), use `.from_hash` or `.wrap`: both stay lenient and
+ignore unknown keys. Types the SDK parses from CLI output (messages, content
+blocks, hook inputs) are not affected.
+
+## `#[]`, `#[]=` and camelCase reach attributes only
+
+These accessors are public API for a type's attributes: the fields it declares,
+predicates such as `options.forkSession?`, and any method your own code adds to
+a subclass, a mixin or an instance. Through 0.37 they reached *any* public
+method. In 1.0 a name that is not an attribute behaves like an undefined one:
+
+| Call | 0.37 | 1.0 |
+|------|------|-----|
+| `msg[:to_h]`, `msg['freeze']` | calls the method, warns | `nil` (method not called) |
+| `msg[:some_method] = x` | calls `some_method=`, warns | ignored; `ArgumentError` on the strict types above |
+| `msg.toH` | calls `to_h`, warns | `NoMethodError`; `respond_to?(:toH)` is `false` |
+
+**Fix:** call the method directly (`msg.to_h`). `UserMessage#text` and
+`AssistantMessage#text` are convenience methods, not attributes, so
+`msg[:text]` is `nil`; use `msg.text`.
+
+## `SessionStoreError` replaces `RuntimeError` on store-backed resume
+
+When `query`, `ask` or `Client#connect` resume a session from
+`session_store:` and a store call raises or exceeds `load_timeout_ms`, they now
+raise `ClaudeAgentSDK::SessionStoreError < ClaudeSDKError`. In 0.37 this was a
+bare `RuntimeError`, and a `RuntimeError` raised by your adapter escaped
+unwrapped, so `rescue ClaudeAgentSDK::ClaudeSDKError` missed both. The message
+names the store call and `#cause` holds your adapter's exception (or the
+timeout):
+
+```ruby
+begin
+  ClaudeAgentSDK.ask('Continue', options: options)
+rescue ClaudeAgentSDK::SessionStoreError => e
+  e.message # "SessionStore#load for session 3f2c… failed during resume materialization: IOError: …"
+  e.cause   # the IOError your adapter raised
+end
+```
+
+**Fix:** replace `rescue RuntimeError` on these paths with
+`rescue ClaudeAgentSDK::SessionStoreError` (or `ClaudeSDKError`). Other store
+paths are unchanged: the session functions called with `session_store:` behave
+exactly as in 0.37, and mirroring failures still arrive as
+`MirrorErrorMessage`, never as exceptions.
+
+## What SemVer covers from 1.0
+
+No breaking changes within 1.x to the public API: everything documented in
+`docs/` and the README, and every class, module, method and constant in the
+YARD docs that is not tagged `@api private`. `@api private` objects (`Query`,
+`MessageParser`, `FiberBoundary`, the `Sessions*` modules, ...) stay callable
+but can change in any release. See
+[CONTRIBUTING.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/CONTRIBUTING.md#what-is-public-api).
+
+A removal is first deprecated in a minor release with a one-time warning that
+names the replacement, and happens in the next major.
+
+## The Hash-key rule
+
+Unchanged in 1.0, and now part of the SemVer contract: a plain Hash passed
+through from the CLI's live stream (`usage`, `origin`, hook `tool_input`, the
+`can_use_tool` input, SDK MCP tool `args`, `Client#mcp_status`) has **Symbol**
+keys spelled as on the wire; a Hash read from a transcript or a `SessionStore`
+(`SessionMessage#message`, `get_subagent_metadata`, store keys and entries) has
+**String** keys. The wrong form reads `nil` rather than raising. See
+[docs/types.md](docs/types.md#hash-keys).
+
+## Deprecated, kept through 1.x
+
+The ten store-specific session functions still work in 1.x and still print a
+one-time warning. They will be removed in 2.0. Each is the same call as its
+replacement:
+
+| Deprecated | Replacement |
+|---|---|
+| `list_sessions_from_store(session_store: s, ...)` | `list_sessions(session_store: s, ...)` |
+| `get_session_info_from_store(session_store: s, ...)` | `get_session_info(session_store: s, ...)` |
+| `get_session_messages_from_store(session_store: s, ...)` | `get_session_messages(session_store: s, ...)` |
+| `list_subagents_from_store(session_store: s, ...)` | `list_subagents(session_store: s, ...)` |
+| `get_subagent_metadata_from_store(session_store: s, ...)` | `get_subagent_metadata(session_store: s, ...)` |
+| `get_subagent_messages_from_store(session_store: s, ...)` | `get_subagent_messages(session_store: s, ...)` |
+| `rename_session_via_store(session_store: s, ...)` | `rename_session(session_store: s, ...)` |
+| `tag_session_via_store(session_store: s, ...)` | `tag_session(session_store: s, ...)` |
+| `delete_session_via_store(session_store: s, ...)` | `delete_session(session_store: s, ...)` |
+| `fork_session_via_store(session_store: s, ...)` | `fork_session(session_store: s, ...)` |
+
+`import_session_to_store` is not deprecated.

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/errors.md

@@ -117,6 +117,11 @@ end
 # no usable home directory exists for the default ~/.claude
 class ConfigDirError < ClaudeSDKError; end
 
+# Raised when resuming from a SessionStore fails: a store call raised or
+# exceeded load_timeout_ms during resume materialization. #cause holds the
+# adapter's exception (or the timeout)
+class SessionStoreError < ClaudeSDKError; end
+
 # Raised when the Claude Code process fails
 class ProcessError < ClaudeSDKError
   attr_reader :exit_code,  # Integer | nil
@@ -155,6 +160,7 @@ end
 | `ControlRequestTimeoutError` | Control protocol timeout (configurable via env var) |
 | `CLINotFoundError` | Claude Code not installed |
 | `ConfigDirError` | A local-disk session API (`list_sessions`, `get_session_*`, `rename_session`, ...) could not locate the Claude config directory: `CLAUDE_CONFIG_DIR` is unset and there is no usable home directory (`HOME` unset with no passwd entry, as under `docker --user` in a minimal image, or an empty/relative `HOME`). Set `CLAUDE_CONFIG_DIR` |
+| `SessionStoreError` | Resuming from `session_store:` failed: a store call (`#load`, `#list_sessions`, `#list_subkeys`) raised or exceeded `load_timeout_ms` while the SDK materialized the transcript, before the CLI started. The message names the call; `#cause` is the adapter's exception. Before 1.0 this was a bare `RuntimeError` — see [Sessions](sessions.md#mirroring-to-a-sessionstore) |
 | `ProcessError` | Process failed (includes `exit_code` and `stderr`) — also raised when the CLI is still running 5s after closing stdout and the SDK had to terminate it |
 | `ResultError` | Run ended on a terminal error result (subclasses `ProcessError`; adds `subtype`, `errors`, `api_error_status`, `terminal_reason`, ...) — rescue it first |
 | `CLIJSONDecodeError` | JSON parsing issues — including stdout ending mid-frame (a truncated final message; `line` holds the partial frame) |

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
 
@@ -227,6 +227,25 @@ 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`).
 
+If a store call raises or exceeds `load_timeout_ms` during resume
+materialization, `ClaudeAgentSDK.query`, `.ask` and `Client#connect` raise
+`ClaudeAgentSDK::SessionStoreError` (a `ClaudeSDKError`) before the CLI
+starts. The message names the call (`SessionStore#load for session <id> failed
+during resume materialization: IOError: ...`) and `#cause` holds the adapter's
+own exception, or the internal timeout:
+
+```ruby
+begin
+  ClaudeAgentSDK.ask('Continue', options: options.dup_with(resume: session_id))
+rescue ClaudeAgentSDK::SessionStoreError => e
+  logger.warn("resume from store failed: #{e.message} (#{e.cause&.class})")
+  raise
+end
+```
+
+Before 1.0 this surfaced as a bare `RuntimeError` (and a `RuntimeError` your
+adapter raised escaped unwrapped), which `rescue ClaudeSDKError` missed.
+
 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
@@ -292,6 +311,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 +469,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`,
@@ -399,7 +497,7 @@ subagents) into a 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
+> deprecation warning; they stay through 1.x and will be removed in 2.0. Replace
 > `ClaudeAgentSDK.x_from_store(session_store: store, ...)` or
 > `x_via_store(session_store: store, ...)` with
 > `ClaudeAgentSDK.x(..., session_store: store)`.