claude-agent-sdk 0.17.0 → 0.18.0

data/lib/claude_agent_sdk.rb

@@ -39,11 +39,79 @@ module ClaudeAgentSDK
   def self.notify_observers(observers, method, *args)
     observers.each do |obs|
       FiberBoundary.invoke { obs.send(method, *args) }
-    rescue StandardError
+    rescue StandardError, ScriptError
+      # ScriptError too: NotImplementedError < ScriptError (not
+      # StandardError), and a stubbed observer must never mask the original
+      # error being notified or abort connect/teardown cleanup.
       nil
     end
   end
 
+  # Extract the user-visible prompt text from a streamed input item, or nil
+  # when there is none (non-user messages, tool_result-only content, …).
+  # Only Hash and JSON-string items are inspected; arbitrary objects written
+  # via to_s are never notified.
+  def self.extract_user_prompt_text(message)
+    data = case message
+           when Hash then message
+           when String
+             # Cheap prefilter: skip the full parse for items that cannot be
+             # user messages (e.g. multi-MB tool_result frames) — parsing
+             # would block the reactor fiber for the duration. False
+             # positives just cost one parse; correctness is unchanged.
+             return nil unless message.include?('user')
+
+             begin
+               JSON.parse(message)
+             rescue JSON::ParserError
+               nil
+             end
+           end
+    return nil unless data.is_a?(Hash)
+    return nil unless (data[:type] || data['type']) == 'user'
+
+    inner = data[:message] || data['message']
+    return nil unless inner.is_a?(Hash)
+
+    prompt_text_from_content(inner[:content] || inner['content'])
+  end
+
+  # Text from a user-message content payload: the string itself, or the
+  # newline-joined non-empty top-level text blocks. Returns nil (never '')
+  # when there is no extractable text — on_user_prompt('') would latch
+  # OTelObserver's first-prompt buffer while never setting the attribute,
+  # permanently suppressing later real prompts.
+  def self.prompt_text_from_content(content)
+    case content
+    when String
+      content.empty? ? nil : content
+    when Array
+      texts = content.filter_map do |block|
+        next unless block.is_a?(Hash)
+        next unless (block[:type] || block['type']) == 'text'
+
+        text = block[:text] || block['text']
+        text unless text.to_s.empty?
+      end
+      texts.empty? ? nil : texts.join("\n")
+    end
+  end
+
+  # Wrap a streaming-input enumerable so observers get on_user_prompt for
+  # each user message before it is written to stdin. Identity when no
+  # observers are configured.
+  def self.observing_prompt_stream(prompt, observers)
+    return prompt if observers.empty?
+
+    Enumerator.new do |yielder|
+      prompt.each do |message|
+        text = extract_user_prompt_text(message)
+        notify_observers(observers, :on_user_prompt, text) if text
+        yielder << message
+      end
+    end
+  end
+
   # Look up a value in a hash that may use symbol or string keys in camelCase or snake_case.
   # Returns the first non-nil value found, preserving false as a meaningful value.
   def self.flexible_fetch(hash, camel_key, snake_key)
@@ -54,35 +122,6 @@ module ClaudeAgentSDK
     val
   end
 
-  # Query Claude Code for one-shot or unidirectional streaming interactions
-  #
-  # This function is ideal for simple, stateless queries where you don't need
-  # bidirectional communication or conversation management.
-  #
-  # @param prompt [String, Enumerator] The prompt to send to Claude, or an Enumerator for streaming input
-  # @param options [ClaudeAgentOptions] Optional configuration
-  # @yield [Message] Each message from the conversation
-  # @return [Enumerator] if no block given
-  #
-  # @example Simple query
-  #   ClaudeAgentSDK.query(prompt: "What is 2 + 2?") do |message|
-  #     puts message
-  #   end
-  #
-  # @example With options
-  #   options = ClaudeAgentSDK::ClaudeAgentOptions.new(
-  #     allowed_tools: ['Read', 'Bash'],
-  #     permission_mode: 'acceptEdits'
-  #   )
-  #   ClaudeAgentSDK.query(prompt: "Create a hello.rb file", options: options) do |msg|
-  #     puts msg.text if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
-  #   end
-  #
-  # @example Streaming input
-  #   messages = Streaming.from_array(['Hello', 'What is 2+2?', 'Thanks!'])
-  #   ClaudeAgentSDK.query(prompt: messages) do |message|
-  #     puts message
-  #   end
   # List sessions for a directory (or all sessions)
   # @param directory [String, nil] Working directory to list sessions for
   # @param limit [Integer, nil] Maximum number of sessions to return
@@ -111,6 +150,26 @@ module ClaudeAgentSDK
     Sessions.get_session_messages(session_id: session_id, directory: directory, limit: limit, offset: offset)
   end
 
+  # List subagent IDs recorded for a session on local disk
+  # @param session_id [String] The session UUID
+  # @param directory [String, nil] Working directory to search in
+  # @return [Array<String>] Subagent IDs
+  def self.list_subagents(session_id:, directory: nil)
+    Sessions.list_subagents(session_id: session_id, directory: directory)
+  end
+
+  # Read a subagent's conversation messages from local disk
+  # @param session_id [String] The session UUID
+  # @param agent_id [String] The subagent ID (without the agent- prefix)
+  # @param directory [String, nil] Working directory to search in
+  # @param limit [Integer, nil] Maximum number of messages
+  # @param offset [Integer] Number of messages to skip
+  # @return [Array<SessionMessage>] Ordered messages from the subagent
+  def self.get_subagent_messages(session_id:, agent_id:, directory: nil, limit: nil, offset: 0)
+    Sessions.get_subagent_messages(session_id: session_id, agent_id: agent_id,
+                                   directory: directory, limit: limit, offset: offset)
+  end
+
   # Rename a session by appending a custom-title entry
   # @param session_id [String] UUID of the session to rename
   # @param title [String] New session title
@@ -246,8 +305,43 @@ module ClaudeAgentSDK
                                      include_subagents: include_subagents, batch_size: batch_size)
   end
 
-  def self.query(prompt:, options: nil, &block)
-    return enum_for(:query, prompt: prompt, options: options) unless block
+  # Query Claude Code for one-shot or unidirectional streaming interactions
+  #
+  # This function is ideal for simple, stateless queries where you don't need
+  # bidirectional communication or conversation management.
+  #
+  # @param prompt [String, Enumerator] The prompt to send to Claude, or an Enumerator for streaming input
+  # @param options [ClaudeAgentOptions] Optional configuration
+  # @yield [Message] Each message from the conversation
+  # @return [Enumerator] if no block given. Internal iteration only: consume
+  #   with #each or each-driven Enumerable methods (#first, #take, #map,
+  #   #to_a). External iteration (#next, #peek, #rewind) is NOT supported —
+  #   message delivery runs inside the SDK's Async reactor, which cannot run
+  #   on the Enumerator's fiber; #next raises or hangs depending on context.
+  # @note An attempted #next may still spawn the CLI subprocess before
+  #   failing and leaves the query unusable.
+  #
+  # @example Simple query
+  #   ClaudeAgentSDK.query(prompt: "What is 2 + 2?") do |message|
+  #     puts message
+  #   end
+  #
+  # @example With options
+  #   options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  #     allowed_tools: ['Read', 'Bash'],
+  #     permission_mode: 'acceptEdits'
+  #   )
+  #   ClaudeAgentSDK.query(prompt: "Create a hello.rb file", options: options) do |msg|
+  #     puts msg.text if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
+  #   end
+  #
+  # @example Streaming input
+  #   messages = Streaming.from_array(['Hello', 'What is 2+2?', 'Thanks!'])
+  #   ClaudeAgentSDK.query(prompt: messages) do |message|
+  #     puts message
+  #   end
+  def self.query(prompt:, options: nil, transport: nil, &block)
+    return enum_for(:query, prompt: prompt, options: options, transport: transport) unless block
 
     options ||= ClaudeAgentOptions.new
 
@@ -269,23 +363,31 @@ module ClaudeAgentSDK
     # Resolve callable observers into fresh instances (thread-safe for global defaults)
     resolved_observers = ClaudeAgentSDK.resolve_observers(configured_options.observers)
 
+    raise ArgumentError, 'transport must respond to #connect (see ClaudeAgentSDK::Transport)' if transport && !transport.respond_to?(:connect)
+
     Async do
       materialized = nil
-      transport = nil
       query_handler = nil
       begin
-        # Resume-from-store: when a session_store is set and resume/continue is
-        # requested, load the session into a temp CLAUDE_CONFIG_DIR and repoint
-        # options at it (env + --resume) BEFORE spawning. Returns options
-        # unchanged when no materialization applies. query() always uses the
-        # default subprocess transport, so no custom-transport gate is needed.
-        materialized = SessionResume.materialize_resume_session(configured_options)
-        configured_options = SessionResume.apply_materialized_options(configured_options, materialized) if materialized
-
-        # Always use streaming mode with control protocol (matches Python SDK).
-        # This sends agents via initialize request instead of CLI args,
-        # avoiding OS ARG_MAX limits.
-        transport = SubprocessCLITransport.new(configured_options)
+        if transport.nil?
+          # Resume-from-store: when a session_store is set and resume/continue
+          # is requested, load the session into a temp CLAUDE_CONFIG_DIR and
+          # repoint options at it (env + --resume) BEFORE spawning. Returns
+          # options unchanged when no materialization applies. Skipped
+          # entirely for an injected transport — the materialized
+          # env/--resume only apply to the CLI subprocess (Python parity:
+          # client.py skips materialization when a transport is supplied).
+          materialized = SessionResume.materialize_resume_session(configured_options)
+          configured_options = SessionResume.apply_materialized_options(configured_options, materialized) if materialized
+
+          # Always use streaming mode with control protocol (matches Python
+          # SDK). This sends agents via initialize request instead of CLI
+          # args, avoiding OS ARG_MAX limits.
+          transport = SubprocessCLITransport.new(configured_options)
+        end
+        # Deliberate deviation from Python: the ensure below also closes an
+        # injected transport whose #connect raised (Python leaves it
+        # unclosed); Transport#close must be idempotent.
         transport.connect
 
         # Extract SDK MCP servers
@@ -323,7 +425,8 @@ module ClaudeAgentSDK
           can_use_tool: configured_options.can_use_tool,
           hooks: hooks,
           agents: configured_options.agents,
-          sdk_mcp_servers: sdk_mcp_servers
+          sdk_mcp_servers: sdk_mcp_servers,
+          skills: configured_options.skills
         )
 
         # Mirror transcripts to the session_store, if configured. Installed
@@ -355,11 +458,18 @@ module ClaudeAgentSDK
             session_id: ''
           }
           transport.write(JSON.generate(message) + "\n")
-          query_handler.wait_for_result_and_end_input
+          # Background-spawn so messages stream to the user block while stdin
+          # close waits (without timeout) for the first result; a synchronous
+          # call would defer all delivery until the turn completes (mirrors
+          # Python's query.spawn_task(query.wait_for_result_and_end_input())).
+          query_handler.spawn_task { query_handler.wait_for_result_and_end_input }
         elsif prompt.is_a?(Enumerator) || prompt.respond_to?(:each)
-          Async do
-            query_handler.stream_input(prompt)
-          end
+          # Tracked on the Query so close() stops it; an untracked Async task
+          # here kept the root reactor alive forever when the read loop died
+          # while the user enumerator was still blocked (matches Python's
+          # query.spawn_task(query.stream_input(prompt))).
+          observed_prompt = ClaudeAgentSDK.observing_prompt_stream(prompt, resolved_observers)
+          query_handler.spawn_task { query_handler.stream_input(observed_prompt) }
         end
 
         # Read and yield messages from the query handler (filters out control messages).
@@ -367,11 +477,20 @@ module ClaudeAgentSDK
         # inside it don't see the async gem's Fiber scheduler.
         query_handler.receive_messages do |data|
           message = MessageParser.parse(data)
-          if message
-            ClaudeAgentSDK.notify_observers(resolved_observers, :on_message, message)
-            FiberBoundary.invoke { block.call(message) }
-          end
+          next unless message
+
+          ClaudeAgentSDK.notify_observers(resolved_observers, :on_message, message)
+          signal = FiberBoundary.invoke_iteration(block, message)
+          break signal.value if signal.is_a?(FiberBoundary::Break)
         end
+      rescue StandardError => e
+        # One notify point for every error surfacing from query() — transport
+        # connect, initialize, stream errors re-raised from the message queue,
+        # parse errors, and user-block errors. StandardError only: Async::Stop
+        # is cancellation, not an error. Bare raise preserves the backtrace;
+        # the ensure below still fires on_close after on_error.
+        ClaudeAgentSDK.notify_observers(resolved_observers, :on_error, e)
+        raise
       ensure
         ClaudeAgentSDK.notify_observers(resolved_observers, :on_close)
         # query_handler.close stops the background read task and closes the
@@ -446,12 +565,49 @@ module ClaudeAgentSDK
       @materialized = nil
     end
 
+    # Block-scoped Client lifecycle, mirroring Python's
+    # `async with ClaudeSDKClient() as client` and File.open ergonomics:
+    # connects, yields the client, and always disconnects (block exceptions
+    # propagate). Kernel#Sync runs inline inside an existing reactor and
+    # creates one otherwise, so this works standalone too. Returns the
+    # block's value.
+    #
+    # @param prompt [String, Enumerator, nil] Optional initial prompt (same as #connect)
+    # @note In standalone (non-Async) use, `break` inside the block raises
+    #   LocalJumpError (teardown still runs) — return a value instead.
+    # @example
+    #   ClaudeAgentSDK::Client.open(options: options) do |client|
+    #     client.query('Hello')
+    #     client.receive_response { |msg| puts msg }
+    #   end
+    def self.open(prompt = nil, options: nil, transport_class: SubprocessCLITransport, transport_args: {})
+      raise ArgumentError, 'Client.open requires a block' unless block_given?
+
+      Sync do
+        client = new(options: options, transport_class: transport_class, transport_args: transport_args)
+        # connect failures self-clean via connect's rescue -> disconnect ->
+        # raise, and disconnect is idempotent — no double-teardown.
+        client.connect(prompt)
+        begin
+          yield client
+        ensure
+          client.disconnect
+        end
+      end
+    end
+
     # Connect to Claude with optional initial prompt.
     #
     # Client always uses streaming mode for bidirectional communication. If you
     # pass a String, it will be sent as an initial user message after the
     # connection is established. If you pass an Enumerator, it should yield
-    # JSONL messages (e.g., from ClaudeAgentSDK::Streaming.user_message).
+    # JSONL messages (e.g., from ClaudeAgentSDK::Streaming.user_message);
+    # the stream is consumed in the BACKGROUND (connect returns immediately)
+    # and stdin closes when it is exhausted, so the stream is the session's
+    # input — a later #query after exhaustion will fail. Enumerator code runs
+    # on the reactor: use a producer Thread + Thread::Queue for blocking
+    # reads (Queue#pop is scheduler-aware). Stream errors are reported via
+    # Observer#on_error and logged, not raised out of connect.
     #
     # @param prompt [String, Enumerator, nil] Initial prompt or message stream
     def connect(prompt = nil)
@@ -470,21 +626,35 @@ module ClaudeAgentSDK
       end
 
       # Fail fast on invalid session_store combinations before spawning the CLI.
+      # Configuration validation is a usage error, like the ArgumentErrors
+      # above — deliberately outside the on_error notify scope.
       SessionStores.validate_session_store_options(configured_options)
 
-      # Resume-from-store: materialize the session from the store into a temp
-      # CLAUDE_CONFIG_DIR BEFORE spawn, then repoint options at it. Skipped for
-      # custom transports (the materialized env/--resume only apply to the CLI
-      # subprocess). On any later connect failure, disconnect cleans up the dir.
-      configured_options = materialize_resume(configured_options)
+      # Resolve observers before the first failable runtime step so
+      # connect-phase failures (including resume materialization) can be
+      # notified via on_error.
+      @resolved_observers = ClaudeAgentSDK.resolve_observers(@options.observers)
 
-      # If anything after materialization fails, tear down (closes the
+      # If anything from materialization onward fails, tear down (closes the
       # subprocess and removes the materialized temp config dir) before
       # surfacing the error, so a partial connect never leaks a temp dir
       # holding a credential copy.
       begin
+        # Resume-from-store: materialize the session from the store into a
+        # temp CLAUDE_CONFIG_DIR BEFORE spawn, then repoint options at it.
+        # Inside the instrumented begin so store IO failures fire on_error
+        # (matching the one-shot query() path) and disconnect cleans up.
+        configured_options = materialize_resume(configured_options)
+
         connect_inner(configured_options, prompt)
-      rescue Exception # rubocop:disable Lint/RescueException
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        # Pre-handshake failures (@connected still false) are notified here;
+        # post-handshake String-prompt send failures were already notified by
+        # the instrumented #query — the gate keeps on_error exactly-once.
+        # (The enumerator branch streams in the background and cannot raise
+        # out of connect.) No on_close follows for pre-handshake failures
+        # (disconnect gates it on @connected): the session never opened.
+        notify_error(e) if e.is_a?(StandardError) && !@connected
         # Tear down the partial connect, but never let a cleanup failure (e.g. a
         # custom transport whose #close raises) mask the original connect error.
         # Rescue Exception (not StandardError) so reactor cancellation
@@ -493,42 +663,78 @@ module ClaudeAgentSDK
         # CLAUDE_CONFIG_DIR that holds the redacted .credentials.json copy.
         begin
           disconnect
-        rescue StandardError => e
-          warn "Claude SDK: cleanup after failed connect raised: #{e.message}"
+        rescue StandardError => cleanup_error
+          warn "Claude SDK: cleanup after failed connect raised: #{cleanup_error.message}"
         end
         raise
       end
     end
 
     # Send a query to Claude
-    # @param prompt [String] The prompt to send
+    # @param prompt [String, Enumerable] The prompt to send — a String, or an
+    #   Enumerable of message Hashes / JSONL Strings streamed inline (blocks
+    #   until exhausted, like Python's async-for). Hashes lacking a
+    #   session_id are stamped with the session_id: argument; JSONL Strings
+    #   pass through VERBATIM — generate them with the matching session_id
+    #   (Streaming.user_message defaults to 'default'). Bare Hashes are
+    #   rejected (they would iterate as key-value pairs).
     # @param session_id [String] Session identifier
     def query(prompt, session_id: 'default')
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+      # A bare Hash responds to #each and would silently iterate [key, value]
+      # pairs (Python's async-for over a dict raises TypeError).
+      raise ArgumentError, 'prompt must be a String or an Enumerable of message Hashes/JSONL Strings (got Hash)' if prompt.is_a?(Hash)
 
-      ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, prompt)
-      message = {
-        type: 'user',
-        message: { role: 'user', content: prompt },
-        parent_tool_use_id: nil,
-        session_id: session_id
-      }
-      writeln(JSON.generate(message))
+      begin
+        if prompt.is_a?(String)
+          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, prompt)
+          message = {
+            type: 'user',
+            message: { role: 'user', content: prompt },
+            parent_tool_use_id: nil,
+            session_id: session_id
+          }
+          writeln(JSON.generate(message))
+        elsif prompt.respond_to?(:each)
+          # Inline iteration on the caller, Python client.py parity — NOT
+          # Query#stream_input, whose ensure always ends input after
+          # exhaustion (correct for connect-time sole-input streams, fatal
+          # for a mid-session query). Blocks until the iterable is exhausted,
+          # identical to Python's async-for.
+          stream_query_messages(prompt, session_id)
+        else
+          raise ArgumentError, "prompt must be a String or respond to #each (got #{prompt.class})"
+        end
+      rescue StandardError => e
+        notify_error(e)
+        raise
+      end
     end
 
     # Receive all messages from Claude
     # @yield [Message] Each message received
+    # @return [Enumerator] when no block is given (internal iteration only)
+    # @note #next/#peek either raise FiberError or hang depending on message
+    #   timing, and can kill the session's read loop, leaving the client
+    #   unusable; iterate with a block or each-driven Enumerable methods
+    #   (#first, #take) inside the Async block instead.
     def receive_messages(&block)
       return enum_for(:receive_messages) unless block
 
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
 
-      @query_handler.receive_messages do |data|
-        message = MessageParser.parse(data)
-        if message
+      begin
+        @query_handler.receive_messages do |data|
+          message = MessageParser.parse(data)
+          next unless message
+
           ClaudeAgentSDK.notify_observers(@resolved_observers, :on_message, message)
-          FiberBoundary.invoke { block.call(message) }
+          signal = FiberBoundary.invoke_iteration(block, message)
+          break signal.value if signal.is_a?(FiberBoundary::Break)
         end
+      rescue StandardError => e
+        notify_error(e)
+        raise
       end
     end
 
@@ -539,16 +745,23 @@ module ClaudeAgentSDK
 
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
 
-      # Keep `break` on the same fiber as the underlying dequeue. Going through
-      # Client#receive_messages would put the FiberBoundary hop above the break
-      # and hang in Client mode — the CLI keeps stdin open and never emits `:end`.
-      @query_handler.receive_messages do |data|
-        message = MessageParser.parse(data)
-        next unless message
+      # Keep loop control on the same fiber as the underlying dequeue: both
+      # the SDK's ResultMessage break and the user's translated break happen
+      # here, never inside the FiberBoundary hop (break in a proc on a
+      # foreign thread raises LocalJumpError).
+      begin
+        @query_handler.receive_messages do |data|
+          message = MessageParser.parse(data)
+          next unless message
 
-        ClaudeAgentSDK.notify_observers(@resolved_observers, :on_message, message)
-        FiberBoundary.invoke { block.call(message) }
-        break if message.is_a?(ResultMessage)
+          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_message, message)
+          signal = FiberBoundary.invoke_iteration(block, message)
+          break signal.value if signal.is_a?(FiberBoundary::Break)
+          break if message.is_a?(ResultMessage)
+        end
+      rescue StandardError => e
+        notify_error(e)
+        raise
       end
     end
 
@@ -684,7 +897,8 @@ module ClaudeAgentSDK
 
     # The connect body, wrapped by #connect so a failure triggers cleanup.
     def connect_inner(configured_options, prompt)
-      # Client always uses streaming mode; keep stdin open for bidirectional communication.
+      # Client always uses streaming mode; keep stdin open for bidirectional
+      # communication. Observers were already resolved by #connect.
       @transport = @transport_class.new(configured_options, **@transport_args)
       @transport.connect
 
@@ -711,7 +925,8 @@ module ClaudeAgentSDK
         hooks: hooks,
         sdk_mcp_servers: sdk_mcp_servers,
         agents: configured_options.agents,
-        exclude_dynamic_sections: exclude_dynamic_sections
+        exclude_dynamic_sections: exclude_dynamic_sections,
+        skills: configured_options.skills
       )
 
       # Mirror transcripts to the session_store, if configured.
@@ -721,9 +936,6 @@ module ClaudeAgentSDK
       @query_handler.start
       @query_handler.initialize_protocol
 
-      # Resolve callable observers into fresh instances (thread-safe for global defaults)
-      @resolved_observers = ClaudeAgentSDK.resolve_observers(@options.observers)
-
       @connected = true
 
       # Optionally send initial prompt/messages after connection is ready.
@@ -733,12 +945,66 @@ module ClaudeAgentSDK
       when String
         query(prompt)
       else
-        prompt.each do |message_json|
-          writeln(message_json.to_s)
+        # Stream in the background, exactly like query()'s Enumerator path
+        # (Python client.py: query.spawn_task(query.stream_input(prompt))).
+        # The old inline `prompt.each` blocked connect until the stream was
+        # exhausted — an interactive stream that waits for a response before
+        # yielding deadlocked connect — and serialized Hash messages with
+        # to_s (Ruby inspect, not JSON). stream_input JSON-generates Hashes
+        # and is tracked on the Query so close() stops it. Stream errors are
+        # notified to observers once, then swallowed-with-warn by
+        # stream_input (Python parity) — they no longer abort connect.
+        observed = ClaudeAgentSDK.observing_prompt_stream(prompt, @resolved_observers)
+        notifying = error_notifying_stream(observed)
+        @query_handler.spawn_task { @query_handler.stream_input(notifying) }
+      end
+    end
+
+    # Wrap a stream so a raising user enumerator fires on_error exactly once
+    # before stream_input's swallow-with-warn handling takes over.
+    def error_notifying_stream(stream)
+      Enumerator.new do |yielder|
+        stream.each { |message| yielder << message }
+      rescue StandardError => e
+        notify_error(e)
+        raise
+      end
+    end
+
+    # Stream an iterable of message Hashes / JSONL Strings as session input,
+    # stamping session_id on Hashes that lack one (key-presence check, both
+    # key styles — an explicit nil is preserved, mirroring Python's
+    # `"session_id" not in msg`). Strings pass through verbatim (Ruby
+    # superset: Streaming.user_message emits pre-serialized JSONL; no
+    # parse-stamp-regenerate, which would block the reactor on huge frames).
+    def stream_query_messages(prompt, session_id)
+      prompt.each do |msg|
+        case msg
+        when Hash
+          msg = msg.merge(session_id: session_id) unless msg.key?(:session_id) || msg.key?('session_id')
+          if (text = ClaudeAgentSDK.extract_user_prompt_text(msg))
+            ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text)
+          end
+          writeln(JSON.generate(msg))
+        when String
+          if (text = ClaudeAgentSDK.extract_user_prompt_text(msg))
+            ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text)
+          end
+          writeln(msg)
+        else
+          # No to_s fallback — silently serializing arbitrary objects is the
+          # exact inspect-garbage bug class this method exists to prevent.
+          raise ArgumentError, "stream items must be Hashes or JSONL Strings (got #{msg.class})"
         end
       end
     end
 
+    # Notify observers of an error surfacing to the consumer. `|| []` keeps a
+    # mis-scoped call before connect harmless instead of NoMethodError on nil.
+    def notify_error(error)
+      ClaudeAgentSDK.notify_observers(@resolved_observers || [], :on_error, error)
+    end
+
     # Build and install the transcript-mirror batcher on the query handler when
     # a session_store is configured, via the shared SessionResume helper (also
     # used by the one-shot query() path).

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Community Contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-10 00:00:00.000000000 Z
+date: 2026-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -28,16 +28,22 @@ dependencies:
   name: mcp
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '1'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement