claude-agent-sdk 0.14.2 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff012ff95472382ecb3dcd851f47157c74a91342800a07c49f0a1be77e7df98b
-  data.tar.gz: 71ee7e4a407d412b949aaa91214167780d7f12297d3037c90cb15b9dd8e4f00e
+  metadata.gz: 9a037f9cca486fc8d6e94269b9f5f7b686574665ff403457761db764f9f50f07
+  data.tar.gz: 01bff518e3306d1fb23b8bc1e9b11b72785a98aecf3636a1096c5522f4720444
 SHA512:
-  metadata.gz: 2b63a4e8aea6c5b5c7a536bef496ba62e86414fc347453f7b72f731684b850650a5bce83f94282d0af7c39ad7557e325b7b9b3c25fddfaf2b6b2ba9d9ccc4852
-  data.tar.gz: a5cb854023470f8a43e791747d084e0b2b8107046ff1992c3198dc75b89e693d7fbe7ec1e6eda2ee2be41d3ab6086695f413ebd7b46aaa7ae46acff4cfd73042
+  metadata.gz: 253df532bcdc4a6e0b13e0d4438944bcf9c6018b5d1062b4831efc6dac7a332c1759f85137e6de4fc44de0e8b1eb7ccfd0033698392c8faf6ca40f7e237b2e51
+  data.tar.gz: 143d4ee8780d1a675e1531edc944de1756bff03faa9c42513b9672a3f37ac670dc17929a936cf0f1520d1cfdc45c53042d8f8fa07ad5a559e4b59439e79848f5

data/CHANGELOG.md

@@ -7,7 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.14.2] - 2026-04-17
+## [0.15.1] - 2026-04-22
+
+### Fixed
+- **Thread-keyed libraries are now safe inside SDK callbacks.** The SDK internally hops to a plain thread at every user-callback boundary — blocks passed to `ClaudeAgentSDK.query` / `Client#receive_messages`, SDK MCP tool handlers, hooks, permission callbacks, and observer methods — so the `async` gem's Fiber scheduler is no longer visible to user code. Previously, any library that keys state on `Thread.current` (ActiveRecord and every DB driver keyed by thread — `pg`, `mysql2`, `sqlite3` — plus per-thread HTTP/cache pools, request stores, etc.) could be corrupted by the scheduler interleaving two fibers onto one checked-out connection. Rails/Sidekiq/Kamal consumers no longer need a caller-side wrapper to avoid this. See the "Thread-keyed libraries are safe inside SDK callbacks" subsection under Rails Integration in the README.
+
+### Changed
+- **Callbacks run on a plain thread, not inside `Async::Task`.** Fiber-specific primitives (e.g. `Async::Task.current.sleep`, `Async::Task.current.async { ... }`) are no longer available inside tool handlers, hooks, permission callbacks, message blocks, or observers. Callbacks that want cooperative concurrency can open their own `Async { }` block. In practice callbacks do ordinary Ruby work and return a value, so this rarely affects real code.
+
+## [0.15.0] - 2026-04-17
+
+### Fixed
+
+#### Protocol & CLI
+- `--setting-sources` is now only emitted when the option is explicitly configured. Previously every invocation sent `--setting-sources ""`, which the CLI can interpret as "no setting sources" rather than "use defaults", overriding the CLI's own source resolution.
+- `extra_args` flag names are validated against a lowercase kebab-case pattern and raise `ArgumentError` otherwise. Prevents option injection from multi-tenant configs (e.g. an attacker-controlled hash injecting `--permission-mode bypassPermissions` and relying on CLI last-wins to defeat SDK-chosen safety).
+
+#### Concurrency
+- `SubprocessCLITransport#close` replaced `Timeout.timeout` with Async-safe polling on `@process.alive?`. Stdlib `Timeout.timeout` raises via `Thread#raise`, which can corrupt fiber-scheduler state when `close` runs inside the Async reactor. Still raises `Timeout::Error` so existing rescue clauses keep working.
+- Inbound `control_request` handlers are now spawned as children of the current read task via `Async::Task.current.async`. Bare `Async do` had ambiguous parent linkage; `@task.stop` could leave handler tasks writing to a closed transport.
+
+#### Sessions
+- `list_sessions` and `get_session_messages` coerce `offset: nil` to 0. Previously callers splatting from an options hash crashed on `nil.positive?` / `messages[nil..]`.
+- `fork_session` streams the source JSONL via `File.foreach` instead of `File.read`, and scrubs non-UTF-8 bytes on each line. Fixes `Encoding::InvalidByteSequenceError` on stray bytes in tool output and avoids slurping sessions that can reach hundreds of MB.
+- `simple_hash` (used for project-dir hashing) now iterates UTF-16 code units to match JavaScript's `charCodeAt`. Previously `each_char` + `ord` diverged from the official tools for supplementary characters (emoji, CJK extensions), so paths containing them hashed to different project directories and silently returned no sessions.
+
+#### Security
+- Replaced shell backticks with `Open3.capture3` (array args) in worktree detection. The path argument was already `Shellwords.escape`d, but running via `/bin/sh` leaves a latent shell-injection surface — any future interpolation without escaping would be exploitable.
+
+### Changed
+- `derive_fork_title` helper is now `private_class_method`, matching its siblings on `SessionMutations`.
+
+
 
 ### Added
 - **`EFFORT_LEVELS` constant** exposing `%w[low medium high xhigh max]`. Consumers can reference `ClaudeAgentSDK::EFFORT_LEVELS` for validation instead of hard-coding the list.

data/README.md

@@ -106,7 +106,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.14.2'
+gem 'claude-agent-sdk', '~> 0.15.1'
 ```
 
 And then execute:
@@ -1194,6 +1194,45 @@ For a complete multi-tool example, see [examples/otel_langfuse_example.rb](examp
 
 The SDK integrates well with Rails applications. Here are common patterns:
 
+### Thread-keyed libraries are safe inside SDK callbacks
+
+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:
+
+```ruby
+tool = ClaudeAgentSDK.create_tool('lookup_user', 'Look up a user', { id: Integer }) do |args|
+  user = User.find(args[:id])                # just works
+  { content: [{ type: 'text', text: user.name }] }
+end
+
+ClaudeAgentSDK.query(prompt: '...') do |message|
+  Message.create!(role: 'assistant', body: message.to_s)   # just works
+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.
+
 ### ActionCable Streaming
 
 Stream Claude responses to the frontend in real-time:

data/lib/claude_agent_sdk/fiber_boundary.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ClaudeAgentSDK
+  # Internal. Consumers of the SDK should never need this directly.
+  #
+  # The SDK depends on `async`, which installs a Fiber scheduler whenever an
+  # `Async { }` block is active. That scheduler 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 one state slot — and interleaved IO on a
+  # shared connection silently corrupts wire protocols. This bites every
+  # DB driver keyed by thread (pg, mysql2, sqlite3), ActiveRecord's
+  # connection pool, and any HTTP/cache client pooled per-thread.
+  #
+  # The SDK invokes user-supplied callbacks (tool handlers, hooks,
+  # permission callbacks, message blocks, observer methods) from inside
+  # its reactor. `FiberBoundary.invoke` hops those calls to a plain
+  # Ruby thread so user code runs on a fiber-scheduler-free thread and
+  # inherits the same thread-keyed state assumptions the rest of the
+  # user's app makes.
+  #
+  # No-op when no scheduler is active, so it's cheap to use unconditionally.
+  module FiberBoundary
+    module_function
+
+    # Run the given block on a plain thread when a Fiber scheduler is active.
+    # Returns the block's value. Exceptions propagate to the caller.
+    def invoke(&block)
+      return block.call unless Fiber.scheduler
+
+      thread = Thread.new(&block)
+      thread.report_on_exception = false
+      thread.value
+    end
+  end
+end

data/lib/claude_agent_sdk/query.rb

@@ -162,14 +162,17 @@ module ClaudeAgentSDK
           handle_control_response(message)
         when 'control_request'
           request_id = message[:request_id] || message[:requestId]
-          task = Async do
+          # Spawn as a child of the current task so @task.stop cascades and
+          # nothing keeps running after close; bare Async do may root at the
+          # reactor and leak past shutdown.
+          handler_task = Async::Task.current.async do
             begin
               handle_control_request(message)
             ensure
               @inflight_control_request_tasks.delete(request_id) if request_id
             end
           end
-          @inflight_control_request_tasks[request_id] = task if request_id
+          @inflight_control_request_tasks[request_id] = handler_task if request_id
         when 'control_cancel_request'
           request_id = message[:request_id] || message[:requestId]
           task = request_id ? @inflight_control_request_tasks[request_id] : nil
@@ -297,11 +300,11 @@ module ClaudeAgentSDK
         agent_id: request_data[:agent_id]
       )
 
-      response = @can_use_tool.call(
-        request_data[:tool_name],
-        request_data[:input],
-        context
-      )
+      # 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
+        @can_use_tool.call(request_data[:tool_name], request_data[:input], context)
+      end
 
       # Convert PermissionResult to expected format
       case response
@@ -335,19 +338,21 @@ module ClaudeAgentSDK
       # Create typed HookContext
       context = HookContext.new(signal: nil)
 
-      hook_output = callback.call(
-        hook_input,
-        request_data[:tool_use_id],
-        context
-      ) unless @hook_callback_timeouts[callback_id]
+      # 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).
+      unless @hook_callback_timeouts[callback_id]
+        hook_output = FiberBoundary.invoke 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
-          callback.call(
-            hook_input,
-            request_data[:tool_use_id],
-            context
-          )
+          FiberBoundary.invoke do
+            callback.call(hook_input, request_data[:tool_use_id], context)
+          end
         end
       end
 

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -79,8 +79,9 @@ module ClaudeAgentSDK
       tool = @tools.find { |t| t.name == name }
       raise "Tool '#{name}' not found" unless tool
 
-      # Call the tool's handler
-      result = tool.handler.call(arguments)
+      # 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) }
 
       # Ensure result has the expected format
       unless result.is_a?(Hash) && result[:content]
@@ -180,8 +181,9 @@ module ClaudeAgentSDK
             end
 
             def call(server_context: nil, **args)
-              # Filter out server_context and pass remaining args to handler
-              result = @tool_def.handler.call(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) }
 
               content = ClaudeAgentSDK.flexible_fetch(result, 'content', 'content')
               unless result.is_a?(Hash) && content

data/lib/claude_agent_sdk/session_mutations.rb

@@ -108,10 +108,10 @@ module ClaudeAgentSDK
       raise Errno::ENOENT, "Session #{session_id} not found#{" in project directory for #{directory}" if directory}" unless result
 
       file_path, project_dir = result
-      content = File.read(file_path)
-      raise ArgumentError, "Session #{session_id} has no messages to fork" if content.empty?
+      file_size = File.size(file_path)
+      raise ArgumentError, "Session #{session_id} has no messages to fork" if file_size.zero?
 
-      transcript, content_replacements = parse_fork_transcript(content, session_id)
+      transcript, content_replacements = parse_fork_transcript(file_path)
       transcript.reject! { |e| e['isSidechain'] }
       raise ArgumentError, "Session #{session_id} has no messages to fork" if transcript.empty?
 
@@ -149,19 +149,9 @@ module ClaudeAgentSDK
                                })
       end
 
-      # Derive title
+      # Derive title — only read head/tail chunks when we need to generate one
       fork_title = title&.strip
-      if fork_title.nil? || fork_title.empty?
-        head = content[0, Sessions::LITE_READ_BUF_SIZE] || ''
-        tail = content.length > Sessions::LITE_READ_BUF_SIZE ? content[-Sessions::LITE_READ_BUF_SIZE..] : head
-        base = Sessions.extract_json_string_field(tail, 'customTitle', last: true) ||
-               Sessions.extract_json_string_field(head, 'customTitle', last: true) ||
-               Sessions.extract_json_string_field(tail, 'aiTitle', last: true) ||
-               Sessions.extract_json_string_field(head, 'aiTitle', last: true) ||
-               Sessions.extract_first_prompt_from_head(head) ||
-               'Forked session'
-        fork_title = "#{base} (fork)"
-      end
+      fork_title = "#{derive_fork_title(file_path, file_size)} (fork)" if fork_title.nil? || fork_title.empty?
 
       lines << JSON.generate({
                                'type' => 'custom-title',
@@ -236,13 +226,20 @@ module ClaudeAgentSDK
       nil
     end
 
-    # Parse a fork transcript, extracting entries and content-replacement data.
-    def parse_fork_transcript(content, _session_id)
+    # Parse a fork transcript by streaming the JSONL file line-by-line.
+    # Opens in binary mode and scrubs invalid UTF-8 so stray non-UTF-8
+    # bytes in tool results do not raise Encoding::InvalidByteSequenceError.
+    def parse_fork_transcript(file_path)
       transcript = []
       content_replacements = nil
 
-      content.each_line do |line|
-        entry = JSON.parse(line.strip)
+      File.foreach(file_path, mode: 'rb') do |line|
+        line = line.force_encoding('UTF-8').scrub
+        begin
+          entry = JSON.parse(line.strip)
+        rescue JSON::ParserError
+          next
+        end
         next unless entry.is_a?(Hash) && entry['uuid']
 
         if entry['type'] == 'content-replacement'
@@ -250,13 +247,33 @@ module ClaudeAgentSDK
           next
         end
         transcript << entry
-      rescue JSON::ParserError
-        next
       end
 
       [transcript, content_replacements]
     end
 
+    # Derive a fork title from the source file's head/tail chunks without
+    # slurping the entire file. Matches the lookup order used for
+    # SDKSessionInfo.custom_title / ai_title / first_prompt.
+    def derive_fork_title(file_path, file_size)
+      buf_size = [Sessions::LITE_READ_BUF_SIZE, file_size].min
+      File.open(file_path, 'rb') do |f|
+        head = (f.read(buf_size) || '').force_encoding('UTF-8').scrub
+        tail = if file_size > Sessions::LITE_READ_BUF_SIZE
+                 f.seek(-buf_size, IO::SEEK_END)
+                 (f.read(buf_size) || '').force_encoding('UTF-8').scrub
+               else
+                 head
+               end
+        Sessions.extract_json_string_field(tail, 'customTitle', last: true) ||
+          Sessions.extract_json_string_field(head, 'customTitle', last: true) ||
+          Sessions.extract_json_string_field(tail, 'aiTitle', last: true) ||
+          Sessions.extract_json_string_field(head, 'aiTitle', last: true) ||
+          Sessions.extract_first_prompt_from_head(head) ||
+          'Forked session'
+      end
+    end
+
     # Build a single forked entry with remapped UUIDs.
     def build_forked_entry(original, index, total, uuid_mapping, by_uuid,
                            forked_session_id, source_session_id, now)
@@ -396,7 +413,7 @@ module ClaudeAgentSDK
 
     private_class_method :find_session_file_with_dir,
                          :find_in_directory, :try_project_dir, :find_in_all_projects,
-                         :parse_fork_transcript, :build_forked_entry, :resolve_parent_uuid,
+                         :parse_fork_transcript, :derive_fork_title, :build_forked_entry, :resolve_parent_uuid,
                          :append_to_session, :append_to_session_in_directory,
                          :append_to_session_global, :try_append, :sanitize_unicode, :unicode_category
   end

data/lib/claude_agent_sdk/sessions.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
-require 'English'
 require 'json'
+require 'open3'
 require 'pathname'
-require 'shellwords'
 
 module ClaudeAgentSDK
   # Session info returned by list_sessions
@@ -59,11 +58,13 @@ module ClaudeAgentSDK
 
     module_function
 
-    # Match TypeScript's simpleHash: signed 32-bit integer, base-36 output
+    # Match TypeScript's simpleHash: signed 32-bit integer, base-36 output.
+    # JS's charCodeAt returns UTF-16 code units, so supplementary characters
+    # (emoji, CJK extensions) emit two surrogate code units — iterate over
+    # UTF-16LE shorts instead of Unicode codepoints to preserve parity.
     def simple_hash(str)
       h = 0
-      str.each_char do |ch|
-        char_code = ch.ord
+      str.encode('UTF-16LE').unpack('v*').each do |char_code|
         h = ((h << 5) - h + char_code) & 0xFFFFFFFF
         h -= 0x100000000 if h >= 0x80000000
       end
@@ -306,6 +307,7 @@ module ClaudeAgentSDK
     # @param include_worktrees [Boolean] Whether to include git worktree sessions
     # @return [Array<SDKSessionInfo>] Sessions sorted by last_modified descending
     def list_sessions(directory: nil, limit: nil, offset: 0, include_worktrees: true)
+      offset ||= 0
       sessions = if directory
                    list_sessions_for_directory(directory, include_worktrees)
                  else
@@ -354,6 +356,8 @@ module ClaudeAgentSDK
     def get_session_messages(session_id:, directory: nil, limit: nil, offset: 0)
       return [] unless session_id.match?(UUID_RE)
 
+      offset ||= 0
+
       file_path = find_session_file(session_id, directory)
       return [] unless file_path && File.exist?(file_path)
 
@@ -439,8 +443,8 @@ module ClaudeAgentSDK
     end
 
     def detect_worktrees(path)
-      output = `git -C #{Shellwords.escape(path)} worktree list --porcelain 2>/dev/null`
-      return [path] unless $CHILD_STATUS.success?
+      output, _err, status = Open3.capture3('git', '-C', path, 'worktree', 'list', '--porcelain')
+      return [path] unless status.success?
 
       paths = output.lines.filter_map do |line|
         line.strip.delete_prefix('worktree ') if line.start_with?('worktree ')

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -12,6 +12,7 @@ module ClaudeAgentSDK
   class SubprocessCLITransport < Transport
     DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024 # 1MB buffer limit
     MINIMUM_CLAUDE_CODE_VERSION = '2.0.0'
+    EXTRA_ARG_FLAG_RE = /\A[a-z0-9][a-z0-9-]*\z/
 
     def initialize(options_or_prompt = nil, options = nil)
       # Support both new single-arg form and legacy two-arg form
@@ -162,15 +163,21 @@ module ClaudeAgentSDK
       build_plugins_args(cmd)
 
       # Setting sources
-      sources_value = @options.setting_sources ? @options.setting_sources.join(',') : ''
-      cmd.concat(['--setting-sources', sources_value])
+      if @options.setting_sources
+        cmd.concat(['--setting-sources', @options.setting_sources.join(',')])
+      end
 
       # Extra args
       @options.extra_args.each do |flag, value|
+        flag_str = flag.to_s
+        unless EXTRA_ARG_FLAG_RE.match?(flag_str)
+          raise ArgumentError, "Invalid extra_args flag name: #{flag.inspect} (expected lowercase kebab-case)"
+        end
+
         if value.nil?
-          cmd << "--#{flag}"
+          cmd << "--#{flag_str}"
         else
-          cmd.concat(["--#{flag}", value.to_s])
+          cmd.concat(["--#{flag_str}", value.to_s])
         end
       end
 
@@ -339,15 +346,12 @@ module ClaudeAgentSDK
       # EOF on stdin. Without this grace period, SIGTERM can interrupt the
       # write and cause the last assistant message to be lost.
       begin
-        if @process.alive?
-          # Give the process up to 5 seconds to exit on its own
-          Timeout.timeout(5) { @process.value }
-        end
+        wait_process_with_timeout(5) if @process.alive?
       rescue Timeout::Error
         # Graceful shutdown timed out — send SIGTERM
         begin
           Process.kill('TERM', @process.pid)
-          Timeout.timeout(2) { @process.value }
+          wait_process_with_timeout(2)
         rescue Timeout::Error
           # SIGTERM didn't work — force kill
           begin
@@ -378,6 +382,22 @@ module ClaudeAgentSDK
       @exit_error = nil
     end
 
+    # Wait for the spawned process to exit, up to +timeout_seconds+. Polls
+    # @process.alive? rather than using stdlib Timeout.timeout, which raises
+    # across threads via Thread#raise and corrupts Async fiber-scheduler state
+    # (close is always called inside an Async task). Yields to the current
+    # Async task when one is active so the reactor keeps running.
+    def wait_process_with_timeout(timeout_seconds)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds
+      task = defined?(Async::Task) ? Async::Task.current? : nil
+      while @process.alive?
+        raise Timeout::Error if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+        task ? task.sleep(0.05) : sleep(0.05)
+      end
+      @process.value
+    end
+
     def write(data)
       raise CLIConnectionError, 'ProcessTransport is not ready for writing' unless @ready && @stdin
       raise CLIConnectionError, "Cannot write to terminated process" if @process && !@process.alive?

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -13,6 +13,7 @@ require_relative 'claude_agent_sdk/sdk_mcp_server'
 require_relative 'claude_agent_sdk/streaming'
 require_relative 'claude_agent_sdk/sessions'
 require_relative 'claude_agent_sdk/session_mutations'
+require_relative 'claude_agent_sdk/fiber_boundary'
 require 'async'
 require 'securerandom'
 
@@ -28,9 +29,12 @@ module ClaudeAgentSDK
   end
 
   # 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)
     observers.each do |obs|
-      obs.send(method, *args)
+      FiberBoundary.invoke { obs.send(method, *args) }
     rescue StandardError
       nil
     end
@@ -230,12 +234,14 @@ module ClaudeAgentSDK
           end
         end
 
-        # Read and yield messages from the query handler (filters out control messages)
+        # 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.
         query_handler.receive_messages do |data|
           message = MessageParser.parse(data)
           if message
             ClaudeAgentSDK.notify_observers(resolved_observers, :on_message, message)
-            block.call(message)
+            FiberBoundary.invoke { block.call(message) }
           end
         end
       ensure
@@ -406,7 +412,7 @@ module ClaudeAgentSDK
         message = MessageParser.parse(data)
         if message
           ClaudeAgentSDK.notify_observers(@resolved_observers, :on_message, message)
-          block.call(message)
+          FiberBoundary.invoke { block.call(message) }
         end
       end
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.14.2
+  version: 0.15.1
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2026-04-17 00:00:00.000000000 Z
+date: 2026-04-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -106,6 +106,7 @@ files:
 - lib/claude_agent_sdk.rb
 - lib/claude_agent_sdk/configuration.rb
 - lib/claude_agent_sdk/errors.rb
+- lib/claude_agent_sdk/fiber_boundary.rb
 - lib/claude_agent_sdk/instrumentation.rb
 - lib/claude_agent_sdk/instrumentation/otel.rb
 - lib/claude_agent_sdk/message_parser.rb