claude-agent-sdk 1.1.0 → 1.2.0

data/lib/claude_agent_sdk/query.rb

@@ -136,14 +136,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
@@ -193,6 +195,8 @@ module ClaudeAgentSDK
 
       # Message stream
       @message_queue = Async::Queue.new
+      # 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
@@ -287,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,
@@ -365,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
 
@@ -669,9 +674,16 @@ module ClaudeAgentSDK
     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
-      clear_run_end_ceiling
       @run_end.end!
+      clear_run_end_ceiling
     end
 
     # Reopen an ended run for work that started after it ended. A waiter the
@@ -842,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
+
+    # 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 +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',
@@ -878,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
@@ -889,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
 
@@ -1272,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)
@@ -1316,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
 
@@ -1369,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
@@ -1717,10 +1800,21 @@ 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
@@ -1748,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)
@@ -1764,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
@@ -1852,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
@@ -1929,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

data/lib/claude_agent_sdk/railtie.rb

@@ -57,11 +57,18 @@ module ClaudeAgentSDK
     #    the interlock keeps a reload from unloading code under it until the
     #    whole SDK call returns.
     # 3. Otherwise (production: no reloading, concurrency allowed) — run the
-    #    callback inside `Rails.application.executor.wrap`.
+    #    callback inside the executor (see .run_in_executor).
     #
     # The configuration is read on every call, so the same wrapper is correct
     # in every environment.
     #
+    # The wrapper reports nothing to `Rails.error`, in any branch. An exception
+    # that escapes a callback reaches the code that called the SDK, whose own
+    # layer (the request middleware, ActiveJob) reports it with its context;
+    # the failures the SDK handles itself — a hook or tool error answered to
+    # the CLI, a swallowed observer error, a cancellation — are not errors of
+    # the application.
+    #
     # @return [Proc] a callable suitable for `callback_wrapper:`
     # @example config/initializers/claude_agent_sdk.rb
     #   ClaudeAgentSDK.configure do |config|
@@ -71,7 +78,7 @@ module ClaudeAgentSDK
       lambda do |invocation|
         app = ::Rails.application
         next invocation.call if app.nil? || app.executor.active?
-        next app.executor.wrap { invocation.call } unless executor_locks?(app.config)
+        next run_in_executor(app.executor, invocation) unless executor_locks?(app.config)
 
         begin
           invocation.call
@@ -81,6 +88,24 @@ module ClaudeAgentSDK
       end
     end
 
+    # `executor.wrap { invocation.call }` minus its error report. `wrap`
+    # rescues what passes through it (every Exception on Rails 8.1, 8.0.2+
+    # and 7.2.3+; StandardError before) and reports it to `Rails.error` as
+    # unhandled, from a callback thread that has none of the caller's
+    # context — and Rails then skips the same exception as already reported
+    # when it reaches the request or job. It reported the SDK's own
+    # cancellations and the callback failures the SDK answers or swallows,
+    # too. `run!` / `complete!` run the same hooks.
+    def self.run_in_executor(executor, invocation)
+      execution = executor.run!
+      begin
+        invocation.call
+      ensure
+        execution.complete!
+      end
+    end
+    private_class_method :run_in_executor
+
     # Whether railties registered a process-wide lock hook on the executor
     # (Rails::Application::Finisher, initializer
     # :configure_executor_for_concurrency).