claude-agent-sdk 1.0.0 → 1.2.0

data/lib/claude_agent_sdk/query.rb

@@ -49,14 +49,103 @@ module ClaudeAgentSDK
     # status, or it will hang the query (see #track_task_lifecycle).
     DEFERRING_TASK_TYPES = %w[local_agent local_workflow].freeze
 
-    # Waiter for control responses awaited OFF the reactor — i.e. a control
-    # method called from inside a hook/can_use_tool/SDK-MCP callback, which
-    # runs on a FiberBoundary worker thread (Python supports this reentrancy
-    # natively: callbacks are event-loop tasks and anyio.Event is
-    # level-triggered). Duck-types Async::Condition#signal for the read
-    # loop's signal sites; the unconditional token push makes it
-    # level-triggered, closing the check-then-wait gap that an
-    # edge-triggered Condition would lose across threads.
+    # The CLI's own wait for background work once stdin is closed; the SDK
+    # bounds its wait for the CLI's "idle" by the same value
+    # (#arm_run_end_ceiling, Python #1279).
+    RUN_END_CEILING_ENV_VAR = 'CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS'
+    DEFAULT_RUN_END_CEILING_MS = 600_000
+    # The longest ceiling honored (~24.8 days), as in the TypeScript and
+    # Python SDKs, whose timers cannot run longer.
+    MAX_RUN_END_CEILING_MS = (2**31) - 1
+    # Frame types that mark a main-thread turn under way (when they carry no
+    # parent_tool_use_id), and the states that do not re-arm the ceiling.
+    TURN_FRAME_TYPES = %w[assistant stream_event].freeze
+    NON_RUNNING_SESSION_STATES = %w[idle requires_action].freeze
+
+    # Read CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS from where the CLI gets it:
+    # +options_env+ (ClaudeAgentOptions#env) overrides the inherited
+    # environment, as it does for the subprocess, and a key present with a nil
+    # value is unset in the child, so the CLI falls back to its default. 0
+    # means no limit. Only plain non-negative integers are read; anything else
+    # falls back to the CLI's default of 10 minutes, including spellings the
+    # CLI itself also reads, such as 1e6 (as in the Python SDK).
+    def self.run_end_ceiling_ms(options_env)
+      env = (options_env || {}).transform_keys(&:to_s)
+      raw = env.key?(RUN_END_CEILING_ENV_VAR) ? env[RUN_END_CEILING_ENV_VAR] : ENV.fetch(RUN_END_CEILING_ENV_VAR, nil)
+      digits = raw.to_s.strip
+      digits.match?(/\A\d+\z/) ? Integer(digits, 10) : DEFAULT_RUN_END_CEILING_MS
+    end
+
+    # One run's end, set at most once (the Python SDK's per-run anyio.Event).
+    # A waiter holds the object it started waiting on, so a run that ends and
+    # is then reopened (#reopen_run swaps in a fresh RunEnd) still releases the
+    # waiters the ended run woke, while later waits wait for the new run.
+    # Reactor-only, like every caller.
+    class RunEnd
+      def initialize
+        @ended = false
+        @condition = Async::Condition.new
+      end
+
+      def ended?
+        @ended
+      end
+
+      def end!
+        return if @ended
+
+        @ended = true
+        @condition.signal
+      end
+
+      def wait
+        @condition.wait until @ended
+      end
+    end
+
+    # Apply ClaudeAgentOptions#verbatim_prompts to one outgoing user message
+    # (Python #1269's stamp_user_message). Off: returns +message+ unchanged.
+    # On: returns a new Hash with `client_composed: true`, dropping any
+    # caller-supplied value under either key spelling first (JSON.generate
+    # would otherwise emit the key twice). A pre-serialized JSONL String — a
+    # Ruby-only input shape — is parsed, marked and handed back as a Hash; one
+    # that is not a single JSON object raises ArgumentError, because sending it
+    # unmarked would silently defeat the option.
+    def self.stamp_user_message(message, verbatim_prompts)
+      return message unless verbatim_prompts
+
+      hash = message.is_a?(Hash) ? message : parse_streamed_message(message.to_s)
+      hash.reject { |key, _| key.to_s == 'client_composed' }.merge(client_composed: true)
+    end
+
+    # The serialized line for one outgoing user message, stamped per
+    # verbatim_prompts. Hashes are JSON-generated; other items pass through
+    # as their String form unless they must be stamped.
+    def self.serialize_user_message(message, verbatim_prompts)
+      stamped = stamp_user_message(message, verbatim_prompts)
+      stamped.is_a?(Hash) ? JSON.generate(stamped) : stamped.to_s
+    end
+
+    def self.parse_streamed_message(string)
+      parsed = JSON.parse(string)
+      return parsed if parsed.is_a?(Hash)
+
+      raise ArgumentError, "verbatim_prompts: a streamed message String must be one JSON object (got #{parsed.class})"
+    rescue JSON::ParserError => e
+      raise ArgumentError, "verbatim_prompts: a streamed message String must be one JSON object (#{e.message})"
+    end
+    private_class_method :parse_streamed_message
+
+    # Waiter for control responses awaited OFF the reactor that owns the
+    # Query — a control method called from inside a hook/can_use_tool/SDK-MCP
+    # callback, which runs on a FiberBoundary worker thread (Python supports
+    # this reentrancy natively: callbacks are event-loop tasks and
+    # anyio.Event is level-triggered), from any other plain thread, or from a
+    # fiber on another thread's reactor (see #send_control_request for the
+    # choice). Duck-types Async::Condition#signal for the read loop's signal
+    # sites; the unconditional token push makes it level-triggered, closing
+    # the check-then-wait gap that an edge-triggered Condition would lose
+    # across threads.
     class ThreadWaiter
       def initialize
         @queue = ::Queue.new
@@ -74,7 +163,8 @@ module ClaudeAgentSDK
     def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil, agents: nil, # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- initializes every control-protocol concern in one place
                    exclude_dynamic_sections: nil, system_prompt_snapshot: nil, skills: nil,
                    forward_subagent_text: false, agent_progress_summaries: nil,
-                   callback_scheduling: :thread, callback_wrapper: nil)
+                   callback_scheduling: :thread, callback_wrapper: nil, verbatim_prompts: false,
+                   run_end_ceiling_ms: DEFAULT_RUN_END_CEILING_MS)
       @transport = transport
       @is_streaming_mode = is_streaming_mode
       @can_use_tool = can_use_tool
@@ -88,6 +178,8 @@ module ClaudeAgentSDK
       @skills = skills
       @forward_subagent_text = forward_subagent_text
       @agent_progress_summaries = agent_progress_summaries
+      @verbatim_prompts = verbatim_prompts
+      @run_end_ceiling_ms = run_end_ceiling_ms
 
       # Control protocol state
       @pending_control_responses = {}
@@ -103,10 +195,32 @@ module ClaudeAgentSDK
 
       # Message stream
       @message_queue = Async::Queue.new
-      # Set when a run-ending result arrives (a result frame with no tasks in
-      # flight) so the stdin-closing waiter can wake. Named for history — it
-      # once tracked the literal first result.
-      @first_result_received = false
+      # Set once #receive_messages has consumed the read loop's end sentinel.
+      @stream_ended = false
+      # Ends when the run is over, so the stdin-closing waiter can wake; see
+      # #read_messages and @inflight_tasks below (Python #1088, #1190/#1279).
+      # Work the CLI takes up after the run ended swaps in a fresh one
+      # (#reopen_run).
+      @run_end = RunEnd.new
+      @result_received = false
+      # The CLI's latest session_state_changed state, or nil while it sends
+      # none (a CLI too old to honor CLAUDE_CODE_SDK_READS_SESSION_STATE). A
+      # CLI that reports state stays "running" while a background agent is
+      # live or its completion is still to be handled, and reports "idle" once
+      # no further turn is owed.
+      @session_state = nil
+      # Ends the run if no new turn starts within the ceiling after a result
+      # (#arm_run_end_ceiling). The generation tells a sleeper that woke after
+      # it was cleared or re-armed to stand down.
+      @run_end_ceiling_task = nil
+      @run_end_ceiling_generation = 0
+      # A main-thread turn is under way (its assistant/stream_event frames
+      # have started and its result has not arrived): the ceiling counts only
+      # the wait between turns, so it is not armed meanwhile.
+      @turn_in_progress = false
+      # Set once stdin is closed or the reader is gone: the run then stays
+      # ended, since nothing can wait on a reopened one.
+      @run_final = false
       # Task IDs of started-but-not-finished deferring tasks. A result frame
       # only ends one turn, not the run: a background task keeps running past
       # it and still needs stdin for hook/SDK-MCP control responses (Python
@@ -119,7 +233,6 @@ module ClaudeAgentSDK
       # reported. Mirrors the TypeScript SDK's `lastErrorResultText`
       # (Query.ts), but keeps the whole payload rather than just the text.
       @last_error_result = nil
-      @first_result_condition = Async::Condition.new
       @task = nil
       @child_tasks = []
       @initialized = false
@@ -178,6 +291,10 @@ module ClaudeAgentSDK
       agents_dict = nil
       if @agents
         agents_dict = @agents.transform_values do |agent_def|
+          # A Hash stands for the AgentDefinition with the same attributes
+          # (the options signature allows either). Built through .new: the
+          # user wrote it, so a misspelled key raises as on the typed class.
+          agent_def = AgentDefinition.new(agent_def) if agent_def.is_a?(Hash)
           {
             description: agent_def.description,
             prompt: agent_def.prompt,
@@ -256,18 +373,15 @@ module ClaudeAgentSDK
       # Reactor-side agent for #close calls arriving from foreign threads
       # (FiberBoundary callbacks, plain user threads): Async::Task#stop needs
       # the owning thread's Fiber.scheduler, so the off-thread caller hands the
-      # whole close over and waits. Transient: must never keep the reactor
-      # alive, and is stopped automatically when the parent task finishes.
-      # One-shot: after serving a close it is done; a reactor-side close wakes
-      # it via @close_requests.close (pop -> nil) so it exits without serving.
+      # whole close over and waits. Transient: while it waits for a request it
+      # must never keep the reactor alive, and it is stopped automatically
+      # once the reactor has nothing else to run. One-shot: it passes the
+      # first request on to a task of its own (#serve_marshalled_close) and
+      # is done; a reactor-side close wakes it via @close_requests.close
+      # (pop -> nil) so it exits without serving.
       @close_watcher = parent.async(transient: true, &FiberBoundary.capture_otel_context do
-        if (reply = @close_requests.pop)
-          begin
-            close
-          ensure
-            reply << true
-          end
-        end
+        reply = @close_requests.pop
+        serve_marshalled_close(reply) if reply
       end)
     end
 
@@ -376,22 +490,26 @@ module ClaudeAgentSDK
         else
           # Track task lifecycle frames so results can tell "one turn ended"
           # apart from "the run is done" (Python #1088/#1103).
-          track_task_lifecycle(message) if message[:type] == 'system'
+          if msg_type == 'system'
+            had_tasks_in_flight = !@inflight_tasks.empty?
+            track_task_lifecycle(message)
+            # The ceiling left the last tracked agent alone; the wait between
+            # turns starts over now that it settled.
+            rearm_run_end_ceiling_between_turns if had_tasks_in_flight && @inflight_tasks.empty?
+            if message[:subtype] == 'session_state_changed'
+              on_session_state(message[:state])
+              # Frames the CLI sent only because the transport asked for them
+              # (CLAUDE_CODE_SDK_READS_SESSION_STATE); the caller did not opt
+              # in, so they never reach the stream, observers or the parser.
+              next if message[:sdk_host_only] == true
+            end
+          end
 
-          if message[:type] == 'result'
+          if msg_type == 'result'
             # Flush the mirror before signaling/yielding the result so a
             # consumer observing the result sees an up-to-date store for the turn.
             flush_transcript_mirror
-            # A result with tasks still in flight ends one turn, not the run:
-            # the tasks may still need hook/SDK-MCP control responses over
-            # stdin, and closing it now silently disables hooks and fails
-            # SDK-MCP calls with "Stream closed". Each deferring task's
-            # completion wakes the parent for a follow-up turn, so a later
-            # result arrives with no tasks in flight and closes stdin then.
-            if @inflight_tasks.empty? && !@first_result_received
-              @first_result_received = true
-              @first_result_condition.signal
-            end
+            on_result
             @last_error_result = message[:is_error] ? message : nil
           elsif !(msg_type == 'system' && message[:subtype] == 'session_state_changed')
             # Anything other than the post-turn session_state_changed marker
@@ -399,6 +517,14 @@ module ClaudeAgentSDK
             # crash, not the expected exit from a prior error result. Mirrors
             # the Python/TypeScript SDK reset logic.
             @last_error_result = nil
+            # A main-thread turn is under way, so the ceiling stops (it counts
+            # only the wait between turns, as the CLI's does) and the run
+            # reopens even if the ceiling ended it while no state changed.
+            if TURN_FRAME_TYPES.include?(msg_type) && message[:parent_tool_use_id].nil?
+              @turn_in_progress = true
+              reopen_run
+              clear_run_end_ceiling
+            end
           end
           # Regular SDK messages go to the queue
           @message_queue.enqueue(message)
@@ -447,10 +573,11 @@ module ClaudeAgentSDK
       begin
         flush_transcript_mirror
       ensure
-        unless @first_result_received
-          @first_result_received = true
-          @first_result_condition.signal
-        end
+        # Unblock the stdin-closing waiter so it doesn't stall on early exit;
+        # with the reader gone the run stays ended. Also stops a pending
+        # ceiling sleeper, which would otherwise keep the reactor alive.
+        @run_final = true
+        end_run
         # Always signal end of stream
         @message_queue.enqueue({ type: 'end' })
       end
@@ -500,6 +627,138 @@ module ClaudeAgentSDK
       end
     end
 
+    # A result ends a turn, not necessarily the run: a background agent that
+    # finished just before it still wakes the session for another turn, whose
+    # hook, permission and SDK MCP requests need stdin (Python #1190/#1279). A
+    # CLI that reports session state stays "running" while such a turn is
+    # owed, so wait for "idle" (some hosts send it just before the result).
+    # Without state events the result is all there is to go on.
+    def on_result
+      @result_received = true
+      @turn_in_progress = false
+      if @session_state.nil? || @session_state == 'idle' || !bidirectional_needs?
+        maybe_end_run
+      elsif @session_state != 'requires_action'
+        # While the SDK is still answering a request the ceiling waits for
+        # the "running" that follows.
+        arm_run_end_ceiling
+      end
+    end
+
+    # Track the CLI's session_state_changed state (Python #1279).
+    def on_session_state(state)
+      @session_state = state
+      if state == 'idle'
+        maybe_end_run if @result_received
+        return
+      end
+      # Work the CLI took up after the run ended (a finished background task
+      # woke it) reopens the run until the next "idle".
+      reopen_run
+      if state == 'requires_action'
+        # The host is answering a request; stdin must outlast it.
+        clear_run_end_ceiling
+      else
+        rearm_run_end_ceiling_between_turns
+      end
+    end
+
+    # End the run unless a tracked background task is still in flight: such
+    # a task may still need hook/SDK-MCP control responses over stdin
+    # (Python #1088), and its completion wakes the parent for a follow-up
+    # turn whose result (or "idle") ends the run then. A CLI that reports
+    # session state never reports "idle" with an agent still live, so this
+    # matters for CLIs that report "idle" at every turn end or not at all.
+    def maybe_end_run
+      end_run if @inflight_tasks.empty?
+    end
+
+    # The run is over: wake the stdin-closing waiter. Idempotent.
+    #
+    # The run is marked ended BEFORE the ceiling is cleared: stopping the
+    # sleeper task yields to whatever else is ready, and a #stream_input task
+    # that writes its next message in that gap must find the run already
+    # ended, so that #reopen_run gives the message a run of its own. Cleared
+    # first, the message joined the run that was about to end, and stdin
+    # closed before the message's own run had produced a frame.
+    def end_run
+      @run_end.end!
+      clear_run_end_ceiling
+    end
+
+    # Reopen an ended run for work that started after it ended. A waiter the
+    # ended run already woke still closes stdin; this makes a later wait
+    # (stream_input's, once its prompts are all written) wait for the new
+    # work too. Once stdin is closed, or the reader is gone, the run stays
+    # ended.
+    def reopen_run
+      @run_end = RunEnd.new if @run_end.ended? && !@run_final
+    end
+
+    # End the run anyway once the ceiling passes with no new turn. The CLI's
+    # own background-wait ceiling only counts once stdin is closed, so without
+    # this, work that never finishes would hold "running", and stdin, open
+    # forever. It counts only the wait between turns: restarted at each result
+    # and whenever the CLI reports "running" again, cleared by main-thread
+    # turn activity and by "requires_action", never armed mid-turn.
+    #
+    # The sleeper is a child of the read task, NOT a #spawn_task entry: it is re-armed at every
+    # result and every "running", and @child_tasks never prunes. The read
+    # task's stop cascades to it, and every exit path clears it (#end_run in
+    # the read loop's ensure, #wait_for_result_and_end_input's ensure), so a
+    # pending sleeper can never keep the enclosing reactor alive.
+    def arm_run_end_ceiling
+      clear_run_end_ceiling
+      # A frame read while close is under way (the result branch flushes the
+      # mirror first) must not leave a sleeper behind either.
+      return if @run_end_ceiling_ms <= 0 || @run_end.ended? || @run_final || @closed ||
+                @turn_in_progress || !bidirectional_needs?
+
+      generation = @run_end_ceiling_generation
+      seconds = [@run_end_ceiling_ms, MAX_RUN_END_CEILING_MS].min / 1000.0
+      @run_end_ceiling_task = @task.async do
+        sleep seconds
+        end_run_at_ceiling(generation)
+      end
+    end
+
+    # Restart the ceiling if the run is between turns, past a result, with
+    # the CLI still reporting work ("running").
+    def rearm_run_end_ceiling_between_turns
+      return unless @result_received
+      return if @session_state.nil? || NON_RUNNING_SESSION_STATES.include?(@session_state)
+
+      arm_run_end_ceiling
+    end
+
+    def end_run_at_ceiling(generation)
+      # Cleared or re-armed while this sleeper was already waking up.
+      return unless generation == @run_end_ceiling_generation
+
+      # Detach before ending the run: #end_run clears the ceiling, and
+      # clearing it must not stop the task running this very method.
+      @run_end_ceiling_task = nil
+      # A tracked background agent still running may still need stdin for its
+      # hook, permission and SDK MCP requests (Python #1088), so it is not cut
+      # off; the ceiling starts over once it settles (#read_messages).
+      return unless @inflight_tasks.empty?
+
+      # A control request the SDK is still answering (a slow hook or SDK MCP
+      # tool) must be able to write its reply, so the clock starts over rather
+      # than closing stdin under it. Ruby-only guard: Python relies on the CLI
+      # reporting requires_action for every such request.
+      return arm_run_end_ceiling unless @inflight_control_request_tasks.empty?
+
+      end_run
+    end
+
+    def clear_run_end_ceiling
+      @run_end_ceiling_generation += 1
+      task = @run_end_ceiling_task
+      @run_end_ceiling_task = nil
+      task&.stop
+    end
+
     # Whether the CLI may still send control requests that need a reply.
     #
     # SDK MCP servers, hooks and the can_use_tool permission callback are all
@@ -595,15 +854,42 @@ module ClaudeAgentSDK
       raise
     rescue StandardError => e
       send_control_error(request_id, e.message)
+    rescue *FiberBoundary::CALLBACK_FAILURES => e
+      # What is left of the list: a callback (or its callback_wrapper)
+      # failing outside StandardError — NotImplementedError, LoadError,
+      # SystemStackError, SecurityError. No `rescue StandardError` on the
+      # way here caught it, not even the one in #handle_sdk_mcp_request that
+      # turns a resource or prompt handler's failure into its JSON-RPC
+      # error, so the answer an ordinary failure gets is built here.
+      # Unanswered, it would also end this task with an exception Async
+      # treats as fatal for the whole reactor.
+      respond_to_callback_failure(request_id, request_data, e.message)
     end
 
-    # The response an ordinary exception from the callback would have
-    # produced, with the process-exit exception named by class: an error
-    # control response for hooks / can_use_tool; for SDK MCP requests an
-    # in-band isError result (tools/call) or a JSON-RPC internal error
-    # (resources/read, prompts/get), inside a successful control response.
+    # Answers the request, then leaves the process-exit exception to its
+    # caller to re-raise: the response an ordinary exception from the
+    # callback would have produced, naming the exception by class.
+    #
+    # The text has the format of FiberBoundary.process_exit_message, built
+    # here from the normalized message instead of calling it: that method
+    # joins the class name to the raw message, which raises
+    # Encoding::CompatibilityError for an encoding that is not
+    # ASCII-compatible (UTF-16). Raised in the rescue clause this runs in,
+    # that error would leave the request unanswered and replace the exit.
+    # +error+ is only read, never changed.
     def respond_to_process_exit(request_id, request_data, error)
-      message = FiberBoundary.process_exit_message(error)
+      detail = wire_text(error.message)
+      message = detail.empty? || detail == error.class.name ? error.class.name : "#{error.class}: #{detail}"
+      respond_to_callback_failure(request_id, request_data, message)
+    end
+
+    # The response an ordinary exception from the callback would have
+    # produced, with +message+ as its text: an error control response for
+    # hooks / can_use_tool; for SDK MCP requests an in-band isError result
+    # (tools/call) or a JSON-RPC internal error (resources/read,
+    # prompts/get), inside a successful control response.
+    def respond_to_callback_failure(request_id, request_data, message)
+      message = wire_text(message)
       mcp_message = request_data[:message] if request_data.is_a?(Hash) && request_data[:subtype] == 'mcp_message'
       return send_control_error(request_id, message) unless mcp_message.is_a?(Hash)
 
@@ -620,10 +906,19 @@ module ClaudeAgentSDK
                                 response: { mcp_response: mcp_response }
                               }
                             }))
+    rescue JSON::GeneratorError
+      # Not reachable through the text, which #wire_text made encodable.
+      # Kept because an exception leaving this method would take the place
+      # of the process exit the caller is about to re-raise.
+      send_control_error(request_id, message)
     rescue CLIConnectionError
       nil # the CLI is already gone; nothing is waiting for the answer
     end
 
+    # Called from the rescue clauses of #handle_control_request, where an
+    # exception raised while building the answer has no rescue left: the
+    # request would stay unanswered. So the text goes through #wire_text, and
+    # whatever JSON.generate still rejects is replaced by a fixed one.
     def send_control_error(request_id, message)
       error_response = {
         type: 'control_response',
@@ -631,10 +926,16 @@ module ClaudeAgentSDK
           subtype: 'error',
           request_id: request_id,
           requestId: request_id,
-          error: message
+          error: wire_text(message)
         }
       }
-      writeln(JSON.generate(error_response))
+      line = begin
+        JSON.generate(error_response)
+      rescue JSON::GeneratorError
+        error_response[:response][:error] = 'Control request failed; its error message could not be encoded as JSON'
+        JSON.generate(error_response)
+      end
+      writeln(line)
     rescue CLIConnectionError
       # EOF/close can invalidate a callback after the peer has gone away.
       # Only this best-effort reply is discarded; read errors still reach
@@ -642,6 +943,27 @@ module ClaudeAgentSDK
       nil
     end
 
+    # Error text as JSON.generate accepts it. An exception message can hold
+    # anything: a multibyte character cut by byteslice, the raw bytes of a
+    # subprocess or an HTTP body, a driver's own encoding. Valid UTF-8
+    # passes through. A UTF-8, BINARY or US-ASCII string is read as UTF-8,
+    # with U+FFFD in place of each byte that is not valid there. Any other
+    # encoding is transcoded, so valid text in it survives, with U+FFFD for
+    # what cannot be converted.
+    def wire_text(text)
+      text = text.to_s
+      return text if text.encoding == Encoding::UTF_8 && text.valid_encoding?
+
+      if [Encoding::UTF_8, Encoding::BINARY, Encoding::US_ASCII].include?(text.encoding)
+        text.dup.force_encoding(Encoding::UTF_8).scrub
+      else
+        text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      end
+    rescue EncodingError
+      # No converter for the declared encoding (a dummy one such as UTF-7).
+      text.dup.force_encoding(Encoding::UTF_8).scrub
+    end
+
     def handle_permission_request(request_data, request_id: nil) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- permission round-trip: input, callback, result conversion
       raise 'canUseTool callback is not provided' unless @can_use_tool
 
@@ -1025,36 +1347,24 @@ module ClaudeAgentSDK
       { mcp_response: mcp_response }
     end
 
-    def convert_hook_output_for_cli(hook_output) # rubocop:disable Metrics/CyclomaticComplexity -- one optional field per hook output key
-      # Handle typed output objects
-      return hook_output.to_h if hook_output.respond_to?(:to_h) && !hook_output.is_a?(Hash)
-
+    # What a hook callback returned, as the object the CLI reads. A typed
+    # output (or anything else with #to_h) contributes its own Hash; a typed
+    # value inside a Hash, such as a *HookSpecificOutput under
+    # hook_specific_output, does the same. The keys of the result are then
+    # normalized, so a Hash written in snake_case or with String keys means
+    # what the typed output means (HookOutputKeys) — and so does the Hash a
+    # typed output carried through as its hook_specific_output.
+    def convert_hook_output_for_cli(hook_output)
+      if hook_output.is_a?(Hash)
+        hook_output = hook_output.transform_values do |value|
+          value.respond_to?(:to_h) && !value.is_a?(Hash) ? value.to_h : value
+        end
+      elsif hook_output.respond_to?(:to_h)
+        hook_output = hook_output.to_h
+      end
       return {} unless hook_output.is_a?(Hash)
 
-      # Convert Ruby hash with symbol keys to CLI format
-      # Handle special keywords that might be Ruby-safe versions
-      converted = {}
-      hook_output.each do |key, value|
-        converted_key = case key
-                        when :async_, 'async_' then 'async'
-                        when :continue_, 'continue_' then 'continue'
-                        when :hook_specific_output then 'hookSpecificOutput'
-                        when :suppress_output then 'suppressOutput'
-                        when :stop_reason then 'stopReason'
-                        when :system_message then 'systemMessage'
-                        when :async_timeout then 'asyncTimeout'
-                        else key.to_s
-                        end
-
-        # Recursively convert nested objects
-        converted_value = if value.respond_to?(:to_h) && !value.is_a?(Hash)
-                            value.to_h
-                          else
-                            value
-                          end
-        converted[converted_key] = converted_value
-      end
-      converted
+      HookOutputKeys.normalize(hook_output)
     end
 
     def send_control_request(request)
@@ -1069,10 +1379,25 @@ module ClaudeAgentSDK
       # RuntimeError; the eventual response dropped by the key? guard).
       task = Async::Task.current?
 
-      # Reactor callers wait on an Async::Condition; worker-thread callers
-      # on a ThreadWaiter. Register atomically with the terminal-state check
-      # so EOF cannot strand a sender that missed the final broadcast.
-      waiter = task ? Async::Condition.new : ThreadWaiter.new
+      # The waiter is chosen by reactor OWNERSHIP, not by "has a task". Only
+      # a fiber of the reactor that owns this Query (the one #start ran on,
+      # whose read loop does the signaling) checks its result slot and parks
+      # with no chance for the read loop to run in between, so only there is
+      # the edge-triggered Async::Condition safe. Every other caller races
+      # the read loop between its check and its park and gets the
+      # level-triggered ThreadWaiter: a FiberBoundary worker thread, a plain
+      # thread, and also a fiber on ANOTHER thread's reactor (`Sync {
+      # client.interrupt }` on a request thread while the session lives on a
+      # background reactor; a Sync block inside a :thread-mode callback).
+      # Given a Condition, such a fiber could lose its wakeup on async >=
+      # 2.29, and on async 2.10-2.28 the cross-thread signal raised
+      # FiberError in the read loop, ending the whole session. The deadline
+      # mechanism (#await_control_response) is still chosen by "has a task".
+      #
+      # Register atomically with the terminal-state check so EOF cannot
+      # strand a sender that missed the final broadcast.
+      on_owning_reactor = task && Fiber.scheduler.equal?(@owning_scheduler)
+      waiter = on_owning_reactor ? Async::Condition.new : ThreadWaiter.new
       request_id = @request_counter_mutex.synchronize do
         raise @control_stream_error if @control_stream_error
 
@@ -1122,7 +1447,12 @@ module ClaudeAgentSDK
         # only this deadline is translated, not an outer task's cancellation.
         FiberBoundary.with_cooperative_timeout(task, timeout_seconds, on_timeout: expired) do
           yield
-          waiter.wait until @pending_control_results.key?(request_id)
+          # A ThreadWaiter here belongs to a fiber on a reactor that does not
+          # own this Query: Thread::Queue#pop parks that fiber through its
+          # own scheduler, and the deadline cancels it like any suspension.
+          until @pending_control_results.key?(request_id)
+            waiter.is_a?(ThreadWaiter) ? waiter.wait(nil) : waiter.wait
+          end
         end
       else
         # Only schedulerless callers use stdlib Timeout. A fresh, private
@@ -1399,45 +1729,62 @@ module ClaudeAgentSDK
                            })
     end
 
-    # Wait for a run-ending result before closing stdin when hooks, SDK MCP
-    # servers or a can_use_tool callback may still need to exchange control
-    # messages with the CLI.
-    # The control protocol requires stdin to stay open for the entire turn
-    # (hook replies, can_use_tool replies and SDK MCP tool results are all
-    # written to stdin), so no timeout is applied — closing stdin mid-turn
-    # silently broke hooks/MCP on turns longer than the old 60s bound
-    # (mirrors Python SDK commit c3d96cb). A result frame ends one turn, not
-    # necessarily the run: while background tasks are in flight the result
-    # branch withholds the signal (Python #1088/#1103), and each deferring
-    # task's completion wakes the parent for a follow-up turn that ends in
-    # another result. The condition is guaranteed to be signaled: by the
-    # result branch in read_messages once no tasks are in flight, or by its
-    # ensure block when the process exits early.
+    # Wait for the end of the run, when hooks, SDK MCP servers or a
+    # can_use_tool callback may still need to exchange control messages with
+    # the CLI, then close stdin. Their replies are all written to stdin, so it
+    # must stay open until the run ends: at the CLI's "idle" session state
+    # after a result, or, from a CLI that reports no session state, at the
+    # first result with no tracked tasks in flight. A result frame ends one
+    # turn, not necessarily the run: background tasks keep running past it,
+    # or have just finished and still wake the parent for a follow-up turn,
+    # and those turns need stdin for control responses (Python #1088, #1190).
     #
-    # Known limitation (same as Python's): the condition is one-shot and is
-    # not aware of prompt messages still queued CLI-side, so an Enumerator
-    # prompt yielding several user messages (several turns) releases the hold
-    # at the first turn boundary with no tracked tasks; control requests from
-    # later turns can then find stdin closed. Single-message and String
-    # prompts — the common one-shot shapes — are fully covered.
+    # No timeout bounds a turn (closing stdin mid-turn silently broke
+    # hooks/MCP on turns longer than the old 60s bound; Python c3d96cb). The
+    # wait BETWEEN turns is bounded: if the CLI still reports "running"
+    # CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS (10 minutes by default, 0 for no
+    # limit) after a result with no new turn, the run ends anyway
+    # (#arm_run_end_ceiling). A turn under way, a request the SDK is still
+    # answering and a tracked background agent still in flight (Python #1088)
+    # stop that clock. The run is guaranteed to end: as above, or in
+    # read_messages' ensure when the process exits early.
+    #
+    # Known limitation (same as Python's): from a CLI that reports no session
+    # state, a result for an earlier message of an Enumerator prompt still
+    # ends the run even when a later message is already queued CLI-side, so
+    # control requests from that later turn can find stdin closed.
+    # Single-message and String prompts are fully covered.
     def wait_for_result_and_end_input
-      @first_result_condition.wait if !@first_result_received && bidirectional_needs?
+      @run_end.wait if bidirectional_needs?
     ensure
+      @run_final = true
+      clear_run_end_ceiling
       @transport.end_input
     end
 
-    # Stream input messages to transport. NOTE: iteration runs on the
-    # reactor (the deliberate FiberBoundary carve-out — see
-    # fiber_boundary.rb): scheduler-aware blocking (Thread::Queue#pop,
-    # sleep, socket IO) parks only this task; CPU-bound or scheduler-opaque
-    # work in the enumerator must be moved to a producer Thread by the user.
+    # Stream input messages to transport, then close stdin once the run ends
+    # (#wait_for_result_and_end_input). Each message written owes a run of its
+    # own, so the wait is for the last message's run, not an earlier one's.
+    #
+    # NOTE: iteration runs on the reactor (the deliberate FiberBoundary
+    # carve-out — see fiber_boundary.rb): scheduler-aware blocking
+    # (Thread::Queue#pop, sleep, socket IO) parks only this task; CPU-bound or
+    # scheduler-opaque work in the enumerator must be moved to a producer
+    # Thread by the user.
     def stream_input(stream)
       wrote_message = false
       stream.each do |message|
         break if @closed
 
-        serialized = message.is_a?(Hash) ? JSON.generate(message) : message.to_s
-        writeln(serialized)
+        # Serialized first: a message verbatim_prompts cannot mark raises
+        # here, before the run is reopened for a message that never went out.
+        line = Query.serialize_user_message(message, @verbatim_prompts)
+        # This message owes a run of its own, result included: an earlier
+        # one having ended does not end it.
+        reopen_run
+        @result_received = false
+        clear_run_end_ceiling
+        writeln(line)
         wrote_message = true
       end
     rescue StandardError => e
@@ -1446,22 +1793,33 @@ module ClaudeAgentSDK
     ensure
       # Three teardown shapes:
       # - #close in progress (@closed, Async::Stop unwinding): do nothing —
-      #   the transport is about to be closed, and waiting on
-      #   @first_result_condition inside a stopping fiber could suspend
-      #   teardown. Mirrors Python, where cancellation skips this entirely.
+      #   the transport is about to be closed, and waiting on the run's end
+      #   inside a stopping fiber could suspend teardown. Mirrors Python,
+      #   where cancellation skips this entirely.
       # - A turn is in flight (some message reached the CLI): hold stdin
-      #   open until its first result so hooks/SDK MCP control replies can
-      #   still be written (no timeout — the result or process exit is
-      #   guaranteed to signal).
+      #   open until the run ends so hooks/SDK MCP control replies can still
+      #   be written (the run's end or process exit is guaranteed to signal).
       # - No complete message ever reached the CLI (empty stream, or the
-      #   stream raised before the first write): no result can ever arrive,
-      #   so waiting would park query() forever beside an idle CLI. Close
-      #   stdin so the CLI sees EOF and exits. Deliberate improvement over
-      #   Python, which leaves stdin open and hangs on this path.
+      #   stream raised before the first write): no result is owed, so there
+      #   is nothing to wait for. Close stdin at once so the CLI sees EOF and
+      #   exits, as the Python and TypeScript SDKs do.
+      #   This is a trade-off, not a free win. An empty stream is also how a
+      #   caller says "send nothing, just resume", and a resumed session can
+      #   have work of its own: a tool call that a PreToolUse hook deferred
+      #   is re-run by the CLI on resume. If that tool is served by an SDK
+      #   MCP server, the CLI's request for it finds stdin already closed and
+      #   the CLI exits with an error (ProcessError, exit code 1;
+      #   anthropics/claude-agent-sdk-python#1226). Waiting instead would
+      #   hang every empty resume that has nothing pending: a CLI that is
+      #   idle with no input reports no session state (seen with 2.1.286),
+      #   so the two cases cannot be told apart without a signal from the
+      #   CLI. Until there is one, resume a deferred tool through Client,
+      #   which keeps stdin open.
       unless @closed
         if wrote_message
           wait_for_result_and_end_input
         else
+          @run_final = true
           @transport.end_input
         end
       end
@@ -1484,8 +1842,21 @@ module ClaudeAgentSDK
       # reception — ResultMessage dropped, the query reported as complete, and
       # on_error never fired. `while` propagates it like any other error.
       while true # rubocop:disable Style/InfiniteLoop
+        # End of stream is sticky. The read loop enqueues ONE sentinel and is
+        # gone, so once a receive has consumed it, every later one must end
+        # at once rather than wait on a queue nothing writes to any more
+        # (Python closes the send side of its stream, so later iterations
+        # end at once there too). The end is remembered, not put back on the
+        # queue: a receive can be made after the reactor has finished, and
+        # async < 2.29 cannot enqueue outside a task. Anything still queued,
+        # such as a mirror error reported after the end, is delivered first.
+        break if @stream_ended && @message_queue.empty?
+
         message = @message_queue.dequeue
-        break if message[:type] == 'end'
+        if message[:type] == 'end'
+          @stream_ended = true
+          break
+        end
         raise message[:error] if message[:type] == 'error'
 
         block.call(message)
@@ -1500,14 +1871,18 @@ module ClaudeAgentSDK
     # plain user threads — don't have; stopping from one raised NoMethodError
     # and left the read/child tasks running. Such callers hand the close to
     # the reactor-side watcher (spawned in #start) and wait for it to finish,
-    # so close semantics are identical regardless of the calling thread.
+    # so close semantics are identical regardless of the calling thread. The
+    # reactor waits for a close it was handed: it stays alive until the
+    # transport's teardown is done, even when the session's own task has
+    # nothing left to do.
     def close
       if @close_watcher&.alive? && !Fiber.scheduler.equal?(@owning_scheduler)
         marshal_close_to_reactor
       else
-        # Same scheduler (reactor-side caller, including the watcher itself),
-        # or no live watcher: when the reactor is gone its task fibers are
-        # dead, so stopping them no longer touches Fiber.scheduler.
+        # Same scheduler (reactor-side caller, including the task serving a
+        # marshalled close), or no live reactor-side task to hand it to: when
+        # the reactor is gone its task fibers are dead, so stopping them no
+        # longer touches Fiber.scheduler.
         close_now
       end
     end
@@ -1588,8 +1963,8 @@ module ClaudeAgentSDK
       # surfaces as Async::Stop (Python parity: a hook that awaits
       # disconnect() gets CancelledError). Applied ONLY inside the trees of
       # the tasks being stopped: the reactor-side caller (Client#disconnect
-      # from the connect task, the close watcher) and foreign threads keep
-      # the plain path, unchanged.
+      # from the connect task, the task serving a marshalled close) and
+      # foreign threads keep the plain path, unchanged.
       #
       # The deferred Stop SUPERSEDES anything the teardown raises: async
       # raises it from defer_stop's ensure with an explicit `cause:`, so a
@@ -1665,11 +2040,51 @@ module ClaudeAgentSDK
       nil
     end
 
-    # Hand the close to the reactor and wait for completion. Polls watcher
-    # liveness instead of waiting forever: if the reactor shuts down
-    # concurrently (the transient watcher is stopped without serving the
-    # request), no reply will ever arrive — fall back to a direct close,
-    # which is safe once the reactor's fibers are dead.
+    # Reactor side of a marshalled close; runs on the close watcher, which
+    # must not run the close itself. The watcher is transient, and a reactor
+    # does not wait for transient tasks: stopping the read task releases the
+    # session's own task (the end sentinel), and if that was the last
+    # non-transient task the reactor winds down and stops the watcher at the
+    # first suspension point of the transport teardown. SubprocessCLITransport
+    # then TERMs the CLI instead of closing stdin and granting the grace
+    # period that lets it finish its last session write, and the caller is
+    # released before the child is reaped.
+    #
+    # So the close runs in a task of its own that the reactor does wait for
+    # (bounded by the transport's teardown). `defer_stop` on the watcher is
+    # not enough: async 2.10 terminates the tasks of a finished reactor with
+    # repeated stops, and a deferral survives only the first.
+    #
+    # The task is a SIBLING of the watcher, created under the watcher's
+    # current parent. A reactor counts only its direct children, so a child
+    # of the transient watcher would not hold it open — and that is what
+    # `parent.async` creates once the task that started the session is gone
+    # and async has re-parented the watcher to the reactor (Scheduler#async
+    # adopts the current task as the parent).
+    #
+    # @close_watcher follows the close: the waiting caller polls it for
+    # liveness (#marshal_close_to_reactor), so it has to name the task that
+    # will answer. Switched before the new task can suspend, while the
+    # watcher that spawned it is still alive.
+    def serve_marshalled_close(reply)
+      body = FiberBoundary.capture_otel_context do |task|
+        @close_watcher = task
+        begin
+          close
+        ensure
+          reply << true
+        end
+      end
+      Async::Task.new(Async::Task.current.parent, &body).run
+    end
+
+    # Hand the close to the reactor and wait for completion. Polls the
+    # liveness of the reactor-side task that is to answer (@close_watcher:
+    # the idle watcher, then the task serving the close) instead of waiting
+    # forever: if the reactor shuts down concurrently (the transient watcher
+    # is stopped without serving the request), no reply will ever arrive —
+    # fall back to a direct close, which is safe once the reactor's fibers
+    # are dead.
     def marshal_close_to_reactor
       reply = ::Thread::Queue.new
       @close_requests << reply