claude-agent-sdk 0.37.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d238195bb7f1725358c2ca33a8396ff1f4ab4121c7cc905e1dc2e1957a4553e
-  data.tar.gz: 480e5d771b68e72b0646bfa102cd921b1797d7134a925c496c5575a5e795c88e
+  metadata.gz: a678100ed5fdb6ba11e9895e534b4a87df8a2b8a57d0a0a459900d81d88bf593
+  data.tar.gz: 8bc65b4056f315abe23a3f1f9089402819137b2abb38cbd1d57afdcfe5366e42
 SHA512:
-  metadata.gz: 91d8f9de96e91aa5297e2342f33a57de100807978ac5c6bb7739927f99e0c41707f335c4e41512c9d843bf19afdc3d30ab97b526319e3cc45d932e5bae2cc761
-  data.tar.gz: e7d2504b2dcda1c0ee5d1d4174d9ece35efc1a53b9832b00595829adacc6039f423d4db4999e1139d1fb6ad93c3b532dad119f9aceb51305328d3d25d847e7f6
+  metadata.gz: b7ec8544374217a99458cc3557504777d5ac4e2a66cab706f9322f326f43220b312fc877388983961a688a1e3c55b3493bae1458c4a7ed71a7614bfe2e6bc0aa
+  data.tar.gz: b119e67d145088a4adbf832f611eaf5d7047c255a2037e5a76372f6ac319d8d6d7addaf4af062b58acbb12ba9acf17799027b89175c02498f65471320683533a

data/CHANGELOG.md

@@ -7,6 +7,23 @@ 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:**

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.37.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'`.
@@ -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/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/sessions.md

@@ -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
@@ -478,7 +497,7 @@ skipped with a warning.
 > `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)`.

data/docs/types.md

@@ -47,8 +47,8 @@ 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).
+**attributes** only; any other method (`to_h`, `freeze`, ...) counts as undefined —
+see [Attributes Only](#attributes-only).
 
 `#[]=` assigns through the attribute's setter, with the same name
 normalization, and returns the assigned value:
@@ -63,8 +63,8 @@ msg[:result] = 'edited' # same as msg.result = 'edited'
   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).
+  its constructor and `dup_with` do), and so do the value types you build and
+  pass in — 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
@@ -380,29 +380,32 @@ end
 
 ### 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:
+`ClaudeAgentOptions` and the value types you build and pass *in* raise `ArgumentError` on a key they do not define, naming the class, the key and the keys it accepts:
 
-```
-app/agents/reviewer.rb:12: warning: ClaudeAgentSDK::HookMatcher: unknown attribute :matchr ignored; this will raise ArgumentError in 1.0 (known: hooks, matcher, timeout)
+```ruby
+ClaudeAgentSDK::HookMatcher.new(matchr: 'Bash', hooks: [check])
+# ArgumentError: ClaudeAgentSDK::HookMatcher: unknown attribute :matchr (known: hooks, matcher, timeout)
 ```
 
-**In 1.0 the same call raises `ArgumentError`.** This covers `.new` and `#[]=` on:
+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.
+A nested value is checked as its own type: `PermissionUpdate.new(rules: [{ rule_contnt: 'x' }])` raises naming `PermissionRuleValue`.
+
+Accepted: Symbol or String keys, snake_case or camelCase spellings, and the fixed discriminator a type sets itself (`type`, `hook_event_name`, `behavior`), so on a type that defines its own `#to_h` (the MCP server configs, `SandboxSettings`, the system prompt types, the hook outputs, ...) `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 is ignored rather than raising, and so does every construction through `.from_hash` or `.wrap`. Use those two for data you did not write yourself, such as a Hash deserialized from the CLI or from storage.
+
+(0.37 printed a one-time warning here and ignored the key; 1.0 raises. See [UPGRADING-1.0.md](../UPGRADING-1.0.md).)
 
 ### 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:
+`#[]`, `#[]=` 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.
 
-```
-app/jobs/sync.rb:8: warning: ClaudeAgentSDK::ResultMessage#[]: :to_h is not an attribute; Type#[] will only read attributes 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`), a camelCase call raises `NoMethodError`, and `respond_to?` answers `false`. So `msg[:to_h]` is `nil`, `msg['freeze']` does not freeze the message, and `msg.toH` raises; call the method directly instead (`msg.to_h`). `UserMessage#text` and `AssistantMessage#text` are convenience methods, not attributes.
 
-**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.
+(Through 0.37 these accessors reached any public method, with a one-time warning in 0.37.)
 
 ## Constants
 

data/lib/claude_agent_sdk/deprecation.rb

@@ -35,56 +35,17 @@ module ClaudeAgentSDK
         return unless first
 
         begin
-          warn("ClaudeAgentSDK.#{name} is deprecated and will be removed in 1.0; " \
+          warn("ClaudeAgentSDK.#{name} is deprecated and will be removed in 2.0; " \
                "use ClaudeAgentSDK.#{replacement}", uplevel: 2)
         rescue StandardError
           nil
         end
       end
 
-      # Warn +message+ once per process per +key+, attributed to the first
-      # caller frame outside the SDK's lib/ directory: the user's call site,
-      # however deep inside the SDK the deprecated behaviour is detected
-      # (e.g. an unknown attribute found by Type#assign_attribute during
-      # HookMatcher.new). Best-effort like #warn_once.
-      #
-      # @param key [Object] once-guard key; any value usable in a Set
-      # @param message [String]
-      # @return [void]
-      def warn_once_at_caller(key, message)
-        first = @mutex.synchronize { @warned.add?(key) }
-        return unless first
-
-        begin
-          locations = caller_locations(1)
-          index = locations.index { |location| !sdk_frame?(location) }
-          index ? warn(message, uplevel: index + 1) : warn(message)
-        rescue StandardError
-          nil
-        end
-      end
-
       # Test hook: forget which deprecations were already reported.
       def reset!
         @mutex.synchronize { @warned.clear }
       end
-
-      private
-
-      # A frame inside the gem's lib/ (both the loaded and the real path, in
-      # case lib/ is reached through a symlink), or a Ruby-internal one
-      # (<internal:...>, e.g. Array#each on 3.4). A C frame such as Class#new
-      # reports its caller's path, so it counts as the caller's.
-      def sdk_frame?(location)
-        path = location.absolute_path || location.path
-        return true if path.nil? || path.start_with?('<internal:')
-
-        SDK_LIB_DIRS.any? { |dir| path.start_with?(dir) }
-      end
     end
-
-    SDK_LIB_DIRS = [File.expand_path('..', File.dirname(__FILE__)), File.expand_path('..', __dir__)]
-                   .uniq.map { |dir| "#{dir}/" }.freeze
-    private_constant :SDK_LIB_DIRS
   end
 end

data/lib/claude_agent_sdk/errors.rb

@@ -31,6 +31,14 @@ module ClaudeAgentSDK
   # relative HOME). Set CLAUDE_CONFIG_DIR to fix it.
   class ConfigDirError < ClaudeSDKError; end
 
+  # Raised when resuming a session from ClaudeAgentOptions#session_store
+  # fails: a store call (#load, #list_sessions, #list_subkeys, ...) raised or
+  # exceeded load_timeout_ms while the SDK was materializing the transcript
+  # for the CLI. Raised by Client#connect, ClaudeAgentSDK.query and .ask,
+  # before the CLI starts. The message names the store call; #cause holds the
+  # adapter's own exception (or the internal timeout).
+  class SessionStoreError < ClaudeSDKError; end
+
   # Raised when the CLI process fails
   class ProcessError < ClaudeSDKError
     attr_reader :exit_code, :stderr
@@ -112,6 +120,8 @@ module ClaudeAgentSDK
     # never disagree. Private to ResultError (Python keeps the equivalent
     # helpers module-private as _normalize_result_errors); callers outside
     # go through .error_text.
+    #
+    # @api private
     module Payload
       module_function
 

data/lib/claude_agent_sdk/session_resume.rb

@@ -119,7 +119,8 @@ module ClaudeAgentSDK
     # Returns a MaterializedResume, or nil when no materialization is needed
     # (no store, no resume/continue, store has no entries, or the resolved
     # session id is not a valid UUID) — the caller then falls through to the
-    # normal spawn path. Raises RuntimeError if a store call fails or times out.
+    # normal spawn path. Raises SessionStoreError (#cause: the adapter's own
+    # exception or the timeout) if a store call fails or times out.
     def materialize_resume_session(options) # rubocop:disable Metrics/AbcSize -- materialization sequence kept in order
       store = options.session_store
       return nil if store.nil?
@@ -290,7 +291,12 @@ module ClaudeAgentSDK
     end
 
     # Run a store call (user code) on a plain thread bounded by timeout_s,
-    # re-raising failures/timeouts as RuntimeError with context. The thread hop
+    # re-raising failures/timeouts as SessionStoreError with context, the
+    # original as #cause (Ruby sets it: the raise is inside the rescue). Every
+    # StandardError is wrapped, the adapter's own RuntimeError included, so
+    # `rescue ClaudeSDKError` catches every materialization failure (0.x let
+    # a RuntimeError through unwrapped and raised the rest as bare
+    # RuntimeErrors, mirroring Python). The thread hop
     # (the default for FiberBoundary with a timeout) both keeps the async
     # scheduler out of the user's store code AND enforces load_timeout_ms
     # unconditionally — including when materialization runs outside an Async
@@ -305,11 +311,11 @@ module ClaudeAgentSDK
     def with_timeout(timeout_s, what, scheduling = :thread, wrapper = nil, &)
       FiberBoundary.invoke(timeout: timeout_s, scheduling: scheduling, wrapper: wrapper, &)
     rescue FiberBoundary::JoinTimeout
-      raise "#{what} timed out after #{(timeout_s * 1000).to_i}ms during resume materialization"
-    rescue RuntimeError
+      raise SessionStoreError, "#{what} timed out after #{(timeout_s * 1000).to_i}ms during resume materialization"
+    rescue SessionStoreError
       raise
     rescue StandardError => e
-      raise "#{what} failed during resume materialization: #{e}"
+      raise SessionStoreError, "#{what} failed during resume materialization: #{e.class}: #{e.message}"
     end
 
     # Write pre-encoded JSON lines (see encode_jsonl_lines), one per line,

data/lib/claude_agent_sdk/types/attributes.rb

@@ -1,20 +1,12 @@
 # frozen_string_literal: true
 
-require_relative '../deprecation'
-
 module ClaudeAgentSDK
   # Attribute declarations and the rules #[], #[]=, .new and the camelCase
   # readers follow (issue #126). Loaded by base.rb right after Type itself,
   # before any subclass declares an attribute.
   class Type
-    # The 1.0 switch for attribute access, false through 0.x. When true:
-    # an unknown key on a strict type (see .strict_attributes) raises
-    # ArgumentError, and #[], #[]= and the camelCase readers reach declared
-    # attributes only. While false, both cases warn once per class and name.
-    ENFORCE_ATTRIBUTES = false
-
     LENIENT_KEY = :__claude_agent_sdk_lenient_attributes
-    private_constant :ENFORCE_ATTRIBUTES, :LENIENT_KEY
+    private_constant :LENIENT_KEY
 
     class << self
       # attr_accessor / attr_reader / attr_writer also declare the names as
@@ -108,9 +100,9 @@ module ClaudeAgentSDK
 
     # Declares a type the user constructs and passes IN (option values, hook
     # matchers and outputs, permission results and updates). Constructing
-    # one directly (.new or #[]=) with a key that is not an attribute warns
-    # once per class and key — a typo would otherwise be dropped silently —
-    # and raises ArgumentError from 1.0. A read-only attribute (the +type+,
+    # one directly (.new or #[]=) with a key that is not an attribute raises
+    # ArgumentError — a typo would otherwise be dropped silently (0.37 warned
+    # here; 1.0 raises). A read-only attribute (the +type+,
     # +hook_event_name+ or +behavior+ discriminator a type sets itself, which
     # its own #to_h emits) is accepted and ignored. Types the SDK parses from
     # CLI output stay lenient so a newer CLI's extra fields never break an
@@ -151,15 +143,14 @@ module ClaudeAgentSDK
           self.class.cache_attribute_reader(method_name, normalized.to_sym)
           return public_send(normalized, ...)
         end
-        return public_send(normalized, ...) if reachable?(normalized, method_name, :camel_case)
+        return public_send(normalized, ...) if user_defined_method?(normalized)
       end
       super
     end
 
     def respond_to_missing?(method_name, include_private = false)
       normalized = normalize_name(method_name)
-      (normalized != method_name.to_s && respond_to?(normalized) &&
-        (!ENFORCE_ATTRIBUTES || attribute_method?(normalized))) || super
+      (normalized != method_name.to_s && respond_to?(normalized) && attribute_method?(normalized)) || super
     end
 
     def assign_attributes(attributes)
@@ -184,12 +175,12 @@ module ClaudeAgentSDK
           self.class.cache_attribute_writer(name, setter)
           return public_send(setter, value)
         end
-        return public_send(setter, value) if reachable?(setter.to_s, name, :write)
+        return public_send(setter, value) if user_defined_method?(setter.to_s)
       end
       return unless self.class.strict_attributes? && !Thread.current[LENIENT_KEY] && !self.class.attribute?(normalized)
       return if respond_to?(normalized) && user_defined_method?(normalized)
 
-      unknown_attribute(name, normalized)
+      unknown_attribute(name)
     end
 
     def read_attribute(name)
@@ -202,7 +193,7 @@ module ClaudeAgentSDK
       if self.class.attribute_method?(getter)
         self.class.cache_attribute_reader(name, getter.to_sym)
         public_send(getter)
-      elsif reachable?(getter, name, :read)
+      elsif user_defined_method?(getter)
         public_send(getter)
       end
     end
@@ -234,38 +225,12 @@ module ClaudeAgentSDK
       !name.nil? && (name == 'ClaudeAgentSDK' || name.start_with?('ClaudeAgentSDK::'))
     end
 
-    # #[], #[]= (and so .new) or a camelCase call resolved to +method_name+, a
-    # public method. An attribute passes. Any other method (to_h, freeze, ...)
-    # passes with a warning once per class and name through 0.x, and is
-    # treated as undefined from 1.0.
-    def reachable?(method_name, name, access)
-      return true if attribute_method?(method_name)
-      return false if ENFORCE_ATTRIBUTES
-
-      class_name = self.class.name || self.class.inspect
-      message = case access
-                when :read then "#{class_name}#[]: #{name.inspect} is not an attribute; " \
-                                'Type#[] will only read attributes in 1.0'
-                when :write then "#{class_name}#[]=: #{name.inspect} is not an attribute; " \
-                                 'Type#[]= and .new will only write attributes in 1.0'
-                else "#{class_name}##{name}: #{method_name} is not an attribute; " \
-                     'camelCase methods will only reach attributes in 1.0'
-                end
-      Deprecation.warn_once_at_caller([:non_attribute, self.class, method_name], message)
-      true
-    end
-
-    def unknown_attribute(name, normalized)
+    # A key that is not an attribute, on a strict type: a typo the user
+    # would otherwise never see.
+    def unknown_attribute(name)
       klass = self.class
-      class_name = klass.name || klass.inspect
-      known = klass.attribute_names.join(', ')
-      raise ArgumentError, "#{class_name}: unknown attribute #{name.inspect} (known: #{known})" if ENFORCE_ATTRIBUTES
-
-      Deprecation.warn_once_at_caller(
-        [:unknown_attribute, klass, normalized],
-        "#{class_name}: unknown attribute #{name.inspect} ignored; " \
-        "this will raise ArgumentError in 1.0 (known: #{known})"
-      )
+      raise ArgumentError, "#{klass.name || klass.inspect}: unknown attribute #{name.inspect} " \
+                           "(known: #{klass.attribute_names.join(', ')})"
     end
   end
 end

data/lib/claude_agent_sdk/types/base.rb

@@ -158,6 +158,8 @@ module ClaudeAgentSDK
     # `seen` holds the Types/containers on the current rendering path (not
     # every one rendered so far), so a shared-but-acyclic value still renders
     # in full wherever it appears.
+    #
+    # @api private
     def inspect_with(depth, seen)
       return "#<#{inspect_class_name} …>" if depth > INSPECT_MAX_DEPTH || seen.key?(self)
 

data/lib/claude_agent_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '0.37.0'
+  VERSION = '1.0.0'
 end