claude-agent-sdk 0.30.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8e1fbf9996a81e6493a2fd8fd15a4922645933fccc93cd7d279763f01658d80
-  data.tar.gz: 87a8bbae7de66555c1c9d81f4791fe11ed51c385c233ec94e2541292d81f5870
+  metadata.gz: ec4f48758138c2a833ba6adc419753f8b8c1b7b2555824c5b2a497d6ab191c8a
+  data.tar.gz: 48787d59ffcbd3fa6c90b953234064065aad8cfc87ddc85d77f042d87a9bb250
 SHA512:
-  metadata.gz: 0d3ad7f14b8b231a4e64cc850acda569818f215e85b6e032e9217903ee650b6d434b7c8e95823fd8d6e3dde78177a3533e683b2cb96dc956c41f921324c3770c
-  data.tar.gz: '093dd27e1cd34afb33998236f761a2515ef787d86980a54bc5c9cc5c16635b8419800b0c6f7010e46cc959703abd12acdaf7cbc0135c3c532cdd2d94903a22de'
+  metadata.gz: dce3bf872a4bfe12c72248a9f036d2c706600679e9724200eef80da47a093c4e1d7be3e9ec7b895105a35f56f07dce26d8516b03c26c040fd60f8a53b594a785
+  data.tar.gz: 4a51034acf467515e897a8739b3f0dc0c85392bd88d88fe90b21251af98f78b29a7fc5877305e7136c7fa5cf9a0e5b64edd718d20794e90fbb14614619ff6246

data/CHANGELOG.md

@@ -7,6 +7,32 @@ 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

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.30.0'
+gem 'claude-agent-sdk', '~> 0.31.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.
@@ -272,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

data/lib/claude_agent_sdk/command_builder.rb

@@ -222,6 +222,7 @@ module ClaudeAgentSDK
       # flags. The equals form always binds the value to its flag.
       cmd.push("--resume=#{@options.resume}") if @options.resume
       append_resume_session_at(cmd)
+      append_resume_drops_turn(cmd)
       cmd.push("--session-id=#{@options.session_id}") if @options.session_id
     end
 
@@ -240,6 +241,29 @@ module ClaudeAgentSDK
       cmd.push("--resume-session-at=#{@options.resume_session_at}")
     end
 
+    # `--resume-drops-turn=<prompt-uuid>` declares, alongside
+    # `--resume-session-at`, which user prompt's turn this truncating resume
+    # intends to discard. The CLI validates at load time that every transcript
+    # entry after the fork point is attributable to that turn and refuses the
+    # resume otherwise — so a caller can rewind to "before my last prompt"
+    # without silently dropping a queued message or task notification the
+    # session absorbed mid-turn that the caller never observed. A refusal
+    # surfaces as an `error_during_execution` result whose message starts with
+    # `Resume rejected by --resume-drops-turn:`.
+    #
+    # No SDK-side validation of the option combination (resume /
+    # resume_session_at): like the TypeScript and Python SDKs this defers to
+    # the CLI.
+    def append_resume_drops_turn(cmd)
+      # `.nil?`, not truthiness: an empty string is forwarded so the CLI
+      # rejects it as a malformed declaration. Dropping it here would silently
+      # disarm the guard the caller believes is armed.
+      return if @options.resume_drops_turn.nil?
+
+      # Equals form for the same reason as --resume above.
+      cmd.push("--resume-drops-turn=#{@options.resume_drops_turn}")
+    end
+
     # Sandbox gating is `!nil?` throughout — Python's `sandbox is not None`.
     # Booleans and {} are forwarded verbatim: an explicit `sandbox: false`
     # must reach the CLI so it can override a sandbox enabled in the

data/lib/claude_agent_sdk/errors.rb

@@ -38,6 +38,153 @@ module ClaudeAgentSDK
     end
   end
 
+  # Raised when the CLI exits after reporting a terminal error result.
+  #
+  # The CLI ends a failed run by emitting a +result+ message with
+  # +is_error: true+ (yielded to you as a ResultMessage) and *then* exiting
+  # non-zero, on purpose, for shell-script consumers. This exception replaces
+  # the bare "exit code 1" ProcessError for that case and carries the
+  # result's payload, so callers can branch on *why* the run failed without
+  # string matching:
+  #
+  #   begin
+  #     ClaudeAgentSDK.query(prompt: '...') { |message| ... }
+  #   rescue ClaudeAgentSDK::ResultError => e
+  #     if e.terminal_reason == 'api_error'   # e.g. overloaded / timeout
+  #       retry_later
+  #     elsif e.subtype == 'error_max_turns'
+  #       ...
+  #     end
+  #   end
+  #
+  # It subclasses ProcessError, so existing +rescue ProcessError+ handlers
+  # keep working.
+  #
+  # Every structured field is type-narrowed: a payload whose +subtype+ is not
+  # a String (or whose +api_error_status+ is not an Integer, ...) reads back
+  # as nil rather than leaking the raw value, so callers can branch on these
+  # without re-validating. #data always holds the payload as the CLI sent it.
+  class ResultError < ProcessError
+    # The result subtype ("error_max_turns", "error_during_execution", ... —
+    # or "success" when the agent loop itself completed but the last turn was
+    # an API error).
+    attr_reader :subtype
+
+    # Error strings reported by the CLI (may be empty). Normalized the same
+    # way the exception text is built, so the two never disagree.
+    attr_reader :errors
+
+    # The result text, if any. For API failures this holds the
+    # "API Error: ..." prose.
+    attr_reader :result
+
+    # HTTP status of the failing API call, if any.
+    attr_reader :api_error_status
+
+    # Why the run ended (e.g. "api_error", "max_turns"), if reported.
+    attr_reader :terminal_reason
+
+    # Session the result belongs to, if reported.
+    attr_reader :session_id
+
+    # The raw +result+ message payload as emitted by the CLI.
+    attr_reader :data
+
+    # The ProcessError this replaced (the bare "exit code 1" exit).
+    #
+    # Ruby only populates #cause for an exception raised inside a rescue
+    # block; the read loop hands this one to the message queue instead of
+    # raising it there, so #cause is nil and the original exit error would be
+    # lost without an explicit accessor. Mirrors Python's __cause__ chaining.
+    attr_reader :original_error
+
+    # Reading a `result` payload: shared by the structured attributes below
+    # and by .error_text, which is the whole point — the exception's fields
+    # and its message are derived from the same normalization, so they can
+    # never disagree. Private to ResultError (Python keeps the equivalent
+    # helpers module-private as _normalize_result_errors); callers outside
+    # go through .error_text.
+    module Payload
+      module_function
+
+      # Normalize the +errors+ field of a +result+ frame to clean strings.
+      #
+      # The CLI emits an Array of Strings; tolerate a bare String (older or
+      # buggy emitters), treat anything else as empty, and drop non-String or
+      # blank entries.
+      def normalize_errors(raw)
+        raw = [raw] if raw.is_a?(String)
+        return [] unless raw.is_a?(Array)
+
+        raw.filter_map { |e| e.strip if e.is_a?(String) && !e.strip.empty? }
+      end
+
+      # Read a payload field, tolerating both key forms.
+      #
+      # Wire messages reach the SDK with symbolized keys, but a payload
+      # reconstructed by a caller (or replayed from JSON.parse without
+      # symbolize_names) uses Strings.
+      def field(data, key)
+        return nil unless data.is_a?(Hash)
+
+        data.key?(key) ? data[key] : data[key.to_s]
+      end
+    end
+    private_constant :Payload
+
+    # Pick the most informative text from a `result` frame with is_error.
+    #
+    # Terminal errors the CLI raises itself (error_max_turns,
+    # error_during_execution, ...) carry their prose in errors[]. A run that
+    # ends on an API failure instead arrives as subtype "success" with
+    # is_error true, an empty errors[] and the "API Error: ..." prose in
+    # `result` — falling back to the subtype there produced the self-
+    # contradictory "Claude Code returned an error result: success". Prefer
+    # errors[], then `result`, then a non-success subtype, then the HTTP
+    # status, mirroring the TypeScript SDK's choice of `result` for the
+    # `success` subtype.
+    #
+    # Public because the read loop builds the exception message from it, and
+    # because it is the documented way to get the same one-line summary out
+    # of a raw error result you already hold (an is_error ResultMessage the
+    # CLI emitted before exiting). Mirrors Python's _error_result_text.
+    def self.error_text(data)
+      errors = Payload.normalize_errors(Payload.field(data, :errors))
+      return errors.join('; ') unless errors.empty?
+
+      result = Payload.field(data, :result)
+      return result.strip if result.is_a?(String) && !result.strip.empty?
+
+      subtype = Payload.field(data, :subtype)
+      return subtype if subtype.is_a?(String) && !subtype.empty? && subtype != 'success'
+
+      status = Payload.field(data, :api_error_status)
+      return "API error (HTTP #{status})" unless status.nil?
+
+      'unknown error'
+    end
+
+    def initialize(message, data: nil, exit_code: nil, stderr: nil, original_error: nil)
+      data = {} unless data.is_a?(Hash)
+      @data = data
+      @original_error = original_error
+
+      subtype = Payload.field(data, :subtype)
+      @subtype = subtype.is_a?(String) ? subtype : nil
+      @errors = Payload.normalize_errors(Payload.field(data, :errors))
+      result = Payload.field(data, :result)
+      @result = result.is_a?(String) ? result : nil
+      status = Payload.field(data, :api_error_status)
+      @api_error_status = status.is_a?(Integer) ? status : nil
+      reason = Payload.field(data, :terminal_reason)
+      @terminal_reason = reason.is_a?(String) ? reason : nil
+      session_id = Payload.field(data, :session_id)
+      @session_id = session_id.is_a?(String) ? session_id : nil
+
+      super(message, exit_code: exit_code, stderr: stderr)
+    end
+  end
+
   # Raised when unable to decode JSON from CLI output
   class CLIJSONDecodeError < ClaudeSDKError
     attr_reader :line, :original_error

data/lib/claude_agent_sdk/message_parser.rb

@@ -25,6 +25,8 @@ module ClaudeAgentSDK
         parse_stream_event(data)
       when 'rate_limit_event'
         parse_rate_limit_event(data)
+      when 'conversation_reset'
+        parse_conversation_reset_message(data)
       when 'tool_progress'
         parse_tool_progress_message(data)
       when 'auth_status'
@@ -53,16 +55,32 @@ module ClaudeAgentSDK
       content = message_data[:content]
       raise MessageParseError.new("Missing content in user message", data: data) unless content
 
+      origin = parse_origin(data)
+
       if content.is_a?(Array)
         content_blocks = parse_content_blocks(content, data)
         UserMessage.new(content: content_blocks, uuid: uuid, parent_tool_use_id: parent_tool_use_id,
-                        tool_use_result: tool_use_result)
+                        tool_use_result: tool_use_result, origin: origin)
       else
         UserMessage.new(content: content, uuid: uuid, parent_tool_use_id: parent_tool_use_id,
-                        tool_use_result: tool_use_result)
+                        tool_use_result: tool_use_result, origin: origin)
       end
     end
 
+    # Returns `data[:origin]` when it is a well-formed origin object.
+    #
+    # Passed through as-is — including keys and kinds this SDK version doesn't
+    # model, and with the wire key spelling untouched (`:fromSession` stays
+    # camelCase) — so newer CLI origin kinds/fields stay visible to callers.
+    # Anything that is not a Hash with a String `:kind` is treated as absent.
+    def self.parse_origin(data)
+      origin = data[:origin]
+      return origin if origin.is_a?(Hash) && origin[:kind].is_a?(String)
+
+      nil
+    end
+    private_class_method :parse_origin
+
     def self.parse_assistant_message(data)
       message_data = data[:message]
       # A non-Hash message (malformed CLI output) raised a raw TypeError from
@@ -124,7 +142,10 @@ module ClaudeAgentSDK
     end
 
     def self.parse_result_message(data)
-      ResultMessage.new(data)
+      # `origin` is overwritten with the validated value (or nil) rather than
+      # letting the base class assign the raw field: a malformed origin must
+      # read as absent, not be surfaced verbatim.
+      ResultMessage.new(data.merge(origin: parse_origin(data)))
     end
 
     def self.parse_stream_event(data)
@@ -135,6 +156,20 @@ module ClaudeAgentSDK
       RateLimitEvent.new(data.merge(raw_data: data))
     end
 
+    # `/clear` (or any other mid-session transcript discard) resets the
+    # conversation without ending the connection. Every field is required —
+    # a frame missing one is malformed CLI output, not a forward-compatible
+    # variant, so it raises rather than yielding a half-built message.
+    def self.parse_conversation_reset_message(data)
+      ConversationResetMessage.new(
+        new_conversation_id: data.fetch(:new_conversation_id),
+        uuid: data.fetch(:uuid),
+        session_id: data.fetch(:session_id)
+      )
+    rescue KeyError => e
+      raise MessageParseError.new("Missing required field in conversation_reset message: #{e.key}", data: data)
+    end
+
     def self.parse_tool_progress_message(data)
       ToolProgressMessage.new(data)
     end