claude-agent-sdk 0.15.0 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16f0d3cdbf4ed8d0c3468e3247500e2e75bb01100314f8412ccb52ce7789c4a0
-  data.tar.gz: b7c4afd9e0e1f585be2eff7104b107af864c47afb3a2c9575f73c001e013d6c7
+  metadata.gz: 9a037f9cca486fc8d6e94269b9f5f7b686574665ff403457761db764f9f50f07
+  data.tar.gz: 01bff518e3306d1fb23b8bc1e9b11b72785a98aecf3636a1096c5522f4720444
 SHA512:
-  metadata.gz: a63193e6e476a0053217fd596efcfa8f3c0a2a2411d1cf0c14c241687201922089f5dc28a0e7417c5de6ad716388320038f040368a2266a97152a05980c9357d
-  data.tar.gz: b78ef0598c31580c6a9d168fe8ba39245133bbb4d7624b0e47dfdd74339ff54d2f88913b64f952d8eecff8e15655048dba2bd178508d8cf042884905e1eee9c2
+  metadata.gz: 253df532bcdc4a6e0b13e0d4438944bcf9c6018b5d1062b4831efc6dac7a332c1759f85137e6de4fc44de0e8b1eb7ccfd0033698392c8faf6ca40f7e237b2e51
+  data.tar.gz: 143d4ee8780d1a675e1531edc944de1756bff03faa9c42513b9672a3f37ac670dc17929a936cf0f1520d1cfdc45c53042d8f8fa07ad5a559e4b59439e79848f5

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

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.15.0'
+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

@@ -300,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
@@ -338,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '0.15.0'
+  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.15.0
+  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