claude-agent-sdk 0.29.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2722d8b996148ef678484d587c1fcd88aaa68d9f3a380b342ad81b784f558cc
-  data.tar.gz: ce8a7d155a9c21fcddd4ad4dee0ec2b728d5397bb378d0b4c53f867febbc9cf0
+  metadata.gz: ec4f48758138c2a833ba6adc419753f8b8c1b7b2555824c5b2a497d6ab191c8a
+  data.tar.gz: 48787d59ffcbd3fa6c90b953234064065aad8cfc87ddc85d77f042d87a9bb250
 SHA512:
-  metadata.gz: 4a73b55a0228259e19e847683c4acccc6ac319f355f7d7fe9c8fd01dbc642e6ff7de767217b770dd95b8e3e847f280f46b49a7888f534278529b576412c29a7a
-  data.tar.gz: 5a1012c3ebd9a59f2a97476210b41873d616f053e7c02ba7c2bb385968f8134fb13b9f13730bb0c404b41877cc169dbde7c94f2d87b461671377492934511d0f
+  metadata.gz: dce3bf872a4bfe12c72248a9f036d2c706600679e9724200eef80da47a093c4e1d7be3e9ec7b895105a35f56f07dce26d8516b03c26c040fd60f8a53b594a785
+  data.tar.gz: 4a51034acf467515e897a8739b3f0dc0c85392bd88d88fe90b21251af98f78b29a7fc5877305e7136c7fa5cf9a0e5b64edd718d20794e90fbb14614619ff6246

data/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-08-28
+
+Syncs the gem with Python SDK **0.2.147** (previously 0.2.134). The intervening Python releases 0.2.135/136/138/139/141–147 only bump the CLI binary Python bundles; this gem does not vendor a CLI, so they carry no Ruby-side change.
+
+### Added
+- **`ConversationResetMessage`** (port of Python [#1196](https://github.com/anthropics/claude-agent-sdk-python/pull/1196), v0.2.137). The CLI announces a mid-session transcript discard (`/clear`, and any other flow that replaces the conversation without ending the connection) with a top-level `conversation_reset` frame. It was previously dropped by the parser's forward-compatibility fallthrough, so applications never saw resets — including ones they did not initiate. Carries `new_conversation_id`, `uuid` and `session_id`. A reset also **zeroes the running totals** on subsequent `ResultMessage`s (`total_cost_usd` and friends), so snapshot them when this arrives. `new_conversation_id` is not the next `session_id`; read that from the following message.
+  - **Compatibility:** this widens the `Message` union with a frame that was previously dropped silently. Code that raises on an unrecognized message class (`case msg ... else raise`) will now see it — on the first `/clear` of a long-lived session.
+- **`origin` on `UserMessage` and `ResultMessage`** (port of Python [#1199](https://github.com/anthropics/claude-agent-sdk-python/pull/1199), v0.2.137). In streaming/`Client` mode one connection interleaves the turns the application sends with turns the session injects on its own — background-task notifications, fired scheduled-task prompts, MCP channel messages, messages relayed from peer sessions. `origin` distinguishes them, so a consumer can tell "this result answers my prompt" from a task-notification follow-up. The CLI's object is passed through **verbatim** — including keys this version does not model, so newer origin kinds stay visible — and anything that is not an object with a String `kind` reads as `nil`. **Keys are Symbols and non-`kind` keys keep the CLI's camelCase spelling** (`origin[:fromSession]`), unlike the Python SDK's string-keyed equivalent. Prompts sent through `query()` / `Client#query` arrive unattributed unless the host stamps `origin: { kind: 'human' }` itself.
+- **`ClaudeAgentOptions#forward_subagent_text`** (port of Python [#1206](https://github.com/anthropics/claude-agent-sdk-python/pull/1206), v0.2.140). Forwards a subagent's text and thinking blocks as messages in the stream, not just its `tool_use` / `tool_result` blocks, so consumers can render the full nested transcript. Negotiated on the control-protocol handshake, so it applies to both `query()` and `Client`. Matches the TypeScript SDK's `forwardSubagentText`.
+- **`ClaudeAgentOptions#resume_drops_turn`** (port of Python [#1198](https://github.com/anthropics/claude-agent-sdk-python/pull/1198), v0.2.137). Completes the truncating-resume pair alongside the existing `resume_session_at`: names the user prompt whose turn a truncating resume intends to discard, and the CLI refuses the resume if anything past the fork point is not attributable to that turn — so a caller can rewind to "before my last prompt" without silently dropping a queued message or task notification the session absorbed mid-turn and the caller never observed. A refusal surfaces as a `ResultError` whose message contains `Resume rejected by --resume-drops-turn:`; treat it as deterministic rather than retrying. Forwarded in equals form, and an empty string is forwarded rather than dropped so the CLI rejects it as malformed instead of the SDK silently disarming a guard the caller believes is armed. As in the TypeScript and Python SDKs, no SDK-side validation of the option combination is applied.
+- **`ClaudeAgentSDK::ResultError`** (port of Python [#1205](https://github.com/anthropics/claude-agent-sdk-python/pull/1205), v0.2.140). When a run fails, the CLI emits a `result` with `is_error: true` and then exits non-zero on purpose, for shell-script consumers; the trailing failure carried nothing beyond "exit code 1". The SDK now raises a typed `ResultError` carrying `subtype`, `errors`, `result`, `api_error_status`, `terminal_reason`, `session_id`, the raw `data`, and `original_error` (the bare exit failure it replaced), so callers can branch on *why* a run failed without string matching. It **subclasses `ProcessError`**, so existing `rescue ProcessError` handlers keep working — rescue `ResultError` first to reach the structured fields.
+- **`SessionMessage#parent_agent_id`**, and `parent_tool_use_id` is now populated for subagent transcripts (port of Python [#1207](https://github.com/anthropics/claude-agent-sdk-python/pull/1207), v0.2.140). `get_subagent_messages` and `get_subagent_messages_from_store` previously returned `parent_tool_use_id: nil` for every message, losing the link to the Agent `tool_use` block in the parent session that spawned the subagent. Both are now recovered from the `agent-<id>.meta.json` sidecar (or the `agent_metadata` entry in a `SessionStore`), and stay `nil` when it is missing or unusable.
+
+### Fixed
+- **A refused or failed resume no longer reports a bare "exit code 1" to in-flight control requests** (port of Python [#1198](https://github.com/anthropics/claude-agent-sdk-python/pull/1198)). The CLI reports a rejected resume as an error result on stdout and then exits **before** answering the SDK's `initialize`. The read loop already replaced the generic process failure with the CLI's own error text for the message stream, but pending control requests — including that in-flight handshake — were signalled with the raw exception first, so callers saw `Command failed with exit code 1` with the actual reason discarded. Pending requests now receive the same enriched `ResultError`. This also improves resuming a nonexistent session, which takes the same path.
+- **`can_use_tool` no longer has its permission requests cut off when it is the only bidirectional feature in use.** The check deciding whether the CLI may still send control requests needing a reply considered only SDK MCP servers and hooks, so an `Enumerator` prompt using `can_use_tool` with neither of those closed stdin as soon as the input ended; any later permission `control_request` then failed CLI-side with "Stream closed". This was a live defect on an already-supported path, independent of the string-prompt change below.
+- **Store-backed resume now seeds the caller's `settings.json` and `cowork_settings.json`** into the temporary config directory (port of Python [#1197](https://github.com/anthropics/claude-agent-sdk-python/pull/1197), v0.2.137). Only `.credentials.json` and `.claude.json` were copied, leaving behind `apiKeyHelper` — a fourth authentication mechanism alongside the credentials file, the macOS Keychain and environment variables — plus the user's `env`, `hooks` and `permissions`. A host authenticating solely via `apiKeyHelper` therefore failed with **"Not logged in"** the moment it resumed from a store, with nothing in the error pointing at why. Both files pass through a transform dropping `enabledPlugins` / `extraKnownMarketplaces` (which would reconcile against the always-empty temporary plugin cache and network-install every declared marketplace on each resume) and `env.CLAUDE_CONFIG_DIR` (which would point the subprocess's config reads back out of the temporary directory). A UTF-8 BOM is tolerated, content that is not a JSON object is copied through byte-for-byte, and the result is written `0600`.
+- **A seed file that cannot be read no longer aborts an otherwise-valid resume.** These files are best-effort enrichment of the temporary config directory: a failure other than "not found" is now logged and skipped (removing any partial destination) rather than propagating. Readers also check for a regular file before opening, so a directory or a FIFO in place of a config file is skipped instead of raising — or, for a FIFO, hanging the resume forever.
+- **An unusable subagent metadata sidecar no longer breaks every later resume.** `JSON.parse` is lenient about illegal bytes inside an otherwise well-formed UTF-8-tagged document, returning a Hash holding invalidly-encoded values that only fail later, at generate time. Session import persisted such a Hash as an `agent_metadata` entry, and every subsequent resume through that store then died re-serializing it with an opaque `JSON::GeneratorError` — permanently, until the store entry was repaired externally. Unusable bytes are now treated as an absent sidecar, matching the helper's documented contract. The same regular-file guard prevents a FIFO sidecar from hanging `get_subagent_messages`.
+- **`settings.json` containing a lone surrogate escape is no longer copied through unstripped.** Ruby's `JSON.parse` rejects lone surrogates outright, which fell back to the byte-for-byte passthrough — so `enabledPlugins` survived and the resumed CLI went on network-installing marketplaces on every resume, the exact misbehavior the seeding transform exists to prevent.
+- **Redacting `.credentials.json` no longer aborts a resume on a serialization failure**, and its comment now describes what the code actually does; the rescue covered only parse failures, so a generate failure propagated and took down a resume that every other seed-file path is designed to survive.
+
+### Changed
+- **`can_use_tool` now works with a String prompt** (port of Python [#1204](https://github.com/anthropics/claude-agent-sdk-python/pull/1204), v0.2.140). The callback previously required an `Enumerator` prompt and raised `ArgumentError` otherwise. The SDK is always streaming internally, so the restriction was unnecessary once stdin is held open for the permission round-trip. Validation of the `can_use_tool` / `permission_prompt_tool_name` conflict and the shadowing advisory are now shared by `query()` and `Client#connect` instead of duplicated.
+
+
+## [0.30.0] - 2026-08-09
+
+### Added
+- **`ClaudeAgentSDK::CLIInstaller`** — downloads a pinned `claude` CLI binary into a project-local directory (`vendor/claude` by default) for hermetic deploys, so a Docker image or CI job runs a known CLI version instead of whatever `npm install -g` last put on `PATH`. `CLIInstaller.install(version: '2.1.220', dir: nil)` resolves `stable`/`latest` dist-tags through the official release endpoint, verifies the platform's SHA-256 from the release manifest, streams the ~280MB binary to an unpredictable sibling temp file (opened `O_EXCL`, so a pre-planted path or symlink is never written through) and renames it into place atomically (`0755`), then records the version **and** the verified checksum in a sibling `VERSION` file. `CLIInstaller.installed_path` returns the vendored binary or `nil`. Stdlib only — no new runtime dependency, and no binary shipped inside the gem. Supports macOS and Linux (glibc + musl, x86_64 + arm64, with a Rosetta 2 override so an x86_64 Ruby on Apple Silicon gets the native build); every failure raises the new `ClaudeAgentSDK::CLIInstallError`, filesystem errors included (wrapped, with `cause` preserved).
+  - **Idempotent without trusting the recorded version alone**: the shortcut re-hashes the vendored binary and skips the download only when version *and* checksum match, so a truncated or swapped binary is reinstalled rather than used. It makes no network request — repeat boots work offline.
+  - **Concurrency-safe**: an exclusive `flock` on `<dir>/.install.lock` covers dist-tag resolution and the whole check → download → record → publish sequence (last resolver wins, so a slow installer cannot downgrade a newer version published while it waited), and the `VERSION` file is written atomically (temp + rename), so parallel installs into one directory can never observe or produce a half-installed state. Temp files abandoned by an install that was killed before it could clean up are swept on the next run. Discovery (`installed_path`, `find_cli`) stays lock-free: the binary only ever changes by an atomic rename of a fully verified file, so a reader sees the intact old binary or the intact new one.
+  - **A failed install never breaks a working one**: the binary is downloaded, verified and *recorded* before the rename that publishes it, and nothing can fail after that rename. A failed upgrade therefore leaves the previously installed binary intact and runnable, with the next `install` redoing it cleanly; a failed first install leaves nothing behind.
+  - Text responses are size-capped (1KB for the version endpoint, 5MB for the manifest), and the binary download is bounded by the manifest's declared `size` when present — an over-long stream is aborted instead of filling the disk. The binary streams to disk and is never buffered in memory.
+- **CLI discovery now honors `CLAUDE_CLI_PATH` and the vendored binary.** `SubprocessCLITransport#find_cli` probes `CLAUDE_CLI_PATH` (when it points at an executable), then `CLIInstaller.installed_path`, then the existing `which claude` and common-location logic. The vendored copy deliberately outranks `PATH` — that is what makes a pinned install hermetic. `CLINotFoundError` now also mentions both escape hatches.
+
 ## [0.29.0] - 2026-08-09
 
 ### Fixed

data/README.md

@@ -25,7 +25,7 @@ All three SDKs share the same underlying mechanism: they spawn the `claude` CLI
 | Hooks (all 27 events) | ✅ | ✅ | ✅ |
 | Permission callbacks | ✅ | ✅ | ✅ |
 | Structured output | ✅ | ✅ | ✅ |
-| All 24 message types | ✅ | partial | ✅ |
+| All 25 message types | ✅ | partial | ✅ |
 | [Sandbox](https://github.com/anthropic-experimental/sandbox-runtime) settings | ✅ | partial | ✅ |
 | Bare mode (`--bare`) | ✅ | ✅ | ✅ |
 | File checkpointing & rewind | ✅ | ✅ | ✅ |
@@ -36,7 +36,7 @@ All three SDKs share the same underlying mechanism: they spawn the `claude` CLI
 | Custom transport (pluggable I/O) | — | — | ✅ |
 | Rails integration | — | — | ✅ |
 
-**Where Ruby goes further:** Built-in OpenTelemetry observer with Langfuse flow diagram support — no third-party instrumentation library needed. Custom transport support lets you swap the subprocess for any I/O layer (e.g., connect to a remote Claude Code instance over SSH or a container). Rails integration provides a `configure` block for initializers with thread-safe observer factories, and plays well with ActionCable for real-time streaming. Full typed coverage for all 24 CLI message types and all 27 hook events.
+**Where Ruby goes further:** Built-in OpenTelemetry observer with Langfuse flow diagram support — no third-party instrumentation library needed. Custom transport support lets you swap the subprocess for any I/O layer (e.g., connect to a remote Claude Code instance over SSH or a container). Rails integration provides a `configure` block for initializers with thread-safe observer factories, and plays well with ActionCable for real-time streaming. Full typed coverage for all 25 CLI message types and all 27 hook events.
 
 **What's missing:** The Ruby gem does not bundle the `claude` CLI binary (`npm install -g @anthropic-ai/claude-code`).
 
@@ -68,7 +68,7 @@ Add this line to your application's Gemfile:
 gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
 
 # Or use a stable version from RubyGems
-gem 'claude-agent-sdk', '~> 0.29.0'
+gem 'claude-agent-sdk', '~> 0.31.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.
@@ -78,6 +78,56 @@ Then `bundle install`, or install directly: `gem install claude-agent-sdk`.
 - Node.js
 - Claude Code 2.0.0+: `npm install -g @anthropic-ai/claude-code`
 
+### Vendoring the CLI (hermetic deploys)
+
+The SDK runs the `claude` CLI as a subprocess, so a deploy is only reproducible if the CLI version is pinned with it. `CLIInstaller` downloads a pinned binary from the official release endpoint into a project-local directory (`vendor/claude` by default) — checksum-verified, no npm/Node at runtime, and nothing extra shipped inside the gem.
+
+```ruby
+require 'claude_agent_sdk'
+
+# 'stable' (default), 'latest', or a concrete version — pin it in production.
+ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')
+# => "/app/vendor/claude/claude"
+
+ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220', dir: '/opt/claude')
+
+# nil unless a binary is already installed there
+ClaudeAgentSDK::CLIInstaller.installed_path
+```
+
+`install` is idempotent and safe to run concurrently, so it fits `bin/setup`, a cached Docker layer, and every process of a multi-process boot:
+
+- The install directory's `VERSION` file records the installed version **and** the SHA-256 that was verified at download time. The shortcut re-hashes the vendored binary (~0.1s for the real 245MB binary) and only skips the download when both match — a truncated, swapped or half-written binary is reinstalled instead of trusted. It makes **no network request**, so repeat boots work offline — with a pinned concrete version; `'stable'`/`'latest'` must always re-resolve through the endpoint, which is one more reason to pin in production.
+- An exclusive `flock` on `<dir>/.install.lock` covers the whole check → download → place → record sequence, so parallel installs into one directory don't race; the loser simply observes the finished install.
+
+Failures (unsupported platform, invalid version, HTTP error, response-size cap, oversized download, checksum mismatch, filesystem errors) raise `ClaudeAgentSDK::CLIInstallError`.
+
+**A failed install never breaks a working one.** The new binary is downloaded to a temp file, checksum-verified and recorded, and only then renamed into place — the rename is the last step, and nothing can fail after it. So a failed upgrade leaves the previously installed binary intact and runnable (the SDK keeps working), and the next `install` redoes it cleanly. A first install that fails leaves nothing behind at all.
+
+> The vendored directory is trusted input: anything that can write to it can replace the binary the SDK executes. Keep it inside your deploy artifact, owned by the deploy user and not world-writable, exactly as you would treat `bin/`.
+
+```dockerfile
+# Dockerfile — pin the CLI in its own cached layer
+RUN bundle exec ruby -e "require 'claude_agent_sdk'; \
+    ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')"
+```
+
+```ruby
+#!/usr/bin/env ruby
+# bin/setup
+require 'claude_agent_sdk'
+puts ClaudeAgentSDK::CLIInstaller.install(version: ENV.fetch('CLAUDE_CLI_VERSION', 'stable'))
+```
+
+Supported platforms: `darwin-arm64`, `darwin-x64` (Rosetta 2 gets the arm64 build), `linux-x64`, `linux-arm64`, and the `-musl` variants. Windows is not supported.
+
+**CLI discovery order.** With no explicit `cli_path:` in `ClaudeAgentOptions`, the transport probes in this order:
+
+1. `CLAUDE_CLI_PATH` — an explicit path to an executable, no discovery at all (a relative value is resolved against the process's working directory, not `cwd:`)
+2. The vendored binary (`CLIInstaller.installed_path`) — deliberately ahead of `PATH`, so a pinned install beats whatever is installed globally
+3. `which claude`
+4. Common install locations (`~/.claude/local/claude`, `/usr/local/bin/claude`, …)
+
 ### Agentic Coding Skill
 
 If you're using [Claude Code](https://claude.ai/claude-code), this repo is a Claude Code plugin marketplace. Add it once, then install the skill:
@@ -222,7 +272,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 |---------|-------------|
 | [quick_start.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/quick_start.rb) | Basic `query()` usage with options |
 | [client_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/client_example.rb) | Interactive Client usage |
-| [message_types_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/message_types_example.rb) | Handling all 24 SDK message types |
+| [message_types_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/message_types_example.rb) | Handling all 25 SDK message types |
 | [streaming_input_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/streaming_input_example.rb) | Streaming input for multi-turn conversations |
 | [session_resumption_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_resumption_example.rb) | Multi-turn conversations with session persistence |
 | [structured_output_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/structured_output_example.rb) | JSON schema structured output |

data/docs/configuration.md

@@ -223,6 +223,23 @@ 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).
 
+## Forwarding Subagent Text
+
+By default only `tool_use` / `tool_result` blocks from subagents (spawned via
+the Agent tool) reach the message stream, as `AssistantMessage` /
+`UserMessage` objects whose `parent_tool_use_id` is the spawning Agent
+`tool_use` id — enough for a progress heartbeat. Set `forward_subagent_text`
+to forward the subagent's **text and thinking** blocks the same way, so you
+can render the full nested transcript:
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(forward_subagent_text: true)
+```
+
+Matches the TypeScript SDK's `forwardSubagentText`. The capability is
+negotiated on the control-protocol handshake, so it applies to both
+`ClaudeAgentSDK.query` and `Client`.
+
 ## File Checkpointing & Rewind
 
 Enable file checkpointing to revert file changes to a previous state:

data/docs/errors.md

@@ -31,6 +31,12 @@ rescue ClaudeAgentSDK::ControlRequestTimeoutError
   puts "Control protocol timed out — consider increasing the timeout"
 rescue ClaudeAgentSDK::CLINotFoundError
   puts "Please install Claude Code"
+rescue ClaudeAgentSDK::ResultError => e
+  # More specific than ProcessError — must be rescued first.
+  case e.terminal_reason
+  when 'api_error' then puts "API failed (HTTP #{e.api_error_status}): #{e.result}"
+  else puts "Run failed (#{e.subtype}): #{e.errors.join('; ')}"
+  end
 rescue ClaudeAgentSDK::ProcessError => e
   puts "Process failed with exit code: #{e.exit_code}"
 rescue ClaudeAgentSDK::CLIJSONDecodeError => e
@@ -38,6 +44,40 @@ rescue ClaudeAgentSDK::CLIJSONDecodeError => e
 end
 ```
 
+## Terminal Error Results
+
+When a run fails, the CLI emits a `result` message with `is_error: true` (which
+you still receive as a `ResultMessage`) and *then* exits non-zero on purpose,
+for shell-script consumers. That trailing process failure carries nothing
+beyond "exit code 1", so the SDK replaces it with a `ResultError` carrying the
+payload the CLI already reported — you can branch on *why* the run failed
+without matching on strings:
+
+```ruby
+begin
+  ClaudeAgentSDK.query(prompt: "...") { |m| handle(m) }
+rescue ClaudeAgentSDK::ResultError => e
+  retry_later    if e.terminal_reason == 'api_error'   # overloaded / timeout
+  widen_budget   if e.subtype == 'error_max_turns'
+  raise
+end
+```
+
+`ResultError` subclasses `ProcessError`, so existing `rescue ProcessError`
+handlers keep working unchanged — but rescue `ResultError` **first** if you
+want the structured fields.
+
+The exception message prefers, in order: the CLI's `errors[]`, then `result`,
+then a non-`success` `subtype`, then the HTTP status. A run that ends on an API
+failure arrives as `subtype: "success"` with `is_error: true` and the prose in
+`result`, which is why `subtype` alone is not used as the message.
+
+A refused resume (a nonexistent session, or a `resume_drops_turn` guard
+failure) reaches you the same way — including on a control request such as the
+initial handshake that was still in flight when the CLI exited. Match on
+`Resume rejected by --resume-drops-turn:` in the message and treat it as
+deterministic: clear the fork target and resume plainly rather than retrying.
+
 ## Configuring Timeout
 
 The control request timeout defaults to **1200 seconds** (20 minutes) to accommodate long-running agent sessions. Override it via environment variable:
@@ -70,6 +110,19 @@ class ProcessError < ClaudeSDKError
               :stderr      # String | nil
 end
 
+# Raised when the CLI exits after reporting a terminal error result.
+# Subclasses ProcessError, so existing `rescue ProcessError` keeps working.
+class ResultError < ProcessError
+  attr_reader :subtype,          # String | nil ('error_max_turns', 'error_during_execution', ...)
+              :errors,           # Array<String> - error strings from the CLI (may be empty)
+              :result,           # String | nil - result text; holds the "API Error: ..." prose
+              :api_error_status, # Integer | nil - HTTP status of the failing API call
+              :terminal_reason,  # String | nil - why the run ended ('api_error', 'max_turns', ...)
+              :session_id,       # String | nil
+              :data,             # Hash - raw `result` payload as emitted by the CLI
+              :original_error    # ProcessError | nil - the bare exit error this replaced
+end
+
 # Raised when JSON parsing fails
 class CLIJSONDecodeError < ClaudeSDKError
   attr_reader :line,           # String - The line that failed to parse

data/docs/sessions.md

@@ -49,6 +49,8 @@ messages = ClaudeAgentSDK.get_subagent_messages(session_id: "uuid-here", agent_i
 
 With `directory:` given, only that project and its git worktrees are searched (no global fallback). Store-backed counterparts: `list_subagents_from_store` / `get_subagent_messages_from_store`.
 
+> Each returned `SessionMessage` carries `parent_tool_use_id` — the id of the Agent `tool_use` block in the parent session that spawned this subagent — and `parent_agent_id`, the spawning subagent's id for nested subagents. Both are read from the `agent-<id>.meta.json` sidecar beside the transcript (or the `agent_metadata` entry in a `SessionStore`), and are `nil` when it is missing or unusable.
+
 ## Renaming a Session
 
 ```ruby
@@ -113,6 +115,46 @@ ClaudeAgentSDK.query(
 
 `resume_session_at` requires `resume`; the SDK raises `ArgumentError` from `CommandBuilder` when this constraint is violated, matching the underlying CLI's validation but surfacing it synchronously in the caller's stack.
 
+### Validating what the truncation discards
+
+A bare `resume_session_at` silently drops everything after the fork point —
+including a queued user message or a task notification the session absorbed
+mid-turn that you never observed. `resume_drops_turn` names the user prompt
+whose turn you *intend* to discard, and the CLI refuses the resume if anything
+past the fork point is not attributable to that turn:
+
+```ruby
+ClaudeAgentSDK.query(
+  prompt: 'try a different approach',
+  options: ClaudeAgentSDK::ClaudeAgentOptions.new(
+    resume: session_id,
+    resume_session_at: last_kept_entry_uuid,
+    resume_drops_turn: discarded_prompt_uuid
+  )
+) { |m| handle(m) }
+```
+
+Rule of thumb: set `resume_session_at` to the **last transcript entry of the
+turn you are keeping** (whatever its type), and `resume_drops_turn` to the
+prompt UUID of the turn immediately after it — the next `SessionMessage` with
+`type == 'user'` from `get_session_messages`, or the `uuid` you supplied on a
+streamed user message.
+
+With structured output (`output_format`) or end-turn MCP tools, a kept turn
+ends on entries *after* its last assistant message, so forking at the assistant
+UUID is refused by design.
+
+A refusal surfaces as a `ResultError` whose message contains
+`Resume rejected by --resume-drops-turn:`. Treat it as **deterministic** —
+clear the pending fork target and resume plainly; do not retry the same
+request. Leave `resume_drops_turn` unset to keep the unvalidated behavior.
+
+Unlike `resume_session_at`, the SDK applies no combination validation to
+`resume_drops_turn` and defers entirely to the CLI. An empty string is
+forwarded rather than dropped, so the CLI rejects it as a malformed
+declaration instead of the SDK silently disarming a guard you believe is
+armed.
+
 ## Mirroring to a `SessionStore`
 
 By default Claude Code writes session transcripts to local disk under

data/docs/types.md

@@ -6,7 +6,8 @@ See [lib/claude_agent_sdk/types.rb](https://github.com/ya-luotao/claude-agent-sd
 
 ```ruby
 # Union type of all possible messages
-Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage
+Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage |
+          StreamEvent | RateLimitEvent | ConversationResetMessage
 ```
 
 ### UserMessage
@@ -18,7 +19,8 @@ class UserMessage
   attr_accessor :content,            # String | Array<ContentBlock>
                 :uuid,               # String | nil - Unique ID for rewind support
                 :parent_tool_use_id, # String | nil
-                :tool_use_result     # Hash | nil - Tool result data when message is a tool response
+                :tool_use_result,    # Hash | nil - Tool result data when message is a tool response
+                :origin              # Hash | nil - message provenance (see Message Origin below)
 end
 ```
 
@@ -91,7 +93,8 @@ class ResultMessage
                 :uuid,               # String | nil
                 :fast_mode_state,    # String | nil ('off', 'cooldown', 'on')
                 :api_error_status,   # Integer | nil (HTTP status on api_error subtype)
-                :terminal_reason     # String | nil (see below)
+                :terminal_reason,    # String | nil (see below)
+                :origin              # Hash | nil - origin of the triggering user message (see below)
 end
 ```
 
@@ -109,6 +112,71 @@ optional `canonicalModel` (canonical id used for the pricing lookup, which can
 differ from the raw model-string key for provider-specific ids/aliases) and
 `provider` (`'firstParty'`, `'bedrock'`, `'vertex'`, ...).
 
+## Message Origin
+
+`UserMessage#origin` and `ResultMessage#origin` carry the provenance of a
+user-role turn. In streaming/`Client` mode one connection interleaves the turns
+your application sends with turns the session injects on its own — background
+task notifications, fired scheduled-task prompts, MCP channel messages,
+messages relayed from peer sessions. `origin` tells them apart:
+
+```ruby
+if result.origin.nil? || result.origin[:kind] == 'human'
+  # a turn this application submitted
+elsif result.origin[:kind] == 'task-notification'
+  # follow-up turn driven by a background task
+end
+```
+
+The Hash is passed through from the CLI **verbatim**, so:
+
+- **Keys are Symbols**, and non-`kind` keys keep the CLI's camelCase spelling —
+  `origin[:fromSession]`, `origin[:senderTaskId]`, `origin[:verifiedPeerPid]`.
+  (The Python SDK's equivalent is string-keyed; do not port `origin["kind"]`
+  literally.)
+- Keys this SDK version does not model still reach you, so newer CLI origin
+  kinds stay visible.
+- Anything that is not an object with a String `kind` reads as `nil`.
+
+Only `kind` is always present. Known kinds — treat anything unrecognized as
+"not human":
+
+`human`, `channel`, `peer`, `task-notification`, `coordinator`,
+`unclassified`, `observer`, `auto-continuation`, `observer-activity`
+
+For `kind == 'task-notification'`, `origin[:subkind]` may be
+`scheduled-trigger` (a scheduled task's prompt fired) or `peer-send-message`
+(a message from another of your sessions); it is absent for ordinary
+background-task notifications.
+
+`nil` means the CLI did not attribute the message. Prompts you send through
+`ClaudeAgentSDK.query` or `Client#query` arrive that way unless you stamp
+`origin: { kind: 'human' }` on the message Hash yourself — only the `human`
+kind is honored from an SDK host. Tool-result messages never carry an origin.
+
+### ConversationResetMessage
+
+Emitted when the session's conversation is replaced without ending the
+connection — after `/clear`, or any other flow that discards the transcript
+mid-session.
+
+```ruby
+class ConversationResetMessage
+  attr_accessor :new_conversation_id, # String - id of the fresh conversation
+                :uuid,                # String - unique ID of this message
+                :session_id           # String - the session that was reset
+end
+```
+
+A reset clears the conversation history **and zeroes the running totals**
+reported on subsequent `ResultMessage` objects (`total_cost_usd`, and the
+rest). If you accumulate those across a long-lived session, snapshot them when
+this message arrives.
+
+`new_conversation_id` is **not** the `session_id` of subsequent messages — it
+is an opaque id for keying an empty transcript in a UI (and for discarding a
+cached session title). Read the new session id from the next message.
+
 ## Content Block Types
 
 ```ruby