claude-agent-sdk 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34802f2c21bd1cf77053b627b48032fa448a616d17379f0c788cee879d12d8ba
-  data.tar.gz: 8f44d432159c6fba9dc453a30702d7a215527a5a52ab9398082e3ef53b1bf037
+  metadata.gz: 48fe05a71686f61555d5985ac8fe92e5d08b1ac530f1c2e2bb071f4d6b0fdb81
+  data.tar.gz: 669eedb9627e578e893e3e214271c172a0169d07fd9f60493c5c2d47c5540acb
 SHA512:
-  metadata.gz: 061a1e5c1bea501e9ced4a7a31a893e633b2b5e8f345ae0b28b94959ff2ec5ad2594fd7374be4eefe67bfbcc57d023d364960721f3a81c0f044ee26b57bb35db
-  data.tar.gz: 96be886af087aab90fddf8355d858f7e2cf7d31c122e30bee6554a56e20f2a45d970ba80f5026d214a5491beca588cae5c7c03028b49a41868ae0a7172562a04
+  metadata.gz: 7efcdba28fd54e81ddbf4b24ae01e14fde11c9c111f39241f65901eb23453d938e4e1be0fee3493fc034f0e81f0ec8373664d68a061d029b280e01f2a7ed4ad0
+  data.tar.gz: 2fb7a50378cb0bd44408b2d31737bd4fc1ec51162473e1417dcd1be58c851b5e369c9de9313edfa48425a5e36d058ccade91cf47bf5681251eeb9fa3c2a89031

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-07-31
+
+### Added
+- **Opt-in fiber-native callback execution: `callback_scheduling: :inline`** (#47). By default the SDK hops every user callback (message blocks, hooks, permission callbacks, SDK MCP handlers, observers) to a plain thread so thread-keyed libraries (ActiveRecord, pg, …) never see the async gem's Fiber scheduler. Hosts that are fiber-isolated end to end — e.g. solid_queue fiber workers (`fibers: N`) with `ActiveSupport::IsolatedExecutionState.isolation_level = :fiber` — can now pass `ClaudeAgentOptions.new(callback_scheduling: :inline)` (or set it globally via `ClaudeAgentSDK.configure`) to run callbacks in place on the reactor fiber: `Fiber.scheduler` is live inside callbacks, no per-call threads exist to strand AR connections, and the session can live directly on the job fiber. This matches the Python SDK's execution model (async callbacks run natively on the event loop). Default behavior is unchanged. In `:inline` mode hook timeouts become cooperative cancellations (the hook is interrupted at its next suspension point and its `ensure` blocks run) instead of hard thread abandonment; `SessionStore` adapter calls intentionally stay on threads so a wedged adapter can never stall the reactor. The SDK warns once when `:inline` is enabled under `isolation_level == :thread`. See "Fiber workers (solid_queue)" in docs/rails.md.
+- `ClaudeAgentSDK.offload { }` — public escape hatch for `:inline` hosts: runs a heavy piece of a callback on a plain thread instead of the reactor fiber. Shields the reactor from scheduler-opaque blocking that releases the GVL (native DB drivers, file/socket I/O); turns pure-Ruby CPU work into GVL time-slicing instead of a hard stall. A C extension that holds the GVL for the whole computation still freezes the process — move such work to a subprocess. No-op outside a reactor.
+
 ## [0.24.0] - 2026-07-27
 
 Parity batch with the Python SDK v0.2.111–v0.2.128 (everything substantive in that span; the rest is bundled-CLI version bumps, which don't apply to this gem).

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.24.0'
+gem 'claude-agent-sdk', '~> 0.25.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.
@@ -210,7 +210,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 | Structured output, thinking config, budget, fallback model, advisor model, beta features, sandbox, bare mode, file checkpointing | [docs/configuration.md](docs/configuration.md) |
 | Session listing, reading, renaming, tagging, deleting, forking, resume-at-message | [docs/sessions.md](docs/sessions.md) |
 | OpenTelemetry tracing, Langfuse setup, custom observers | [docs/observability.md](docs/observability.md) |
-| Rails integration (fiber safety, ActionCable, sessions, jobs, HTTP MCP, observability initializer) | [docs/rails.md](docs/rails.md) |
+| Rails integration (fiber safety, solid_queue fiber workers / `callback_scheduling: :inline`, ActionCable, sessions, jobs, HTTP MCP, observability initializer) | [docs/rails.md](docs/rails.md) |
 | Message, content block, and configuration type reference | [docs/types.md](docs/types.md) |
 | Error handling, exception hierarchy, timeout configuration | [docs/errors.md](docs/errors.md) |
 

data/docs/rails.md

@@ -6,7 +6,7 @@ The SDK integrates well with Rails applications. Below are the common patterns.
 
 The SDK depends on [`async`](https://github.com/socketry/async), which installs a Fiber scheduler that multiplexes fibers onto a single OS thread and intercepts IO so blocking calls yield to siblings. Most mature Ruby libraries are thread-safe but not fiber-safe — they key state (checked-out DB connections, per-thread caches, request stores) on `Thread.current`. When the scheduler interleaves two fibers on one thread, those fibers share the same state slot, and interleaved IO on a shared connection silently corrupts wire protocols. This affects every DB driver keyed by thread (`pg`, `mysql2`, `sqlite3`), ActiveRecord's connection pool, and HTTP/cache clients pooled per thread.
 
-You do **not** need to think about this. The SDK hops to a plain thread at every user-callback boundary — message blocks given to `query` / `Client`, SDK MCP tool handlers, hooks, permission callbacks, and observer methods — so your code runs with no Fiber scheduler active and inherits the ordinary thread-keyed assumptions every Rails / Sidekiq / Kamal app already makes:
+You do **not** need to think about this. By default (`callback_scheduling: :thread`; see the fiber-workers section below for the opt-in alternative) the SDK hops to a plain thread at every user-callback boundary — message blocks given to `query` / `Client`, SDK MCP tool handlers, hooks, permission callbacks, and observer methods — so your code runs with no Fiber scheduler active and inherits the ordinary thread-keyed assumptions every Rails / Sidekiq / Kamal app already makes:
 
 ```ruby
 tool = ClaudeAgentSDK.create_tool('lookup_user', 'Look up a user', { id: Integer }) do |args|
@@ -21,6 +21,51 @@ 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.
 
+## 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:
+
+```ruby
+# config/application.rb
+ActiveSupport::IsolatedExecutionState.isolation_level = :fiber
+```
+
+On Rails 7.2+, ActiveRecord releases connections between queries under fiber isolation, so fiber counts can far exceed the pool size (e.g. 50 fibers on 25 connections).
+
+In such a host the default thread hop works *against* you: every callback is ejected from the reactor onto a fresh bare thread, where `Fiber.scheduler` is `nil` (reactor APIs like `Async::Task#stop` / `Async::Notification` are unusable), and an implicitly checked-out AR connection dies with the throwaway thread (stranded until the reaper reclaims it). For these hosts the SDK offers opt-in inline scheduling:
+
+```ruby
+# config/initializers/claude_agent_sdk.rb — process-wide, matching
+# isolation_level's process-wide nature. Only set this in processes that run
+# fiber workers; or pass it per-session via ClaudeAgentOptions instead.
+ClaudeAgentSDK.configure do |config|
+  config.default_options = { callback_scheduling: :inline }
+end
+```
+
+With `:inline`, every user callback — message blocks, hooks, permission callbacks, SDK MCP handlers, observers — runs in place on the reactor fiber of the job. This is the same execution model as the Python SDK (async callbacks run natively on the event loop). Concretely:
+
+- `Fiber.scheduler` is live inside callbacks; reactor primitives work directly. DB access goes through the Rails 7.2+ fiber-aware pool under the same assumptions as the rest of your fiber-worker jobs.
+- No per-call threads exist, so nothing can strand an AR connection.
+- The whole SDK session can live directly on the job fiber — no bridge threads. `Client#connect` already requires an Async context, and the transport's pipe I/O is scheduler-aware.
+- Hook timeouts become **cooperative**: a timed-out inline hook is cancelled at its next suspension point (its `ensure` blocks run), instead of being abandoned on a worker thread. A CPU-stuck hook cannot be timed out.
+- The CLI's cancellation of an in-flight callback (e.g. permission prompt superseded) can now actually interrupt it at a suspension point.
+
+The one real risk: **scheduler-opaque blocking stalls the whole reactor.** CPU-bound work or a GVL-holding C extension inside an inline callback blocks every job on that worker, not just yours. Blocking that releases the GVL and pure-Ruby CPU work can be moved onto a thread explicitly:
+
+```ruby
+tool = ClaudeAgentSDK.create_tool('lookup', 'Query legacy DB', { id: String }) do |args|
+  row = ClaudeAgentSDK.offload { legacy_client.fetch(args[:id]) }  # plain thread
+  { content: [{ type: 'text', text: row.to_json }] }
+end
+```
+
+`ClaudeAgentSDK.offload` is a no-op outside a reactor, so it's safe to call unconditionally. Be precise about what it protects, though: it fully shields the reactor from blocking calls that *release* the GVL (native DB drivers, file/socket I/O the scheduler can't see), and it turns pure-Ruby CPU work from a hard stall into GVL time-slicing (added latency for sibling jobs, not starvation). A C extension that **holds** the GVL for the whole computation still freezes the process — `offload` cannot help there; run that work in a subprocess.
+
+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.
+
 ## ActionCable Streaming
 
 Stream Claude responses to the frontend in real-time:

data/lib/claude_agent_sdk/fiber_boundary.rb

@@ -24,6 +24,26 @@ module ClaudeAgentSDK
   #
   # No-op when no scheduler is active, so it's cheap to use unconditionally.
   #
+  # OPT-IN INLINE MODE: hosts that are already fiber-isolated (e.g. Rails
+  # apps with `IsolatedExecutionState.isolation_level = :fiber` running
+  # solid_queue fiber workers) can pass `scheduling: :inline` to run
+  # callbacks in place on the reactor fiber instead of hopping. This is the
+  # same code path as the no-scheduler case — semantically the already-
+  # shipped synchronous path, and Python SDK parity (async callbacks run
+  # natively on the event loop there). The mode is plumbed per-call from
+  # `ClaudeAgentOptions#callback_scheduling` — never a thread-local (the
+  # reactor thread is shared by many fibers, so a set/reset window across
+  # 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.
+  #
+  # 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.
+  #
   # The thread hop severs `break`/`return`/`next` from the surrounding method,
   # so SDK loops yielding user callbacks must keep loop control outside the
   # invoked block (see `Client#receive_response`); user-initiated `break` is
@@ -44,6 +64,57 @@ module ClaudeAgentSDK
     # in-flight call may still complete).
     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
+    # 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
+    # hook into a success (Async::TimeoutError is a StandardError, so it
+    # cannot be injected directly). The SDK translates it back to
+    # Async::TimeoutError once control returns from user code.
+    # @api private
+    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
+    # 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
+
+    # The value stored under SCHEDULING_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.
+    # Restoring the dispatching fiber's own slot is therefore not enough —
+    # a child task spawned inside a handler that outlives the dispatch
+    # would keep reading the stale mode forever. Closing the scope in the
+    # dispatch's ensure invalidates it for ALL inheritors at once; readers
+    # 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.
+    # @api private
+    class SchedulingScope
+      attr_reader :mode
+
+      def initialize(mode)
+        @mode = mode
+        @active = true
+      end
+
+      def active?
+        @active
+      end
+
+      def close
+        @active = false
+      end
+    end
+
     # Sentinel returned by .invoke_iteration when the user block attempted `break`.
     class Break
       attr_reader :value
@@ -59,10 +130,15 @@ module ClaudeAgentSDK
     # Returns the block's value. Exceptions propagate to the caller.
     #
     # With +timeout+ (seconds) the thread hop happens unconditionally — even
-    # without a scheduler — so the bound is enforced in plain synchronous code
-    # too; JoinTimeout is raised when it expires.
-    def invoke(timeout: nil, &block)
-      return block.call if timeout.nil? && !Fiber.scheduler
+    # without a scheduler or with `scheduling: :inline` — so the bound is
+    # enforced in plain synchronous code too; JoinTimeout is raised when it
+    # expires.
+    #
+    # 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)
 
       thread = Thread.new(&block)
       thread.report_on_exception = false
@@ -77,10 +153,10 @@ module ClaudeAgentSDK
     # LocalJumpError(reason: :break) on the worker thread; translate it into
     # a Break sentinel so the SDK loop can break on the calling fiber.
     # Returns Break when the user broke, nil when the block completed.
-    # Without a scheduler the block runs in place and `break` unwinds
-    # natively, never reaching the translation.
-    def invoke_iteration(block, *args)
-      invoke do
+    # 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
         block.call(*args)
         nil
       rescue LocalJumpError => e

data/lib/claude_agent_sdk/query.rb

@@ -63,12 +63,13 @@ 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)
+                   exclude_dynamic_sections: nil, skills: nil, callback_scheduling: :thread)
       @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
       @agents = agents
       @exclude_dynamic_sections = exclude_dynamic_sections
       @skills = skills
@@ -564,9 +565,12 @@ module ClaudeAgentSDK
         description: request_data[:description]
       )
 
-      # User-supplied permission callback runs on a plain thread, not the
-      # Async reactor, so AR/PG calls inside it aren't intercepted.
-      response = FiberBoundary.invoke do
+      # User-supplied permission callback runs on a plain thread by default,
+      # so AR/PG calls inside it aren't intercepted by the Fiber scheduler;
+      # 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
         @can_use_tool.call(request_data[:tool_name], request_data[:input], context)
       end
 
@@ -602,22 +606,46 @@ module ClaudeAgentSDK
       # Create typed HookContext
       context = HookContext.new(signal: nil)
 
-      # Hop off the Fiber scheduler before invoking user hook code. The
-      # Async-side timeout still wraps the hop; if it fires, .value returns
-      # early with an exception and the worker thread is left to finish on
-      # its own (matches prior best-effort cancellation semantics).
+      # Hop off the Fiber scheduler before invoking user hook code (default
+      # :thread mode). With a timeout, the Async-side with_timeout wraps the
+      # hop; if it fires, .value returns early with an exception and the
+      # worker thread is left to finish on its own (best-effort abandonment).
+      # In :inline mode the callback runs in place, so with_timeout becomes
+      # genuine cooperative cancellation: the hook is interrupted at its next
+      # 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 do
+        hook_output = FiberBoundary.invoke(scheduling: @callback_scheduling) do
           callback.call(hook_input, request_data[:tool_use_id], context)
         end
       end
 
       if (timeout = @hook_callback_timeouts[callback_id])
-        hook_output = Async::Task.current.with_timeout(timeout) do
-          FiberBoundary.invoke do
-            callback.call(hook_input, request_data[:tool_use_id], context)
+        hook_output =
+          if @callback_scheduling == :inline
+            # The timeout exception is raised INSIDE user code here, and
+            # 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.
+            begin
+              Async::Task.current.with_timeout(timeout, FiberBoundary::InlineCancellation) do
+                FiberBoundary.invoke(scheduling: :inline) do
+                  callback.call(hook_input, request_data[:tool_use_id], context)
+                end
+              end
+            rescue FiberBoundary::InlineCancellation
+              raise Async::TimeoutError, 'execution expired'
+            end
+          else
+            Async::Task.current.with_timeout(timeout) do
+              FiberBoundary.invoke do
+                callback.call(hook_input, request_data[:tool_use_id], context)
+              end
+            end
           end
-        end
       end
 
       # Convert Ruby-safe field names to CLI-expected names
@@ -966,6 +994,23 @@ 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
+      # 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:
+      # 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)
+      Fiber[FiberBoundary::SCHEDULING_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
 
@@ -1014,6 +1059,9 @@ module ClaudeAgentSDK
         id: message[:id],
         error: { code: -32603, message: e.message }
       }
+    ensure
+      dispatch_scope&.close
+      Fiber[FiberBoundary::SCHEDULING_KEY] = previous_scheduling
     end
 
     def handle_mcp_initialize(server, message)

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -81,12 +81,35 @@ module ClaudeAgentSDK
   class SdkMcpServer
     attr_reader :name, :version, :tools, :resources, :prompts, :mcp_server
 
+    # Default for where user handlers run when this server is invoked
+    # DIRECTLY (call_tool / read_resource / get_prompt outside a session):
+    # :thread hops to a plain thread, :inline runs in place. When a session
+    # dispatches to this server, the session's own mode arrives via fiber
+    # 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
+
+    # 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.
+    # @api private
+    def effective_callback_scheduling
+      scope = Fiber[FiberBoundary::SCHEDULING_KEY]
+      scope&.active? ? scope.mode : @callback_scheduling
+    end
+
     def initialize(name:, version: '1.0.0', tools: [], resources: [], prompts: [])
       @name = name
       @version = version
       @tools = tools
       @resources = resources
       @prompts = prompts
+      @callback_scheduling = :thread
 
       # Create dynamic Tool classes from tool definitions
       tool_classes = create_tool_classes(tools)
@@ -171,9 +194,10 @@ module ClaudeAgentSDK
       tool = @tools.find { |t| t.name == name }
       return error_tool_result("Tool '#{name}' not found") unless tool
 
-      # Call the tool's handler on a plain thread so the async gem's
-      # Fiber scheduler is not visible to user code (which may hit AR/PG).
-      result = FiberBoundary.invoke { tool.handler.call(arguments) }
+      # 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) }
 
       # Guard before flexible_fetch: it raises on non-Hash inputs.
       content = result.is_a?(Hash) ? ClaudeAgentSDK.flexible_fetch(result, "content", "content") : nil
@@ -208,7 +232,7 @@ 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 { resource.reader.call }
+      content = FiberBoundary.invoke(scheduling: effective_callback_scheduling) { resource.reader.call }
 
       # Ensure content has the expected format (symbol or string keys; guard
       # before flexible_fetch — it raises on non-Hash inputs)
@@ -240,7 +264,7 @@ module ClaudeAgentSDK
 
       # Hop off the Fiber scheduler before invoking user code — same reason
       # as `call_tool` above.
-      result = FiberBoundary.invoke { prompt.generator.call(arguments) }
+      result = FiberBoundary.invoke(scheduling: effective_callback_scheduling) { prompt.generator.call(arguments) }
 
       # Ensure result has the expected format (symbol or string keys)
       messages = result.is_a?(Hash) ? ClaudeAgentSDK.flexible_fetch(result, "messages", "messages") : nil
@@ -281,10 +305,14 @@ module ClaudeAgentSDK
 
     # Create dynamic Tool classes from tool definitions
     def create_tool_classes(tools)
+      # Captured so the dynamic class can resolve the effective scheduling
+      # mode at call time — same pattern as prompt classes.
+      sdk_server = self
       tools.map do |tool_def|
         # Create a new class that extends MCP::Tool
         Class.new(MCP::Tool) do
           @tool_def = tool_def
+          @sdk_server = sdk_server
 
           class << self
             attr_reader :tool_def
@@ -335,8 +363,11 @@ module ClaudeAgentSDK
 
             def call(server_context: nil, **args)
               # Filter out server_context and pass remaining args to handler.
-              # Hop to a plain thread so user handlers don't see the Fiber scheduler.
-              result = FiberBoundary.invoke { @tool_def.handler.call(args) }
+              # 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
+                @tool_def.handler.call(args)
+              end
 
               # Guard BEFORE flexible_fetch: on a non-Hash it raises
               # TypeError/NoMethodError, surfacing garbage instead of the

data/lib/claude_agent_sdk/types.rb

@@ -1575,7 +1575,8 @@ module ClaudeAgentSDK
                   :session_store, :session_store_flush, :load_timeout_ms
     attr_reader :bare, :fork_session, :enable_file_checkpointing,
                 :include_partial_messages, :continue_conversation,
-                :include_hook_events, :strict_mcp_config
+                :include_hook_events, :strict_mcp_config,
+                :callback_scheduling
 
     def initialize(attributes = {})
       self.fork_session = false
@@ -1598,6 +1599,7 @@ module ClaudeAgentSDK
       self.session_store_flush ||= 'batched'
       # 0 is a valid (immediate) timeout, so only fill in the default for nil.
       self.load_timeout_ms = 60_000 if load_timeout_ms.nil?
+      self.callback_scheduling = :thread if callback_scheduling.nil?
     end
 
     def dup_with(**changes)
@@ -1671,6 +1673,37 @@ module ClaudeAgentSDK
       @strict_mcp_config = coerce_boolean(value)
     end
 
+    CALLBACK_SCHEDULING_MODES = %i[thread inline].freeze
+
+    # Where user callbacks (hooks, can_use_tool, SDK MCP handlers, message
+    # blocks, observers) run when the SDK is hosted inside an Async reactor:
+    #   :thread (default) — each callback hops to a plain thread, so
+    #     thread-keyed libraries (ActiveRecord, pg, ...) behave as usual.
+    #   :inline — callbacks run in place on the reactor fiber. Only for
+    #     hosts that are fiber-isolated end to end (e.g. solid_queue fiber
+    #     workers with IsolatedExecutionState.isolation_level = :fiber).
+    #     Scheduler-opaque blocking (CPU-bound work, GVL-holding C
+    #     extensions) then stalls the whole reactor — wrap GVL-releasing
+    #     blocking and Ruby CPU work in ClaudeAgentSDK.offload { }; work
+    #     that holds the GVL throughout needs a subprocess.
+    # Named after the mechanism, not a safety claim: whether inline is safe
+    # depends on the host satisfying the fiber-isolation precondition.
+    def callback_scheduling=(value)
+      if value.nil?
+        @callback_scheduling = nil
+        return
+      end
+
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+      unless CALLBACK_SCHEDULING_MODES.include?(mode)
+        raise ArgumentError,
+              "callback_scheduling must be one of #{CALLBACK_SCHEDULING_MODES.map(&:inspect).join(', ')} " \
+              "(got #{value.inspect})"
+      end
+
+      @callback_scheduling = mode
+    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.24.0'
+  VERSION = '0.25.0'
 end

data/lib/claude_agent_sdk.rb

@@ -83,10 +83,10 @@ module ClaudeAgentSDK
   # Safely call a method on each observer, suppressing any errors.
   # 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.
-  def self.notify_observers(observers, method, *args)
+  # the SDK's Async reactor — or in place when scheduling is :inline.
+  def self.notify_observers(observers, method, *args, scheduling: :thread)
     observers.each do |obs|
-      FiberBoundary.invoke { obs.send(method, *args) }
+      FiberBoundary.invoke(scheduling: scheduling) { obs.send(method, *args) }
     rescue StandardError, ScriptError
       # ScriptError too: NotImplementedError < ScriptError (not
       # StandardError), and a stubbed observer must never mask the original
@@ -95,6 +95,45 @@ module ClaudeAgentSDK
     end
   end
 
+  # Public escape hatch for hosts running with callback_scheduling: :inline:
+  # run a heavy piece of a callback on a plain thread instead of the shared
+  # reactor fiber. What that buys, precisely:
+  # - scheduler-opaque BLOCKING that releases the GVL (native DB drivers,
+  #   file/socket calls the scheduler can't see): the reactor keeps running.
+  # - pure-Ruby CPU-bound work: degrades a hard reactor stall into GVL
+  #   time-slicing — added latency for other fibers, not starvation.
+  # - a C extension that HOLDS the GVL for the whole computation: no help;
+  #   nothing in-process can protect the reactor from that — move such work
+  #   to a subprocess.
+  # No-op outside a Fiber scheduler, so it is safe to call unconditionally.
+  # Returns the block's value; exceptions propagate.
+  #
+  # @example Inside an inline-mode tool handler
+  #   ClaudeAgentSDK.offload { blocking_db_call }
+  def self.offload(&block)
+    FiberBoundary.invoke(&block)
+  end
+
+  # 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
+  # (solid_queue fiber workers require isolation_level = :fiber).
+  # 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
+    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 ' \
+         'thread-keyed Rails state will leak across fibers. Set ' \
+         'isolation_level = :fiber (as solid_queue fiber workers require) ' \
+         'or use the default callback_scheduling: :thread.'
+  end
+
   # Extract the user-visible prompt text from a streamed input item, or nil
   # when there is none (non-user messages, tool_result-only content, …).
   # Only Hash and JSON-string items are inspected; arbitrary objects written
@@ -148,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)
+  def self.observing_prompt_stream(prompt, observers, scheduling: :thread)
     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) if text
+        notify_observers(observers, :on_user_prompt, text, scheduling: scheduling) if text
         yielder << message
       end
     end
@@ -422,6 +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).
+    callback_scheduling = configured_options.callback_scheduling || :thread
+    ClaudeAgentSDK.check_inline_isolation(callback_scheduling)
+
     raise ArgumentError, 'transport must respond to #connect (see ClaudeAgentSDK::Transport)' if transport && !transport.respond_to?(:connect)
 
     Async do
@@ -481,7 +524,8 @@ module ClaudeAgentSDK
           agents: configured_options.agents,
           sdk_mcp_servers: sdk_mcp_servers,
           exclude_dynamic_sections: ClaudeAgentSDK.extract_exclude_dynamic_sections(configured_options.system_prompt),
-          skills: configured_options.skills
+          skills: configured_options.skills,
+          callback_scheduling: callback_scheduling
         )
 
         # Mirror transcripts to the session_store, if configured. Installed
@@ -505,7 +549,7 @@ 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)
+          ClaudeAgentSDK.notify_observers(resolved_observers, :on_user_prompt, prompt, scheduling: callback_scheduling)
           message = {
             type: 'user',
             message: { role: 'user', content: prompt },
@@ -523,19 +567,20 @@ 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)
+          observed_prompt = ClaudeAgentSDK.observing_prompt_stream(prompt, resolved_observers, scheduling: callback_scheduling)
           query_handler.spawn_task { query_handler.stream_input(observed_prompt) }
         end
 
         # Read and yield messages from the query handler (filters out control messages).
         # User block is invoked through FiberBoundary so ActiveRecord / PG calls
-        # inside it don't see the async gem's Fiber scheduler.
+        # inside it don't see the async gem's Fiber scheduler (default :thread
+        # mode; :inline runs it in place on the reactor fiber).
         query_handler.receive_messages do |data|
           message = MessageParser.parse(data)
           next unless message
 
-          ClaudeAgentSDK.notify_observers(resolved_observers, :on_message, message)
-          signal = FiberBoundary.invoke_iteration(block, message)
+          ClaudeAgentSDK.notify_observers(resolved_observers, :on_message, message, scheduling: callback_scheduling)
+          signal = FiberBoundary.invoke_iteration(block, message, scheduling: callback_scheduling)
           break signal.value if signal.is_a?(FiberBoundary::Break)
         end
       rescue StandardError => e
@@ -544,10 +589,10 @@ 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)
+        ClaudeAgentSDK.notify_observers(resolved_observers, :on_error, e, scheduling: callback_scheduling)
         raise
       ensure
-        ClaudeAgentSDK.notify_observers(resolved_observers, :on_close)
+        ClaudeAgentSDK.notify_observers(resolved_observers, :on_close, scheduling: callback_scheduling)
         # 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.
@@ -617,6 +662,7 @@ module ClaudeAgentSDK
     # @param transport_args [Hash] Additional keyword arguments passed to transport_class.new(options, **transport_args)
     def initialize(options: nil, transport_class: SubprocessCLITransport, transport_args: {})
       @options = options || ClaudeAgentOptions.new
+      @callback_scheduling = @options.callback_scheduling || :thread
       @transport_class = transport_class
       @transport_args = transport_args
       @transport = nil
@@ -699,6 +745,8 @@ module ClaudeAgentSDK
       # notified via on_error.
       @resolved_observers = ClaudeAgentSDK.resolve_observers(@options.observers)
 
+      ClaudeAgentSDK.check_inline_isolation(@callback_scheduling)
+
       # If anything from materialization onward fails, tear down (closes the
       # subprocess and removes the materialized temp config dir) before
       # surfacing the error, so a partial connect never leaks a temp dir
@@ -751,7 +799,7 @@ module ClaudeAgentSDK
 
       begin
         if prompt.is_a?(String)
-          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, prompt)
+          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, prompt, scheduling: @callback_scheduling)
           message = {
             type: 'user',
             message: { role: 'user', content: prompt },
@@ -792,8 +840,8 @@ module ClaudeAgentSDK
           message = MessageParser.parse(data)
           next unless message
 
-          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_message, message)
-          signal = FiberBoundary.invoke_iteration(block, message)
+          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_message, message, scheduling: @callback_scheduling)
+          signal = FiberBoundary.invoke_iteration(block, message, scheduling: @callback_scheduling)
           break signal.value if signal.is_a?(FiberBoundary::Break)
         end
       rescue StandardError => e
@@ -818,8 +866,8 @@ module ClaudeAgentSDK
           message = MessageParser.parse(data)
           next unless message
 
-          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_message, message)
-          signal = FiberBoundary.invoke_iteration(block, message)
+          ClaudeAgentSDK.notify_observers(@resolved_observers, :on_message, message, scheduling: @callback_scheduling)
+          signal = FiberBoundary.invoke_iteration(block, message, scheduling: @callback_scheduling)
           break signal.value if signal.is_a?(FiberBoundary::Break)
           break if message.is_a?(ResultMessage)
         end
@@ -911,7 +959,7 @@ module ClaudeAgentSDK
 
     # Disconnect from Claude
     def disconnect
-      ClaudeAgentSDK.notify_observers(@resolved_observers || [], :on_close) if @connected
+      ClaudeAgentSDK.notify_observers(@resolved_observers || [], :on_close, scheduling: @callback_scheduling) if @connected
       # 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
@@ -997,7 +1045,8 @@ module ClaudeAgentSDK
         sdk_mcp_servers: sdk_mcp_servers,
         agents: configured_options.agents,
         exclude_dynamic_sections: exclude_dynamic_sections,
-        skills: configured_options.skills
+        skills: configured_options.skills,
+        callback_scheduling: @callback_scheduling
       )
 
       # Mirror transcripts to the session_store, if configured.
@@ -1028,7 +1077,7 @@ 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)
+        observed = ClaudeAgentSDK.observing_prompt_stream(prompt, @resolved_observers, scheduling: @callback_scheduling)
         @query_handler.spawn_task { @query_handler.stream_input(observed) }
       end
     end
@@ -1045,12 +1094,12 @@ 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)
+            ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text, scheduling: @callback_scheduling)
           end
           writeln(JSON.generate(msg))
         when String
           if (text = ClaudeAgentSDK.extract_user_prompt_text(msg))
-            ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text)
+            ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text, scheduling: @callback_scheduling)
           end
           writeln(msg)
         else
@@ -1064,7 +1113,7 @@ 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)
+      ClaudeAgentSDK.notify_observers(@resolved_observers || [], :on_error, error, scheduling: @callback_scheduling)
     end
 
     # Build and install the transcript-mirror batcher on the query handler when

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.25.0
 platform: ruby
 authors:
 - Community Contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-27 00:00:00.000000000 Z
+date: 2026-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async