claude-agent-sdk 0.37.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d238195bb7f1725358c2ca33a8396ff1f4ab4121c7cc905e1dc2e1957a4553e
-  data.tar.gz: 480e5d771b68e72b0646bfa102cd921b1797d7134a925c496c5575a5e795c88e
+  metadata.gz: ecc2b309c23e9e07ce4d03aed2997d7f8c2b3fc8909f48601bfd3c1b0ca93152
+  data.tar.gz: f7c56c6cde059b2edf3b57e633ac49fa761074d633a9532f503ff2261b846795
 SHA512:
-  metadata.gz: 91d8f9de96e91aa5297e2342f33a57de100807978ac5c6bb7739927f99e0c41707f335c4e41512c9d843bf19afdc3d30ab97b526319e3cc45d932e5bae2cc761
-  data.tar.gz: e7d2504b2dcda1c0ee5d1d4174d9ece35efc1a53b9832b00595829adacc6039f423d4db4999e1139d1fb6ad93c3b532dad119f9aceb51305328d3d25d847e7f6
+  metadata.gz: 422bd92af76c1785ce33e3c50b7750d74c4dbdeb096445a0f441497be2e3f5f41a463cabd7f55374606fa236c524ae356e4a282cd75db9c7fde3fbbd4e8e07e2
+  data.tar.gz: 17b52f5f14f603cadb4fdc989b4236a5d75c4862f1ec8672014548288a67f886ede5695afce8078327d779331da87b82cc5fbfcc3fadee419037615ce7bc134b

data/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-09-30
+
+Syncs with Python SDK 0.2.162. Additive only: one new option and a fix to when `query()` closes stdin.
+
+### Added
+- **`ClaudeAgentOptions#verbatim_prompts`** (default `false`; Python SDK #1269). When `true`, every user message the SDK writes carries `client_composed: true`: String prompts and each message of a streamed prompt, through `query`, `Client#connect` and `Client#query`. Claude Code then delivers the text as written, with no `@path` file expansion and no slash-command dispatch. Use it when a prompt includes text your end user did not type. `tools: []` and `disallowed_tools` do not stop `@path` expansion, which reads the file before the model runs. While the option is on, a caller's `client_composed` key is overwritten, and caller Hashes are never mutated. A streamed JSONL String is parsed and re-serialized; one that is not a single JSON object raises `ArgumentError` rather than going out unmarked. `Client` reads the option once, at `connect`. On current CLIs such a turn also skips the turn-start attachment pass (nested `CLAUDE.md` and rules files, skill and tool listings). Requires Claude Code 2.1.248 or later; the SDK warns when it connects to an older CLI with the option on. See `docs/configuration.md`.
+- Development only, nothing ships in the gem: TLA+ models in `formal/tla/` of the two most concurrency-sensitive designs. `CLIInstaller.tla` covers `CLIInstaller.install`'s publish order, the in-lock dist-tag resolve and the stale-temp sweep. `ControlProtocol.tla` covers the outbound control-request waiter protocol in `Query`. `formal/tla/run.sh` model-checks both with TLC. It confirms that the shipped design passes and that each alternative the source comments reject, including the historical rename-then-record order, produces a counterexample.
+
+### Changed
+- `CLIInstaller::PINNED_CLI_VERSION` moves from 2.1.280 (the 1.0.0 pin) to **2.1.285**, the CLI the Python SDK 0.2.162 bundles. `CLIInstaller.install_pinned` installs it. It honors both `client_composed` (`verbatim_prompts`) and `CLAUDE_CODE_SDK_READS_SESSION_STATE` (the fix below).
+
+### Fixed
+- **`query()` with hooks, `can_use_tool` or SDK MCP servers no longer closes stdin while a follow-up turn is still owed** (Python SDK #1279, fixing Python issue #1190). A background subagent that finished just before the turn's result was already off the in-flight ledger, so stdin closed at that result, and the follow-up turn its completion triggered had every hook, permission and SDK MCP request fail with "Stream closed" (the model reported the tool as refused). The transport now sets `CLAUDE_CODE_SDK_READS_SESSION_STATE=1` unless `options.env` or the environment already names it (in any case; a `nil` value in `options.env` unsets it). The CLI then sends `session_state_changed` frames marked `sdk_host_only`, which the SDK drops from the message stream for `query()` and `Client` alike. `query()` keeps stdin open until the CLI reports `idle` after a result:
+  - The wait between turns is bounded by `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`, read from `options.env` and then the environment; the default is 10 minutes and `0` means no limit. The clock restarts at each result and at each `running`. A main-thread turn, the CLI reporting `requires_action`, a tracked background agent and a hook, permission or SDK MCP request the SDK is still answering each stop it.
+  - With an Enumerable prompt, each message written waits for its own run. Work the CLI takes up after the run ended reopens it.
+  - A CLI that sends no state (2.1.282 and earlier) gets the old behavior: stdin closes at the first result with no tracked task in flight.
+  - Background agents, bounded monitors and MCP tasks can now keep a one-shot run open, up to the ceiling. Background shells, persistent monitors and remote agents do not, because the CLI leaves them out of its `running` report.
+  - `SessionStateChangedMessage` reaches your code only if you set `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1` yourself; the SDK never sets it.
+  - A custom transport must pass `CLAUDE_CODE_SDK_READS_SESSION_STATE=1` to the CLI itself to get this behavior (see `docs/client.md`); the E2B example transport now does.
+
+## [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/client.md

@@ -117,6 +117,17 @@ A transport must implement six methods:
 | `close` | Terminate and clean up |
 | `ready?` | Report whether the transport can accept I/O |
 
+**Environment your transport should give the CLI.** `SubprocessCLITransport`
+sets a few variables that a custom transport has to set itself. The one that
+changes SDK behavior is `CLAUDE_CODE_SDK_READS_SESSION_STATE=1`: with it, the
+CLI reports its session state, and a one-shot `query()` with hooks,
+`can_use_tool` or SDK MCP servers keeps stdin open until the CLI reports
+`idle`. That is what lets a follow-up turn woken by a background subagent get
+its control requests answered. Without it, `query()` closes stdin at the first
+result with no tracked task in flight, the pre-1.1 behavior. The state frames
+arrive marked `sdk_host_only`, and the SDK drops them from your message
+stream.
+
 Then plug it into `Client` via `transport_class:` / `transport_args:`. All connect orchestration (option transforms, MCP extraction, hook conversion, Query lifecycle) is handled for you.
 
 ```ruby

data/docs/configuration.md

@@ -245,6 +245,48 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 
 See [examples/bare_mode_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/bare_mode_example.rb).
 
+## Verbatim Prompts
+
+Claude Code expands an `@/absolute/path` token anywhere in a user message into
+that file's contents, and dispatches a leading `/name` as a slash command. The
+expansion happens before the model runs and without a tool call, so `tools: []`,
+`allowed_tools` and `disallowed_tools` do not stop it. If your prompt includes
+text your end user did not type (earlier turns, tool output, third-party
+content), set `verbatim_prompts` so that text cannot make Claude Code read a
+local file:
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(verbatim_prompts: true)
+ClaudeAgentSDK.query(prompt: text_that_may_contain_at_paths, options: options) { |message| ... }
+```
+
+Every user message the SDK writes is then marked `client_composed`, and Claude
+Code delivers it exactly as written. That covers String prompts and every
+message of a streamed prompt, through `ClaudeAgentSDK.query`, `Client#connect`
+and `Client#query`.
+
+- **No per-message opt-out.** A `client_composed` key on a streamed message
+  Hash is overwritten. For per-turn control, leave the option off and set
+  `client_composed: true` on individual streamed messages.
+- Your message Hashes are never mutated.
+- A streamed JSONL String is parsed, marked and re-serialized. One that is not
+  a single JSON object raises `ArgumentError` instead of going out unmarked
+  (on the background streaming paths the stream stops with a warning, like any
+  stream error).
+- `Client` reads the option once, at `connect`.
+- **It skips more than `@path` expansion.** On current Claude Code versions a
+  turn delivered this way skips the whole turn-start attachment pass:
+  `@server:resource` MCP mentions are not expanded, and the prompt goes without
+  the context Claude Code normally attaches (nested `CLAUDE.md` and rules files,
+  skill and tool listings, other per-turn reminders). The pass between tool
+  calls still runs, so most of that context arrives after the turn's first tool
+  call.
+- Requires Claude Code **2.1.248** or later. Older versions ignore the field
+  and still expand prompts; the SDK prints a warning when it connects to one
+  with the option on.
+
+Matches the Python SDK's `verbatim_prompts`.
+
 ## Forwarding Subagent Text
 
 By default only `tool_use` / `tool_result` blocks from subagents (spawned via

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/cli_installer.rb

@@ -53,7 +53,7 @@ module ClaudeAgentSDK
     # Single source of truth: bumped here (and only here) by
     # .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'
+    PINNED_CLI_VERSION = '2.1.285'
     # @api private
     BINARY_NAME = 'claude'
     # @api private

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