claude-agent-sdk 0.23.0 → 0.25.0

data/lib/claude_agent_sdk/query.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'set'
 require 'async'
 require 'async/queue'
 require 'async/condition'
@@ -23,6 +24,22 @@ module ClaudeAgentSDK
     CONTROL_REQUEST_TIMEOUT_ENV_VAR = 'CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS'
     DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS = 1200.0
 
+    # Task types whose completion runs a follow-up turn, and which therefore
+    # may still need the control channel after the turn's result frame.
+    #
+    # Mirrors the set the CLI itself holds a result back for, which is
+    # narrower than its notion of "delegated agent work". The types left out
+    # are left out on purpose:
+    #   - background shells and monitors run indefinitely by design, so
+    #     deferring the close on one withholds it forever rather than briefly;
+    #   - teammates are long-lived too — their status stays running for their
+    #     whole lifetime, so they never settle the ledger;
+    #   - remote agents can be long-running monitors the CLI likewise refuses
+    #     to wait on.
+    # Anything added here must be a type that reliably reaches a terminal
+    # status, or it will hang the query (see #track_task_lifecycle).
+    DEFERRING_TASK_TYPES = %w[local_agent local_workflow].freeze
+
     # Waiter for control responses awaited OFF the reactor — i.e. a control
     # method called from inside a hook/can_use_tool/SDK-MCP callback, which
     # runs on a FiberBoundary worker thread (Python supports this reentrancy
@@ -46,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
@@ -68,7 +86,16 @@ module ClaudeAgentSDK
 
       # Message stream
       @message_queue = Async::Queue.new
+      # Set when a run-ending result arrives (a result frame with no tasks in
+      # flight) so the stdin-closing waiter can wake. Named for history — it
+      # once tracked the literal first result.
       @first_result_received = false
+      # Task IDs of started-but-not-finished deferring tasks. A result frame
+      # only ends one turn, not the run: a background task keeps running past
+      # it and still needs stdin for hook/SDK-MCP control responses (Python
+      # #1088/#1103), so a result that arrives while this set is non-empty
+      # must not close stdin.
+      @inflight_tasks = Set.new
       @last_error_result_text = nil
       @first_result_condition = Async::Condition.new
       @task = nil
@@ -307,11 +334,21 @@ module ClaudeAgentSDK
           @transcript_mirror_batcher&.enqueue(message[:filePath] || message[:file_path], message[:entries] || [])
           next
         else
+          # Track task lifecycle frames so results can tell "one turn ended"
+          # apart from "the run is done" (Python #1088/#1103).
+          track_task_lifecycle(message) if message[:type] == 'system'
+
           if message[:type] == 'result'
             # Flush the mirror before signaling/yielding the result so a
             # consumer observing the result sees an up-to-date store for the turn.
             flush_transcript_mirror
-            unless @first_result_received
+            # A result with tasks still in flight ends one turn, not the run:
+            # the tasks may still need hook/SDK-MCP control responses over
+            # stdin, and closing it now silently disables hooks and fails
+            # SDK-MCP calls with "Stream closed". Each deferring task's
+            # completion wakes the parent for a follow-up turn, so a later
+            # result arrives with no tasks in flight and closes stdin then.
+            if @inflight_tasks.empty? && !@first_result_received
               @first_result_received = true
               @first_result_condition.signal
             end
@@ -376,6 +413,50 @@ module ClaudeAgentSDK
       end
     end
 
+    # Track in-flight tasks from `system` task lifecycle frames.
+    #
+    # `task_started` marks a task in flight; `task_notification` or a
+    # `task_updated` patch with a terminal status clears it. Terminal
+    # completion can arrive as either frame (not every terminal task emits a
+    # notification), so both are handled; Set deletion keeps the pair
+    # idempotent.
+    #
+    # This is a mitigation, not a complete answer to Python #1088. An empty
+    # set means "nothing we know of is running", which is not the same as
+    # "the run is over": a task that settles *before* the turn's result frame
+    # leaves the set empty at that result, so stdin closes even though the
+    # completion may still wake the parent for a continuation turn. What this
+    # does fix is the common ordering, where the task outlives the turn that
+    # spawned it.
+    #
+    # Only delegated agent work is tracked (DEFERRING_TASK_TYPES). A
+    # background *shell* is also reported through these frames, but it may
+    # never reach a terminal status, and the CLI in stream-json mode only
+    # exits on stdin EOF — tracking one would withhold the close forever.
+    #
+    # `background_tasks_changed` is deliberately not consumed, in either
+    # direction: its payload is the live *background* set, while a subagent
+    # is registered in the foreground and only flips to backgrounded later
+    # without a second task_started, so narrowing against the snapshot would
+    # drop an agent that goes on to outlive its turn, and widening from it
+    # could admit an id no later frame ever clears (observer agents suppress
+    # both their start and terminal frames).
+    def track_task_lifecycle(message)
+      task_id = message[:task_id]
+      return if task_id.nil? || task_id.to_s.empty?
+
+      case message[:subtype]
+      when 'task_started'
+        @inflight_tasks.add(task_id) if DEFERRING_TASK_TYPES.include?(message[:task_type])
+      when 'task_notification'
+        @inflight_tasks.delete(task_id)
+      when 'task_updated'
+        patch = message[:patch]
+        status = patch.is_a?(Hash) ? patch[:status] : nil
+        @inflight_tasks.delete(task_id) if TERMINAL_TASK_STATUSES.include?(status)
+      end
+    end
+
     # Flush the transcript-mirror batcher, swallowing errors — a mirror failure
     # must never propagate into the read loop or its teardown.
     def flush_transcript_mirror
@@ -484,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
 
@@ -522,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
@@ -886,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
 
@@ -934,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)
@@ -1104,15 +1232,19 @@ module ClaudeAgentSDK
                            })
     end
 
-    # Wait for the first result before closing stdin when hooks or SDK MCP
+    # Wait for a run-ending result before closing stdin when hooks or SDK MCP
     # servers may still need to exchange control messages with the CLI.
     # The control protocol requires stdin to stay open for the entire turn
     # (hook replies, can_use_tool replies and SDK MCP tool results are all
     # written to stdin), so no timeout is applied — closing stdin mid-turn
     # silently broke hooks/MCP on turns longer than the old 60s bound
-    # (mirrors Python SDK commit c3d96cb). The condition is guaranteed to be
-    # signaled: by the result branch in read_messages, or by its ensure block
-    # when the process exits early.
+    # (mirrors Python SDK commit c3d96cb). A result frame ends one turn, not
+    # necessarily the run: while background tasks are in flight the result
+    # branch withholds the signal (Python #1088/#1103), and each deferring
+    # task's completion wakes the parent for a follow-up turn that ends in
+    # another result. The condition is guaranteed to be signaled: by the
+    # result branch in read_messages once no tasks are in flight, or by its
+    # ensure block when the process exits early.
     def wait_for_result_and_end_input
       if !@first_result_received &&
          ((@sdk_mcp_servers && !@sdk_mcp_servers.empty?) || (@hooks && !@hooks.empty?))

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/subprocess_cli_transport.rb

@@ -328,6 +328,66 @@ module ClaudeAgentSDK
       @ready = false
       return unless @process
 
+      process = @process
+      process_teardown_complete = false
+      begin
+        teardown_process
+        process_teardown_complete = true
+      ensure
+        # The graceful escalation in teardown_process suspends (task sleep,
+        # thread join), so a cancellation (Async::Stop) delivered mid-close
+        # used to skip TERM/KILL entirely and leak a live CLI child until
+        # interpreter exit (the at_exit reaper fires only then, TERM only).
+        # Nothing here may suspend: a synchronous TERM plus a plain
+        # background thread for the KILL escalation. On this path the
+        # process deliberately STAYS in the at_exit registry as a second
+        # safety net; the normal path deregisters in teardown_process.
+        force_terminate_in_background(process) unless process_teardown_complete
+
+        # Snapshot-then-nil BEFORE the best-effort pipe close below: once the
+        # references are cleared, even a close that somehow failed leaves the
+        # IOs unreachable from this (still-referenced) transport, so GC can
+        # finalize them — "wait for GC" alone would never fire while the
+        # transport keeps pointing at them, and with @process nil a repeat
+        # #close returns immediately, so a cancelled close used to leak the
+        # pipe descriptors for the life of the object.
+        #
+        # @stdin is cleared WITHOUT its mutex (taking it could suspend
+        # mid-cancellation): the ivar swap is atomic, and #write takes its
+        # snapshot under the mutex, so a concurrent writer sees either nil
+        # (raises not-ready — @ready is already false) or the old IO, whose
+        # in-flight write then fails with IOError and is converted to
+        # CLIConnectionError — the documented shutdown behavior either way.
+        stdin_io = @stdin
+        stdout_io = @stdout
+        stderr_io = @stderr
+        @process = nil
+        @stdin = nil
+        @stdout = nil
+        @stderr = nil
+        @stderr_task = nil
+        @exit_error = nil
+
+        unless process_teardown_complete
+          # Cancellation can land before teardown_process reached the pipe
+          # closes. stdout/stderr are read ends (close never blocks); stdin's
+          # implicit flush is a no-op in practice because #write flushes
+          # after every write. Best-effort: an IO that is already closed or
+          # fails to close is left to GC, which the nil-ing above enables.
+          [stdin_io, stdout_io, stderr_io].each do |io|
+            io&.close
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+
+    # Pre-existing #close body: stop the stderr drain, close pipes, wait for
+    # graceful exit after stdin EOF, escalate TERM → KILL on timeout. Runs on
+    # the reactor and suspends at several points; #close's ensure covers the
+    # cancellation-abandoned case.
+    def teardown_process
       cleanup_errors = []
 
       # Kill stderr thread
@@ -404,12 +464,34 @@ module ClaudeAgentSDK
       end
 
       self.class.deregister_active_process(@process)
-      @process = nil
-      @stdout = nil
-      # @stdin already nilled under the mutex above.
-      @stderr = nil
-      @stderr_task = nil
-      @exit_error = nil
+    end
+
+    # Last-resort termination when #close was interrupted before the graceful
+    # escalation finished. Contains no suspension points, so it is safe
+    # inside an ensure during fiber cancellation: synchronous SIGTERM now,
+    # then a plain (non-reactor) thread escalates to SIGKILL after a grace
+    # period. Open3's Process::Waiter thread keeps reaping, so no zombie is
+    # left either way. The alive? guard also makes the delayed KILL
+    # pid-reuse-safe: while the waiter thread reports alive (not yet reaped),
+    # the pid cannot have been recycled.
+    def force_terminate_in_background(process, grace_seconds: 2)
+      return unless process&.alive?
+
+      pid = process.pid
+      begin
+        Process.kill('TERM', pid)
+      rescue StandardError
+        return # ESRCH: already gone; EPERM: not ours to signal
+      end
+
+      Thread.new do
+        sleep grace_seconds
+        begin
+          Process.kill('KILL', pid) if process.alive?
+        rescue StandardError
+          nil # died inside the grace window
+        end
+      end
     end
 
     # Wait for the spawned process to exit, up to +timeout_seconds+. Polls

data/lib/claude_agent_sdk/types.rb

@@ -409,15 +409,31 @@ module ClaudeAgentSDK
 
   # Result message with cost and usage information
   class ResultMessage < Type
+    # model_usage maps model name => per-model usage Hash, passed through
+    # verbatim from the CLI's modelUsage field, so its keys are camelCase
+    # (matches the TypeScript/Python SDKs' ModelUsage shape): inputTokens,
+    # outputTokens, cacheReadInputTokens, cacheCreationInputTokens,
+    # webSearchRequests, costUSD, contextWindow, maxOutputTokens, plus
+    # optional canonicalModel (canonical id used for the pricing lookup —
+    # may differ from the raw model-string key for provider-specific
+    # ids/aliases) and provider ('firstParty', 'bedrock', 'vertex', ...).
+    #
+    # terminal_reason says why the query loop ended ("completed",
+    # "max_turns", "aborted_streaming", ...). "aborted_streaming" /
+    # "aborted_tools" mean the turn was cancelled via Client#interrupt (an
+    # interrupt control request). nil when the CLI did not report one
+    # (older CLI versions, or a result that bypassed the query loop such
+    # as a local slash command).
     attr_accessor :subtype, :duration_ms, :duration_api_ms, :is_error,
                   :num_turns, :session_id, :stop_reason, :total_cost_usd, :usage,
                   :result, :structured_output,
-                  :model_usage,        # Hash of { model_name => usage_data }
+                  :model_usage,        # Hash of { model_name => usage_data }, see above
                   :permission_denials, # Array of { tool_name:, tool_use_id:, tool_input: }
                   :errors,             # Array of error strings (present on error subtypes)
                   :uuid,
                   :fast_mode_state,    # "off", "cooldown", or "on"
-                  :api_error_status    # Integer HTTP status (429, 500, 529) on api_error subtype (CLI 2.1.110+)
+                  :api_error_status,   # Integer HTTP status (429, 500, 529) on api_error subtype (CLI 2.1.110+)
+                  :terminal_reason     # why the query loop ended, see above
 
     attr_reader :deferred_tool_use     # DeferredToolUse, populated when a PreToolUse hook deferred
 
@@ -1559,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
@@ -1582,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)
@@ -1655,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.23.0'
+  VERSION = '0.25.0'
 end