claude-agent-sdk 0.33.0 → 0.34.0

data/lib/claude_agent_sdk/transcript_mirror_batcher.rb

@@ -18,6 +18,12 @@ module ClaudeAgentSDK
   # background flush). This keeps adapter latency off the hot path during
   # model streaming.
   #
+  # At most ONE background drain task is live at a time. Frames arriving
+  # while it is busy stay in the pending buffer, and the drainer picks them up
+  # as one coalesced append when its current one completes — so a store slower
+  # than the frame rate costs buffered entries, never a task (plus detached
+  # batch) per frame, and #enqueue never suspends the read loop.
+  #
   # Adapter failures are retried (MIRROR_APPEND_MAX_ATTEMPTS total) with short
   # backoff; timeouts are not retried since the in-flight call may still land.
   # Failures never raise — the local-disk transcript is already durable, so the
@@ -25,17 +31,19 @@ module ClaudeAgentSDK
   # (which surfaces them as a MirrorErrorMessage). Adapters should dedupe by
   # entry["uuid"] when present, since a retried batch may overlap a prior write.
   #
-  # The semaphore serializes appends, but a #send that exceeds send_timeout is
-  # abandoned (its worker thread keeps running) and the next drain proceeds, so
-  # two #append calls for the SAME key can briefly overlap. SessionStore#append
-  # must be thread-safe per key (see that method's contract). For adapters
-  # declaring `callback_scheduling -> :inline` the timed-out call is instead
-  # cancelled cooperatively (interrupted at its next suspension point, ensure
-  # runs) — but only on the adapter's own fiber; work the adapter offloaded
-  # may still land, so timeouts are not retried in either mode and the
-  # cancelled append may remain permanently HALF-applied in the store. The
-  # drop is surfaced (MirrorErrorMessage, batches_dropped?); the local
-  # transcript remains the source of truth.
+  # The semaphore serializes appends (FIFO, and every drain detaches its batch
+  # immediately before queueing on it, so append order matches enqueue order),
+  # but a #send that exceeds send_timeout is abandoned (its worker thread keeps
+  # running) and the next drain proceeds, so two #append calls for the SAME
+  # key can briefly overlap. SessionStore#append must be thread-safe per key
+  # (see that method's contract). For adapters declaring
+  # `callback_scheduling -> :inline` the timed-out call is instead cancelled
+  # cooperatively (interrupted at its next suspension point, ensure runs) —
+  # but only on the adapter's own fiber; work the adapter offloaded may still
+  # land, so timeouts are not retried in either mode and the cancelled append
+  # may remain permanently HALF-applied in the store. The drop is surfaced
+  # (MirrorErrorMessage, batches_dropped?); the local transcript remains the
+  # source of truth.
   class TranscriptMirrorBatcher
     # Eager-flush thresholds (exposed for tests).
     MAX_PENDING_ENTRIES = 500
@@ -72,6 +80,12 @@ module ClaudeAgentSDK
       @pending = []
       @pending_entries = 0
       @pending_bytes = 0
+      # True while the background drain task is live; #enqueue spawns another
+      # only once it has exited (see #schedule_background_drain).
+      @background_drain_live = false
+      # Set when #close starts; from then on anything still in @pending counts
+      # as dropped (see #batches_dropped?).
+      @closed = false
       # Batches that exhausted retries (or could not be keyed) and never
       # reached the store. Written only under @lock; read cross-thread by
       # #batches_dropped? (a plain Integer read is safe under the GVL).
@@ -86,12 +100,24 @@ module ClaudeAgentSDK
     # mirror copy is incomplete. Consulted at teardown by the resume-from-store
     # cleanup so the materialized temp dir (which then holds the only copy of
     # the dropped turns) is preserved instead of deleted.
+    #
+    # Frames still buffered once #close has started count too. Query#close
+    # stops the read task (the background drainer's parent) right after
+    # #close returns, so a frame the read loop enqueued during the close
+    # window — or any below-threshold frame after it — is never appended.
+    # The old per-frame drain detached it into a parked task whose
+    # cancellation counted it; with coalescing it stays in @pending, so it is
+    # accounted here. Evaluated lazily: frames the drainer still manages to
+    # deliver before the check are not drops, and nothing past #close has to
+    # run for a stranded frame to be counted. (A plain ivar/Array#empty? read
+    # is safe cross-thread under the GVL, like @dropped_batches.)
     def batches_dropped?
-      @dropped_batches.positive?
+      @dropped_batches.positive? || (@closed && !@pending.empty?)
     end
 
     # Buffer a frame; schedule an eager background flush if thresholds are
-    # exceeded. Synchronous and fire-and-forget.
+    # exceeded and no background drain is already live (a live one will pick
+    # this frame up). Synchronous and fire-and-forget.
     #
     # +entries+ are deep-stringified because the transport parses CLI output
     # with symbolized keys, but SessionStore entries are opaque JSON blobs that
@@ -109,12 +135,10 @@ module ClaudeAgentSDK
       @pending << { file_path: file_path, entries: entries }
       @pending_entries += entries.length
       @pending_bytes += size
-      return unless @pending_entries > @max_pending_entries || @pending_bytes > @max_pending_bytes
+      return unless over_threshold?
 
       task = Async::Task.current?
-      # Fire-and-forget on the reactor; @lock in #drain serializes against any
-      # in-flight flush so append ordering holds. #drain never raises.
-      task ? task.async { drain } : drain
+      task ? schedule_background_drain(task) : drain
     end
 
     # Flush all pending entries, serialized after any in-flight eager flush.
@@ -122,8 +146,11 @@ module ClaudeAgentSDK
       drain
     end
 
-    # Final flush before teardown. Never raises.
+    # Final flush before teardown. Never raises. Bounded: it waits behind at
+    # most the in-flight append, and frames arriving after it detached are
+    # not chased (they count as dropped unless delivered; #batches_dropped?).
     def close
+      @closed = true
       flush
     rescue StandardError => e
       warn "Claude SDK: TranscriptMirrorBatcher close flush failed: #{e.message}"
@@ -131,6 +158,38 @@ module ClaudeAgentSDK
 
     private
 
+    def over_threshold?
+      @pending_entries > @max_pending_entries || @pending_bytes > @max_pending_bytes
+    end
+
+    # Fire-and-forget on the reactor. The drainer loops until the buffer is
+    # back under the thresholds, so while it is live every later frame is
+    # simply buffered and coalesced into its next #drain — live background
+    # tasks <= 1 and detached batches <= 1 + one per #flush / #close caller
+    # parked on @lock, independent of frame rate and store latency.
+    #
+    # No lost wakeup: the loop's final over_threshold? check and the ensure
+    # clearing the flag run with no suspension point between them, so an
+    # #enqueue that saw the flag set is always observed by that check.
+    # Every drainer (this one, #flush, #close) keeps detach-then-acquire, so
+    # detach order == @lock FIFO order and append ordering holds. #drain
+    # never raises.
+    def schedule_background_drain(task)
+      return if @background_drain_live
+
+      @background_drain_live = true
+      task.async do
+        drain while over_threshold?
+      ensure
+        @background_drain_live = false
+      end
+    rescue StandardError
+      # Task#async raises synchronously (e.g. FinishedError) before the block
+      # runs; don't let a stuck flag disable background drains for good.
+      @background_drain_live = false
+      raise
+    end
+
     # Detach the pending buffer, await any prior flush, then send. Detaching
     # before acquiring the lock lets #enqueue keep accumulating into a fresh
     # buffer while a prior flush is in flight. Never raises.

data/lib/claude_agent_sdk/types.rb

@@ -9,7 +9,7 @@ module ClaudeAgentSDK
 
   # Effort levels for `ClaudeAgentOptions#effort`. The CLI (Claude Code 2.1.111+)
   # accepts these values; the set of *supported* levels is model-dependent
-  # (e.g. `xhigh` is only supported on Opus 4.7 and falls back to `high` on
+  # (e.g. `xhigh` arrived with Opus 4.7 and falls back to `high` on
   # Opus 4.6 / Sonnet 4.6). An Integer is also accepted and forwarded verbatim.
   EFFORT_LEVELS = %w[low medium high xhigh max].freeze
 
@@ -90,6 +90,73 @@ module ClaudeAgentSDK
       {}
     end
 
+    # The copy hook used wherever ClaudeAgentOptions are copied (dup_with and
+    # the configured-defaults merge). Identity by default: most Type instances
+    # are messages or callback payloads that never live inside options, and a
+    # user-supplied object that does (an observer, a store adapter) must stay
+    # the same object. Option VALUE types include OptionValue to opt in to
+    # copying, so a per-session change to e.g. sandbox rules can never reach
+    # another session or the configured defaults.
+    def dup_for_options
+      self
+    end
+
+    # Mixed into the mutable value types that ClaudeAgentOptions holds
+    # (SandboxSettings, SystemPromptPreset, AgentDefinition, ...). The copy
+    # recurses into the value's own state with Type.deep_dup_for_options, so
+    # nested containers and nested value types (SandboxSettings#network) are
+    # copied too while identity leaves (McpSdkServerConfig#instance, the
+    # callables in HookMatcher#hooks) stay shared. #dup never copies frozen
+    # state, so a copy of a frozen value (the configured-defaults snapshot) is
+    # mutable.
+    module OptionValue
+      def dup_for_options
+        copy = dup
+        copy.instance_variables.each do |ivar|
+          copy.instance_variable_set(ivar, Type.deep_dup_for_options(copy.instance_variable_get(ivar)))
+        end
+        copy
+      end
+    end
+
+    # Recurse into Hash/Array containers and option value types, and copy
+    # mutable (unfrozen) Strings — a caller-built prompt, model or
+    # allowed_tools entry is as much shared state as an Array, and `str <<
+    # 'x'` on one copy would otherwise change every other. A frozen String
+    # (any literal under frozen_string_literal) is immutable and keeps
+    # identity. Every other leaf keeps object identity (observer factories,
+    # callbacks, SDK MCP server instances must not be duped). Rebuild
+    # containers via dup.clear (never Hash#to_h / Array#map) to preserve
+    # container SUBCLASSES: to_h flattens e.g. Rails'
+    # HashWithIndifferentAccess into a plain Hash, silently breaking symbol
+    # lookups on the copy (config[:type] == 'sdk' → nil). Hash keys: Ruby
+    # already stores a dup'd, frozen copy of an unfrozen plain String key, but
+    # not of a String SUBCLASS key, so those are copied (and frozen, as keys
+    # should be) here. A compare_by_identity Hash is left keyed by the
+    # caller's objects: copying a key would break the caller's own lookups.
+    def self.deep_dup_for_options(value)
+      case value
+      when Hash
+        copy = value.dup.clear
+        value.each { |k, v| copy[option_hash_key(k, value)] = deep_dup_for_options(v) }
+        copy
+      when Array
+        copy = value.dup.clear
+        value.each { |v| copy << deep_dup_for_options(v) }
+        copy
+      when Type then value.dup_for_options
+      when String then value.frozen? ? value : value.dup # #dup keeps subclass and encoding
+      else value
+      end
+    end
+
+    def self.option_hash_key(key, hash)
+      return key unless key.is_a?(String) && !key.frozen? && !hash.compare_by_identity?
+
+      key.dup.freeze
+    end
+    private_class_method :option_hash_key
+
     private
 
     # Allow camelCase attribute access
@@ -785,13 +852,16 @@ module ClaudeAgentSDK
   # `display` controls how thinking content appears in responses. Valid values
   # are `"summarized"` (plaintext summary) and `"omitted"` (empty thinking
   # field, signature only). Defaults are model-dependent: Opus 4.6/Sonnet 4.6
-  # default to `"summarized"`; Opus 4.7 and Mythos Preview default to
-  # `"omitted"`. Pass `display: "summarized"` explicitly on Opus 4.7 to get
+  # default to `"summarized"`; Opus 4.7 and every later model default to
+  # `"omitted"`. Pass `display: "summarized"` explicitly on those to get
   # visible thinking text. Not supported with `ThinkingConfigDisabled`.
   THINKING_DISPLAY_VALUES = %w[summarized omitted].freeze
 
-  # Adaptive thinking: uses a default budget of 32000 tokens
+  # Adaptive thinking: the model decides when and how much to think
+  # (sent as `--thinking adaptive`, no budget); control depth with `effort`.
   class ThinkingConfigAdaptive < Type
+    include Type::OptionValue
+
     attr_reader :type, :display
 
     def initialize(attributes = {})
@@ -816,6 +886,8 @@ module ClaudeAgentSDK
 
   # Enabled thinking: uses a user-specified budget
   class ThinkingConfigEnabled < Type
+    include Type::OptionValue
+
     attr_accessor :budget_tokens
     attr_reader :type, :display
 
@@ -841,6 +913,8 @@ module ClaudeAgentSDK
 
   # Disabled thinking: sets thinking tokens to 0
   class ThinkingConfigDisabled < Type
+    include Type::OptionValue
+
     attr_reader :type
 
     def initialize(attributes = {})
@@ -851,6 +925,8 @@ module ClaudeAgentSDK
 
   # Agent definition configuration
   class AgentDefinition < Type
+    include Type::OptionValue
+
     attr_accessor :description, :prompt, :tools, :disallowed_tools, :model, :skills, :memory, :mcp_servers,
                   :initial_prompt, :max_turns, :background, :effort, :permission_mode
   end
@@ -942,6 +1018,8 @@ module ClaudeAgentSDK
 
   # Hook matcher configuration
   class HookMatcher < Type
+    include Type::OptionValue
+
     attr_accessor :matcher, :hooks, :timeout
 
     def initialize(attributes = {})
@@ -1640,6 +1718,8 @@ module ClaudeAgentSDK
 
   # MCP Server configurations
   class McpStdioServerConfig < Type
+    include Type::OptionValue
+
     attr_accessor :command, :args, :env
     attr_reader :type
 
@@ -1657,6 +1737,8 @@ module ClaudeAgentSDK
   end
 
   class McpSSEServerConfig < Type
+    include Type::OptionValue
+
     attr_accessor :url, :headers
     attr_reader :type
 
@@ -1673,6 +1755,8 @@ module ClaudeAgentSDK
   end
 
   class McpHttpServerConfig < Type
+    include Type::OptionValue
+
     attr_accessor :url, :headers
     attr_reader :type
 
@@ -1689,6 +1773,8 @@ module ClaudeAgentSDK
   end
 
   class McpSdkServerConfig < Type
+    include Type::OptionValue
+
     attr_accessor :name, :instance
     attr_reader :type
 
@@ -1704,6 +1790,8 @@ module ClaudeAgentSDK
 
   # SDK Plugin configuration
   class SdkPluginConfig < Type
+    include Type::OptionValue
+
     attr_accessor :path
     attr_reader :type
 
@@ -1719,6 +1807,8 @@ module ClaudeAgentSDK
 
   # Sandbox network configuration
   class SandboxNetworkConfig < Type
+    include Type::OptionValue
+
     attr_accessor :allowed_domains, :denied_domains, :allow_managed_domains_only,
                   :allow_unix_sockets, :allow_all_unix_sockets, :allow_local_binding,
                   :allow_mach_lookup, :http_proxy_port, :socks_proxy_port
@@ -1740,6 +1830,8 @@ module ClaudeAgentSDK
 
   # Sandbox filesystem configuration
   class SandboxFilesystemConfig < Type
+    include Type::OptionValue
+
     attr_accessor :allow_write, :deny_write, :deny_read, :allow_read, :allow_managed_read_paths_only
 
     def to_h
@@ -1755,6 +1847,8 @@ module ClaudeAgentSDK
 
   # Sandbox settings for isolated command execution
   class SandboxSettings < Type
+    include Type::OptionValue
+
     attr_accessor :enabled, :fail_if_unavailable, :auto_allow_bash_if_sandboxed,
                   :excluded_commands, :allow_unsandboxed_commands, :network, :filesystem,
                   :ignore_violations, :enable_weaker_nested_sandbox,
@@ -1786,6 +1880,8 @@ module ClaudeAgentSDK
   # When set, the model is made aware of its remaining token budget so it can
   # pace tool use and wrap up before the limit.
   class TaskBudget < Type
+    include Type::OptionValue
+
     attr_accessor :total
 
     def to_h
@@ -1795,6 +1891,8 @@ module ClaudeAgentSDK
 
   # System prompt file configuration — loads system prompt from a file path
   class SystemPromptFile < Type
+    include Type::OptionValue
+
     attr_accessor :path
     attr_reader :type
 
@@ -1822,6 +1920,8 @@ module ClaudeAgentSDK
   # before 2.1.265 a session with an +append+ prompt recorded it only when
   # +snapshot+ was true. Older CLIs silently ignore it.
   class SystemPromptPreset < Type
+    include Type::OptionValue
+
     attr_reader :type
     attr_accessor :preset, :append, :exclude_dynamic_sections, :snapshot
 
@@ -1844,6 +1944,8 @@ module ClaudeAgentSDK
   # (+--system-prompt <prompt>+); the object form exists so +snapshot+ can be
   # set alongside it (see SystemPromptPreset#snapshot for its semantics).
   class SystemPromptCustom < Type
+    include Type::OptionValue
+
     attr_reader :type
     attr_accessor :prompt, :snapshot
 
@@ -1861,6 +1963,8 @@ module ClaudeAgentSDK
 
   # Tools preset configuration
   class ToolsPreset < Type
+    include Type::OptionValue
+
     attr_reader :type
     attr_accessor :preset
 
@@ -1955,14 +2059,16 @@ module ClaudeAgentSDK
 
     def dup_with(**changes)
       new_options = self.dup
-      # A shallow #dup shares nested containers, so mutating a derived copy
-      # (e.g. `variant.allowed_tools << 'Bash'`) would bleed into the base and
-      # every sibling — including the security-relevant allow/deny lists.
-      # Deep-dup Hash/Array containers only; non-container values (procs,
-      # SDK MCP server instances, store adapters) must keep their identity.
+      # A shallow #dup shares nested containers and typed option values, so
+      # mutating a derived copy (e.g. `variant.allowed_tools << 'Bash'` or
+      # `variant.sandbox.enabled = false`) would bleed into the base and every
+      # sibling — including the security-relevant allow/deny lists and sandbox
+      # rules. Deep-dup Hash/Array containers and option value types (Type#
+      # dup_for_options, including those nested inside containers such as
+      # agents[:x]); every other leaf (procs, SDK MCP server instances, store
+      # adapters) keeps its identity.
       new_options.instance_variables.each do |ivar|
-        value = new_options.instance_variable_get(ivar)
-        new_options.instance_variable_set(ivar, deep_dup_containers(value)) if value.is_a?(Hash) || value.is_a?(Array)
+        new_options.instance_variable_set(ivar, Type.deep_dup_for_options(new_options.instance_variable_get(ivar)))
       end
       changes.each { |key, value| new_options[key] = value }
       new_options
@@ -2160,12 +2266,20 @@ module ClaudeAgentSDK
       defaults = ClaudeAgentSDK.default_options
       return attributes unless defaults.any?
 
-      # Start from configured defaults. Container values are recursively
-      # duped so per-instance mutation (options.allowed_tools << 'Bash')
-      # can never corrupt the global defaults; non-container leaves
-      # (Strings, Procs, SdkMcpServer instances) intentionally keep identity.
+      # Start from configured defaults. Container values, typed option
+      # values (SandboxSettings, SystemPromptPreset, AgentDefinition, ...)
+      # and mutable Strings are recursively copied (Type.deep_dup_for_options)
+      # so per-instance mutation (options.allowed_tools << 'Bash',
+      # options.sandbox.enabled = false) can never corrupt the global
+      # defaults or reach another session; other leaves (frozen Strings,
+      # Procs, SdkMcpServer instances, store adapters) intentionally keep
+      # identity. The stored defaults are a frozen snapshot
+      # (Configuration#default_options=), and the copy is what makes each
+      # session's containers and values mutable again — its Strings stay the
+      # snapshot's frozen ones, so `options.model << 'x'` fails loudly rather
+      # than reaching other sessions; reassign instead.
       result = {}
-      defaults.each { |key, value| result[option_key(key)] = deep_dup_containers(value) }
+      defaults.each { |key, value| result[option_key(key)] = Type.deep_dup_for_options(value) }
       attributes.each do |key, value|
         key = option_key(key)
         default_val = result[key]
@@ -2187,26 +2301,6 @@ module ClaudeAgentSDK
       normalized = normalize_name(name)
       respond_to?(:"#{normalized}=") ? normalized.to_sym : name
     end
-
-    # Recurse ONLY into Hash/Array; leaves keep object identity (observer
-    # factories, callbacks, SDK MCP server instances must not be duped).
-    # Rebuild via dup.clear (never Hash#to_h / Array#map) to preserve
-    # container SUBCLASSES: to_h flattens e.g. Rails'
-    # HashWithIndifferentAccess into a plain Hash, silently breaking symbol
-    # lookups on the copy (config[:type] == 'sdk' → nil).
-    def deep_dup_containers(value)
-      case value
-      when Hash
-        copy = value.dup.clear
-        value.each { |k, v| copy[k] = deep_dup_containers(v) }
-        copy
-      when Array
-        copy = value.dup.clear
-        value.each { |v| copy << deep_dup_containers(v) }
-        copy
-      else value
-      end
-    end
   end
 
   # SDK MCP Tool definition

data/lib/claude_agent_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '0.33.0'
+  VERSION = '0.34.0'
 end

data/lib/claude_agent_sdk.rb

@@ -52,18 +52,43 @@ module ClaudeAgentSDK
   # Internal: pull live SDK MCP server instances out of an mcp_servers Hash.
   # Accepts both raw Hash configs and typed Mcp*ServerConfig objects — a
   # McpSdkServerConfig passed without .to_h previously failed the Hash-only
-  # guard, so its in-process server was silently never registered.
+  # guard, so its in-process server was silently never registered. Hash
+  # configs may use String or Symbol keys (and a Symbol :sdk type) — the
+  # recognition rule must match CommandBuilder#append_mcp_servers, which
+  # strips the instance from exactly these entries.
   def self.extract_sdk_mcp_servers(mcp_servers)
     return {} unless mcp_servers.is_a?(Hash)
 
     servers = {}
     mcp_servers.each do |name, config|
       config = config.to_h if config.is_a?(Type)
-      servers[name] = config[:instance] if config.is_a?(Hash) && config[:type] == 'sdk'
+      next unless config.is_a?(Hash) && (config[:type] || config['type']).to_s == 'sdk'
+
+      servers[name] = config.key?(:instance) ? config[:instance] : config['instance']
     end
     servers
   end
 
+  # Internal: normalize hook lists for the control protocol. An absent or
+  # disabled event must not become an empty registration in initialize.
+  def self.convert_hooks_to_internal_format(hooks)
+    return nil unless hooks
+
+    internal_hooks = {}
+    hooks.each do |event, matchers|
+      next if matchers.nil? || matchers.empty?
+
+      entries = []
+      matchers.each do |matcher|
+        config = { matcher: matcher.matcher, hooks: matcher.hooks }
+        config[:timeout] = matcher.timeout if matcher.timeout
+        entries << config
+      end
+      internal_hooks[event.to_s] = entries unless entries.empty?
+    end
+    internal_hooks.empty? ? nil : internal_hooks
+  end
+
   # Internal: validate can_use_tool and route permission prompts over stdio.
   #
   # Shared by query() and Client#connect so both entry points enforce the
@@ -422,6 +447,7 @@ module ClaudeAgentSDK
   # rename_session). Appends a custom-title entry carrying a fresh uuid +
   # timestamp via SessionStore#append.
   # @raise [ArgumentError] if session_id is invalid or title is empty
+  # @raise [Errno::ENOENT] if the session is not found in the store (nothing is appended)
   def self.rename_session_via_store(session_store:, session_id:, title:, directory: nil)
     SessionMutations.rename_session_via_store(session_store: session_store, session_id: session_id,
                                               title: title, directory: directory)
@@ -430,6 +456,7 @@ module ClaudeAgentSDK
   # Tag a session in a SessionStore (store-backed counterpart to tag_session).
   # Pass nil to clear the tag.
   # @raise [ArgumentError] if session_id is invalid or tag is empty after sanitization
+  # @raise [Errno::ENOENT] if the session is not found in the store (nothing is appended)
   def self.tag_session_via_store(session_store:, session_id:, tag:, directory: nil)
     SessionMutations.tag_session_via_store(session_store: session_store, session_id: session_id,
                                            tag: tag, directory: directory)
@@ -528,7 +555,7 @@ module ClaudeAgentSDK
 
     raise ArgumentError, 'transport must respond to #connect (see ClaudeAgentSDK::Transport)' if transport && !transport.respond_to?(:connect)
 
-    Async do
+    Async(&FiberBoundary.capture_otel_context do
       materialized = nil
       query_handler = nil
       begin
@@ -556,25 +583,7 @@ module ClaudeAgentSDK
         # Extract SDK MCP servers
         sdk_mcp_servers = extract_sdk_mcp_servers(configured_options.mcp_servers)
 
-        hooks = nil
-        if configured_options.hooks
-          hooks = {}
-          configured_options.hooks.each do |event, matchers|
-            next if matchers.nil? || matchers.empty?
-
-            entries = []
-            matchers.each do |matcher|
-              config = {
-                matcher: matcher.matcher,
-                hooks: matcher.hooks
-              }
-              config[:timeout] = matcher.timeout if matcher.timeout
-              entries << config
-            end
-            hooks[event.to_s] = entries unless entries.empty?
-          end
-          hooks = nil if hooks.empty?
-        end
+        hooks = convert_hooks_to_internal_format(configured_options.hooks)
 
         # Create Query handler for control protocol
         query_handler = Query.new(
@@ -686,7 +695,7 @@ module ClaudeAgentSDK
           end
         end
       end
-    end.wait
+    end).wait
   end
 
   # Client for bidirectional, interactive conversations with Claude Code
@@ -762,7 +771,7 @@ module ClaudeAgentSDK
     def self.open(prompt = nil, options: nil, transport_class: SubprocessCLITransport, transport_args: {})
       raise ArgumentError, 'Client.open requires a block' unless block_given?
 
-      Sync do
+      Sync(&FiberBoundary.capture_otel_context do
         client = new(options: options, transport_class: transport_class, transport_args: transport_args)
         # connect failures self-clean via connect's rescue -> disconnect ->
         # raise, and disconnect is idempotent — no double-teardown.
@@ -772,7 +781,7 @@ module ClaudeAgentSDK
         ensure
           client.disconnect
         end
-      end
+      end)
     end
 
     # Connect to Claude with optional initial prompt.
@@ -792,6 +801,7 @@ module ClaudeAgentSDK
     def connect(prompt = nil)
       return if @connected
 
+      raise ArgumentError, 'prompt must be a String or an Enumerable of message Hashes/JSONL Strings (got Hash)' if prompt.is_a?(Hash)
       raise ArgumentError, "prompt must be a String, an Enumerator, or nil (got #{prompt.class})" unless prompt.nil? || prompt.is_a?(String) || prompt.respond_to?(:each)
 
       # Validate and configure permission settings
@@ -1050,6 +1060,19 @@ module ClaudeAgentSDK
     end
 
     # Disconnect from Claude
+    #
+    # Callable from inside a user callback (tool handler / hook /
+    # can_use_tool). With the default `callback_scheduling: :thread` the
+    # callback runs on a worker thread: the close is marshalled to the
+    # reactor, returns normally once the teardown completed, and the
+    # callback's return value is dropped (its reactor task was stopped). With
+    # `:inline` the callback's task is a child of the read task being
+    # stopped, so once the teardown has completed the deferred Async::Stop
+    # unwinds the callback — disconnect raises rather than returns there;
+    # ensure blocks run, `rescue StandardError` does not see it. The same
+    # holds, in every scheduling mode, for a streaming-input enumerator that
+    # calls disconnect: it is iterated on the reactor inside a task the close
+    # stops, so it unwinds with Async::Stop once the teardown has completed.
     def disconnect
       if @connected
         ClaudeAgentSDK.notify_observers(@resolved_observers || [], :on_close,
@@ -1125,7 +1148,7 @@ module ClaudeAgentSDK
       sdk_mcp_servers = ClaudeAgentSDK.extract_sdk_mcp_servers(configured_options.mcp_servers)
 
       # Convert hooks to internal format
-      hooks = convert_hooks_to_internal_format(configured_options.hooks) if configured_options.hooks
+      hooks = ClaudeAgentSDK.convert_hooks_to_internal_format(configured_options.hooks)
 
       # Extract exclude_dynamic_sections and snapshot from the system prompt
       # for the initialize request (older CLIs ignore unknown initialize fields)
@@ -1236,24 +1259,6 @@ module ClaudeAgentSDK
       @query_handler.set_transcript_mirror_batcher(batcher)
     end
 
-    def convert_hooks_to_internal_format(hooks)
-      return nil unless hooks
-
-      internal_hooks = {}
-      hooks.each do |event, matchers|
-        internal_hooks[event.to_s] = []
-        matchers.each do |matcher|
-          config = {
-            matcher: matcher.matcher,
-            hooks: matcher.hooks
-          }
-          config[:timeout] = matcher.timeout if matcher.timeout
-          internal_hooks[event.to_s] << config
-        end
-      end
-      internal_hooks
-    end
-
     def writeln(string)
       write string.end_with?("\n") ? string : "#{string}\n"
     end