claude-agent-sdk 0.25.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48fe05a71686f61555d5985ac8fe92e5d08b1ac530f1c2e2bb071f4d6b0fdb81
-  data.tar.gz: 669eedb9627e578e893e3e214271c172a0169d07fd9f60493c5c2d47c5540acb
+  metadata.gz: d4e4fcd2fa1c18916f41409482c8edfe3367ea5b06db9a90b80ed168f339a45e
+  data.tar.gz: 3726daa4aa431b4dba5cd181433066bc8f541efbe13984799c8642bfc671e75e
 SHA512:
-  metadata.gz: 7efcdba28fd54e81ddbf4b24ae01e14fde11c9c111f39241f65901eb23453d938e4e1be0fee3493fc034f0e81f0ec8373664d68a061d029b280e01f2a7ed4ad0
-  data.tar.gz: 2fb7a50378cb0bd44408b2d31737bd4fc1ec51162473e1417dcd1be58c851b5e369c9de9313edfa48425a5e36d058ccade91cf47bf5681251eeb9fa3c2a89031
+  metadata.gz: 00cb37c301d1c1eae778bd55b0d19330e21b6069a0943a6cd7a7931da4d32d8da847c8362f102d530aed8cdcf66f28eb9ca57ac248ed5ce2cbcd5609b3435ab0
+  data.tar.gz: 0bcabed11ba7e49c78ab383bf1186d39cd65873e1190f13a7cbfc102f1c2c7f0226fc8604818f3fc4cf3706760334abb5bc82a7c9ab6e6c9d1e178fd3a1c3002

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.26.0] - 2026-07-31
+
+### Added
+- **`ClaudeAgentOptions#callback_wrapper`** (#47 phase 2): optional middleware wrapped around every user-callback dispatch (message blocks, observers, hooks, permission callbacks, SDK MCP handlers). A callable receiving a zero-arg invocation that it must call and return: `callback_wrapper: ->(inv) { Rails.application.executor.wrap { inv.call } }`. The wrapper runs on the same execution context as the callback — inside the worker thread in the default `:thread` mode (so `executor.wrap` checks ActiveRecord connections back in when the callback ends, retiring the stranded-connection workaround without adopting `:inline`), in place on the reactor fiber in `:inline` mode. Exceptions propagate through it unchanged. Also settable per SDK MCP server for direct calls (`server.callback_wrapper=`); session dispatches carry the session's wrapper via the same fiber-storage scope as `callback_scheduling`. See "Rails executor around callbacks" in docs/rails.md.
+
 ## [0.25.0] - 2026-07-31
 
 ### Added

data/README.md

@@ -68,7 +68,7 @@ Add this line to your application's Gemfile:
 gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
 
 # Or use a stable version from RubyGems
-gem 'claude-agent-sdk', '~> 0.25.0'
+gem 'claude-agent-sdk', '~> 0.26.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.

data/docs/rails.md

@@ -21,6 +21,22 @@ end
 
 The trade-off: because callbacks run on a plain thread rather than inside an `Async::Task`, fiber-specific primitives aren't available to them — `Async::Task.current` will raise "No async task available". If a callback wants cooperative concurrency it should open its own `Async { }` block. In practice, callbacks typically do some Ruby work, call external services, and return — so this rarely matters. If you wrap your own call site in an outer `Async { }` block, the scheduler is visible to your code again; you've opted in, and whatever fiber-safety rules your app uses apply there.
 
+### Rails executor around callbacks: `callback_wrapper`
+
+One consequence of the thread hop: an ActiveRecord connection implicitly checked out inside a callback belongs to that throwaway thread and stays stranded until the pool reaper reclaims it. Rails' own answer to "code running on a thread Rails didn't create" is the executor — and `callback_wrapper` lets you install it around every user-callback dispatch:
+
+```ruby
+ClaudeAgentSDK.configure do |config|
+  config.default_options = {
+    callback_wrapper: ->(invocation) { Rails.application.executor.wrap { invocation.call } }
+  }
+end
+```
+
+The wrapper is a callable receiving a zero-arg `invocation`; it must call it and return its value. It runs on the **same execution context as the callback** — inside the worker thread in `:thread` mode, which is the whole point: `executor.wrap` runs on the thread that touches ActiveRecord, so connections check back in when the callback ends. Exceptions from the callback propagate through the wrapper unchanged (don't rescue them); `ensure`-based wrappers like `executor.wrap` are safe, including around a `break` from a message block. Beyond the executor, this is a generic hook for APM span propagation, `CurrentAttributes`/logging context, etc.
+
+When do you want this vs `callback_scheduling: :inline`? `callback_wrapper` + default `:thread` mode is the right choice for ordinary threaded hosts (Puma, threaded Sidekiq/solid_queue): it fixes connection hygiene without any fiber-isolation precondition. `:inline` is only for hosts that are fiber-isolated end to end (solid_queue fiber workers with `isolation_level = :fiber`); there the wrapper still applies — it simply runs in place on the reactor fiber.
+
 ## Fiber workers (solid_queue) and `callback_scheduling: :inline`
 
 [solid_queue 728](https://github.com/rails/solid_queue/pull/728) added a fiber-based worker mode: workers configured with `fibers: N` run claimed jobs as fibers on one async reactor thread — built for exactly the long-lived, I/O-bound "LLM streaming" jobs this SDK produces. It requires the app to be fiber-isolated end to end:

data/lib/claude_agent_sdk/fiber_boundary.rb

@@ -97,12 +97,16 @@ module ClaudeAgentSDK
     # fall back to the server's own default. Benign race on close vs. a
     # concurrent reader: either value is a defensible mode for a call that
     # straddles the dispatch boundary.
+    # Also carries the session's callback wrapper — the two travel (and are
+    # invalidated) together, so a descendant that outlives the dispatch can
+    # neither run with the session's mode nor with its wrapper.
     # @api private
     class SchedulingScope
-      attr_reader :mode
+      attr_reader :mode, :wrapper
 
-      def initialize(mode)
+      def initialize(mode, wrapper = nil)
         @mode = mode
+        @wrapper = wrapper
         @active = true
       end
 
@@ -137,10 +141,31 @@ module ClaudeAgentSDK
     # With `scheduling: :inline` (and no timeout) the block runs in place on
     # the current fiber, scheduler or not. The caller opts in via
     # `ClaudeAgentOptions#callback_scheduling`.
-    def invoke(timeout: nil, scheduling: :thread, &block)
-      return block.call if timeout.nil? && (scheduling == :inline || !Fiber.scheduler)
+    #
+    # With +wrapper+ (a callable, from `ClaudeAgentOptions#callback_wrapper`)
+    # the executed body becomes `wrapper.call(block)` — composed BEFORE the
+    # thread hop, so the wrapper runs on the same execution context as the
+    # callback: on the worker thread in :thread mode (the whole point —
+    # `Rails.application.executor.wrap` must run on the thread that touches
+    # ActiveRecord), in place on the reactor fiber in :inline mode. The
+    # wrapper must call its argument and return its value; exceptions from
+    # the callback propagate through it unchanged, and exceptions raised by
+    # the wrapper itself are treated exactly like callback exceptions. The
+    # wrapper must not swallow exceptions and must return
+    # the invocation's value — a user's `break` in a message block reaches
+    # the wrapper as a clean return (invoke_iteration translates it BEFORE
+    # the wrapper sees it), never as an exception a rescue/report wrapper
+    # could falsely flag. In inline/no-scheduler mode `break` unwinds natively through the
+    # wrapper's stack, so ensure-based wrappers (executor.wrap) are safe.
+    #
+    # The timeout path deliberately ignores the wrapper: it belongs to the
+    # store-adapter carve-out (TranscriptMirrorBatcher, SessionResume),
+    # which never carries user callbacks.
+    def invoke(timeout: nil, scheduling: :thread, wrapper: nil, &block)
+      body = wrapper && timeout.nil? ? -> { wrapper.call(block) } : block
+      return body.call if timeout.nil? && (scheduling == :inline || !Fiber.scheduler)
 
-      thread = Thread.new(&block)
+      thread = Thread.new(&body)
       thread.report_on_exception = false
       return thread.value if timeout.nil?
       raise JoinTimeout, "timed out after #{timeout}s" unless thread.join(timeout)
@@ -155,8 +180,15 @@ module ClaudeAgentSDK
     # Returns Break when the user broke, nil when the block completed.
     # Without a scheduler (or with `scheduling: :inline`) the block runs in
     # place and `break` unwinds natively, never reaching the translation.
-    def invoke_iteration(block, *args, scheduling: :thread)
-      invoke(scheduling: scheduling) do
+    # The LocalJumpError -> Break translation lives INSIDE the invocation
+    # handed to the +wrapper+: a user's `break` is normal loop control, not
+    # an error, so a conforming rescue/report/re-raise wrapper must observe
+    # a clean return (the Break sentinel as the invocation's value), never
+    # a LocalJumpError it could falsely report or swallow. In inline /
+    # no-scheduler mode `break` unwinds natively through the wrapper's
+    # stack instead (ensure-based wrappers still run their cleanup).
+    def invoke_iteration(block, *args, scheduling: :thread, wrapper: nil)
+      invocation = lambda do
         block.call(*args)
         nil
       rescue LocalJumpError => e
@@ -164,6 +196,8 @@ module ClaudeAgentSDK
 
         Break.new(e.exit_value)
       end
+      body = wrapper ? -> { wrapper.call(invocation) } : invocation
+      invoke(scheduling: scheduling) { body.call }
     end
   end
 end

data/lib/claude_agent_sdk/query.rb

@@ -63,13 +63,14 @@ module ClaudeAgentSDK
     end
 
     def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil, agents: nil,
-                   exclude_dynamic_sections: nil, skills: nil, callback_scheduling: :thread)
+                   exclude_dynamic_sections: nil, skills: nil, callback_scheduling: :thread, callback_wrapper: nil)
       @transport = transport
       @is_streaming_mode = is_streaming_mode
       @can_use_tool = can_use_tool
       @hooks = hooks || {}
       @sdk_mcp_servers = sdk_mcp_servers || {}
       @callback_scheduling = callback_scheduling || :thread
+      @callback_wrapper = callback_wrapper
       @agents = agents
       @exclude_dynamic_sections = exclude_dynamic_sections
       @skills = skills
@@ -570,7 +571,7 @@ module ClaudeAgentSDK
       # 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) do
+      response = FiberBoundary.invoke(scheduling: @callback_scheduling, wrapper: @callback_wrapper) do
         @can_use_tool.call(request_data[:tool_name], request_data[:input], context)
       end
 
@@ -615,7 +616,7 @@ module ClaudeAgentSDK
       # suspension point and its ensure blocks run (Python parity — anyio
       # cancels the coroutine). A CPU-stuck inline hook cannot be timed out.
       unless @hook_callback_timeouts[callback_id]
-        hook_output = FiberBoundary.invoke(scheduling: @callback_scheduling) do
+        hook_output = FiberBoundary.invoke(scheduling: @callback_scheduling, wrapper: @callback_wrapper) do
           callback.call(hook_input, request_data[:tool_use_id], context)
         end
       end
@@ -629,10 +630,13 @@ module ClaudeAgentSDK
             # convert the expired hook into a success (or keep running past
             # the deadline). Inject a non-StandardError cancellation
             # instead, translated back once control leaves user code so the
-            # outward contract (Async::TimeoutError) is unchanged.
+            # outward contract (Async::TimeoutError) is unchanged. The
+            # wrapper composes INSIDE with_timeout, and the cancellation
+            # passes through it un-swallowed (InlineCancellation is not a
+            # StandardError, so a wrapper's ordinary rescue can't eat it).
             begin
               Async::Task.current.with_timeout(timeout, FiberBoundary::InlineCancellation) do
-                FiberBoundary.invoke(scheduling: :inline) do
+                FiberBoundary.invoke(scheduling: :inline, wrapper: @callback_wrapper) do
                   callback.call(hook_input, request_data[:tool_use_id], context)
                 end
               end
@@ -641,7 +645,7 @@ module ClaudeAgentSDK
             end
           else
             Async::Task.current.with_timeout(timeout) do
-              FiberBoundary.invoke do
+              FiberBoundary.invoke(wrapper: @callback_wrapper) do
                 callback.call(hook_input, request_data[:tool_use_id], context)
               end
             end
@@ -994,10 +998,11 @@ module ClaudeAgentSDK
     end
 
     def handle_sdk_mcp_request(server_name, message)
-      # Carry this session's scheduling mode across the dispatch into the
-      # (possibly session-shared) SdkMcpServer via fiber storage — set on
-      # the dispatching fiber, read back by the server's handlers at invoke
-      # time (see SdkMcpServer#effective_callback_scheduling). Fiber
+      # 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
+      # handlers at invoke time (see
+      # SdkMcpServer#effective_callback_scheduling / _wrapper). Fiber
       # storage is per-fiber, so concurrent sessions cannot see each
       # other's value even across suspension points. The value is a
       # closable SchedulingScope, closed + restored in the ensure below:
@@ -1008,7 +1013,7 @@ module ClaudeAgentSDK
       # into later direct server calls, and nothing stays stamped on
       # long-lived fibers.
       previous_scheduling = Fiber[FiberBoundary::SCHEDULING_KEY]
-      dispatch_scope = FiberBoundary::SchedulingScope.new(@callback_scheduling)
+      dispatch_scope = FiberBoundary::SchedulingScope.new(@callback_scheduling, @callback_wrapper)
       Fiber[FiberBoundary::SCHEDULING_KEY] = dispatch_scope
 
       # Convert server_name to symbol if needed for hash lookup

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -90,17 +90,47 @@ module ClaudeAgentSDK
     # so modes cannot cross-contaminate or persist past a session.
     attr_accessor :callback_scheduling
 
+    # Default callback wrapper for DIRECT invocations of this server
+    # (call_tool / read_resource / get_prompt outside a session). When a
+    # session dispatches to this server, the session's own wrapper arrives
+    # via fiber storage instead (see #effective_callback_wrapper) — same
+    # never-mutate-the-shared-server rule as callback_scheduling.
+    attr_accessor :callback_wrapper
+
     # Internal — public only so the dynamic tool classes can reach it. The
-    # scheduling mode for the current invocation: the dispatching session's
-    # mode (a live SchedulingScope in fiber storage, set by Query around
-    # the dispatch) when present, else this server's own default. A scope
-    # inherited from an already-finished dispatch is closed and
-    # deliberately ignored — a child task spawned inside a handler must not
-    # carry the session mode into later direct calls.
+    # (scheduling mode, wrapper) pair for the current invocation, resolved
+    # from ONE liveness decision: the dispatching session's pair when a
+    # live SchedulingScope is in fiber storage (set by Query around the
+    # dispatch), else this server's own defaults. The pair MUST be resolved
+    # together — deciding `active?` once per accessor lets the scope close
+    # between the two reads (the dispatch's ensure runs concurrently with a
+    # descendant reader) and yields a torn mix of session mode with server
+    # wrapper. A scope inherited from an already-finished dispatch is
+    # closed and deliberately ignored — a child task spawned inside a
+    # handler must not carry the session's pair into later direct calls.
     # @api private
-    def effective_callback_scheduling
+    # @return [Array(Symbol, #call)] `[scheduling, wrapper]`
+    def effective_callback_dispatch
       scope = Fiber[FiberBoundary::SCHEDULING_KEY]
-      scope&.active? ? scope.mode : @callback_scheduling
+      if scope&.active?
+        [scope.mode, scope.wrapper]
+      else
+        [@callback_scheduling, @callback_wrapper]
+      end
+    end
+
+    # Internal. Prefer #effective_callback_dispatch when both values are
+    # needed — separate calls re-decide scope liveness and can tear.
+    # @api private
+    def effective_callback_scheduling
+      effective_callback_dispatch[0]
+    end
+
+    # Internal. Prefer #effective_callback_dispatch when both values are
+    # needed — separate calls re-decide scope liveness and can tear.
+    # @api private
+    def effective_callback_wrapper
+      effective_callback_dispatch[1]
     end
 
     def initialize(name:, version: '1.0.0', tools: [], resources: [], prompts: [])
@@ -110,6 +140,7 @@ module ClaudeAgentSDK
       @resources = resources
       @prompts = prompts
       @callback_scheduling = :thread
+      @callback_wrapper = nil
 
       # Create dynamic Tool classes from tool definitions
       tool_classes = create_tool_classes(tools)
@@ -197,7 +228,10 @@ module ClaudeAgentSDK
       # Call the tool's handler on a plain thread (default) so the async
       # gem's Fiber scheduler is not visible to user code (which may hit
       # AR/PG); in :inline mode it runs in place on the reactor fiber.
-      result = FiberBoundary.invoke(scheduling: effective_callback_scheduling) { tool.handler.call(arguments) }
+      scheduling, wrapper = effective_callback_dispatch
+      result = FiberBoundary.invoke(scheduling: scheduling, wrapper: wrapper) do
+        tool.handler.call(arguments)
+      end
 
       # Guard before flexible_fetch: it raises on non-Hash inputs.
       content = result.is_a?(Hash) ? ClaudeAgentSDK.flexible_fetch(result, "content", "content") : nil
@@ -232,7 +266,10 @@ module ClaudeAgentSDK
       # Hop off the Fiber scheduler before invoking user code — same reason
       # as `call_tool` above: reader blocks may touch Thread.current-keyed
       # libraries (ActiveRecord, pg, ...) and must run on a plain thread.
-      content = FiberBoundary.invoke(scheduling: effective_callback_scheduling) { resource.reader.call }
+      scheduling, wrapper = effective_callback_dispatch
+      content = FiberBoundary.invoke(scheduling: scheduling, wrapper: wrapper) do
+        resource.reader.call
+      end
 
       # Ensure content has the expected format (symbol or string keys; guard
       # before flexible_fetch — it raises on non-Hash inputs)
@@ -264,7 +301,10 @@ module ClaudeAgentSDK
 
       # Hop off the Fiber scheduler before invoking user code — same reason
       # as `call_tool` above.
-      result = FiberBoundary.invoke(scheduling: effective_callback_scheduling) { prompt.generator.call(arguments) }
+      scheduling, wrapper = effective_callback_dispatch
+      result = FiberBoundary.invoke(scheduling: scheduling, wrapper: wrapper) do
+        prompt.generator.call(arguments)
+      end
 
       # Ensure result has the expected format (symbol or string keys)
       messages = result.is_a?(Hash) ? ClaudeAgentSDK.flexible_fetch(result, "messages", "messages") : nil
@@ -365,7 +405,8 @@ module ClaudeAgentSDK
               # Filter out server_context and pass remaining args to handler.
               # Hop to a plain thread (default) so user handlers don't see
               # the Fiber scheduler; :inline runs in place on the reactor.
-              result = FiberBoundary.invoke(scheduling: @sdk_server.effective_callback_scheduling) do
+              scheduling, wrapper = @sdk_server.effective_callback_dispatch
+              result = FiberBoundary.invoke(scheduling: scheduling, wrapper: wrapper) do
                 @tool_def.handler.call(args)
               end
 

data/lib/claude_agent_sdk/types.rb

@@ -1576,7 +1576,7 @@ module ClaudeAgentSDK
     attr_reader :bare, :fork_session, :enable_file_checkpointing,
                 :include_partial_messages, :continue_conversation,
                 :include_hook_events, :strict_mcp_config,
-                :callback_scheduling
+                :callback_scheduling, :callback_wrapper
 
     def initialize(attributes = {})
       self.fork_session = false
@@ -1704,6 +1704,24 @@ module ClaudeAgentSDK
       @callback_scheduling = mode
     end
 
+    # Middleware wrapped around EVERY user-callback dispatch (message
+    # blocks, observers, hooks, permission callbacks, SDK MCP handlers).
+    # A callable receiving a zero-arg invocation; it MUST call it and
+    # return its value:
+    #
+    #   callback_wrapper: ->(invocation) { Rails.application.executor.wrap { invocation.call } }
+    #
+    # The wrapper runs on the same execution context as the callback —
+    # inside the worker thread in :thread mode (so executor.wrap checks AR
+    # connections back in when the callback ends), in place on the reactor
+    # fiber in :inline mode. Exceptions propagate through it unchanged; it
+    # must not swallow them. Default nil (no wrapping).
+    def callback_wrapper=(value)
+      raise ArgumentError, "callback_wrapper must be a callable or nil (got #{value.inspect})" unless value.nil? || value.respond_to?(:call)
+
+      @callback_wrapper = value
+    end
+
     private
 
     # Strict key validation: unlike other Type subclasses (which silently drop

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -84,9 +84,9 @@ module ClaudeAgentSDK
   # Each observer is invoked through FiberBoundary so that user code runs
   # on a plain thread (no Fiber scheduler) even when called from inside
   # the SDK's Async reactor — or in place when scheduling is :inline.
-  def self.notify_observers(observers, method, *args, scheduling: :thread)
+  def self.notify_observers(observers, method, *args, scheduling: :thread, wrapper: nil)
     observers.each do |obs|
-      FiberBoundary.invoke(scheduling: scheduling) { obs.send(method, *args) }
+      FiberBoundary.invoke(scheduling: scheduling, wrapper: wrapper) { obs.send(method, *args) }
     rescue StandardError, ScriptError
       # ScriptError too: NotImplementedError < ScriptError (not
       # StandardError), and a stubbed observer must never mask the original
@@ -187,13 +187,13 @@ module ClaudeAgentSDK
   # Wrap a streaming-input enumerable so observers get on_user_prompt for
   # each user message before it is written to stdin. Identity when no
   # observers are configured.
-  def self.observing_prompt_stream(prompt, observers, scheduling: :thread)
+  def self.observing_prompt_stream(prompt, observers, scheduling: :thread, wrapper: nil)
     return prompt if observers.empty?
 
     Enumerator.new do |yielder|
       prompt.each do |message|
         text = extract_user_prompt_text(message)
-        notify_observers(observers, :on_user_prompt, text, scheduling: scheduling) if text
+        notify_observers(observers, :on_user_prompt, text, scheduling: scheduling, wrapper: wrapper) if text
         yielder << message
       end
     end
@@ -461,8 +461,10 @@ module ClaudeAgentSDK
     # Resolve callable observers into fresh instances (thread-safe for global defaults)
     resolved_observers = ClaudeAgentSDK.resolve_observers(configured_options.observers)
 
-    # Where user callbacks run (see ClaudeAgentOptions#callback_scheduling).
+    # Where user callbacks run (see ClaudeAgentOptions#callback_scheduling)
+    # and the middleware wrapped around them (#callback_wrapper).
     callback_scheduling = configured_options.callback_scheduling || :thread
+    callback_wrapper = configured_options.callback_wrapper
     ClaudeAgentSDK.check_inline_isolation(callback_scheduling)
 
     raise ArgumentError, 'transport must respond to #connect (see ClaudeAgentSDK::Transport)' if transport && !transport.respond_to?(:connect)
@@ -525,7 +527,8 @@ module ClaudeAgentSDK
           sdk_mcp_servers: sdk_mcp_servers,
           exclude_dynamic_sections: ClaudeAgentSDK.extract_exclude_dynamic_sections(configured_options.system_prompt),
           skills: configured_options.skills,
-          callback_scheduling: callback_scheduling
+          callback_scheduling: callback_scheduling,
+          callback_wrapper: callback_wrapper
         )
 
         # Mirror transcripts to the session_store, if configured. Installed
@@ -549,7 +552,8 @@ module ClaudeAgentSDK
 
         # Send prompt(s) as user messages, then close stdin
         if prompt.is_a?(String)
-          ClaudeAgentSDK.notify_observers(resolved_observers, :on_user_prompt, prompt, scheduling: callback_scheduling)
+          ClaudeAgentSDK.notify_observers(resolved_observers, :on_user_prompt, prompt,
+                                          scheduling: callback_scheduling, wrapper: callback_wrapper)
           message = {
             type: 'user',
             message: { role: 'user', content: prompt },
@@ -567,7 +571,8 @@ module ClaudeAgentSDK
           # here kept the root reactor alive forever when the read loop died
           # while the user enumerator was still blocked (matches Python's
           # query.spawn_task(query.stream_input(prompt))).
-          observed_prompt = ClaudeAgentSDK.observing_prompt_stream(prompt, resolved_observers, scheduling: callback_scheduling)
+          observed_prompt = ClaudeAgentSDK.observing_prompt_stream(prompt, resolved_observers,
+                                                                   scheduling: callback_scheduling, wrapper: callback_wrapper)
           query_handler.spawn_task { query_handler.stream_input(observed_prompt) }
         end
 
@@ -579,8 +584,10 @@ module ClaudeAgentSDK
           message = MessageParser.parse(data)
           next unless message
 
-          ClaudeAgentSDK.notify_observers(resolved_observers, :on_message, message, scheduling: callback_scheduling)
-          signal = FiberBoundary.invoke_iteration(block, message, scheduling: callback_scheduling)
+          ClaudeAgentSDK.notify_observers(resolved_observers, :on_message, message,
+                                          scheduling: callback_scheduling, wrapper: callback_wrapper)
+          signal = FiberBoundary.invoke_iteration(block, message, scheduling: callback_scheduling,
+                                                                  wrapper: callback_wrapper)
           break signal.value if signal.is_a?(FiberBoundary::Break)
         end
       rescue StandardError => e
@@ -589,10 +596,12 @@ module ClaudeAgentSDK
         # parse errors, and user-block errors. StandardError only: Async::Stop
         # is cancellation, not an error. Bare raise preserves the backtrace;
         # the ensure below still fires on_close after on_error.
-        ClaudeAgentSDK.notify_observers(resolved_observers, :on_error, e, scheduling: callback_scheduling)
+        ClaudeAgentSDK.notify_observers(resolved_observers, :on_error, e,
+                                        scheduling: callback_scheduling, wrapper: callback_wrapper)
         raise
       ensure
-        ClaudeAgentSDK.notify_observers(resolved_observers, :on_close, scheduling: callback_scheduling)
+        ClaudeAgentSDK.notify_observers(resolved_observers, :on_close,
+                                        scheduling: callback_scheduling, wrapper: callback_wrapper)
         # query_handler.close stops the background read task and closes the
         # transport (flushing the mirror batcher first). Fall back to a bare
         # transport close when the handler was never built.
@@ -663,6 +672,7 @@ module ClaudeAgentSDK
     def initialize(options: nil, transport_class: SubprocessCLITransport, transport_args: {})
       @options = options || ClaudeAgentOptions.new
       @callback_scheduling = @options.callback_scheduling || :thread
+      @callback_wrapper = @options.callback_wrapper
       @transport_class = transport_class
       @transport_args = transport_args
       @transport = nil
@@ -799,7 +809,8 @@ module ClaudeAgentSDK
 
       begin
         if prompt.is_a?(String)
-          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, prompt, scheduling: @callback_scheduling)
+          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, prompt,
+                                          scheduling: @callback_scheduling, wrapper: @callback_wrapper)
           message = {
             type: 'user',
             message: { role: 'user', content: prompt },
@@ -840,8 +851,10 @@ module ClaudeAgentSDK
           message = MessageParser.parse(data)
           next unless message
 
-          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_message, message, scheduling: @callback_scheduling)
-          signal = FiberBoundary.invoke_iteration(block, message, scheduling: @callback_scheduling)
+          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_message, message,
+                                          scheduling: @callback_scheduling, wrapper: @callback_wrapper)
+          signal = FiberBoundary.invoke_iteration(block, message, scheduling: @callback_scheduling,
+                                                                  wrapper: @callback_wrapper)
           break signal.value if signal.is_a?(FiberBoundary::Break)
         end
       rescue StandardError => e
@@ -866,8 +879,10 @@ module ClaudeAgentSDK
           message = MessageParser.parse(data)
           next unless message
 
-          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_message, message, scheduling: @callback_scheduling)
-          signal = FiberBoundary.invoke_iteration(block, message, scheduling: @callback_scheduling)
+          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_message, message,
+                                          scheduling: @callback_scheduling, wrapper: @callback_wrapper)
+          signal = FiberBoundary.invoke_iteration(block, message, scheduling: @callback_scheduling,
+                                                                  wrapper: @callback_wrapper)
           break signal.value if signal.is_a?(FiberBoundary::Break)
           break if message.is_a?(ResultMessage)
         end
@@ -959,7 +974,10 @@ module ClaudeAgentSDK
 
     # Disconnect from Claude
     def disconnect
-      ClaudeAgentSDK.notify_observers(@resolved_observers || [], :on_close, scheduling: @callback_scheduling) if @connected
+      if @connected
+        ClaudeAgentSDK.notify_observers(@resolved_observers || [], :on_close,
+                                        scheduling: @callback_scheduling, wrapper: @callback_wrapper)
+      end
       # Tear down whatever exists — robust to a partial/failed connect, where
       # @connected is still false but a transport and/or materialized temp dir
       # were already created. #close on the query handler also closes the
@@ -1046,7 +1064,8 @@ module ClaudeAgentSDK
         agents: configured_options.agents,
         exclude_dynamic_sections: exclude_dynamic_sections,
         skills: configured_options.skills,
-        callback_scheduling: @callback_scheduling
+        callback_scheduling: @callback_scheduling,
+        callback_wrapper: @callback_wrapper
       )
 
       # Mirror transcripts to the session_store, if configured.
@@ -1077,7 +1096,8 @@ module ClaudeAgentSDK
         # Observer#on_error contract; notifying a swallowed error would mark
         # a still-live OTel trace as failed). Same behavior as query()'s
         # streaming path.
-        observed = ClaudeAgentSDK.observing_prompt_stream(prompt, @resolved_observers, scheduling: @callback_scheduling)
+        observed = ClaudeAgentSDK.observing_prompt_stream(prompt, @resolved_observers,
+                                                          scheduling: @callback_scheduling, wrapper: @callback_wrapper)
         @query_handler.spawn_task { @query_handler.stream_input(observed) }
       end
     end
@@ -1094,12 +1114,14 @@ module ClaudeAgentSDK
         when Hash
           msg = msg.merge(session_id: session_id) unless msg.key?(:session_id) || msg.key?('session_id')
           if (text = ClaudeAgentSDK.extract_user_prompt_text(msg))
-            ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text, scheduling: @callback_scheduling)
+            ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text,
+                                            scheduling: @callback_scheduling, wrapper: @callback_wrapper)
           end
           writeln(JSON.generate(msg))
         when String
           if (text = ClaudeAgentSDK.extract_user_prompt_text(msg))
-            ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text, scheduling: @callback_scheduling)
+            ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text,
+                                            scheduling: @callback_scheduling, wrapper: @callback_wrapper)
           end
           writeln(msg)
         else
@@ -1113,7 +1135,8 @@ module ClaudeAgentSDK
     # Notify observers of an error surfacing to the consumer. `|| []` keeps a
     # mis-scoped call before connect harmless instead of NoMethodError on nil.
     def notify_error(error)
-      ClaudeAgentSDK.notify_observers(@resolved_observers || [], :on_error, error, scheduling: @callback_scheduling)
+      ClaudeAgentSDK.notify_observers(@resolved_observers || [], :on_error, error,
+                                      scheduling: @callback_scheduling, wrapper: @callback_wrapper)
     end
 
     # Build and install the transcript-mirror batcher on the query handler when

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.26.0
 platform: ruby
 authors:
 - Community Contributors