claude-agent-sdk 0.35.0 → 0.37.0

data/lib/claude_agent_sdk/fiber_boundary.rb

@@ -71,6 +71,8 @@ module ClaudeAgentSDK
   # scheduler-aware and park only the stream task; CPU-bound or
   # scheduler-opaque work must be moved by the user (a producer Thread
   # feeding a Thread::Queue, or FiberBoundary.invoke inside the enumerator).
+  #
+  # @api private
   module FiberBoundary
     # Raised by .invoke when a timeout-bounded call exceeds its allotted time.
     # The worker thread is abandoned (cancellation is best-effort; the
@@ -133,6 +135,58 @@ module ClaudeAgentSDK
       end
     end
 
+    # Carries a SystemExit / SignalException (Interrupt included) raised by
+    # a user callback out of the FiberBoundary hop — see .invoke_callback.
+    # A StandardError so the hop ends normally: a :thread worker that died
+    # with SystemExit would have it re-raised by Ruby on the MAIN thread,
+    # asynchronously, before the SDK could answer the pending request.
+    # #cause (and #original) is the exception it carries. A callback_wrapper
+    # sees this carrier, never the original.
+    # @api private
+    class ProcessExitCarrier < StandardError
+      attr_reader :original
+
+      def initialize(original)
+        @original = original
+        super(FiberBoundary.process_exit_message(original))
+      end
+    end
+
+    # Hands a callback's process-exit exception from the code running the
+    # callback to the SDK code waiting for it — or, once that waiter has
+    # stopped waiting (hook timeout, cancelled request), lets the callback
+    # side re-raise it where it is, as plain Ruby would. Either way it is
+    # never dropped.
+    # @api private
+    class ProcessExitHandoff
+      def initialize
+        @mutex = Mutex.new
+        @state = :waiting
+        @original = nil
+      end
+
+      # Callback side: true when the waiter will receive +original+.
+      def hand_off(original)
+        @mutex.synchronize do
+          next false unless @state == :waiting
+
+          @state = :handed_off
+          @original = original
+          true
+        end
+      end
+
+      # Waiter side, when it stops waiting: the exception handed off but not
+      # yet received, if any.
+      def abandon
+        @mutex.synchronize do
+          handed_off = @state == :handed_off
+          @state = :abandoned
+          handed_off ? @original : nil
+        end
+      end
+    end
+
     # Sentinel returned by .invoke_iteration when the user block attempted `break`.
     class Break
       attr_reader :value
@@ -144,6 +198,63 @@ module ClaudeAgentSDK
 
     module_function
 
+    # Invoke a user callback that answers a CLI control request (hook,
+    # can_use_tool, SDK MCP tool / resource / prompt handler) across the
+    # boundary, like .invoke. A SystemExit or SignalException (Interrupt
+    # included) raised while the callback runs is never swallowed: it is
+    # re-raised here, on the calling fiber, as the ORIGINAL exception, so
+    # Query#handle_control_request can answer the request first and then let
+    # it terminate the process as Ruby normally would.
+    #
+    # The conversion must sit INSIDE the hop, innermost around the user
+    # call: in :thread mode a worker dying with SystemExit has it re-raised
+    # by Ruby on the main thread at an arbitrary point, before any response
+    # is written. So the worker ends with a ProcessExitCarrier instead, and
+    # the carrier is unwrapped once control is back on the calling fiber. In
+    # :inline mode the callback runs on the reactor fiber — usually the main
+    # thread — so this also covers a real Ctrl-C / SIGTERM delivered while
+    # the callback runs. A callback_wrapper sees the carrier (a
+    # StandardError, #cause = the original); ensure-based wrappers still
+    # run their cleanup, and a wrapper that swallows the carrier cannot
+    # swallow the exit (the handoff re-raises it).
+    #
+    # If the caller stops waiting first (hook timeout, cancelled request),
+    # the exception is re-raised in the abandoned worker thread instead — a
+    # SystemExit from a non-main thread then ends the process, as in plain
+    # Ruby. Cancellation (Async::Stop, InlineCancellation) is not a
+    # SignalException and passes through untouched.
+    # @api private
+    def invoke_callback(scheduling: :thread, wrapper: nil, &callback)
+      handoff = ProcessExitHandoff.new
+      received = false
+      begin
+        invoke(scheduling: scheduling, wrapper: wrapper) do
+          callback.call
+        rescue SystemExit, SignalException => e
+          raise unless handoff.hand_off(e)
+
+          raise ProcessExitCarrier, e
+        end
+      rescue ProcessExitCarrier => e
+        received = true
+        raise e.original
+      ensure
+        unless received
+          pending = handoff.abandon
+          raise pending if pending
+        end
+      end
+    end
+
+    # Text reporting a process-exit exception to the CLI: its class, plus
+    # its message when that adds anything ("SystemExit: exit",
+    # "SignalException: SIGTERM", "Interrupt").
+    # @api private
+    def process_exit_message(error)
+      detail = error.message
+      detail.empty? || detail == error.class.name ? error.class.name : "#{error.class}: #{detail}"
+    end
+
     # Capture only the optional OTel context before crossing a fiber/thread
     # boundary. OTel keeps its current context fiber-local; copying generic
     # thread locals would also copy unsafe connection/request state. The
@@ -267,10 +378,10 @@ module ClaudeAgentSDK
     # need a bounded wait use :thread scheduling (hard Thread#join bound);
     # inline callbacks keep their cleanup fiber-aware.
     # @api private
-    def with_cooperative_timeout(task, timeout, on_timeout:, &block)
+    def with_cooperative_timeout(task, timeout, on_timeout:, &)
       cancellation = Class.new(InlineCancellation)
       begin
-        task.with_timeout(timeout, cancellation, &block)
+        task.with_timeout(timeout, cancellation, &)
       rescue cancellation
         raise on_timeout.call
       end

data/lib/claude_agent_sdk/instrumentation/otel.rb

@@ -34,7 +34,7 @@ module ClaudeAgentSDK
     #   observer = ClaudeAgentSDK::Instrumentation::OTelObserver.new
     #   options = ClaudeAgentSDK::ClaudeAgentOptions.new(observers: [observer])
     #   ClaudeAgentSDK.query(prompt: "Hello", options: options) { |msg| ... }
-    class OTelObserver
+    class OTelObserver # rubocop:disable Metrics/ClassLength -- one observer mapping every message type to spans
       include ClaudeAgentSDK::Observer
 
       TRACER_NAME = 'claude_agent_sdk'
@@ -124,7 +124,7 @@ module ClaudeAgentSDK
 
       private
 
-      def start_trace(message)
+      def start_trace(message) # rubocop:disable Metrics/AbcSize -- flat mapping of init-message fields to root span attributes
         # A new init without an intervening ResultMessage (e.g. /clear or an
         # interrupted turn) supersedes the current trace; finish it so it is
         # exported instead of leaking as a never-ended span, and reset the
@@ -157,15 +157,21 @@ module ClaudeAgentSDK
           'session.id' => message.session_id
         }.merge(@default_attributes)
 
-        attrs['claude_code.version'] = message.claude_code_version if message.respond_to?(:claude_code_version) && message.claude_code_version
+        if message.respond_to?(:claude_code_version) && message.claude_code_version
+          attrs['claude_code.version'] = message.claude_code_version
+        end
         attrs['claude_code.cwd'] = message.cwd if message.respond_to?(:cwd) && message.cwd
-        attrs['claude_code.permission_mode'] = message.permission_mode if message.respond_to?(:permission_mode) && message.permission_mode
+        if message.respond_to?(:permission_mode) && message.permission_mode
+          attrs['claude_code.permission_mode'] = message.permission_mode
+        end
 
         @root_span = @tracer.start_span('claude_agent.session', attributes: compact_attrs(attrs))
         @root_context = OpenTelemetry::Trace.context_with_span(@root_span)
 
         # Apply buffered prompt if on_user_prompt was called before InitMessage arrived
-        @root_span.set_attribute('input.value', truncate(@first_user_input)) if @first_user_input && !@first_user_input.empty?
+        return unless @first_user_input && !@first_user_input.empty?
+
+        @root_span.set_attribute('input.value', truncate(@first_user_input))
       end
 
       def handle_assistant(message)
@@ -222,7 +228,7 @@ module ClaudeAgentSDK
         end
       end
 
-      def end_trace(message)
+      def end_trace(message) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- flat mapping of optional usage/cost fields to span attributes
         return unless @root_span
 
         usage = message.usage || {}
@@ -235,7 +241,9 @@ module ClaudeAgentSDK
         # tokens (Anthropic's input_tokens excludes them; OpenInference's own
         # Anthropic instrumentation sums them in). gen_ai.usage.* keys keep
         # the raw exclusive values — Langfuse prices those additively.
-        prompt_tokens = (input_tokens || 0) + (cache_creation_tokens || 0) + (cache_read_tokens || 0) if input_tokens || cache_creation_tokens || cache_read_tokens
+        if input_tokens || cache_creation_tokens || cache_read_tokens
+          prompt_tokens = (input_tokens || 0) + (cache_creation_tokens || 0) + (cache_read_tokens || 0)
+        end
         total_tokens = (prompt_tokens || 0) + (output_tokens || 0) if prompt_tokens || output_tokens
 
         # Set trace output (last assistant response — shown in Langfuse UI)

data/lib/claude_agent_sdk/message_parser.rb

@@ -5,9 +5,11 @@ require_relative 'errors'
 
 module ClaudeAgentSDK
   # Parse message from CLI output into typed Message objects
+  #
+  # @api private
   class MessageParser
-    def self.parse(data)
-      raise MessageParseError.new("Invalid message data type", data: data) unless data.is_a?(Hash)
+    def self.parse(data) # rubocop:disable Metrics/CyclomaticComplexity -- flat dispatch over CLI message types
+      raise MessageParseError.new('Invalid message data type', data: data) unless data.is_a?(Hash)
 
       message_type = data[:type]
       raise MessageParseError.new("Message missing 'type' field", data: data) unless message_type
@@ -47,13 +49,17 @@ module ClaudeAgentSDK
       uuid = data[:uuid] # UUID for rewind support
       tool_use_result = data[:tool_use_result]
       message_data = data[:message]
-      raise MessageParseError.new("Missing message field in user message", data: data) unless message_data
+      raise MessageParseError.new('Missing message field in user message', data: data) unless message_data
       # A non-Hash message (malformed CLI output) raised a raw TypeError from
       # message_data[:content] instead of the documented MessageParseError.
-      raise MessageParseError.new("Invalid message field in user message (expected Hash, got #{message_data.class})", data: data) unless message_data.is_a?(Hash)
+      unless message_data.is_a?(Hash)
+        raise MessageParseError.new(
+          "Invalid message field in user message (expected Hash, got #{message_data.class})", data: data
+        )
+      end
 
       content = message_data[:content]
-      raise MessageParseError.new("Missing content in user message", data: data) unless content
+      raise MessageParseError.new('Missing content in user message', data: data) unless content
 
       origin = parse_origin(data)
 
@@ -85,11 +91,17 @@ module ClaudeAgentSDK
       message_data = data[:message]
       # A non-Hash message (malformed CLI output) raised a raw TypeError from
       # dig instead of the documented MessageParseError.
-      raise MessageParseError.new("Invalid message field in assistant message (expected Hash, got #{message_data.class})", data: data) unless message_data.is_a?(Hash)
+      unless message_data.is_a?(Hash)
+        raise MessageParseError.new(
+          "Invalid message field in assistant message (expected Hash, got #{message_data.class})", data: data
+        )
+      end
 
       content = message_data[:content]
-      raise MessageParseError.new("Missing content in assistant message", data: data) unless content
-      raise MessageParseError.new("Invalid assistant content (expected Array, got #{content.class})", data: data) unless content.is_a?(Array)
+      raise MessageParseError.new('Missing content in assistant message', data: data) unless content
+      unless content.is_a?(Array)
+        raise MessageParseError.new("Invalid assistant content (expected Array, got #{content.class})", data: data)
+      end
 
       content_blocks = parse_content_blocks(content, data)
       AssistantMessage.new(
@@ -194,7 +206,9 @@ module ClaudeAgentSDK
     # opaque TypeError/NoMethodError from `block[:type]` deep in parsing.
     def self.parse_content_blocks(content, data)
       content.map do |block|
-        raise MessageParseError.new("Invalid content block (expected Hash, got #{block.class})", data: data) unless block.is_a?(Hash)
+        unless block.is_a?(Hash)
+          raise MessageParseError.new("Invalid content block (expected Hash, got #{block.class})", data: data)
+        end
 
         parse_content_block(block)
       end

data/lib/claude_agent_sdk/observer.rb

@@ -39,7 +39,8 @@ module ClaudeAgentSDK
     # Client#query/#receive_messages/#receive_response/#connect (after
     # argument/configuration validation — usage errors such as 'Not
     # connected' or invalid options do not notify) — including errors raised
-    # by the user's own message block — before on_close where both fire. query() fires on_close even for connect-phase failures (its
+    # by the user's own message block — before on_close where both fire.
+    # query() fires on_close even for connect-phase failures (its
     # ensure always runs); a Client#connect failure before the handshake
     # completes fires on_error WITHOUT on_close (the session never opened).
     # Not notified (by design): errors raised by control-request methods

data/lib/claude_agent_sdk/option_warnings.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require 'set'
-
 module ClaudeAgentSDK
   # Advisory warnings for option combinations that silently change behavior.
+  #
+  # @api private
   module OptionWarnings
     @emitted = Set.new
     @mutex = Mutex.new

data/lib/claude_agent_sdk/query.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'json'
-require 'set'
 require 'async'
 require 'async/queue'
 require 'async/condition'
@@ -20,9 +19,17 @@ module ClaudeAgentSDK
   # - Tool permission callbacks
   # - Message streaming
   # - Initialization handshake
-  class Query
+  #
+  # @api private
+  class Query # rubocop:disable Metrics/ClassLength -- control-protocol hub: routing, hooks, permissions, MCP bridge
     attr_reader :transport, :is_streaming_mode, :sdk_mcp_servers
 
+    # The CLI's response to the initialize control request (nil before
+    # #initialize_protocol completes). Read by Client#server_info.
+    #
+    # @api private
+    attr_reader :initialization_result
+
     CONTROL_REQUEST_TIMEOUT_ENV_VAR = 'CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS'
     DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS = 1200.0
 
@@ -64,7 +71,7 @@ module ClaudeAgentSDK
       end
     end
 
-    def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil, agents: nil,
+    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)
@@ -133,7 +140,7 @@ module ClaudeAgentSDK
 
     # Initialize control protocol if in streaming mode
     # @return [Hash, nil] Initialize response with supported commands, or nil if not streaming
-    def initialize_protocol
+    def initialize_protocol # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- builds the initialize request from every optional option
       return nil unless @is_streaming_mode
 
       # Build hooks configuration for initialization
@@ -238,7 +245,10 @@ module ClaudeAgentSDK
       return if @task
 
       parent = Async::Task.current?
-      raise CLIConnectionError, 'Query#start must be called inside an Async{} block (e.g. wrap Client#connect in Async{...})' unless parent
+      unless parent
+        raise CLIConnectionError,
+              'Query#start must be called inside an Async{} block (e.g. wrap Client#connect in Async{...})'
+      end
 
       @owning_scheduler = Fiber.scheduler
       # Async child fibers do not inherit OTel's fiber-local current context.
@@ -271,11 +281,11 @@ module ClaudeAgentSDK
     # Fine for the current one-shot call sites (max two tasks per Query); do
     # not route per-request work (control handlers, per-turn streams) through
     # this without adding completion-based removal.
-    def spawn_task(&block)
+    def spawn_task(&)
       parent = Async::Task.current?
       raise CLIConnectionError, 'Query#spawn_task must be called inside an Async{} block' unless parent
 
-      task = parent.async(&FiberBoundary.capture_otel_context(&block))
+      task = parent.async(&FiberBoundary.capture_otel_context(&))
       @child_tasks << task
       task
     end
@@ -323,8 +333,8 @@ module ClaudeAgentSDK
       DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS
     end
 
-    def read_messages
-      @transport.read_messages do |message|
+    def read_messages # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- concurrency-sensitive read loop; kept whole on purpose
+      @transport.read_messages do |message| # rubocop:disable Metrics/BlockLength -- see read_messages
         break if @closed
 
         msg_type = message[:type]
@@ -339,14 +349,12 @@ module ClaudeAgentSDK
           # nothing keeps running after close; bare Async do may root at the
           # reactor and leak past shutdown.
           handler_task = Async::Task.current.async(&FiberBoundary.capture_otel_context do
-            begin
-              handle_control_request(message)
-            ensure
-              # Identity-guarded: if the CLI ever reused an in-flight request
-              # id, the later handler owns the slot and must stay cancellable.
-              if request_id && @inflight_control_request_tasks[request_id].equal?(Async::Task.current)
-                @inflight_control_request_tasks.delete(request_id)
-              end
+            handle_control_request(message)
+          ensure
+            # Identity-guarded: if the CLI ever reused an in-flight request
+            # id, the later handler owns the slot and must stay cancellable.
+            if request_id && @inflight_control_request_tasks[request_id].equal?(Async::Task.current)
+              @inflight_control_request_tasks.delete(request_id)
             end
           end)
           # A handler that never suspends (MCP metadata, unsupported-subtype
@@ -384,11 +392,7 @@ module ClaudeAgentSDK
               @first_result_received = true
               @first_result_condition.signal
             end
-            if message[:is_error]
-              @last_error_result = message
-            else
-              @last_error_result = nil
-            end
+            @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
             # means the conversation moved on; a ProcessError now is a fresh
@@ -534,11 +538,12 @@ module ClaudeAgentSDK
       waiter = @pending_control_responses[request_id]
       return unless waiter
 
-      if response[:subtype] == 'error'
-        @pending_control_results[request_id] = StandardError.new(response[:error] || 'Unknown error')
-      else
-        @pending_control_results[request_id] = response
-      end
+      @pending_control_results[request_id] =
+        if response[:subtype] == 'error'
+          StandardError.new(response[:error] || 'Unknown error')
+        else
+          response
+        end
 
       # Signal that response is ready. INVARIANT: the result slot above
       # MUST be written before this signal — senders check the slot before
@@ -546,7 +551,7 @@ module ClaudeAgentSDK
       waiter.signal
     end
 
-    def handle_control_request(request)
+    def handle_control_request(request) # rubocop:disable Metrics/MethodLength -- subtype dispatch plus the shared error response
       request_id = request[:request_id] || request[:requestId]
       request_data = request[:request]
       subtype = request_data[:subtype]
@@ -575,13 +580,50 @@ module ClaudeAgentSDK
         }
       }
       writeln(JSON.generate(success_response))
+      responded = true
     rescue Async::Stop
       # Cancellation requested; respond with an error so the CLI can unblock.
       send_control_error(request_id, 'Cancelled')
+    rescue SystemExit, SignalException => e
+      # exit / Interrupt / a signal raised while a user callback ran
+      # (FiberBoundary.invoke_callback re-raises it here, on the reactor) —
+      # or a real signal landing on this fiber. Never swallowed: answer the
+      # request the way an ordinary callback failure is answered, so the CLI
+      # is not left waiting, then let it terminate the process as Ruby
+      # normally would. The transport flushes every write.
+      respond_to_process_exit(request_id, request_data, e) unless responded
+      raise
     rescue StandardError => e
       send_control_error(request_id, 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.
+    def respond_to_process_exit(request_id, request_data, error)
+      message = FiberBoundary.process_exit_message(error)
+      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)
+
+      mcp_response = { jsonrpc: '2.0', id: mcp_message[:id] }
+      if mcp_message[:method] == 'tools/call'
+        mcp_response[:result] = { content: [{ type: 'text', text: message }], isError: true }
+      else
+        mcp_response[:error] = { code: -32_603, message: message }
+      end
+      writeln(JSON.generate({
+                              type: 'control_response',
+                              response: {
+                                subtype: 'success', request_id: request_id, requestId: request_id,
+                                response: { mcp_response: mcp_response }
+                              }
+                            }))
+    rescue CLIConnectionError
+      nil # the CLI is already gone; nothing is waiting for the answer
+    end
+
     def send_control_error(request_id, message)
       error_response = {
         type: 'control_response',
@@ -600,7 +642,7 @@ module ClaudeAgentSDK
       nil
     end
 
-    def handle_permission_request(request_data, request_id: nil)
+    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
 
       signal = CancellationSignal.new
@@ -608,13 +650,17 @@ module ClaudeAgentSDK
       original_input = request_data[:input]
 
       # Field order mirrors Python _internal/query.py's can_use_tool branch.
-      # Suggestions are hydrated into PermissionUpdate (Python #920); a
-      # malformed entry raises here, on the reactor, and becomes an error
-      # control_response — same observable behavior as Python.
+      # Suggestions are hydrated into PermissionUpdate (Python #920) through
+      # the lenient .wrap, so fields a newer CLI adds never trip the
+      # strict-attribute warning meant for user-built updates. A nil (or
+      # false) entry becomes an empty PermissionUpdate, as PermissionUpdate.new
+      # made it before; any other non-Hash entry raises here, on the reactor,
+      # and becomes an error control_response — same observable behavior as
+      # Python.
       context = ToolPermissionContext.new(
         signal: signal,
         request_id: request_id,
-        suggestions: (request_data[:permission_suggestions] || []).map { |s| PermissionUpdate.new(s) },
+        suggestions: (request_data[:permission_suggestions] || []).map { |s| PermissionUpdate.wrap(s || {}) },
         tool_use_id: request_data[:tool_use_id],
         agent_id: request_data[:agent_id],
         blocked_path: request_data[:blocked_path],
@@ -628,8 +674,10 @@ module ClaudeAgentSDK
       # so AR/PG calls inside it aren't intercepted by the Fiber scheduler;
       # with callback_scheduling: :inline it runs in place on this control-
       # request task, where control_cancel_request (task.stop) can actually
-      # cancel it at suspension points.
-      response = FiberBoundary.invoke(scheduling: @callback_scheduling, wrapper: @callback_wrapper) do
+      # cancel it at suspension points. exit / Interrupt from the callback
+      # re-raise here after the hop; handle_control_request answers the
+      # request before letting them propagate (FiberBoundary.invoke_callback).
+      response = FiberBoundary.invoke_callback(scheduling: @callback_scheduling, wrapper: @callback_wrapper) do
         @can_use_tool.call(request_data[:tool_name], request_data[:input], context)
       end
       # A worker may return a decision after the read loop invalidated the
@@ -643,9 +691,7 @@ module ClaudeAgentSDK
           behavior: 'allow',
           updatedInput: response.updated_input || original_input
         }
-        if response.updated_permissions
-          result[:updatedPermissions] = response.updated_permissions.map(&:to_h)
-        end
+        result[:updatedPermissions] = response.updated_permissions.map(&:to_h) if response.updated_permissions
         result
       when PermissionResultDeny
         result = { behavior: 'deny', message: response.message }
@@ -661,7 +707,7 @@ module ClaudeAgentSDK
       untrack_callback_signal(request_id, signal)
     end
 
-    def handle_hook_callback(request_data, request_id: nil)
+    def handle_hook_callback(request_data, request_id: nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- hook round-trip: timeout, callback, output conversion
       callback_id = request_data[:callback_id]
       callback = @hook_callbacks[callback_id]
       raise "No hook callback found for ID: #{callback_id}" unless callback
@@ -684,8 +730,11 @@ module ClaudeAgentSDK
       # genuine cooperative cancellation: the hook is interrupted at its next
       # suspension point and its ensure blocks run (Python parity — anyio
       # cancels the coroutine). A CPU-stuck inline hook cannot be timed out.
+      # All three variants go through FiberBoundary.invoke_callback, so exit
+      # / Interrupt from the hook reach handle_control_request, which answers
+      # the request before letting them propagate.
       unless @hook_callback_timeouts[callback_id]
-        hook_output = FiberBoundary.invoke(scheduling: @callback_scheduling, wrapper: @callback_wrapper) do
+        hook_output = FiberBoundary.invoke_callback(scheduling: @callback_scheduling, wrapper: @callback_wrapper) do
           callback.call(hook_input, request_data[:tool_use_id], context)
         end
       end
@@ -709,13 +758,13 @@ module ClaudeAgentSDK
               Async::Task.current, timeout,
               on_timeout: -> { Async::TimeoutError.new('execution expired') }
             ) do
-              FiberBoundary.invoke(scheduling: :inline, wrapper: @callback_wrapper) do
+              FiberBoundary.invoke_callback(scheduling: :inline, wrapper: @callback_wrapper) do
                 callback.call(hook_input, request_data[:tool_use_id], context)
               end
             end
           else
             Async::Task.current.with_timeout(timeout) do
-              FiberBoundary.invoke(wrapper: @callback_wrapper) do
+              FiberBoundary.invoke_callback(wrapper: @callback_wrapper) do
                 callback.call(hook_input, request_data[:tool_use_id], context)
               end
             end
@@ -743,7 +792,7 @@ module ClaudeAgentSDK
       @callback_request_signals.delete(request_id)
     end
 
-    def parse_hook_input(input_data)
+    def parse_hook_input(input_data) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength -- one branch per hook event type
       event_name = input_data[:hook_event_name] || input_data['hook_event_name']
       fetch = lambda do |key|
         if input_data.key?(key)
@@ -976,11 +1025,9 @@ module ClaudeAgentSDK
       { mcp_response: mcp_response }
     end
 
-    def convert_hook_output_for_cli(hook_output)
+    def convert_hook_output_for_cli(hook_output) # rubocop:disable Metrics/CyclomaticComplexity -- one optional field per hook output key
       # Handle typed output objects
-      if hook_output.respond_to?(:to_h) && !hook_output.is_a?(Hash)
-        return hook_output.to_h
-      end
+      return hook_output.to_h if hook_output.respond_to?(:to_h) && !hook_output.is_a?(Hash)
 
       return {} unless hook_output.is_a?(Hash)
 
@@ -1094,7 +1141,7 @@ module ClaudeAgentSDK
       end
     end
 
-    def handle_sdk_mcp_request(server_name, message)
+    def handle_sdk_mcp_request(server_name, message) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength -- JSON-RPC method dispatch for SDK MCP servers
       # Carry this session's scheduling mode and callback wrapper across the
       # dispatch into the (possibly session-shared) SdkMcpServer via fiber
       # storage — set on the dispatching fiber, read back by the server's
@@ -1121,7 +1168,7 @@ module ClaudeAgentSDK
           jsonrpc: '2.0',
           id: message[:id],
           error: {
-            code: -32601,
+            code: -32_601,
             message: "Server '#{server_name}' not found"
           }
         }
@@ -1152,14 +1199,14 @@ module ClaudeAgentSDK
         {
           jsonrpc: '2.0',
           id: message[:id],
-          error: { code: -32601, message: "Method '#{method}' not found" }
+          error: { code: -32_601, message: "Method '#{method}' not found" }
         }
       end
     rescue StandardError => e
       {
         jsonrpc: '2.0',
         id: message[:id],
-        error: { code: -32603, message: e.message }
+        error: { code: -32_603, message: e.message }
       }
     ensure
       dispatch_scope&.close
@@ -1388,6 +1435,7 @@ module ClaudeAgentSDK
       wrote_message = false
       stream.each do |message|
         break if @closed
+
         serialized = message.is_a?(Hash) ? JSON.generate(message) : message.to_s
         writeln(serialized)
         wrote_message = true