claude-agent-sdk 0.27.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 760ec1fb0cf80f6e56d7b5d3adb20ca2956b209d0961020ae36fa52a13e28144
-  data.tar.gz: 6ba365de4438e4081f9bfa47afadc4859d9a001bb6238c0b66f00437cb032626
+  metadata.gz: 5a12b68451568e5428820499fb4bf42401596477ea74d6b25a8fad3637b70178
+  data.tar.gz: d0465a73a3cbe17d3775d65d83978c16527548f9f752f8786b606f2c8c1c3713
 SHA512:
-  metadata.gz: 672d6640b3bdefc6c5d9cf599c41b89b6259107f780981da382b18bfa56180788225d5e278ab9a7ef22e79a09a000b48147a1a285b74182b5f4254d8d8ec474e
-  data.tar.gz: 0b6eff840de87f744de373bea259fd89a36ca1af33fbc2c678ac84296115b9a5fad841941feabaeb8ebda9c8333d6f4d72a380379c09c410e6358c571af1b26b
+  metadata.gz: 8051e5090a5361c74eb67506cec3021c69da07e9150b41cce91c674af759f7f03a3b9547e08abf0297f17bd32441cc3d04e1ea62fb92c47168841fd9991e5669
+  data.tar.gz: c70f056865cd07758f372b35bf7e8a14571f88b4ae4189c41ef26309a637068593293d1057aba021c8c4d184821a384962e7547048d66d2c615090067d796231

data/CHANGELOG.md

@@ -7,10 +7,19 @@ 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. 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`.
+- **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
 

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.27.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`) 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.
+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

@@ -218,6 +218,12 @@ 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

@@ -38,7 +38,7 @@ 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:` forces the thread hop — `Thread#join(timeout)` is a hard
   # bound that can abandon a wedged call, which cooperative `with_timeout`
@@ -88,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.
@@ -112,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)
@@ -175,30 +175,28 @@ 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. 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.
+      # 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?)
-        cancellation = Class.new(InlineCancellation)
-        begin
-          return task.with_timeout(timeout, cancellation, &block)
-        rescue cancellation
-          raise JoinTimeout, "timed out after #{timeout}s"
-        end
+        expired = -> { JoinTimeout.new("timed out after #{timeout}s") }
+        return with_cooperative_timeout(task, timeout, on_timeout: expired) { body.call }
       end
 
       thread = Thread.new(&body)
@@ -209,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

@@ -629,25 +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).
-            # 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
-              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
+            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 cancellation
-              raise Async::TimeoutError, 'execution expired'
             end
           else
             Async::Task.current.with_timeout(timeout) do
@@ -1011,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
@@ -1072,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
 
@@ -112,6 +113,10 @@ module ClaudeAgentSDK
       # 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 =
@@ -120,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, scheduling)
+          load_candidate(store, project_key, options.resume, timeout_s, scheduling, wrapper)
         else
-          resolve_continue_candidate(store, project_key, timeout_s, scheduling)
+          resolve_continue_candidate(store, project_key, timeout_s, scheduling, wrapper)
         end
       return nil if resolved.nil?
 
@@ -137,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, scheduling) 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
@@ -153,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, scheduling)
-      entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id}", scheduling) 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?
@@ -166,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, scheduling)
-      sessions = with_timeout(timeout_s, 'SessionStore#list_sessions', scheduling) 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, scheduling)
+      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']
@@ -182,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, scheduling)
+        loaded = load_candidate(store, project_key, sid, timeout_s, scheduling, wrapper)
         next if loaded.nil?
 
         first = loaded[1][0]
@@ -198,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, scheduling)
+    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', scheduling) 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|
@@ -239,9 +244,11 @@ module ClaudeAgentSDK
     # 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)
+    # 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
@@ -371,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, scheduling)
+    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}", scheduling) 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
 
@@ -385,7 +392,7 @@ module ClaudeAgentSDK
           next
         end
 
-        sub_entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id} subpath #{subpath}", scheduling) 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/transcript_mirror_batcher.rb

@@ -51,12 +51,19 @@ 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)
@@ -248,9 +255,13 @@ module ClaudeAgentSDK
     # 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).
+    # 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, scheduling: @store_scheduling) { @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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '0.27.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.27.0
+  version: 0.28.0
 platform: ruby
 authors:
 - Community Contributors