claude-agent-sdk 0.26.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4e4fcd2fa1c18916f41409482c8edfe3367ea5b06db9a90b80ed168f339a45e
-  data.tar.gz: 3726daa4aa431b4dba5cd181433066bc8f541efbe13984799c8642bfc671e75e
+  metadata.gz: 5a12b68451568e5428820499fb4bf42401596477ea74d6b25a8fad3637b70178
+  data.tar.gz: d0465a73a3cbe17d3775d65d83978c16527548f9f752f8786b606f2c8c1c3713
 SHA512:
-  metadata.gz: 00cb37c301d1c1eae778bd55b0d19330e21b6069a0943a6cd7a7931da4d32d8da847c8362f102d530aed8cdcf66f28eb9ca57ac248ed5ce2cbcd5609b3435ab0
-  data.tar.gz: 0bcabed11ba7e49c78ab383bf1186d39cd65873e1190f13a7cbfc102f1c2c7f0226fc8604818f3fc4cf3706760334abb5bc82a7c9ab6e6c9d1e178fd3a1c3002
+  metadata.gz: 8051e5090a5361c74eb67506cec3021c69da07e9150b41cce91c674af759f7f03a3b9547e08abf0297f17bd32441cc3d04e1ea62fb92c47168841fd9991e5669
+  data.tar.gz: c70f056865cd07758f372b35bf7e8a14571f88b4ae4189c41ef26309a637068593293d1057aba021c8c4d184821a384962e7547048d66d2c615090067d796231

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.28.0] - 2026-07-31
+
+### Changed
+- **`callback_wrapper` now composes around timeout-bounded SessionStore adapter dispatch** (mirror-batcher appends and every resume-materialization store call), inside the timeout bound — on the worker thread in the default thread-hop mode, inside the cooperative timeout for inline-declared adapters. A Rails `executor.wrap` wrapper therefore covers an ActiveRecord-backed store adapter too: connections check out and back in per call instead of stranding on the throwaway thread. The bound itself is unchanged (`JoinTimeout` semantics, no-retry-on-timeout); a wrapper-raised error is treated like a store error (retryable on the batcher path). Previously the timeout path silently ignored the wrapper.
+
+### Fixed
+- `SdkMcpServer#callback_scheduling=` / `#callback_wrapper=` now validate like their `ClaudeAgentOptions` counterparts: the String form (`"inline"`) is coerced to the Symbol, and invalid values raise `ArgumentError` at set time. Previously the bare accessors accepted anything, and because the dispatch layer special-cases only the exact Symbol `:inline`, a String or typo silently degraded to the thread hop — the opposite of what an inline host asked for.
+- The once-per-process `:inline`-under-`isolation_level = :thread` warning is now emitted under a mutex, closing a benign race where two sessions connecting concurrently could both warn.
+
+## [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. An invalid declared value fails fast with `ArgumentError` at construction, and a declaration that itself raises propagates its own exception at the same construction point rather than mid-session (conformance contract 17 covers both). Apps can opt a third-party fiber-native adapter in via `def store.callback_scheduling = :inline`.
+
 ## [0.26.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.26.0'
+gem 'claude-agent-sdk', '~> 0.28.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.

data/docs/rails.md

@@ -35,6 +35,8 @@ 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.
 
+The wrapper also composes around every timeout-bounded `SessionStore` adapter call (mirror-batcher appends, resume-materialization loads and listings), inside the timeout bound — so an ActiveRecord-backed store adapter gets the same connection hygiene as your callbacks.
+
 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`
@@ -80,7 +82,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. In both cases a configured `callback_wrapper` composes around the adapter call inside the bound.
 
 ## 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,54 @@ 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).
+
+A session-configured `callback_wrapper` (see docs/rails.md) composes around
+every one of these adapter calls, inside the timeout bound — on the worker
+thread for default adapters, inside the cooperative timeout for inline
+declarers (the cancellation passes through the wrapper un-swallowed and the
+wrapper's `ensure` runs at cancellation).
+
 ### 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.
   #
@@ -36,13 +38,21 @@ module ClaudeAgentSDK
   # suspension points would leak across sessions). The one path a call
   # argument cannot cross (SDK-MCP dispatch through the mcp gem) carries
   # it via a scoped, invalidatable fiber-storage entry instead — see
-  # SCHEDULING_KEY / SchedulingScope below.
+  # DISPATCH_KEY / CallbackDispatchScope 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
@@ -77,16 +88,16 @@ module ClaudeAgentSDK
     class InlineCancellation < Exception; end # rubocop:disable Lint/InheritException
 
     # Fiber-storage key carrying the dispatching session's callback
-    # scheduling mode across the SDK-MCP dispatch path (Query ->
-    # MCP::Server -> dynamic tool class). Fiber storage is per-fiber, so
+    # dispatch pair (scheduling mode + wrapper) across the SDK-MCP dispatch
+    # path (Query -> MCP::Server -> dynamic tool class). Fiber storage is per-fiber, so
     # concurrent sessions with different modes sharing one SdkMcpServer
     # instance cannot cross-contaminate — unlike mutating the shared
     # server (last-writer-wins, persists past close) or a thread-local
     # (the reactor thread is shared by many fibers).
     # @api private
-    SCHEDULING_KEY = :claude_agent_sdk_callback_scheduling
+    DISPATCH_KEY = :claude_agent_sdk_callback_dispatch
 
-    # The value stored under SCHEDULING_KEY: a
+    # The value stored under DISPATCH_KEY: a
     # closable carrier rather than a bare symbol. Fiber-storage inheritance
     # copies the storage HASH but shares value REFERENCES, so every fiber
     # (and thread) created during a dispatch inherits this same object.
@@ -101,7 +112,7 @@ module ClaudeAgentSDK
     # 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
+    class CallbackDispatchScope
       attr_reader :mode, :wrapper
 
       def initialize(mode, wrapper = nil)
@@ -133,10 +144,16 @@ 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
@@ -158,13 +175,30 @@ module ClaudeAgentSDK
     # 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.
+    # On timeout-bounded calls (the store-adapter paths:
+    # TranscriptMirrorBatcher, SessionResume) the wrapper composes INSIDE
+    # the bound: on the worker thread within the `Thread#join` deadline in
+    # :thread mode (so `executor.wrap` covers an AR-backed store adapter —
+    # connections check back in when the call ends; on a timeout the
+    # abandoned worker still runs the wrapper's ensure whenever the wedged
+    # call eventually finishes), and inside the cooperative `with_timeout`
+    # in inline mode (the cancellation passes through the wrapper
+    # un-swallowed — InlineCancellation is not a StandardError — and the
+    # wrapper's ensure runs at cancellation).
     def invoke(timeout: nil, scheduling: :thread, wrapper: nil, &block)
-      body = wrapper && timeout.nil? ? -> { wrapper.call(block) } : block
+      body = wrapper ? -> { 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 (delivery
+      # and translation mechanics live in .with_cooperative_timeout). The
+      # wrapper is already composed into `body`, so it sits inside the
+      # timeout scope.
+      if timeout && scheduling == :inline && (task = Async::Task.current?)
+        expired = -> { JoinTimeout.new("timed out after #{timeout}s") }
+        return with_cooperative_timeout(task, timeout, on_timeout: expired) { body.call }
+      end
+
       thread = Thread.new(&body)
       thread.report_on_exception = false
       return thread.value if timeout.nil?
@@ -173,6 +207,36 @@ module ClaudeAgentSDK
       thread.value
     end
 
+    # Run +block+ on +task+ bounded by a cooperative +timeout+: the deadline
+    # is delivered INSIDE user code as an InlineCancellation at the block's
+    # next suspension point (ensure blocks run; a callback's ordinary
+    # `rescue StandardError` cannot swallow it), then translated into the
+    # exception built by +on_timeout+ (a zero-arg callable) once control has
+    # returned from user code — each call site keeps its own outward
+    # contract (JoinTimeout on the store-adapter path in .invoke,
+    # Async::TimeoutError on the inline hook path in Query).
+    #
+    # 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. an
+    # inline store call nested 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.
+    #
+    # Wrapper composition is the caller's choice — +block+ runs verbatim
+    # inside the timeout scope (.invoke composes the callback wrapper into
+    # its body beforehand; the hook path composes it inside the block).
+    # @api private
+    def with_cooperative_timeout(task, timeout, on_timeout:, &block)
+      cancellation = Class.new(InlineCancellation)
+      begin
+        task.with_timeout(timeout, cancellation, &block)
+      rescue cancellation
+        raise on_timeout.call
+      end
+    end
+
     # Invoke a user-supplied iteration block across the boundary. The thread
     # hop severs `break` from the surrounding loop, surfacing as
     # LocalJumpError(reason: :break) on the worker thread; translate it into

data/lib/claude_agent_sdk/query.rb

@@ -270,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])
@@ -628,20 +629,21 @@ module ClaudeAgentSDK
             # Async::TimeoutError is a StandardError — a hook's ordinary
             # `rescue StandardError` would swallow the cancellation and
             # 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. The
-            # wrapper composes INSIDE with_timeout, and the cancellation
+            # the deadline). FiberBoundary.with_cooperative_timeout injects
+            # a non-StandardError cancellation instead (fresh subclass per
+            # scope — the nested-scope rationale lives on the helper),
+            # translated back once control leaves user code so the outward
+            # contract (Async::TimeoutError) is unchanged. The wrapper
+            # composes INSIDE the timeout scope, 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, wrapper: @callback_wrapper) do
-                  callback.call(hook_input, request_data[:tool_use_id], context)
-                end
+            FiberBoundary.with_cooperative_timeout(
+              Async::Task.current, timeout,
+              on_timeout: -> { Async::TimeoutError.new('execution expired') }
+            ) do
+              FiberBoundary.invoke(scheduling: :inline, wrapper: @callback_wrapper) do
+                callback.call(hook_input, request_data[:tool_use_id], context)
               end
-            rescue FiberBoundary::InlineCancellation
-              raise Async::TimeoutError, 'execution expired'
             end
           else
             Async::Task.current.with_timeout(timeout) do
@@ -1005,16 +1007,16 @@ module ClaudeAgentSDK
       # 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:
+      # closable CallbackDispatchScope, closed + restored in the ensure below:
       # fibers/threads created during the dispatch inherit the same scope
       # OBJECT (storage inheritance copies the hash, shares references), so
       # closing it invalidates the mode for every inheritor at once — a
       # child task that outlives the dispatch cannot carry the session mode
       # 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, @callback_wrapper)
-      Fiber[FiberBoundary::SCHEDULING_KEY] = dispatch_scope
+      previous_dispatch = Fiber[FiberBoundary::DISPATCH_KEY]
+      dispatch_scope = FiberBoundary::CallbackDispatchScope.new(@callback_scheduling, @callback_wrapper)
+      Fiber[FiberBoundary::DISPATCH_KEY] = dispatch_scope
 
       # Convert server_name to symbol if needed for hash lookup
       server_key = @sdk_mcp_servers.key?(server_name) ? server_name : server_name.to_sym
@@ -1066,7 +1068,7 @@ module ClaudeAgentSDK
       }
     ensure
       dispatch_scope&.close
-      Fiber[FiberBoundary::SCHEDULING_KEY] = previous_scheduling
+      Fiber[FiberBoundary::DISPATCH_KEY] = previous_dispatch
     end
 
     def handle_mcp_initialize(server, message)

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -88,19 +88,46 @@ module ClaudeAgentSDK
     # storage instead (see #effective_callback_scheduling) — a server
     # shared by concurrent sessions with different modes is never mutated,
     # so modes cannot cross-contaminate or persist past a session.
-    attr_accessor :callback_scheduling
+    attr_reader :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
+    attr_reader :callback_wrapper
+
+    # Same coercion + whitelist rule as ClaudeAgentOptions#callback_scheduling
+    # (String form coerced to Symbol, anything else raises). FiberBoundary
+    # only special-cases the exact Symbol :inline, so an unvalidated value —
+    # e.g. the String "inline" or a typo — would silently degrade to the
+    # thread hop, which is precisely what an inline host must not get. Unlike
+    # the options setter there is no nil form: the server always holds a
+    # concrete default (:thread from #initialize).
+    def callback_scheduling=(value)
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+      unless ClaudeAgentOptions::CALLBACK_SCHEDULING_MODES.include?(mode)
+        raise ArgumentError,
+              'callback_scheduling must be one of ' \
+              "#{ClaudeAgentOptions::CALLBACK_SCHEDULING_MODES.map(&:inspect).join(', ')} (got #{value.inspect})"
+      end
+
+      @callback_scheduling = mode
+    end
+
+    # Same rule as ClaudeAgentOptions#callback_wrapper: callable or nil.
+    # Validated at set time so a non-callable fails here, not later as a
+    # NoMethodError inside a tool dispatch.
+    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
 
     # Internal — public only so the dynamic tool classes can reach it. The
     # (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
+    # live CallbackDispatchScope 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
@@ -111,7 +138,7 @@ module ClaudeAgentSDK
     # @api private
     # @return [Array(Symbol, #call)] `[scheduling, wrapper]`
     def effective_callback_dispatch
-      scope = Fiber[FiberBoundary::SCHEDULING_KEY]
+      scope = Fiber[FiberBoundary::DISPATCH_KEY]
       if scope&.active?
         [scope.mode, scope.wrapper]
       else

data/lib/claude_agent_sdk/session_resume.rb

@@ -87,13 +87,14 @@ module ClaudeAgentSDK
     # locate the projects dir (already repointed at the temp dir when resuming
     # from a store). Eager flush mode zeroes the buffer thresholds so every
     # transcript_mirror frame triggers a background flush.
-    def build_mirror_batcher(store:, env:, on_error:, eager: false)
+    def build_mirror_batcher(store:, env:, on_error:, eager: false, callback_wrapper: nil)
       TranscriptMirrorBatcher.new(
         store: store,
         projects_dir: SessionStores.projects_dir(env),
         on_error: on_error,
         max_pending_entries: eager ? 0 : TranscriptMirrorBatcher::MAX_PENDING_ENTRIES,
-        max_pending_bytes: eager ? 0 : TranscriptMirrorBatcher::MAX_PENDING_BYTES
+        max_pending_bytes: eager ? 0 : TranscriptMirrorBatcher::MAX_PENDING_BYTES,
+        callback_wrapper: callback_wrapper
       )
     end
 
@@ -108,6 +109,14 @@ 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)
+      # The session's callback_wrapper composes around every store call below,
+      # inside the timeout bound (see FiberBoundary.invoke) — so e.g. Rails'
+      # executor.wrap covers an AR-backed adapter during materialization too.
+      wrapper = options.callback_wrapper
       project_key = Sessions.project_key_for_directory(options.cwd)
 
       resolved =
@@ -116,9 +125,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, wrapper)
         else
-          resolve_continue_candidate(store, project_key, timeout_s)
+          resolve_continue_candidate(store, project_key, timeout_s, scheduling, wrapper)
         end
       return nil if resolved.nil?
 
@@ -133,7 +142,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, wrapper) 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 +158,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, wrapper)
+      entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id}", scheduling, wrapper) do
         store.load('project_key' => project_key, 'session_id' => session_id)
       end
       return nil if entries.nil? || entries.empty?
@@ -162,13 +171,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, wrapper)
+      sessions = with_timeout(timeout_s, 'SessionStore#list_sessions', scheduling, wrapper) 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, wrapper)
 
       sessions.sort_by { |s| -sortable_mtime(s['mtime']) }.each do |cand|
         sid = cand['session_id']
@@ -178,7 +187,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, wrapper)
         next if loaded.nil?
 
         first = loaded[1][0]
@@ -194,10 +203,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, wrapper)
       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, wrapper) do
         store.list_session_summaries(project_key)
       end
       Array(rows).each_with_object({}) do |row, acc|
@@ -227,13 +236,19 @@ 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. The session's callback_wrapper
+    # composes inside the bound (see FiberBoundary.invoke); a wrapper-raised
+    # error surfaces like a store error, with the same context message.
+    def with_timeout(timeout_s, what, scheduling = :thread, wrapper = nil, &block)
+      FiberBoundary.invoke(timeout: timeout_s, scheduling: scheduling, wrapper: wrapper, &block)
     rescue FiberBoundary::JoinTimeout
       raise "#{what} timed out after #{(timeout_s * 1000).to_i}ms during resume materialization"
     rescue RuntimeError
@@ -363,9 +378,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, wrapper)
       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, wrapper) do
         store.list_subkeys('project_key' => project_key, 'session_id' => session_id)
       end
 
@@ -377,7 +392,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, wrapper) 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
@@ -44,12 +51,22 @@ module ClaudeAgentSDK
     # @param projects_dir [String] base dir for file_path -> SessionKey mapping
     # @param on_error [#call] called as on_error.call(key, message) after a batch
     #   exhausts retries; must not raise
+    # @param callback_wrapper [#call, nil] the session's
+    #   ClaudeAgentOptions#callback_wrapper, composed around each #append
+    #   inside the timeout bound (worker thread in :thread mode, cooperative
+    #   timeout in :inline mode) — so e.g. Rails' executor.wrap covers an
+    #   AR-backed adapter and checks connections back in per call
     def initialize(store:, projects_dir:, on_error:, send_timeout: SEND_TIMEOUT_SECONDS,
-                   max_pending_entries: MAX_PENDING_ENTRIES, max_pending_bytes: MAX_PENDING_BYTES)
+                   max_pending_entries: MAX_PENDING_ENTRIES, max_pending_bytes: MAX_PENDING_BYTES,
+                   callback_wrapper: nil)
       @store = store
       @projects_dir = projects_dir
       @on_error = on_error
       @send_timeout = send_timeout
+      @callback_wrapper = callback_wrapper
+      # 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 +220,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 +248,20 @@ 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). The session's callback_wrapper composes
+    # inside the bound (see FiberBoundary.invoke); a wrapper-raised error is
+    # indistinguishable from a store error here — [:error, e], retryable.
     def invoke_append(key, entries)
-      FiberBoundary.invoke(timeout: @send_timeout) { @store.append(key, entries) }
+      FiberBoundary.invoke(timeout: @send_timeout, scheduling: @store_scheduling, wrapper: @callback_wrapper) do
+        @store.append(key, entries)
+      end
       [: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

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -114,6 +114,11 @@ module ClaudeAgentSDK
     FiberBoundary.invoke(&block)
   end
 
+  # Guards the once-per-process flag below: two sessions connecting
+  # concurrently must not both pass the unset check and warn twice.
+  INLINE_ISOLATION_WARN_LOCK = Mutex.new
+  private_constant :INLINE_ISOLATION_WARN_LOCK
+
   # Internal: warn once per process when :inline callback scheduling is
   # enabled while ActiveSupport reports thread isolation — the host then
   # almost certainly violates inline mode's fiber-isolation precondition
@@ -121,11 +126,14 @@ module ClaudeAgentSDK
   # defined? probing only; the SDK never loads ActiveSupport itself.
   def self.check_inline_isolation(scheduling)
     return unless scheduling == :inline
-    return if @inline_isolation_warned
     return unless defined?(ActiveSupport::IsolatedExecutionState)
     return unless ActiveSupport::IsolatedExecutionState.isolation_level == :thread
 
-    @inline_isolation_warned = true
+    INLINE_ISOLATION_WARN_LOCK.synchronize do
+      return if @inline_isolation_warned
+
+      @inline_isolation_warned = true
+    end
     warn 'ClaudeAgentSDK: callback_scheduling: :inline is enabled but ' \
          'ActiveSupport::IsolatedExecutionState.isolation_level is :thread. ' \
          'Inline callbacks run on reactor fibers that share one thread, so ' \
@@ -539,7 +547,8 @@ module ClaudeAgentSDK
               store: configured_options.session_store,
               env: configured_options.env,
               on_error: ->(key, message) { query_handler.report_mirror_error(key, message) },
-              eager: configured_options.session_store_flush.to_s == 'eager'
+              eager: configured_options.session_store_flush.to_s == 'eager',
+              callback_wrapper: callback_wrapper
             )
           )
         end
@@ -1149,7 +1158,8 @@ module ClaudeAgentSDK
         store: options.session_store,
         env: options.env,
         on_error: ->(key, message) { @query_handler.report_mirror_error(key, message) },
-        eager: options.session_store_flush.to_s == 'eager'
+        eager: options.session_store_flush.to_s == 'eager',
+        callback_wrapper: @callback_wrapper
       )
       @query_handler.set_transcript_mirror_batcher(batcher)
     end

metadata

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