claude-agent-sdk 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48fe05a71686f61555d5985ac8fe92e5d08b1ac530f1c2e2bb071f4d6b0fdb81
-  data.tar.gz: 669eedb9627e578e893e3e214271c172a0169d07fd9f60493c5c2d47c5540acb
+  metadata.gz: 760ec1fb0cf80f6e56d7b5d3adb20ca2956b209d0961020ae36fa52a13e28144
+  data.tar.gz: 6ba365de4438e4081f9bfa47afadc4859d9a001bb6238c0b66f00437cb032626
 SHA512:
-  metadata.gz: 7efcdba28fd54e81ddbf4b24ae01e14fde11c9c111f39241f65901eb23453d938e4e1be0fee3493fc034f0e81f0ec8373664d68a061d029b280e01f2a7ed4ad0
-  data.tar.gz: 2fb7a50378cb0bd44408b2d31737bd4fc1ec51162473e1417dcd1be58c851b5e369c9de9313edfa48425a5e36d058ccade91cf47bf5681251eeb9fa3c2a89031
+  metadata.gz: 672d6640b3bdefc6c5d9cf599c41b89b6259107f780981da382b18bfa56180788225d5e278ab9a7ef22e79a09a000b48147a1a285b74182b5f4254d8d8ec474e
+  data.tar.gz: 0b6eff840de87f744de373bea259fd89a36ca1af33fbc2c678ac84296115b9a5fad841941feabaeb8ebda9c8333d6f4d72a380379c09c410e6358c571af1b26b

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-07-31
+
+### Added
+- **Fiber-native SessionStore adapters** (#47 phase 3): an adapter whose IO is entirely Fiber-scheduler-aware can declare it by defining an optional `callback_scheduling` method returning `:inline`. Every timeout-bounded store call the SDK makes (mirror-batcher appends; resume-materialization loads **and** the listing methods `list_sessions` / `list_session_summaries` / `list_subkeys`) then runs in place on the reactor fiber under a **cooperative** timeout — interrupted at the next suspension point with `ensure` blocks running — instead of on a throwaway thread with a hard `Thread#join` bound. The outward exception contract is unchanged (`FiberBoundary::JoinTimeout`); undeclared adapters are byte-for-byte untouched, and outside a reactor the hard bound still applies even for declared adapters. Cancellation reaches only the adapter's own fiber (offloaded work may still land afterwards), so timed-out appends are not retried in either mode and may remain permanently half-applied in the store — the drop is surfaced (`MirrorErrorMessage`, `batches_dropped?`) and the local transcript remains the source of truth. Invalid or raising declarations fail fast (`ArgumentError` at construction; conformance contract 17). Apps can opt a third-party fiber-native adapter in via `def store.callback_scheduling = :inline`.
+
+## [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.27.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:
@@ -64,7 +80,7 @@ end
 
 Preconditions, spelled out: `:inline` is only correct when the process satisfies the same requirements as solid_queue's fiber workers — `isolation_level = :fiber`, Rails 7.2+ for AR, and no thread-keyed libraries used inside callbacks without a fiber-aware wrapper. The SDK warns once if it detects `:inline` under `isolation_level == :thread`. Everything else (Puma request threads, threaded Sidekiq/solid_queue workers) should stay on the default `callback_scheduling: :thread`.
 
-Note that `SessionStore` adapter calls (`#append` / `#load`) intentionally stay on threads even in `:inline` mode — their timeouts are hard bounds (`Thread#join`) so a wedged store adapter can never stall the reactor.
+Note that `SessionStore` adapter calls (`#append` / `#load`) stay on threads by default even in `:inline` mode — their timeouts are hard bounds (`Thread#join`) so a wedged store adapter can never stall the reactor. The exception is an adapter that declares itself fiber-native via an optional `callback_scheduling` method returning `:inline` (see "Fiber-native adapters" in [docs/sessions.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/sessions.md)); its calls then run on the reactor under a cooperative timeout.
 
 ## ActionCable Streaming
 

data/docs/sessions.md

@@ -154,7 +154,8 @@ during resume materialization, default `60_000`).
 > Python and TypeScript SDKs.
 >
 > The temp dir is deleted at disconnect — **unless the mirror dropped batches**
-> (adapter failures that exhausted retries, surfaced as `MirrorErrorMessage`):
+> (terminal append failures — timeouts immediately, other failures after up to
+> three attempts — surfaced as `MirrorErrorMessage`):
 > the store copy is then incomplete and the temp dir holds the only copy of the
 > dropped turns, so the SDK scrubs the credential copies, keeps the transcripts,
 > and warns with the preserved path so you can import them into the store.
@@ -175,6 +176,48 @@ Copy-in reference adapters for **S3, Redis, and Postgres** live in
 [`examples/session_stores/`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_stores/README.md), each with a
 production checklist.
 
+#### Fiber-native adapters
+
+By default the SDK runs every timeout-bounded adapter call (`#append` from the
+mirror batcher, `#load` and friends during resume materialization) on a
+throwaway thread with a hard `Thread#join` timeout, so a wedged adapter can
+never stall the reactor. An adapter whose IO is **entirely
+Fiber-scheduler-aware** (e.g. built on `async`-native clients) can opt out of
+the thread hop by declaring it:
+
+```ruby
+class MyAsyncStore
+  def callback_scheduling = :inline
+  # append/load ...
+end
+```
+
+Declaring `:inline` means the calls run in place on the reactor fiber under a
+**cooperative** timeout. Three consequences to understand before opting in:
+
+- The declaration covers **every method the SDK invokes on the adapter** —
+  `append`, `load`, `list_sessions`, `list_session_summaries`,
+  `list_subkeys` — not just append/load: resume materialization runs the
+  listing calls inline too. **All** blocking inside all of them must yield to
+  the scheduler. Scheduler-opaque blocking (CPU-bound work, GVL-holding C
+  extensions, native drivers the scheduler can't see) stalls every job on
+  that worker **and** the cooperative timeout cannot fire while it blocks.
+- Cancellation semantics change: a timed-out call is interrupted at its next
+  suspension point and its `ensure` blocks run, instead of being abandoned on
+  a thread. The cancellation reaches only the adapter's **own fiber** — work
+  the adapter offloaded (descendant tasks, an already-issued remote write)
+  may still land afterwards. Timed-out appends are therefore **not retried**
+  (same as thread mode; a retry would race that still-landing work), and the
+  interrupted append may remain permanently **half-applied** in the store.
+  The drop is surfaced like every dropped batch — `MirrorErrorMessage` on
+  the stream, `batches_dropped?` on the batcher — and the local transcript
+  remains the source of truth, so nothing is lost from the session itself.
+
+Anything other than `:thread`/`:inline` raises `ArgumentError` when the
+session is set up; without a reactor the hard thread-hop bound still applies
+even for declared adapters. To opt in a third-party fiber-native adapter you
+don't own: `def store.callback_scheduling = :inline` (singleton method).
+
 ### Store-backed helpers
 
 The browsing/mutation helpers above have store-backed counterparts that take a

data/lib/claude_agent_sdk/fiber_boundary.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'async'
+
 module ClaudeAgentSDK
   # Internal. Consumers of the SDK should never need this directly.
   #
@@ -38,11 +40,19 @@ module ClaudeAgentSDK
   # it via a scoped, invalidatable fiber-storage entry instead — see
   # SCHEDULING_KEY / SchedulingScope below.
   #
-  # A `timeout:` always forces the thread hop regardless of scheduling —
-  # `Thread#join(timeout)` is a hard bound that can abandon a wedged call,
-  # which cooperative `with_timeout` cancellation cannot guarantee. The
-  # store-adapter call sites (TranscriptMirrorBatcher, SessionResume) rely
-  # on this to never stall the reactor on a wedged adapter.
+  # A `timeout:` forces the thread hop — `Thread#join(timeout)` is a hard
+  # bound that can abandon a wedged call, which cooperative `with_timeout`
+  # cancellation cannot guarantee — unless the caller passes
+  # `scheduling: :inline` inside a reactor, where the bound becomes a
+  # cooperative `with_timeout` cancellation instead (issue #47 phase 3:
+  # fiber-native SessionStore adapters that declare
+  # `callback_scheduling -> :inline`). The store-adapter call sites
+  # (TranscriptMirrorBatcher, SessionResume) default to the thread hop so
+  # an undeclared (possibly scheduler-opaque) adapter can never stall the
+  # 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.
   #
   # The thread hop severs `break`/`return`/`next` from the surrounding method,
   # so SDK loops yielding user callbacks must keep loop control outside the
@@ -65,8 +75,9 @@ module ClaudeAgentSDK
     class JoinTimeout < StandardError; end
 
     # Cancellation injected into INLINE user callbacks by timeout
-    # enforcement (hook timeouts under scheduling: :inline) — user code
-    # should let it propagate. Deliberately
+    # enforcement (hook timeouts under scheduling: :inline; store-adapter
+    # timeouts for adapters declaring callback_scheduling :inline) — user
+    # code should let it propagate. Deliberately
     # NOT a StandardError: the exception is raised inside user code at a
     # suspension point, and a callback's ordinary `rescue StandardError`
     # must not be able to swallow the cancellation and convert an expired
@@ -97,12 +108,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
 
@@ -129,18 +144,64 @@ module ClaudeAgentSDK
     # Run the given block on a plain thread when a Fiber scheduler is active.
     # Returns the block's value. Exceptions propagate to the caller.
     #
-    # With +timeout+ (seconds) the thread hop happens unconditionally — even
-    # without a scheduler or with `scheduling: :inline` — so the bound is
-    # enforced in plain synchronous code too; JoinTimeout is raised when it
-    # expires.
+    # With +timeout+ (seconds) the thread hop happens regardless of a
+    # scheduler being active, so the bound is enforced in plain synchronous
+    # code too; JoinTimeout is raised when it expires. Exception: with
+    # `scheduling: :inline` INSIDE an Async task, the block instead runs in
+    # place under a cooperative `with_timeout` — the deadline is delivered
+    # as InlineCancellation at the block's next suspension point (its
+    # ensure blocks run; not swallowable by `rescue StandardError`) and
+    # surfaces as the same JoinTimeout, so callers need no changes. When
+    # inline is requested but no Async task is present, the hard
+    # thread-hop bound applies — the timeout guarantee is never lost.
     #
     # 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)
+
+      # Cooperative timeout for inline-declared store adapters: in place on
+      # the reactor fiber, cancelled at the next suspension point. The
+      # wrapper stays ignored on timeout paths (store adapters are never
+      # wrapped), so `body` is the bare block here. The cancellation class
+      # is a fresh per-invocation subclass: rescuing the shared base would
+      # also catch an OUTER timeout's cancellation delivered while this
+      # call is suspended (nested with_timeout — e.g. a store call inside a
+      # timed inline hook), mis-attributing the outer deadline to this call
+      # and letting execution continue past it. An outer cancellation is a
+      # different subclass, so it propagates through untouched.
+      if timeout && scheduling == :inline && (task = Async::Task.current?)
+        cancellation = Class.new(InlineCancellation)
+        begin
+          return task.with_timeout(timeout, cancellation, &block)
+        rescue cancellation
+          raise JoinTimeout, "timed out after #{timeout}s"
+        end
+      end
 
-      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 +216,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 +232,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
@@ -269,8 +270,9 @@ module ClaudeAgentSDK
     end
 
     # Synthesize a `mirror_error` system message and put it on the SDK message
-    # stream so consumers learn a mirror batch was dropped after exhausting
-    # retries. Non-blocking: the message queue is unbounded, so unlike the
+    # stream so consumers learn a mirror batch was dropped (timeouts
+    # immediately, other failures after up to three attempts).
+    # Non-blocking: the message queue is unbounded, so unlike the
     # Python SDK there is no buffer-full drop path.
     def report_mirror_error(key, error)
       session_id = key && (key['session_id'] || key[:session_id])
@@ -570,7 +572,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 +617,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,19 +631,27 @@ 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).
+            # Fresh per-invocation subclass: rescuing the shared base would
+            # also catch an OUTER timeout's cancellation (e.g. an inline
+            # store call nested inside this hook already uses its own), so
+            # each timeout scope must only consume its own deadline.
             begin
-              Async::Task.current.with_timeout(timeout, FiberBoundary::InlineCancellation) do
-                FiberBoundary.invoke(scheduling: :inline) do
+              cancellation = Class.new(FiberBoundary::InlineCancellation)
+              Async::Task.current.with_timeout(timeout, cancellation) do
+                FiberBoundary.invoke(scheduling: :inline, wrapper: @callback_wrapper) do
                   callback.call(hook_input, request_data[:tool_use_id], context)
                 end
               end
-            rescue FiberBoundary::InlineCancellation
+            rescue cancellation
               raise Async::TimeoutError, 'execution expired'
             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 +1004,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 +1019,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/session_resume.rb

@@ -108,6 +108,10 @@ module ClaudeAgentSDK
       return nil if options.resume.nil? && !options.continue_conversation
 
       timeout_s = options.load_timeout_ms / 1000.0
+      # Probed ONCE at materialization entry (the resume path's construction
+      # point) so an invalid callback_scheduling declaration fails fast here,
+      # before any store IO or temp-dir work.
+      scheduling = SessionStores.store_callback_scheduling(store)
       project_key = Sessions.project_key_for_directory(options.cwd)
 
       resolved =
@@ -116,9 +120,9 @@ module ClaudeAgentSDK
           # prevent traversal and match every other resume path.
           return nil unless options.resume.match?(Sessions::UUID_RE)
 
-          load_candidate(store, project_key, options.resume, timeout_s)
+          load_candidate(store, project_key, options.resume, timeout_s, scheduling)
         else
-          resolve_continue_candidate(store, project_key, timeout_s)
+          resolve_continue_candidate(store, project_key, timeout_s, scheduling)
         end
       return nil if resolved.nil?
 
@@ -133,7 +137,7 @@ module ClaudeAgentSDK
         # so it can authenticate. Missing files are fine (API-key auth, etc.).
         copy_auth_files(tmp_base, options.env)
 
-        materialize_subkeys(store, project_dir, project_key, session_id, timeout_s) if SessionStore.implements?(store, :list_subkeys)
+        materialize_subkeys(store, project_dir, project_key, session_id, timeout_s, scheduling) if SessionStore.implements?(store, :list_subkeys)
       rescue Exception # rubocop:disable Lint/RescueException
         # Any failure after mkdtemp leaves tmp_base (which may already hold a
         # .credentials.json copy) on disk with no path for the caller to clean
@@ -149,8 +153,8 @@ module ClaudeAgentSDK
     # -- Helpers --
 
     # Load entries for session_id; return [session_id, entries] or nil if empty.
-    def load_candidate(store, project_key, session_id, timeout_s)
-      entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id}") do
+    def load_candidate(store, project_key, session_id, timeout_s, scheduling)
+      entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id}", scheduling) do
         store.load('project_key' => project_key, 'session_id' => session_id)
       end
       return nil if entries.nil? || entries.empty?
@@ -162,13 +166,13 @@ module ClaudeAgentSDK
     # transcripts are mirrored as ordinary top-level keys and often have the
     # highest mtime, so walk newest->oldest and skip them so --continue resumes
     # the user's conversation, not a subagent's.
-    def resolve_continue_candidate(store, project_key, timeout_s)
-      sessions = with_timeout(timeout_s, 'SessionStore#list_sessions') do
+    def resolve_continue_candidate(store, project_key, timeout_s, scheduling)
+      sessions = with_timeout(timeout_s, 'SessionStore#list_sessions', scheduling) do
         store.list_sessions(project_key)
       end
       return nil if sessions.nil? || sessions.empty?
 
-      sidechain_flags = sidechain_flags_from_summaries(store, project_key, timeout_s)
+      sidechain_flags = sidechain_flags_from_summaries(store, project_key, timeout_s, scheduling)
 
       sessions.sort_by { |s| -sortable_mtime(s['mtime']) }.each do |cand|
         sid = cand['session_id']
@@ -178,7 +182,7 @@ module ClaudeAgentSDK
         # --continue O(sum of transcript sizes) instead of O(candidates).
         next if sidechain_flags&.fetch(sid, false)
 
-        loaded = load_candidate(store, project_key, sid, timeout_s)
+        loaded = load_candidate(store, project_key, sid, timeout_s, scheduling)
         next if loaded.nil?
 
         first = loaded[1][0]
@@ -194,10 +198,10 @@ module ClaudeAgentSDK
     # fails (callers then fall back to checking each full load). The per-load
     # isSidechain check above stays even on the summary path: a missing or
     # stale sidecar row costs one extra load, never a wrong resume.
-    def sidechain_flags_from_summaries(store, project_key, timeout_s)
+    def sidechain_flags_from_summaries(store, project_key, timeout_s, scheduling)
       return nil unless SessionStore.implements?(store, :list_session_summaries)
 
-      rows = with_timeout(timeout_s, 'SessionStore#list_session_summaries') do
+      rows = with_timeout(timeout_s, 'SessionStore#list_session_summaries', scheduling) do
         store.list_session_summaries(project_key)
       end
       Array(rows).each_with_object({}) do |row, acc|
@@ -227,13 +231,17 @@ module ClaudeAgentSDK
 
     # Run a store call (user code) on a plain thread bounded by timeout_s,
     # re-raising failures/timeouts as RuntimeError with context. The thread hop
-    # (FiberBoundary with a timeout always hops) both keeps the async scheduler
-    # out of the user's store code AND enforces load_timeout_ms unconditionally
-    # — including when materialization runs outside an Async reactor, where a
-    # direct call would let a hung adapter block connect forever. A timed-out
-    # worker is left running (not killed) since it may still complete.
-    def with_timeout(timeout_s, what, &block)
-      FiberBoundary.invoke(timeout: timeout_s, &block)
+    # (the default for FiberBoundary with a timeout) both keeps the async
+    # scheduler out of the user's store code AND enforces load_timeout_ms
+    # unconditionally — including when materialization runs outside an Async
+    # reactor, where a direct call would let a hung adapter block connect
+    # forever. A timed-out worker is left running (not killed) since it may
+    # still complete. An adapter declaring `callback_scheduling -> :inline`
+    # (probed once at materialization entry) instead runs in place under a
+    # cooperative timeout when a reactor is present — outside one, the hard
+    # thread-hop bound still applies.
+    def with_timeout(timeout_s, what, scheduling = :thread, &block)
+      FiberBoundary.invoke(timeout: timeout_s, scheduling: scheduling, &block)
     rescue FiberBoundary::JoinTimeout
       raise "#{what} timed out after #{(timeout_s * 1000).to_i}ms during resume materialization"
     rescue RuntimeError
@@ -363,9 +371,9 @@ module ClaudeAgentSDK
     end
 
     # Load and write all subagent transcripts/metadata under session_id.
-    def materialize_subkeys(store, project_dir, project_key, session_id, timeout_s)
+    def materialize_subkeys(store, project_dir, project_key, session_id, timeout_s, scheduling)
       session_dir = File.join(project_dir, session_id)
-      subkeys = with_timeout(timeout_s, "SessionStore#list_subkeys for session #{session_id}") do
+      subkeys = with_timeout(timeout_s, "SessionStore#list_subkeys for session #{session_id}", scheduling) do
         store.list_subkeys('project_key' => project_key, 'session_id' => session_id)
       end
 
@@ -377,7 +385,7 @@ module ClaudeAgentSDK
           next
         end
 
-        sub_entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id} subpath #{subpath}") do
+        sub_entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id} subpath #{subpath}", scheduling) do
           store.load('project_key' => project_key, 'session_id' => session_id, 'subpath' => subpath)
         end
         next if sub_entries.nil? || sub_entries.empty?

data/lib/claude_agent_sdk/session_store.rb

@@ -32,6 +32,32 @@ module ClaudeAgentSDK
   #   - entries: raw JSONL transcript objects (opaque pass-through blobs)
   #   - list_sessions result: [{ 'session_id' => String, 'mtime' => Integer }]
   #   - summary entries: { 'session_id', 'mtime', 'data' } (see SessionSummary)
+  #
+  # FIBER-NATIVE ADAPTERS (issue #47 phase 3): an adapter whose IO is
+  # entirely Fiber-scheduler-aware may additionally define an optional
+  # `callback_scheduling` method returning `:inline` (`:thread` = default
+  # behavior). The SDK then runs the adapter's timeout-bounded calls in place
+  # on the reactor fiber under a cooperative timeout instead of on a
+  # throwaway thread with a hard `Thread#join` bound. The declaration covers
+  # EVERY method the SDK invokes on the adapter — append, load,
+  # list_sessions, list_session_summaries, list_subkeys — not just
+  # append/load: resume materialization inlines the listing calls too. Only
+  # the adapter author can make this call — declare :inline ONLY if every
+  # blocking operation in every method yields to the scheduler;
+  # scheduler-opaque blocking stalls every job on the worker AND escapes the
+  # cooperative deadline. A timed-out inline call is interrupted at its next
+  # suspension point (ensure blocks run) rather than abandoned. The
+  # cancellation reaches only the adapter's own fiber — work the adapter
+  # offloaded (descendant tasks, an already-issued remote write) may still
+  # land afterwards — so timed-out appends are NOT retried (same as thread
+  # mode) and a cancelled append may remain permanently half-applied in the
+  # store. The drop is surfaced (MirrorErrorMessage, batches_dropped?) and
+  # the local transcript remains the source of truth; the
+  # dedupe-by-entry-uuid recommendation above stays advisory. The method is deliberately NOT defined here: the SDK probes
+  # `respond_to?(:callback_scheduling)` (see
+  # SessionStores.store_callback_scheduling), so pure duck-typed adapters
+  # stay minimal, and an app can opt a third-party fiber-native adapter in
+  # via a singleton method (`def store.callback_scheduling = :inline`).
   class SessionStore
     # True if +store+ overrides +method+ rather than inheriting the base
     # implementation that raises NotImplementedError. Works for both subclasses
@@ -249,8 +275,31 @@ module ClaudeAgentSDK
 
   # Internal SessionStore support functions (path mapping, option validation).
   module SessionStores
+    STORE_CALLBACK_SCHEDULING_MODES = %i[thread inline].freeze
+
     module_function
 
+    # Where an adapter's timeout-bounded #append/#load calls run: :thread
+    # (default — hard-bounded thread hop) unless the adapter declares
+    # fiber-nativeness via an optional `callback_scheduling` method returning
+    # :inline (String form coerced, matching ClaudeAgentOptions). Probed
+    # respond_to?-style like the rest of the subsystem. Called once at
+    # construction time (batcher initialize, resume-materialization entry)
+    # so an invalid declaration fails fast there, not mid-session.
+    def store_callback_scheduling(store)
+      return :thread unless store.respond_to?(:callback_scheduling)
+
+      value = store.callback_scheduling
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+      unless STORE_CALLBACK_SCHEDULING_MODES.include?(mode)
+        raise ArgumentError,
+              'session_store#callback_scheduling must return one of ' \
+              "#{STORE_CALLBACK_SCHEDULING_MODES.map(&:inspect).join(', ')} (got #{value.inspect})"
+      end
+
+      mode
+    end
+
     # Derive a SessionKey from an absolute transcript file path.
     #
     #   Main:     <projects_dir>/<project_key>/<session_id>.jsonl

data/lib/claude_agent_sdk/testing/session_store_conformance.rb

@@ -13,9 +13,11 @@ module ClaudeAgentSDK
 
     module_function
 
-    # Assert the 16 SessionStore behavioral contracts against an adapter.
+    # Assert the 17 SessionStore behavioral contracts against an adapter.
     #
     # Contracts 1-14 mirror the Python SDK's run_session_store_conformance.
+    # Contract 17 (Ruby extension) validates the optional
+    # `callback_scheduling` fiber-nativeness declaration (:thread/:inline).
     # Contract 16 (Ruby extension) locks one-row-per-session `list_sessions`
     # under multiple appends — the naive one-row-per-append implementation
     # passed every other contract and then showed N duplicate sessions in
@@ -62,6 +64,7 @@ module ClaudeAgentSDK
       has_delete = optional?(probe, 'delete', skip_optional)
       has_list_subkeys = optional?(probe, 'list_subkeys', skip_optional)
 
+      check_callback_scheduling_declaration(fresh)
       check_append_and_load(fresh, has_list_sessions)
       check_list_sessions(fresh) if has_list_sessions
       check_list_session_summaries(fresh, has_list_sessions, has_delete) if has_list_summaries
@@ -71,6 +74,30 @@ module ClaudeAgentSDK
       nil
     end
 
+    # -- Optional: callback_scheduling declaration ---------------------------
+
+    # 17. an adapter declaring the optional callback_scheduling method (issue
+    # #47 phase 3: fiber-native adapters) must return :thread or :inline —
+    # the SDK probes it at construction and raises ArgumentError otherwise,
+    # so a bad declaration would fail every session using the store. Runs
+    # first because the SDK probes before any store IO; skipped entirely for
+    # non-declaring adapters (the probe defaults to :thread).
+    def check_callback_scheduling_declaration(fresh)
+      store = fresh.call
+      return unless store.respond_to?(:callback_scheduling)
+
+      begin
+        SessionStores.store_callback_scheduling(store)
+      rescue ArgumentError => e
+        assert(false, "callback_scheduling declaration must be :thread or :inline (#{e.message})")
+      rescue StandardError, NotImplementedError => e
+        # A raising declaration is as fatal as a bad value — the SDK probes
+        # it at construction. Report through the harness's documented
+        # ConformanceError instead of leaking the raw exception.
+        assert(false, "callback_scheduling declaration raised #{e.class}: #{e.message}")
+      end
+    end
+
     # -- Required: append + load -------------------------------------------
 
     def check_append_and_load(fresh, has_list_sessions) # rubocop:disable Metrics/MethodLength
@@ -347,8 +374,9 @@ module ClaudeAgentSDK
             "SessionStore conformance failed: #{message}\n  expected: #{expected.inspect}\n  actual:   #{actual.inspect}"
     end
 
-    private_class_method :check_append_and_load, :check_list_sessions, :check_list_session_summaries,
-                         :check_delete, :check_list_subkeys, :check_uuid_dedupe_contract, :key, :entry,
+    private_class_method :check_callback_scheduling_declaration, :check_append_and_load, :check_list_sessions,
+                         :check_list_session_summaries, :check_delete, :check_list_subkeys,
+                         :check_uuid_dedupe_contract, :key, :entry,
                          :epoch_ms?, :optional?, :summaries_by_id, :assert, :assert_eq
   end
 end

data/lib/claude_agent_sdk/transcript_mirror_batcher.rb

@@ -28,7 +28,14 @@ module ClaudeAgentSDK
   # 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).
+  # 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
@@ -50,6 +57,9 @@ module ClaudeAgentSDK
       @projects_dir = projects_dir
       @on_error = on_error
       @send_timeout = send_timeout
+      # Probed ONCE here so an invalid callback_scheduling declaration fails
+      # at construction, not mid-session inside a flush.
+      @store_scheduling = SessionStores.store_callback_scheduling(store)
       @max_pending_entries = max_pending_entries
       @max_pending_bytes = max_pending_bytes
       @pending = []
@@ -203,9 +213,18 @@ module ClaudeAgentSDK
           succeeded = true
           break
         when :timeout
-          # Don't retry on timeout: the in-flight call may still land, so a
-          # retry would launch a concurrent duplicate. Also bounds worst-case
-          # lock hold at ~send_timeout rather than ~3x.
+          # Don't retry on timeout — in EITHER mode. Thread mode: the
+          # abandoned in-flight call may still land, so a retry would launch
+          # a concurrent duplicate. Inline mode: cooperative cancellation
+          # interrupts only the adapter's own fiber — work the adapter
+          # itself offloaded (descendant tasks, an already-issued remote
+          # write) may still land after the cancellation, so a retry races
+          # it exactly like the thread case (adversarially demonstrated in
+          # review: a dedupe-conforming adapter still persisted duplicates).
+          # Uniform no-retry also bounds worst-case lock hold at
+          # ~send_timeout. The dropped batch is surfaced (MirrorErrorMessage,
+          # batches_dropped?) and the local transcript remains the source of
+          # truth.
           last_err = err
           break
         else # :error — retryable
@@ -222,11 +241,16 @@ module ClaudeAgentSDK
 
     # Run SessionStore#append (user code) on a plain thread via FiberBoundary,
     # bounded by send_timeout (enforced with or without an active reactor).
-    # Returns [:ok, nil] / [:timeout, err] / [:error, err]. On timeout the
-    # worker thread is left running (cancellation is best-effort; the in-flight
-    # call may still land) and not retried.
+    # Returns [:ok, nil] / [:timeout, err] / [:error, err]. On timeout in
+    # thread mode the worker thread is left running (cancellation is
+    # best-effort; the in-flight call may still land) and not retried. An
+    # adapter declaring `callback_scheduling -> :inline` instead runs in
+    # place on the reactor under a cooperative timeout (interrupted at its
+    # next suspension point, ensure blocks run) — same JoinTimeout contract
+    # and same no-retry semantics (see append_with_retry: offloaded work
+    # may outlive the cancellation).
     def invoke_append(key, entries)
-      FiberBoundary.invoke(timeout: @send_timeout) { @store.append(key, entries) }
+      FiberBoundary.invoke(timeout: @send_timeout, scheduling: @store_scheduling) { @store.append(key, entries) }
       [:ok, nil]
     rescue FiberBoundary::JoinTimeout
       [:timeout, "append timed out after #{@send_timeout}s"]

data/lib/claude_agent_sdk/types.rb

@@ -290,9 +290,11 @@ module ClaudeAgentSDK
     attr_accessor :uuid, :session_id, :content
   end
 
-  # Emitted when a session_store mirror batch exhausts its retries and is
-  # dropped. The local-disk transcript is still durable; this is the consumer's
-  # only signal that the external store missed a batch (at-most-once delivery).
+  # Emitted when a session_store mirror batch fails terminally and is
+  # dropped — timeouts immediately (never retried), other failures after up
+  # to three attempts. The local-disk transcript is still durable; this is
+  # the consumer's only signal that the external store missed a batch
+  # (at-most-once delivery).
   class MirrorErrorMessage < SystemMessage
     attr_accessor :uuid, :session_id, :error, :key
   end
@@ -1576,7 +1578,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 +1706,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.27.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.27.0
 platform: ruby
 authors:
 - Community Contributors