v1.0.0

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 and run your suite on 0.37 first.

1.0 (#126): three breaking changes, the first two of which 0.37 warns about at the call site. Read 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). 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 RuntimeErrors (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). Nothing else about them changes: each still works and still warns once per process.

Upgrading from 0.x

1. Upgrade to ~> 0.37.0 and run your suite with warnings visible — every call that 1.0 rejects prints a warning pointing at your code.
2. Fix those, check any rescue RuntimeError around store-backed resume (now SessionStoreError).
3. gem 'claude-agent-sdk', '~> 1.0'.

Full guide: UPGRADING-1.0.md

What's changed

• #138 1.0: strict attribute keys, attribute-only access, SessionStoreError — @ya-luotao
• #139 RBS signatures for the public API — @ya-luotao

The road here: #126 (0.35 Rails integration → 0.36 API consolidation → 0.37 deprecations → 1.0).

Full Changelog: v0.37.0...v1.0.0

---

gem install claude-agent-sdk -v 1.0.0