claude-agent-sdk 0.30.0 → 0.32.0

data/docs/configuration.md

@@ -78,6 +78,28 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 
 When set, the CLI strips per-user dynamic sections (working directory, auto-memory, git status) from the system prompt and re-injects them into the first user message instead. Older CLIs silently ignore this option.
 
+### System Prompt Snapshot
+
+By default, Claude Code builds the system prompt on a session's first request, records it, and reuses it on every later request, including after you resume the session. A changed custom prompt, or changed `append` text on the `claude_code` preset, then has no effect until the session is compacted or you start a new session. To rebuild the prompt on every request instead, for example while you iterate on its wording, set `snapshot: false` on a `SystemPromptPreset` or on `SystemPromptCustom` (the object form of a String prompt, which exists so `snapshot` can be set alongside it):
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  system_prompt: ClaudeAgentSDK::SystemPromptCustom.new(
+    prompt: 'You are a release bot.',
+    snapshot: false
+  )
+)
+
+# Hash forms work too:
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  system_prompt: { type: 'preset', preset: 'claude_code', append: '...', snapshot: false }
+)
+```
+
+`snapshot` is sent on the control-protocol `initialize` request (never as a CLI flag), so it applies to both `query()` and `Client`. When omitted it acts as `true`, except in bare mode (`bare: true`), where it acts as `false`. A `SystemPromptFile` has no `snapshot`.
+
+Requires Claude Code CLI 2.1.257 or later. Before 2.1.265, a session with an `append` or custom prompt recorded it only when `snapshot` was `true`. See [Modifying system prompts](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session) for details.
+
 ## Budget Control
 
 ```ruby
@@ -223,6 +245,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
@@ -199,7 +267,9 @@ end
 | `SandboxSettings` | Sandbox settings for isolated command execution |
 | `SandboxNetworkConfig` | Network configuration for sandbox |
 | `SandboxIgnoreViolations` | Configure which sandbox violations to ignore |
-| `SystemPromptPreset` | System prompt preset configuration |
+| `SystemPromptPreset` | System prompt preset configuration (`preset`, `append`, `exclude_dynamic_sections`, `snapshot`) |
+| `SystemPromptCustom` | Custom system prompt configuration — the object form of a String prompt, so `snapshot` can be set alongside it |
+| `SystemPromptFile` | System prompt loaded from a file path |
 | `ToolsPreset` | Tools preset configuration for base tools selection |
 
 ## Constants

data/lib/claude_agent_sdk/command_builder.rb

@@ -72,6 +72,10 @@ module ClaudeAgentSDK
         cmd.push("--system-prompt", @options.system_prompt)
       when SystemPromptFile
         cmd.push("--system-prompt-file", @options.system_prompt.path)
+      when SystemPromptCustom
+        # The object form of a String prompt; snapshot travels on the
+        # initialize request, not as a CLI flag.
+        cmd.push("--system-prompt", custom_prompt_text(@options.system_prompt.prompt))
       when SystemPromptPreset
         # Preset activates the default Claude Code system prompt by not passing --system-prompt ""
         # Only --append-system-prompt is passed if append text is provided
@@ -87,6 +91,9 @@ module ClaudeAgentSDK
       when "file"
         prompt_path = prompt_hash[:path] || prompt_hash["path"]
         cmd.push("--system-prompt-file", prompt_path) if prompt_path
+      when "custom"
+        prompt = prompt_hash.fetch(:prompt) { prompt_hash["prompt"] }
+        cmd.push("--system-prompt", custom_prompt_text(prompt))
       when "preset"
         append = prompt_hash[:append] || prompt_hash["append"]
         # Preset activates the default Claude Code system prompt by not passing --system-prompt ""
@@ -94,6 +101,17 @@ module ClaudeAgentSDK
       end
     end
 
+    # A custom prompt is always forwarded, even when empty (an empty String
+    # suppresses the default Claude Code prompt, exactly like a nil
+    # system_prompt). A missing prompt is rejected loudly rather than
+    # falling through and silently activating the default prompt — the
+    # Python SDK raises KeyError on the same input.
+    def custom_prompt_text(prompt)
+      raise ArgumentError, "system_prompt of type 'custom' requires a :prompt String" unless prompt.is_a?(String)
+
+      prompt
+    end
+
     def append_allowed_tools(cmd, allowed_tools)
       cmd.push("--allowedTools", allowed_tools.join(",")) unless allowed_tools.empty?
     end
@@ -222,6 +240,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 +259,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