claude-agent-sdk 0.33.0 → 0.34.0

data/lib/claude_agent_sdk/command_builder.rb

@@ -373,7 +373,7 @@ module ClaudeAgentSDK
     end
 
     # `--thinking-display` toggles between `"summarized"` (visible thinking
-    # text) and `"omitted"` (empty thinking, signature only). Opus 4.7 defaults
+    # text) and `"omitted"` (empty thinking, signature only). Current models default
     # to `"omitted"`, so pass `display: "summarized"` to see reasoning.
     def append_thinking_display(cmd, display)
       return if display.nil?
@@ -444,8 +444,12 @@ module ClaudeAgentSDK
           # Typed Mcp*ServerConfig objects serialize via their wire hash —
           # without this they'd JSON-stringify as "#<...>" via to_s.
           config = config.to_h if config.is_a?(Type)
-          servers_for_cli[name] = if config.is_a?(Hash) && config[:type] == "sdk"
-                                    config.except(:instance)
+          # Same recognition rule as ClaudeAgentSDK.extract_sdk_mcp_servers:
+          # either key style (and a Symbol :sdk type). The live instance is
+          # never serialized — JSON.generate would raise on it or leak its
+          # #to_s onto the command line.
+          servers_for_cli[name] = if config.is_a?(Hash) && (config[:type] || config["type"]).to_s == "sdk"
+                                    config.except(:instance, "instance")
                                   else
                                     config
                                   end
@@ -506,6 +510,10 @@ module ClaudeAgentSDK
     end
 
     def load_settings_file(path)
+      # Match the CLI's path resolution when --settings is passed through
+      # without a sandbox merge: the subprocess runs in options.cwd.
+      # Do not expand lexically: symlink/.. must resolve through the filesystem.
+      path = File.join(@options.cwd&.to_s || Dir.pwd, path) unless File.absolute_path?(path)
       # Missing file: warn and continue with sandbox-only settings (Python
       # parity: logger.warning("Settings file not found: ...") and an empty
       # settings object). Raising here turned a misconfiguration the CLI

data/lib/claude_agent_sdk/configuration.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# default_options= copies through Type.deep_dup_for_options: keep this file
+# loadable on its own (require 'claude_agent_sdk/configuration').
+require_relative 'types'
+
 module ClaudeAgentSDK
   # Configuration class for setting default options
   #
@@ -28,11 +32,59 @@ module ClaudeAgentSDK
   #     prompt: "Hello!",
   #     options: ClaudeAgentOptions.new(model: 'opus')  # overrides default
   #   )
+  #
+  # Assignment stores a frozen deep copy of the Hash (containers, typed
+  # option values such as SandboxSettings, and mutable Strings are copied;
+  # procs, observers, SDK MCP server instances and store adapters keep
+  # identity). To change the defaults, assign a new Hash — in-place mutation
+  # of the stored one (including `<<` on one of its Strings) raises
+  # FrozenError, and later changes to the Hash or Strings you passed in have
+  # no effect.
   class Configuration
-    attr_accessor :default_options
+    # The configured defaults: a frozen snapshot (see class docs).
+    #
+    # @return [Hash]
+    attr_reader :default_options
+
+    EMPTY_DEFAULTS = {}.freeze
+    private_constant :EMPTY_DEFAULTS
 
     def initialize
-      @default_options = {}
+      @default_options = EMPTY_DEFAULTS
+    end
+
+    # The defaults are read at request time by every ClaudeAgentOptions.new
+    # (merge_with_defaults) with no lock, possibly from many threads at once.
+    # A live, caller-owned Hash made that a race: an in-place write from one
+    # thread while another iterated the merge raised "can't add a new key
+    # into hash during iteration" or tore the read. Storing a private frozen
+    # snapshot removes the shared mutable state instead of guarding it — the
+    # ivar swap is atomic, a reader only ever sees a complete Hash, and an
+    # in-place write fails loudly. Only the copy is frozen: the caller's
+    # Hash and objects, and identity leaves, are left untouched.
+    #
+    # @param value [Hash, nil] nil clears the defaults
+    def default_options=(value)
+      @default_options = value.nil? ? EMPTY_DEFAULTS : deep_freeze(Type.deep_dup_for_options(value))
+    end
+
+    private
+
+    # Mirrors Type.deep_dup_for_options' recursion: freeze the containers,
+    # option value copies and String copies it produced (and their nested
+    # state), never a leaf it returned by identity — freezing an
+    # SdkMcpServer or a store adapter would break it. A String reaching here
+    # is either the copier's own copy or was already frozen, so freezing it
+    # never touches a caller's mutable String.
+    def deep_freeze(value)
+      case value
+      when Hash then value.each_value { |v| deep_freeze(v) }
+      when Array then value.each { |v| deep_freeze(v) }
+      when Type::OptionValue then value.instance_variables.each { |ivar| deep_freeze(value.instance_variable_get(ivar)) }
+      when String then nil # nothing nested; fall through to freeze the copy
+      else return value
+      end
+      value.freeze
     end
   end
 

data/lib/claude_agent_sdk/errors.rb

@@ -129,6 +129,15 @@ module ClaudeAgentSDK
 
         data.key?(key) ? data[key] : data[key.to_s]
       end
+
+      # The +api_error_status+ field narrowed to Integer-or-nil — the one
+      # narrowing both #api_error_status and .error_text read, so a "500"
+      # String can neither show up in the message nor go missing from the
+      # accessor on its own.
+      def api_error_status(data)
+        status = field(data, :api_error_status)
+        status.is_a?(Integer) ? status : nil
+      end
     end
     private_constant :Payload
 
@@ -158,7 +167,7 @@ module ClaudeAgentSDK
       subtype = Payload.field(data, :subtype)
       return subtype if subtype.is_a?(String) && !subtype.empty? && subtype != 'success'
 
-      status = Payload.field(data, :api_error_status)
+      status = Payload.api_error_status(data)
       return "API error (HTTP #{status})" unless status.nil?
 
       'unknown error'
@@ -174,8 +183,7 @@ module ClaudeAgentSDK
       @errors = Payload.normalize_errors(Payload.field(data, :errors))
       result = Payload.field(data, :result)
       @result = result.is_a?(String) ? result : nil
-      status = Payload.field(data, :api_error_status)
-      @api_error_status = status.is_a?(Integer) ? status : nil
+      @api_error_status = Payload.api_error_status(data)
       reason = Payload.field(data, :terminal_reason)
       @terminal_reason = reason.is_a?(String) ? reason : nil
       session_id = Payload.field(data, :session_id)

data/lib/claude_agent_sdk/fiber_boundary.rb

@@ -52,7 +52,10 @@ module ClaudeAgentSDK
   # reactor; a declared-inline adapter accepts that a scheduler-opaque
   # blocking call would stall it AND escape the cooperative deadline.
   # Outside a reactor the hard bound applies even to inline-declared
-  # adapters — the timeout guarantee is never lost.
+  # adapters — the timeout guarantee is never lost. Even inside one, the
+  # cooperative deadline only bounds the cancellation request: cleanup in
+  # the cancelled block's ensure runs unbounded afterwards (see
+  # .with_cooperative_timeout).
   #
   # The thread hop severs `break`/`return`/`next` from the surrounding method,
   # so SDK loops yielding user callbacks must keep loop control outside the
@@ -141,6 +144,19 @@ module ClaudeAgentSDK
 
     module_function
 
+    # 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
+    # returned block activates this context on its destination and restores
+    # the destination's prior context even when the operation raises.
+    # @api private
+    def capture_otel_context(&block)
+      return block unless defined?(OpenTelemetry::Context) && OpenTelemetry::Context.respond_to?(:current)
+
+      context = OpenTelemetry::Context.current
+      proc { |*args| OpenTelemetry::Context.with_current(context) { block.call(*args) } }
+    end
+
     # Run the given block on a plain thread when a Fiber scheduler is active.
     # Returns the block's value. Exceptions propagate to the caller.
     #
@@ -199,8 +215,15 @@ module ClaudeAgentSDK
         return with_cooperative_timeout(task, timeout, on_timeout: expired) { body.call }
       end
 
-      thread = Thread.new(&body)
-      thread.report_on_exception = false
+      work = capture_otel_context(&body)
+      thread = Thread.new do
+        # The caller re-raises the failure via #value, so the default report
+        # would be a duplicate stderr dump. Set as the thread's FIRST
+        # statement: assigning it from the caller after Thread.new races a
+        # body that raises before the caller gets scheduled again.
+        Thread.current.report_on_exception = false
+        work.call
+      end
       return thread.value if timeout.nil?
       raise JoinTimeout, "timed out after #{timeout}s" unless thread.join(timeout)
 
@@ -227,6 +250,22 @@ module ClaudeAgentSDK
     # Wrapper composition is the caller's choice — +block+ runs verbatim
     # inside the timeout scope (.invoke composes the callback wrapper into
     # its body beforehand; the hook path composes it inside the block).
+    #
+    # CONTRACT: the deadline bounds the cancellation REQUEST, not the
+    # block's completion (issue #71). The cancellation is delivered exactly
+    # once, at the block's next suspension point; from there the block's
+    # rescue/ensure clauses run to completion on the reactor fiber with no
+    # further deadline, and +on_timeout+ is raised only after they return.
+    # Fiber-aware cleanup (scheduler-visible IO, sleep, Async primitives)
+    # delays just this callback and whoever awaits it — siblings keep
+    # running. Scheduler-opaque cleanup — file fsync, non-fiber-aware
+    # drivers, a GVL-holding C extension — stalls the whole reactor for its
+    # duration, and no deadline can interrupt it. Deliberately not "fixed":
+    # a live fiber stack cannot be migrated to a thread, and a second
+    # deadline could only interrupt cooperative cleanup (abandoning locks /
+    # transactions) while still not touching opaque blocking. Callers that
+    # 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)
       cancellation = Class.new(InlineCancellation)

data/lib/claude_agent_sdk/instrumentation/otel.rb

@@ -53,6 +53,8 @@ module ClaudeAgentSDK
         @first_user_input = nil # first user prompt of the current trace
         @pending_prompt = nil # prompt that belongs to the NEXT trace (see on_user_prompt)
         @last_assistant_text = nil # capture last assistant text for trace output
+        @cost_session_id = nil
+        @last_total_cost_usd = nil
       end
 
       def on_user_prompt(prompt)
@@ -116,6 +118,8 @@ module ClaudeAgentSDK
         # end_trace/supersede resets by design — but the session is over now,
         # and a reused observer must not leak it into the next session.
         @pending_prompt = nil
+        @cost_session_id = nil
+        @last_total_cost_usd = nil
       end
 
       private
@@ -237,10 +241,11 @@ module ClaudeAgentSDK
         # Set trace output (last assistant response — shown in Langfuse UI)
         # ResultMessage.result has the final text; fall back to last tracked assistant text
         trace_output = message.result || @last_assistant_text
+        cost = cost_since_last_result(message)
 
         attrs = {
           # gen_ai conventions
-          'gen_ai.usage.cost' => message.total_cost_usd,
+          'gen_ai.usage.cost' => cost,
           # OpenInference conventions (Langfuse maps these to usage/cost);
           # prompt includes cache tokens so prompt_details.* are true subsets
           'llm.token_count.prompt' => prompt_tokens,
@@ -249,7 +254,7 @@ module ClaudeAgentSDK
           # OpenInference prompt-cache breakdown (cache_read/cache_write details)
           'llm.token_count.prompt_details.cache_read' => cache_read_tokens,
           'llm.token_count.prompt_details.cache_write' => cache_creation_tokens,
-          'llm.cost.total' => message.total_cost_usd,
+          'llm.cost.total' => cost,
           # Trace output (Langfuse shows this in the trace detail view)
           'output.value' => truncate(trace_output),
           # Session metadata
@@ -270,6 +275,20 @@ module ClaudeAgentSDK
         reset_session_buffers
       end
 
+      # Results carry cumulative cost, but each init/result pair gets its
+      # own span. Keep this baseline across trace resets, not across close.
+      # /clear changes the session ID; a decreasing counter also starts a
+      # new baseline. Missing costs leave the last known total intact.
+      def cost_since_last_result(message)
+        total = message.total_cost_usd
+        return if total.nil?
+
+        previous = @last_total_cost_usd if @cost_session_id == message.session_id
+        @cost_session_id = message.session_id
+        @last_total_cost_usd = total
+        previous && total >= previous ? total - previous : total
+      end
+
       def start_tool_span(block)
         return unless @root_context
 

data/lib/claude_agent_sdk/query.rb

@@ -6,6 +6,7 @@ require 'async'
 require 'async/queue'
 require 'async/condition'
 require 'securerandom'
+require 'timeout'
 require_relative 'transport'
 require_relative 'errors'
 require_relative 'cancellation_signal'
@@ -89,6 +90,7 @@ module ClaudeAgentSDK
       @next_callback_id = 0
       @request_counter = 0
       @request_counter_mutex = Mutex.new
+      @control_stream_error = nil
       @inflight_control_request_tasks = {}
       @callback_request_signals = {}
 
@@ -239,7 +241,8 @@ module ClaudeAgentSDK
       raise CLIConnectionError, 'Query#start must be called inside an Async{} block (e.g. wrap Client#connect in Async{...})' unless parent
 
       @owning_scheduler = Fiber.scheduler
-      @task = parent.async { read_messages }
+      # Async child fibers do not inherit OTel's fiber-local current context.
+      @task = parent.async(&FiberBoundary.capture_otel_context { read_messages })
       # 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
@@ -247,7 +250,7 @@ module ClaudeAgentSDK
       # 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.
-      @close_watcher = parent.async(transient: true) do
+      @close_watcher = parent.async(transient: true, &FiberBoundary.capture_otel_context do
         if (reply = @close_requests.pop)
           begin
             close
@@ -255,7 +258,7 @@ module ClaudeAgentSDK
             reply << true
           end
         end
-      end
+      end)
     end
 
     # Spawn a child task that is stopped by #close (mirrors the Python SDK's
@@ -272,7 +275,7 @@ module ClaudeAgentSDK
       parent = Async::Task.current?
       raise CLIConnectionError, 'Query#spawn_task must be called inside an Async{} block' unless parent
 
-      task = parent.async(&block)
+      task = parent.async(&FiberBoundary.capture_otel_context(&block))
       @child_tasks << task
       task
     end
@@ -335,7 +338,7 @@ module ClaudeAgentSDK
           # Spawn as a child of the current task so @task.stop cascades and
           # nothing keeps running after close; bare Async do may root at the
           # reactor and leak past shutdown.
-          handler_task = Async::Task.current.async do
+          handler_task = Async::Task.current.async(&FiberBoundary.capture_otel_context do
             begin
               handle_control_request(message)
             ensure
@@ -345,7 +348,7 @@ module ClaudeAgentSDK
                 @inflight_control_request_tasks.delete(request_id)
               end
             end
-          end
+          end)
           # A handler that never suspends (MCP metadata, unsupported-subtype
           # error path) already ran to completion inside the async{} above —
           # its ensure-delete fired before this insert, so registering it here
@@ -413,24 +416,21 @@ module ClaudeAgentSDK
                 e
               end
 
-      # Unblock pending control requests (e.g., initialize) so callers don't
-      # hang until timeout. Computed AFTER the replacement above so they get
-      # the same enriched error the message stream does: a refused resume (a
-      # nonexistent session, a failed --resume-drops-turn guard) is reported
-      # by the CLI as an error result followed by exit 1 *before* it answers
-      # the SDK's `initialize`, so signaling the raw `e` here handed that
-      # in-flight request "Command failed with exit code 1" and discarded the
-      # real reason (Python #1198).
-      # INVARIANT: store the result before signaling — senders check the slot
-      # before waiting (level-trigger).
-      @pending_control_responses.dup.each do |request_id, condition|
-        @pending_control_results[request_id] ||= error
-        condition.signal
-      end
-
       # Put error in queue so iterators can handle it
       @message_queue.enqueue({ type: 'error', error: error })
     ensure
+      # EOF is terminal for control requests even when the message stream
+      # ends successfully. Serialize terminal publication with registration:
+      # every sender is either in this snapshot or rejected before writing.
+      # Preserve enriched ResultError from the rescue path (Python #1198).
+      waiters = @request_counter_mutex.synchronize do
+        @control_stream_error = error || CLIConnectionError.new('Control stream ended')
+        @pending_control_responses.dup
+      end
+      waiters.each do |request_id, condition|
+        @pending_control_results[request_id] ||= @control_stream_error
+        condition.signal
+      end
       # A callback can no longer be answered after EOF, transport failure,
       # or reactor cancellation. Wake cooperative worker-thread callbacks too.
       @callback_request_signals.dup.each_value(&:cancel)
@@ -1022,18 +1022,19 @@ module ClaudeAgentSDK
       # RuntimeError; the eventual response dropped by the key? guard).
       task = Async::Task.current?
 
-      # Generate unique request ID (callbacks may issue requests from
-      # worker threads concurrently with the reactor)
+      # 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
       request_id = @request_counter_mutex.synchronize do
+        raise @control_stream_error if @control_stream_error
+
         @request_counter += 1
-        "req_#{@request_counter}_#{SecureRandom.hex(4)}"
+        id = "req_#{@request_counter}_#{SecureRandom.hex(4)}"
+        @pending_control_responses[id] = waiter
+        id
       end
 
-      # Reactor callers wait on an Async::Condition; worker-thread callers
-      # on a ThreadWaiter. Registration must precede the write.
-      waiter = task ? Async::Condition.new : ThreadWaiter.new
-      @pending_control_responses[request_id] = waiter
-
       control_request = {
         type: 'control_request',
         request_id: request_id,
@@ -1041,20 +1042,18 @@ module ClaudeAgentSDK
         request: request
       }
 
-      writeln(JSON.generate(control_request))
-
-      begin
-        await_control_response(request_id, waiter, task, timeout_seconds, request[:subtype])
-        result = @pending_control_results[request_id]
-        raise result if result.is_a?(Exception)
-
-        result&.[](:response) || {}
-      ensure
-        # Always evict the entries so a late control_response (after timeout)
-        # or an Async::Stop propagating through wait does not leak state.
-        @pending_control_responses.delete(request_id)
-        @pending_control_results.delete(request_id)
+      await_control_response(request_id, waiter, task, timeout_seconds, request[:subtype]) do
+        writeln(JSON.generate(control_request))
       end
+      result = @pending_control_results[request_id]
+      raise result if result.is_a?(Exception)
+
+      result&.[](:response) || {}
+    ensure
+      # Registration, serialization, write and wait share one cleanup scope.
+      # In particular, failed or cancelled writes never retain a waiter.
+      @pending_control_responses.delete(request_id)
+      @pending_control_results.delete(request_id)
     end
 
     # Level-triggered wait: every signal site stores the result BEFORE
@@ -1068,22 +1067,29 @@ module ClaudeAgentSDK
     # Do NOT reimplement the reactor wait as a nested `Async do ... end.wait`
     # — that spawned a separate task and leaked the pending entries when an
     # Async::Stop propagated through `.wait` before cleanup ran.
+    # The yielded send runs inside the same deadline as the response wait.
     def await_control_response(request_id, waiter, task, timeout_seconds, subtype)
+      expired = -> { ControlRequestTimeoutError.new("Control request timeout: #{subtype}") }
       if task
-        begin
-          task.with_timeout(timeout_seconds) do
-            waiter.wait until @pending_control_results.key?(request_id)
-          end
-        rescue Async::TimeoutError
-          raise ControlRequestTimeoutError, "Control request timeout: #{subtype}"
+        # A non-StandardError deadline escapes the transport's write rescue;
+        # 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)
         end
       else
-        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds
-        until @pending_control_results.key?(request_id)
-          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          raise ControlRequestTimeoutError, "Control request timeout: #{subtype}" if remaining <= 0
-
-          waiter.wait(remaining)
+        # Only schedulerless callers use stdlib Timeout. A fresh, private
+        # non-StandardError deadline bypasses transport write rescues without
+        # relabeling a transport's own Timeout::Error or an outer deadline.
+        # Interrupt the caller rather than abandoning a still-writing worker.
+        cancellation = Class.new(Exception) # rubocop:disable Lint/InheritException -- cancellation must bypass transport rescues
+        begin
+          Timeout.timeout(timeout_seconds, cancellation) do
+            yield
+            waiter.wait(nil) until @pending_control_results.key?(request_id)
+          end
+        rescue cancellation
+          raise expired.call
         end
       end
     end
@@ -1195,9 +1201,12 @@ module ClaudeAgentSDK
       # server validates arguments against the tool's inputSchema BEFORE the
       # handler runs and reports validation failures, unknown tools, and
       # handler exceptions as in-band isError results). tools/list,
-      # initialize, resources/* and prompts/* stay on the SDK paths — the
-      # gem drops annotations/_meta from tools/list and negotiates newer
-      # protocol versions.
+      # initialize, resources/* and prompts/* stay on the SDK paths: the
+      # gem's tools/list injects "$schema" and drops `required: []` (and
+      # would advertise the empty fallback schema where the SDK advertises
+      # the user's own), and its initialize negotiates newer protocol
+      # versions and advertises prompts/resources/logging even for a
+      # tools-only server. Annotations/_meta do survive the gem path.
       server.handle_message(message)
     end
 
@@ -1509,6 +1518,53 @@ module ClaudeAgentSDK
       # Final mirror flush BEFORE stopping the read task, so the last turn's
       # entries reach the store. #close on the batcher never raises.
       @transcript_mirror_batcher&.close
+      # A close can be called from inside one of the tasks it stops:
+      #   - an inline callback (callback_scheduling: :inline) runs on a
+      #     control-request handler task that is a CHILD of the read task,
+      #     so the read task's unwind (`stopped!` -> `stop_children`)
+      #     cascades straight back into this fiber as Async::Stop from
+      #     inside `@task.stop` (issue #81);
+      #   - a streaming-input enumerator is iterated ON the reactor inside
+      #     a spawn_task child tracked in @child_tasks, so
+      #     `@child_tasks.each(&:stop)` stops the CURRENT task — a direct
+      #     raise (Async::Task#stop on `current?`), no cascade needed.
+      # Either way the Stop used to unwind close_now before the transport
+      # and @close_requests were closed. `defer_stop` makes both the
+      # cascade and the self-stop set a flag instead of raising
+      # (Async::Task#stop checks the deferral before the current?/deliver
+      # branch), so the whole teardown section runs to completion; the
+      # deferred stop is then raised on exit of the block, after the
+      # invariant "close returned/raised => transport closed, waiters
+      # released, close requests closed" already holds. The caller's task
+      # still ends — it belongs to a stopped tree — so its Client#disconnect
+      # 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.
+      #
+      # The deferred Stop SUPERSEDES anything the teardown raises: async
+      # raises it from defer_stop's ensure with an explicit `cause:`, so a
+      # transport #close error would vanish from the chain entirely. Warn
+      # before it is lost. (An inline hook's cooperative timeout landing
+      # while the teardown is suspended is superseded the same way; harmless,
+      # the handler is ending anyway.)
+      if (caller_task = task_inside_stopped_trees)
+        caller_task.defer_stop do
+          stop_tasks_and_close_transport
+        rescue StandardError => e
+          warn "Claude SDK: close from inside a stopping task failed during teardown: #{e.class}: #{e.message}"
+          raise
+        end
+      else
+        stop_tasks_and_close_transport
+      end
+    end
+
+    # The teardown section that must run to completion once the read and
+    # child tasks are being stopped — see close_now for why a caller inside
+    # one of their trees wraps it in defer_stop.
+    def stop_tasks_and_close_transport
       # Stop tracked child tasks (e.g. stream_input) before the read task and
       # transport so a parked input stream can never keep the reactor alive
       # (mirrors Python close() cancelling _child_tasks).
@@ -1526,11 +1582,39 @@ module ClaudeAgentSDK
 
         warn "Claude SDK: skipped stopping tasks during off-reactor close: #{e.message}"
       end
-      @transport.close
-      # Release a still-parked close watcher: pop returns nil and it exits
-      # without serving. Any foreign-thread close arriving after this point
-      # falls back to a direct close (safe — the fibers are now dead).
-      @close_requests.close
+      begin
+        @transport.close
+      ensure
+        # Release a still-parked close watcher: pop returns nil and it exits
+        # without serving. Any foreign-thread close arriving after this point
+        # falls back to a direct close (safe — the fibers are now dead).
+        # In the ensure because transport.close can suspend (process reap)
+        # and a deadline delivered there — e.g. an inline hook's cooperative
+        # timeout, which defer_stop does not cover — must not strand the
+        # watcher; this close has no suspension point of its own.
+        @close_requests.close
+      end
+    end
+
+    # The current Async task when it is one of the tasks close_now stops —
+    # the read task or a tracked child task (stream_input) — or a descendant
+    # of one (a control-request handler running an inline callback); nil
+    # otherwise, including on a foreign thread (no task) and for the close
+    # watcher / connect task, which are siblings of those tasks.
+    def task_inside_stopped_trees
+      task = Async::Task.current?
+      return nil unless task
+
+      roots = [@task, *@child_tasks].compact
+      return nil if roots.empty?
+
+      node = task
+      while node
+        return task if roots.any? { |root| root.equal?(node) }
+
+        node = node.parent
+      end
+      nil
     end
 
     # Hand the close to the reactor and wait for completion. Polls watcher