claude-agent-sdk 0.30.0 → 0.32.0

data/lib/claude_agent_sdk/sessions.rb

@@ -30,16 +30,24 @@ module ClaudeAgentSDK
     end
   end
 
-  # A single message from a session transcript
+  # A single message from a session transcript.
+  #
+  # +parent_tool_use_id+ / +parent_agent_id+ are only populated for messages
+  # returned by get_subagent_messages / get_subagent_messages_from_store:
+  # respectively the id of the Agent tool_use block in the parent session that
+  # spawned the subagent, and (for nested subagents) the agent id of the
+  # subagent that spawned it. Both are nil when the subagent's metadata is
+  # unavailable, and always nil for top-level session messages.
   class SessionMessage
-    attr_accessor :type, :uuid, :session_id, :message, :parent_tool_use_id
+    attr_accessor :type, :uuid, :session_id, :message, :parent_tool_use_id, :parent_agent_id
 
-    def initialize(type:, uuid:, session_id:, message:, parent_tool_use_id: nil)
+    def initialize(type:, uuid:, session_id:, message:, parent_tool_use_id: nil, parent_agent_id: nil)
       @type = type
       @uuid = uuid
       @session_id = session_id
       @message = message
       @parent_tool_use_id = parent_tool_use_id
+      @parent_agent_id = parent_agent_id
     end
 
     # Concatenated text across every TextBlock in this message.
@@ -614,7 +622,49 @@ module ClaudeAgentSDK
         # `except OSError: return []`).
         return []
       end
-      entries_to_subagent_messages(entries, limit, offset)
+
+      # The .meta.json sidecar next to the transcript records which Agent
+      # tool_use spawned this subagent (and, for nested subagents, the parent
+      # agent id). Like the transcript read above this is best-effort: any
+      # failure to read it degrades to "no metadata" rather than raising.
+      meta = begin
+        read_agent_metadata_sidecar(path)
+      rescue SystemCallError
+        nil
+      end
+      parent_tool_use_id, parent_agent_id = parent_ids_from_agent_metadata(meta)
+
+      entries_to_subagent_messages(entries, limit, offset, parent_tool_use_id, parent_agent_id)
+    end
+
+    # agent-<id>.jsonl -> agent-<id>.meta.json in the same directory. The single
+    # definition of the sidecar naming convention, shared by the disk read path,
+    # session import, and resume materialization.
+    # @param transcript_path [String] Path to the subagent .jsonl transcript
+    # @return [String] Path to the sidecar
+    def agent_metadata_sidecar_path(transcript_path)
+      "#{transcript_path.delete_suffix('.jsonl')}.meta.json"
+    end
+
+    # Separate the synthetic agent_metadata entry from transcript lines.
+    #
+    # A subagent's SessionStore stream carries its .meta.json sidecar as
+    # { 'type' => 'agent_metadata', ... } entries alongside the transcript.
+    # Returns [metadata, transcript] where metadata is the LAST such entry (it
+    # is rewritten on resume, so last wins) or nil.
+    # @param entries [Array] Raw store/transcript entries
+    # @return [Array(Hash, Array)] [metadata_or_nil, transcript_entries]
+    def split_agent_metadata(entries)
+      metadata = nil
+      transcript = []
+      entries.each do |e|
+        if e.is_a?(Hash) && e['type'] == 'agent_metadata'
+          metadata = e
+        else
+          transcript << e
+        end
+      end
+      [metadata, transcript]
     end
 
     # ---- SessionStore-backed reads (store counterparts to the disk readers) ----
@@ -725,12 +775,15 @@ module ClaudeAgentSDK
       entries = session_store.load('project_key' => project_key, 'session_id' => session_id, 'subpath' => subpath)
       return [] if entries.nil? || entries.empty?
 
-      # Drop synthetic agent_metadata entries (they describe the .meta.json
-      # sidecar, not transcript lines).
-      transcript = entries.reject { |e| e.is_a?(Hash) && e['type'] == 'agent_metadata' }
+      # The synthetic agent_metadata entry (the store's copy of the .meta.json
+      # sidecar) records which Agent tool_use spawned this subagent. Recover the
+      # parent ids from it, then drop it: it is not a transcript line.
+      meta_entry, transcript = split_agent_metadata(entries)
       return [] if transcript.empty?
 
-      entries_to_subagent_messages(filter_transcript_entries(transcript), limit, offset)
+      parent_tool_use_id, parent_agent_id = parent_ids_from_agent_metadata(meta_entry)
+      entries_to_subagent_messages(filter_transcript_entries(transcript), limit, offset,
+                                   parent_tool_use_id, parent_agent_id)
     end
 
     # Replay a local on-disk session transcript into a SessionStore (inverse of
@@ -908,7 +961,8 @@ module ClaudeAgentSDK
     # filter_visible_messages drops sidechain entries) would return [] for
     # every real subagent transcript. Mirrors Python's
     # _entries_to_subagent_messages: type-only filter, no flag rejection.
-    def entries_to_subagent_messages(entries, limit, offset)
+    # Every message in one subagent transcript shares the same parent ids.
+    def entries_to_subagent_messages(entries, limit, offset, parent_tool_use_id = nil, parent_agent_id = nil)
       offset ||= 0
       messages = build_subagent_chain(entries).filter_map do |entry|
         next unless %w[user assistant].include?(entry['type'])
@@ -917,7 +971,9 @@ module ClaudeAgentSDK
           type: entry['type'],
           uuid: entry['uuid'],
           session_id: entry['sessionId'] || entry['session_id'] || '',
-          message: entry['message']
+          message: entry['message'],
+          parent_tool_use_id: parent_tool_use_id,
+          parent_agent_id: parent_agent_id
         )
       end
       messages = messages[offset..] || []
@@ -966,20 +1022,56 @@ module ClaudeAgentSDK
         sub_key = { 'project_key' => project_key, 'session_id' => session_id, 'subpath' => subpath }
         append_jsonl_file_in_batches(file_path, sub_key, store, batch_size)
 
-        meta_text = begin
-          File.read("#{file_path.delete_suffix('.jsonl')}.meta.json", encoding: 'UTF-8')
-        rescue Errno::ENOENT
-          nil
-        end
-        next if meta_text.nil?
+        # A missing, corrupt, or non-object sidecar is treated as absent (the
+        # transcript is still imported); other IO errors propagate.
+        meta = read_agent_metadata_sidecar(file_path)
+        next if meta.nil?
 
-        meta = JSON.parse(meta_text)
         # Synthetic 'agent_metadata' marker must always win so a future meta key
         # named 'type' can't reclassify the sidecar as a transcript line on resume.
-        store.append(sub_key, [meta.merge('type' => 'agent_metadata')]) if meta.is_a?(Hash)
+        store.append(sub_key, [meta.merge('type' => 'agent_metadata')])
       end
     end
 
+    # Read the .meta.json sidecar beside a subagent transcript. Returns nil when
+    # the sidecar is missing, is not a regular file, is not valid UTF-8, is not
+    # valid JSON, or is not a JSON object — an unusable optional sidecar
+    # degrades to an absent one. Other IO errors (EACCES, ...) propagate;
+    # callers that need a best-effort read rescue them.
+    def read_agent_metadata_sidecar(transcript_path)
+      path = agent_metadata_sidecar_path(transcript_path)
+      # Check the type on the stat, before any open: opening a FIFO with no
+      # writer blocks forever, and this optional read would hang the caller
+      # with no exception for its best-effort rescue to catch.
+      return nil unless File.stat(path).ftype == 'file'
+
+      text = File.read(path, encoding: 'UTF-8')
+      # JSON.parse is lenient about illegal bytes inside an otherwise
+      # well-formed UTF-8-tagged document: it returns a Hash holding
+      # invalidly-encoded values that only blow up later, at JSON.generate
+      # time. Session import would persist such a Hash as an agent_metadata
+      # entry, and every subsequent resume through that store would then die
+      # re-serializing the sidecar. Treat unusable bytes as an absent sidecar.
+      return nil unless text.valid_encoding?
+
+      meta = JSON.parse(text)
+      meta.is_a?(Hash) ? meta : nil
+    rescue Errno::ENOENT, JSON::ParserError
+      nil
+    end
+
+    # Extract [toolUseId, parentAgentId] from an agent metadata hash, narrowing
+    # both to String. Works for the on-disk .meta.json sidecar and for the
+    # synthetic agent_metadata entry a SessionStore receives in its place.
+    def parent_ids_from_agent_metadata(meta)
+      return [nil, nil] unless meta.is_a?(Hash)
+
+      tool_use_id = meta['toolUseId']
+      parent_agent_id = meta['parentAgentId']
+      [tool_use_id.is_a?(String) ? tool_use_id : nil,
+       parent_agent_id.is_a?(String) ? parent_agent_id : nil]
+    end
+
     def append_jsonl_file_in_batches(file_path, key, store, batch_size)
       batch = []
       nbytes = 0
@@ -1357,7 +1449,8 @@ module ClaudeAgentSDK
                          :derive_info_from_entries, :mtime_from_entries, :apply_sort_limit_offset,
                          :filter_transcript_entries, :entries_to_messages,
                          :entries_to_subagent_messages, :build_subagent_chain, :resolve_subagent_subpath,
-                         :import_subagent_files, :append_jsonl_file_in_batches, :collect_jsonl_files
+                         :import_subagent_files, :append_jsonl_file_in_batches, :collect_jsonl_files,
+                         :read_agent_metadata_sidecar, :parent_ids_from_agent_metadata
 
     # These remain accessible for SessionMutations:
     # config_dir, sanitize_path, find_project_dir, detect_worktrees

data/lib/claude_agent_sdk/types.rb

@@ -212,6 +212,64 @@ module ClaudeAgentSDK
   class UserMessage < Type
     attr_accessor :content, :uuid, :parent_tool_use_id, :tool_use_result
 
+    # Provenance of this message — where the turn came from.
+    #
+    # In streaming-input mode a single connection interleaves the turns you
+    # send 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 —
+    # see {ResultMessage#origin} for deciding whether a result answers *your*
+    # prompt.
+    #
+    # **Key form — read this before indexing into it.** A plain Hash, passed
+    # through from the CLI untouched: the SDK does not model it, whitelist its
+    # keys, or rewrite them, so kinds and fields newer CLI versions add stay
+    # visible. Keys therefore follow the transport's JSON parsing, which uses
+    # `symbolize_names: true` — they are **Symbols with the wire spelling
+    # preserved**, so camelCase keys stay camelCase and you index with
+    # `origin[:kind]`, `origin[:fromSession]`, `origin[:senderTaskId]`,
+    # `origin[:verifiedPeerPid]`. This is unlike the snake_case attributes
+    # elsewhere in this SDK, and unlike the Python SDK's string keys: a
+    # `origin["kind"]` or `origin[:from_session]` lookup silently returns nil
+    # and makes every attributed turn look unattributed. Only `:kind` is
+    # guaranteed present; the rest depend on it.
+    #
+    # `nil` means the CLI did not attribute the message — that is the normal
+    # case for prompts you send through {ClaudeAgentSDK.query} / {Client#query},
+    # unless the host stamps `origin: { kind: 'human' }` on the message Hash
+    # itself (only the `human` kind is honored from an SDK host). Populated on
+    # injected turns (task notifications, channel/peer messages, ...) and on
+    # user messages the CLI replays; tool-result messages never carry it.
+    #
+    # Known `:kind` values — documentation, not validation; treat anything
+    # unrecognized as "not human":
+    #
+    # - `'human'` — a turn submitted by the SDK host
+    # - `'channel'` — arrived on an MCP channel; `:server` names the MCP server
+    # - `'peer'` — relayed from a peer session. `:from` (sender address,
+    #   sender-asserted — for reply routing or display, never as proof of
+    #   identity), `:name` (display name, already normalized by the CLI),
+    #   `:fromSession` (the sender's host-openable session id, a navigation
+    #   target only), `:senderTaskId` (task id of the in-process background
+    #   subagent that sent it; absent for cross-session peers), `:body`
+    #   (decoded message body with the peer envelope stripped, byte-exact with
+    #   what the model saw — render this instead of re-parsing the message
+    #   text), `:verifiedPeerPid` (kernel-verified pid of the process that
+    #   connected to this session's local messaging socket — the *connecting*
+    #   process, which for relayed traffic is the relay; absent when
+    #   unverifiable)
+    # - `'task-notification'` — a background task's delivery. `:subkind` is
+    #   `'scheduled-trigger'` (the fired prompt of a scheduled task) or
+    #   `'peer-send-message'` (a message sent from another of the user's
+    #   sessions); absent for ordinary background-task notifications
+    # - `'coordinator'`, `'unclassified'`, `'observer'` (`:from` /
+    #   `:senderTaskId` as for `peer`), `'auto-continuation'`,
+    #   `'observer-activity'`
+    #
+    # @return [Hash{Symbol => Object}, nil]
+    # @see ResultMessage#origin
+    attr_accessor :origin
+
     # Concatenated text of this message. Handles both String content
     # (plain-text user prompt) and Array-of-blocks content (typed content).
     # Returns "" when there is no text.
@@ -442,6 +500,32 @@ module ClaudeAgentSDK
     def deferred_tool_use=(value)
       @deferred_tool_use = value.is_a?(Hash) ? DeferredToolUse.from_hash(value) : value
     end
+
+    # Provenance of the user message that triggered this turn — `nil` when the
+    # CLI did not attribute it. Lets a streaming-input consumer distinguish the
+    # result of its own prompt from the result of a turn the session injected
+    # on its own:
+    #
+    #     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
+    #
+    # **Key form.** A plain Hash passed through from the CLI untouched, so its
+    # keys are **Symbols with the wire spelling preserved** — camelCase stays
+    # camelCase (`origin[:kind]`, `origin[:fromSession]`,
+    # `origin[:verifiedPeerPid]`), unlike the snake_case attributes elsewhere
+    # in this SDK and unlike the Python SDK's string keys. Indexing with
+    # `origin["kind"]` silently returns nil and makes every attributed turn
+    # look unattributed.
+    #
+    # See {UserMessage#origin} for the full list of known `:kind` values and
+    # their per-kind keys.
+    #
+    # @return [Hash{Symbol => Object}, nil]
+    # @see UserMessage#origin
+    attr_accessor :origin
   end
 
   # Stream event for partial message updates
@@ -507,6 +591,33 @@ module ClaudeAgentSDK
     end
   end
 
+  # Emitted when the session's conversation is replaced without ending the
+  # connection — e.g. after `/clear` or any other flow that discards the
+  # transcript mid-session (type: 'conversation_reset').
+  #
+  # In streaming-input mode a single connection carries many user turns, and a
+  # reset clears the conversation history *and* zeroes the running totals
+  # reported on subsequent {ResultMessage} objects (e.g. `total_cost_usd`). If
+  # you accumulate those totals across a long-lived session, snapshot them when
+  # this message arrives.
+  #
+  # @!attribute [rw] new_conversation_id
+  #   Opaque identifier for the fresh conversation, for UIs to key an empty
+  #   transcript on (and to discard any cached session title). This is *not*
+  #   the `session_id` of subsequent messages — read that from the next
+  #   message.
+  #   @return [String]
+  # @!attribute [rw] uuid
+  #   Unique ID of this message.
+  #   @return [String]
+  # @!attribute [rw] session_id
+  #   ID of the session that was reset (the outgoing session; messages after
+  #   the reset carry a new `session_id`).
+  #   @return [String]
+  class ConversationResetMessage < Type
+    attr_accessor :new_conversation_id, :uuid, :session_id
+  end
+
   # Thinking configuration types
   #
   # `display` controls how thinking content appears in responses. Valid values
@@ -1529,10 +1640,22 @@ module ClaudeAgentSDK
     end
   end
 
-  # System prompt preset configuration
+  # System prompt preset configuration.
+  #
+  # +snapshot+ controls whether the session keeps the system prompt it
+  # recorded on its first request. When true, every later request (including
+  # after resume) sends the recorded prompt, so a changed +append+ has no
+  # effect until the session is compacted or a new session starts. When
+  # false, the prompt is rebuilt on every request — useful while iterating on
+  # +append+ text across calls that resume the same session. When nil
+  # (omitted), the CLI treats it as true, except in bare mode (+--bare+),
+  # where it acts as false. Sent on the control-protocol +initialize+ request
+  # (never as a CLI flag); requires Claude Code CLI 2.1.257 or later, and
+  # before 2.1.265 a session with an +append+ prompt recorded it only when
+  # +snapshot+ was true. Older CLIs silently ignore it.
   class SystemPromptPreset < Type
     attr_reader :type
-    attr_accessor :preset, :append, :exclude_dynamic_sections
+    attr_accessor :preset, :append, :exclude_dynamic_sections, :snapshot
 
     def initialize(attributes = {})
       super
@@ -1543,6 +1666,27 @@ module ClaudeAgentSDK
       result = { type: @type, preset: @preset }
       result[:append] = @append if @append
       result[:exclude_dynamic_sections] = @exclude_dynamic_sections unless @exclude_dynamic_sections.nil?
+      result[:snapshot] = @snapshot unless @snapshot.nil?
+      result
+    end
+  end
+
+  # Custom system prompt configuration — the object form of passing a String
+  # as +system_prompt+. Reaches the CLI the same way a String does
+  # (+--system-prompt <prompt>+); the object form exists so +snapshot+ can be
+  # set alongside it (see SystemPromptPreset#snapshot for its semantics).
+  class SystemPromptCustom < Type
+    attr_reader :type
+    attr_accessor :prompt, :snapshot
+
+    def initialize(attributes = {})
+      super
+      @type = 'custom'
+    end
+
+    def to_h
+      result = { type: @type, prompt: @prompt }
+      result[:snapshot] = @snapshot unless @snapshot.nil?
       result
     end
   end
@@ -1580,6 +1724,42 @@ module ClaudeAgentSDK
                 :include_hook_events, :strict_mcp_config,
                 :callback_scheduling, :callback_wrapper
 
+    # With {#resume_session_at}: the UUID of the user prompt whose turn this
+    # truncating resume intends to discard.
+    #
+    # When set, the CLI validates at load time that every transcript entry
+    # after the `resume_session_at` point is attributable to that turn, and
+    # refuses the resume otherwise — e.g. when the discarded range contains a
+    # queued user message or task notification the session absorbed mid-turn
+    # that the caller had not yet observed. Leave unset to keep the
+    # unvalidated truncation behavior.
+    #
+    # **Choosing the fork point.** 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
+    # (e.g. the next `SessionMessage` of `type == "user"` from
+    # {ClaudeAgentSDK.get_session_messages}, or the `uuid` you supplied on a
+    # streamed user message). Note that 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.
+    #
+    # **On refusal.** The CLI reports an `error_during_execution` result whose
+    # message starts with `Resume rejected by --resume-drops-turn:` — match on
+    # that text. Treat it as deterministic: clear the pending fork target and
+    # resume plainly rather than retrying the same request.
+    #
+    # Forwarded whenever it is not `nil`. An empty string reaches the CLI and
+    # is rejected there as a malformed declaration rather than being dropped by
+    # the SDK, which would silently disarm the guard you believe is armed. The
+    # SDK does not validate the option combination (`resume` /
+    # `resume_session_at`); like the TypeScript and Python SDKs that is the
+    # CLI's call.
+    #
+    # @return [String, nil]
+    # @see #resume_session_at
+    attr_accessor :resume_drops_turn
+
     def initialize(attributes = {})
       self.fork_session = false
       self.continue_conversation = false
@@ -1587,6 +1767,7 @@ module ClaudeAgentSDK
       self.enable_file_checkpointing = false
       self.include_hook_events = false
       self.strict_mcp_config = false
+      self.forward_subagent_text = false
 
       super(merge_with_defaults(attributes || {}))
 
@@ -1675,6 +1856,38 @@ module ClaudeAgentSDK
       @strict_mcp_config = coerce_boolean(value)
     end
 
+    # Forward subagent text and thinking blocks as messages in the stream.
+    # Defaults to `false`.
+    #
+    # By default only `tool_use` / `tool_result` blocks from subagents
+    # (spawned via the Agent tool) are emitted, as {AssistantMessage} /
+    # {UserMessage} objects whose `parent_tool_use_id` is the spawning Agent
+    # `tool_use` id — enough for a progress heartbeat. When true, the
+    # subagent's text and thinking blocks are forwarded the same way, so
+    # consumers can render the full nested transcript. Matches the TypeScript
+    # SDK's `forwardSubagentText`.
+    #
+    # Sent as the `forwardSubagentText` initialize capability rather than a CLI
+    # flag, and only when enabled, so an older CLI never sees an unknown key on
+    # the common path. Both {ClaudeAgentSDK.query} and {Client} run the control
+    # protocol, so the option applies to either entry point.
+    #
+    # Assigning coerces to a Boolean; {#forward_subagent_text?} is the
+    # predicate form.
+    #
+    # @return [Boolean]
+    attr_reader :forward_subagent_text
+
+    # @return [Boolean] {#forward_subagent_text}, as a strict Boolean.
+    def forward_subagent_text?
+      !!forward_subagent_text
+    end
+
+    # @see #forward_subagent_text
+    def forward_subagent_text=(value)
+      @forward_subagent_text = coerce_boolean(value)
+    end
+
     CALLBACK_SCHEDULING_MODES = %i[thread inline].freeze
 
     # Where user callbacks (hooks, can_use_tool, SDK MCP handlers, message

data/lib/claude_agent_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '0.30.0'
+  VERSION = '0.32.0'
 end

data/lib/claude_agent_sdk.rb

@@ -64,6 +64,34 @@ module ClaudeAgentSDK
     servers
   end
 
+  # Internal: validate can_use_tool and route permission prompts over stdio.
+  #
+  # Shared by query() and Client#connect so both entry points enforce the
+  # same rules. Returns options unchanged when no callback is set; otherwise
+  # checks it is not combined with permission_prompt_tool_name, emits the
+  # shadowing advisory, and returns a copy with permission_prompt_tool_name
+  # set to 'stdio' so the CLI sends permission requests over the control
+  # protocol.
+  #
+  # A String prompt is fine here: the SDK is always streaming internally (a
+  # String is written to stdin as a user message like any other), so as long
+  # as stdin stays open for the turn — which Query#bidirectional_needs? now
+  # guarantees for can_use_tool — the permission round-trip works. The old
+  # "requires streaming mode" ArgumentError was a needless restriction
+  # (Python #1204).
+  def self.configure_can_use_tool(options)
+    return options unless options.can_use_tool
+
+    # can_use_tool and permission_prompt_tool_name are mutually exclusive
+    raise ArgumentError, 'can_use_tool callback cannot be used with permission_prompt_tool_name' if options.permission_prompt_tool_name
+
+    # Advisory: warn if other options shadow the callback. After the
+    # ArgumentError above so invalid configs raise, not warn.
+    OptionWarnings.warn_if_can_use_tool_shadowed(options)
+
+    options.dup_with(permission_prompt_tool_name: 'stdio')
+  end
+
   # Internal: pull exclude_dynamic_sections out of a preset system prompt for
   # the initialize request (older CLIs ignore unknown initialize fields).
   # Shared by Client#connect and the one-shot query() path.
@@ -81,6 +109,26 @@ module ClaudeAgentSDK
     nil
   end
 
+  # Internal: pull snapshot out of a preset or custom system prompt for the
+  # initialize request (older CLIs ignore unknown initialize fields). A
+  # String or file prompt has no snapshot, and only a genuine true/false is
+  # forwarded — `snapshot: false` is the primary use case, so the Hash lookup
+  # must not collapse it to nil. Shared by Client#connect and query().
+  def self.extract_system_prompt_snapshot(system_prompt)
+    case system_prompt
+    when SystemPromptPreset, SystemPromptCustom
+      snapshot = system_prompt.snapshot
+      return snapshot if [true, false].include?(snapshot)
+    when Hash
+      type = system_prompt[:type] || system_prompt['type']
+      if %w[preset custom].include?(type)
+        snapshot = system_prompt.fetch(:snapshot) { system_prompt['snapshot'] }
+        return snapshot if [true, false].include?(snapshot)
+      end
+    end
+    nil
+  end
+
   # Safely call a method on each observer, suppressing any errors.
   # Each observer is invoked through FiberBoundary so that user code runs
   # on a plain thread (no Fiber scheduler) even when called from inside
@@ -448,21 +496,7 @@ module ClaudeAgentSDK
 
     options ||= ClaudeAgentOptions.new
 
-    configured_options = options
-    if options.can_use_tool
-      if prompt.is_a?(String)
-        raise ArgumentError,
-              'can_use_tool callback requires streaming mode. Please provide prompt as an Enumerator instead of a String.'
-      end
-
-      raise ArgumentError, 'can_use_tool callback cannot be used with permission_prompt_tool_name' if options.permission_prompt_tool_name
-
-      configured_options = options.dup_with(permission_prompt_tool_name: 'stdio')
-    end
-
-    # Advisory: warn if other options shadow the can_use_tool callback.
-    # After the ArgumentError validations so invalid configs raise, not warn.
-    OptionWarnings.warn_if_can_use_tool_shadowed(options)
+    configured_options = ClaudeAgentSDK.configure_can_use_tool(options)
 
     # Fail fast on invalid session_store combinations before spawning the CLI.
     SessionStores.validate_session_store_options(configured_options)
@@ -535,7 +569,9 @@ module ClaudeAgentSDK
           agents: configured_options.agents,
           sdk_mcp_servers: sdk_mcp_servers,
           exclude_dynamic_sections: ClaudeAgentSDK.extract_exclude_dynamic_sections(configured_options.system_prompt),
+          system_prompt_snapshot: ClaudeAgentSDK.extract_system_prompt_snapshot(configured_options.system_prompt),
           skills: configured_options.skills,
+          forward_subagent_text: configured_options.forward_subagent_text?,
           callback_scheduling: callback_scheduling,
           callback_wrapper: callback_wrapper
         )
@@ -742,18 +778,7 @@ module ClaudeAgentSDK
       raise ArgumentError, "prompt must be a String, an Enumerator, or nil (got #{prompt.class})" unless prompt.nil? || prompt.is_a?(String) || prompt.respond_to?(:each)
 
       # Validate and configure permission settings
-      configured_options = @options
-      if @options.can_use_tool
-        # can_use_tool and permission_prompt_tool_name are mutually exclusive
-        raise ArgumentError, 'can_use_tool callback cannot be used with permission_prompt_tool_name' if @options.permission_prompt_tool_name
-
-        # Set permission_prompt_tool_name to stdio for control protocol
-        configured_options = @options.dup_with(permission_prompt_tool_name: 'stdio')
-      end
-
-      # Advisory: warn if other options shadow the can_use_tool callback.
-      # After the ArgumentError validations so invalid configs raise, not warn.
-      OptionWarnings.warn_if_can_use_tool_shadowed(@options)
+      configured_options = ClaudeAgentSDK.configure_can_use_tool(@options)
 
       # Fail fast on invalid session_store combinations before spawning the CLI.
       # Configuration validation is a usage error, like the ArgumentErrors
@@ -1060,9 +1085,10 @@ module ClaudeAgentSDK
       # Convert hooks to internal format
       hooks = convert_hooks_to_internal_format(configured_options.hooks) if configured_options.hooks
 
-      # Extract exclude_dynamic_sections from preset system prompt for the
-      # initialize request (older CLIs ignore unknown initialize fields)
+      # Extract exclude_dynamic_sections and snapshot from the system prompt
+      # for the initialize request (older CLIs ignore unknown initialize fields)
       exclude_dynamic_sections = ClaudeAgentSDK.extract_exclude_dynamic_sections(configured_options.system_prompt)
+      system_prompt_snapshot = ClaudeAgentSDK.extract_system_prompt_snapshot(configured_options.system_prompt)
 
       # Create Query handler
       @query_handler = Query.new(
@@ -1073,7 +1099,9 @@ module ClaudeAgentSDK
         sdk_mcp_servers: sdk_mcp_servers,
         agents: configured_options.agents,
         exclude_dynamic_sections: exclude_dynamic_sections,
+        system_prompt_snapshot: system_prompt_snapshot,
         skills: configured_options.skills,
+        forward_subagent_text: configured_options.forward_subagent_text?,
         callback_scheduling: @callback_scheduling,
         callback_wrapper: @callback_wrapper
       )

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.32.0
 platform: ruby
 authors:
 - Community Contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
+date: 2026-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -110,6 +110,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- docs/cli-installer.md
 - docs/client.md
 - docs/configuration.md
 - docs/errors.md