claude-agent-sdk 1.1.0 → 1.2.1

data/lib/claude_agent_sdk/query.rb

@@ -9,6 +9,7 @@ require 'timeout'
 require_relative 'transport'
 require_relative 'errors'
 require_relative 'cancellation_signal'
+require_relative 'query/run_lifecycle'
 
 module ClaudeAgentSDK
   # Handles bidirectional control protocol on top of Transport
@@ -30,37 +31,22 @@ module ClaudeAgentSDK
     # @api private
     attr_reader :initialization_result
 
+    # When stdin may close (RunLifecycle). Read by specs.
+    #
+    # @api private
+    attr_reader :run_lifecycle
+
     CONTROL_REQUEST_TIMEOUT_ENV_VAR = 'CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS'
     DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS = 1200.0
 
-    # Task types whose completion runs a follow-up turn, and which therefore
-    # may still need the control channel after the turn's result frame.
-    #
-    # Mirrors the set the CLI itself holds a result back for, which is
-    # narrower than its notion of "delegated agent work". The types left out
-    # are left out on purpose:
-    #   - background shells and monitors run indefinitely by design, so
-    #     deferring the close on one withholds it forever rather than briefly;
-    #   - teammates are long-lived too — their status stays running for their
-    #     whole lifetime, so they never settle the ledger;
-    #   - remote agents can be long-running monitors the CLI likewise refuses
-    #     to wait on.
-    # Anything added here must be a type that reliably reaches a terminal
-    # status, or it will hang the query (see #track_task_lifecycle).
-    DEFERRING_TASK_TYPES = %w[local_agent local_workflow].freeze
-
     # 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).
+    # (RunLifecycle#arm, 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
@@ -76,33 +62,6 @@ module ClaudeAgentSDK
       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
@@ -136,14 +95,16 @@ module ClaudeAgentSDK
     end
     private_class_method :parse_streamed_message
 
-    # 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.
+    # 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
@@ -162,7 +123,7 @@ module ClaudeAgentSDK
                    exclude_dynamic_sections: nil, system_prompt_snapshot: nil, skills: nil,
                    forward_subagent_text: false, agent_progress_summaries: nil,
                    callback_scheduling: :thread, callback_wrapper: nil, verbatim_prompts: false,
-                   run_end_ceiling_ms: DEFAULT_RUN_END_CEILING_MS)
+                   run_end_ceiling_ms: DEFAULT_RUN_END_CEILING_MS, sleeper: nil)
       @transport = transport
       @is_streaming_mode = is_streaming_mode
       @can_use_tool = can_use_tool
@@ -177,7 +138,6 @@ module ClaudeAgentSDK
       @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 = {}
@@ -193,36 +153,16 @@ module ClaudeAgentSDK
 
       # Message stream
       @message_queue = Async::Queue.new
-      # 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
-      # #1088/#1103), so a result that arrives while this set is non-empty
-      # must not close stdin.
-      @inflight_tasks = Set.new
+      # Set once #receive_messages has consumed the read loop's end sentinel.
+      @stream_ended = false
+      # When stdin may close: the end of the run (Python #1088, #1190/#1279).
+      # +sleeper+ replaces the ceiling's timer in specs; the default reads @task
+      # when it is called, which is after #start.
+      @run_lifecycle = RunLifecycle.new(
+        ceiling_ms: run_end_ceiling_ms, sleeper: sleeper || method(:sleep_on_read_task),
+        bidirectional_needs: -> { bidirectional_needs? }, closed: -> { @closed },
+        control_requests_in_flight: -> { !@inflight_control_request_tasks.empty? }
+      )
       # Set to the result payload when the most recent message is a result
       # with is_error=true. Used to replace the generic "exit code 1"
       # ProcessError with a ResultError carrying what the CLI already
@@ -287,6 +227,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 = OptionForms.agent_definition(agent_def)
           {
             description: agent_def.description,
             prompt: agent_def.prompt,
@@ -365,18 +309,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
 
@@ -483,43 +424,27 @@ module ClaudeAgentSDK
           @transcript_mirror_batcher&.enqueue(message[:filePath] || message[:file_path], message[:entries] || [])
           next
         else
-          # Track task lifecycle frames so results can tell "one turn ended"
-          # apart from "the run is done" (Python #1088/#1103).
-          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
+          session_state_frame = msg_type == 'system' && message[:subtype] == 'session_state_changed'
+          # 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 if msg_type == 'result'
+          # Every frame that gets here drives the run's end (task lifecycle,
+          # session state, results, main-thread turns), whether or not it goes
+          # on to the stream.
+          @run_lifecycle.frame(message)
+          # 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 session_state_frame && message[:sdk_host_only] == true
 
           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
-            on_result
             @last_error_result = message[:is_error] ? message : nil
-          elsif !(msg_type == 'system' && message[:subtype] == 'session_state_changed')
+          elsif !session_state_frame
             # Anything other than the post-turn session_state_changed marker
             # means the conversation moved on; a ProcessError now is a fresh
             # 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)
@@ -571,182 +496,12 @@ module ClaudeAgentSDK
         # 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
+        @run_lifecycle.reader_gone
         # Always signal end of stream
         @message_queue.enqueue({ type: 'end' })
       end
     end
 
-    # Track in-flight tasks from `system` task lifecycle frames.
-    #
-    # `task_started` marks a task in flight; `task_notification` or a
-    # `task_updated` patch with a terminal status clears it. Terminal
-    # completion can arrive as either frame (not every terminal task emits a
-    # notification), so both are handled; Set deletion keeps the pair
-    # idempotent.
-    #
-    # This is a mitigation, not a complete answer to Python #1088. An empty
-    # set means "nothing we know of is running", which is not the same as
-    # "the run is over": a task that settles *before* the turn's result frame
-    # leaves the set empty at that result, so stdin closes even though the
-    # completion may still wake the parent for a continuation turn. What this
-    # does fix is the common ordering, where the task outlives the turn that
-    # spawned it.
-    #
-    # Only delegated agent work is tracked (DEFERRING_TASK_TYPES). A
-    # background *shell* is also reported through these frames, but it may
-    # never reach a terminal status, and the CLI in stream-json mode only
-    # exits on stdin EOF — tracking one would withhold the close forever.
-    #
-    # `background_tasks_changed` is deliberately not consumed, in either
-    # direction: its payload is the live *background* set, while a subagent
-    # is registered in the foreground and only flips to backgrounded later
-    # without a second task_started, so narrowing against the snapshot would
-    # drop an agent that goes on to outlive its turn, and widening from it
-    # could admit an id no later frame ever clears (observer agents suppress
-    # both their start and terminal frames).
-    def track_task_lifecycle(message)
-      task_id = message[:task_id]
-      return if task_id.nil? || task_id.to_s.empty?
-
-      case message[:subtype]
-      when 'task_started'
-        @inflight_tasks.add(task_id) if DEFERRING_TASK_TYPES.include?(message[:task_type])
-      when 'task_notification'
-        @inflight_tasks.delete(task_id)
-      when 'task_updated'
-        patch = message[:patch]
-        status = patch.is_a?(Hash) ? patch[:status] : nil
-        @inflight_tasks.delete(task_id) if TERMINAL_TASK_STATUSES.include?(status)
-      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.
-    def end_run
-      clear_run_end_ceiling
-      @run_end.end!
-    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
@@ -765,6 +520,17 @@ module ClaudeAgentSDK
       !@sdk_mcp_servers.empty? || !@hooks.empty? || !!@can_use_tool
     end
 
+    # The run-end ceiling's timer (RunLifecycle's sleeper): runs +on_wake+ once
+    # +seconds+ have passed. 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.
+    def sleep_on_read_task(seconds, &on_wake)
+      @task.async do
+        sleep seconds
+        on_wake.call
+      end
+    end
+
     # Flush the transcript-mirror batcher, swallowing errors — a mirror failure
     # must never propagate into the read loop or its teardown.
     def flush_transcript_mirror
@@ -842,15 +608,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
+
+    # 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)
+      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 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.
-    def respond_to_process_exit(request_id, request_data, error)
-      message = FiberBoundary.process_exit_message(error)
+    # 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)
 
@@ -867,10 +660,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',
@@ -878,10 +680,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
@@ -889,6 +697,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
 
@@ -1272,36 +1101,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)
@@ -1316,10 +1133,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
 
@@ -1369,7 +1201,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
@@ -1661,7 +1498,7 @@ module ClaudeAgentSDK
     # 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
+    # (RunLifecycle#arm). 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.
@@ -1672,10 +1509,9 @@ module ClaudeAgentSDK
     # 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
-      @run_end.wait if bidirectional_needs?
+      @run_lifecycle.wait
     ensure
-      @run_final = true
-      clear_run_end_ceiling
+      @run_lifecycle.stdin_closing
       @transport.end_input
     end
 
@@ -1698,9 +1534,7 @@ module ClaudeAgentSDK
         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
+        @run_lifecycle.message_will_write
         writeln(line)
         wrote_message = true
       end
@@ -1717,15 +1551,26 @@ module ClaudeAgentSDK
       #   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
+          @run_lifecycle.empty_input
           @transport.end_input
         end
       end
@@ -1748,8 +1593,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)
@@ -1764,14 +1622,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
@@ -1852,8 +1714,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
@@ -1929,11 +1791,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