claude-agent-sdk 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16f0d3cdbf4ed8d0c3468e3247500e2e75bb01100314f8412ccb52ce7789c4a0
-  data.tar.gz: b7c4afd9e0e1f585be2eff7104b107af864c47afb3a2c9575f73c001e013d6c7
+  metadata.gz: 9c6e7dfb9b25404169db87bff2a8688c9bd1103bb04ebc980bd8206091b33f87
+  data.tar.gz: 1c921d464b1b8272742f8de36800635e5f777fb88a42304ac9a5a1d7f9027beb
 SHA512:
-  metadata.gz: a63193e6e476a0053217fd596efcfa8f3c0a2a2411d1cf0c14c241687201922089f5dc28a0e7417c5de6ad716388320038f040368a2266a97152a05980c9357d
-  data.tar.gz: b78ef0598c31580c6a9d168fe8ba39245133bbb4d7624b0e47dfdd74339ff54d2f88913b64f952d8eecff8e15655048dba2bd178508d8cf042884905e1eee9c2
+  metadata.gz: 5b7b2c4e0503db55b36d761bec12bdc43619e16688a3b3e38c79d50a34af92d68e6ccea29e523eaaa0279f577a296cb25ba0c447cafb388c2127bc870b3cc703
+  data.tar.gz: bd05dac1831ce8b77462019f026f88b2618ca6df4be31bc84c86c145fbc59fb54738530a8b6f188c654d588171acfe28efd216a8c12b846d4d3e5ae1cfe2d37f

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-04-22
+
+### Added
+- **`#text` on every message type that carries content.** No more hand-rolling a `select { TextBlock }.map(&:text).join` in every consumer.
+  - `AssistantMessage#text` — joins text across `TextBlock`s in the content array.
+  - `UserMessage#text` — handles both String content (plain prompt) and Array-of-blocks content.
+  - `SessionMessage#text` — joins text across parsed content blocks from a historical transcript.
+  - `#to_s` on each message type is aliased to `#text`, so `puts message` and string interpolation just work.
+  - Non-text blocks (`ToolUseBlock`, `ThinkingBlock`, `ToolResultBlock`, `UnknownBlock`) intentionally do **not** answer `#text` — only `TextBlock` is textual. The message helpers use `Array#grep(TextBlock)` to select text blocks.
+- **`SessionMessage#content_blocks`** returns typed block objects (`TextBlock`, `ThinkingBlock`, `ToolUseBlock`, `ToolResultBlock`, `UnknownBlock`) instead of the raw hash blocks from the JSONL transcript. Unknown block types become `UnknownBlock` for forward compatibility with newer CLI versions.
+
+### Changed
+- Rails Integration / Quick Start / Observability / File Checkpointing README examples dropped the `content.select { is_a?(TextBlock) }.map(&:text).join` dance in favor of `message.text`.
+
+## [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.16.0'
 ```
 
 And then execute:
@@ -159,11 +159,7 @@ require 'claude_agent_sdk'
 
 # Simple query
 ClaudeAgentSDK.query(prompt: "Hello Claude") do |message|
-  if message.is_a?(ClaudeAgentSDK::AssistantMessage)
-    message.content.each do |block|
-      puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
-    end
-  end
+  puts message.text if message.is_a?(ClaudeAgentSDK::AssistantMessage)
 end
 
 # With options
@@ -260,11 +256,10 @@ Async do
 
     # Receive the response
     client.receive_response do |msg|
-      if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
-        msg.content.each do |block|
-          puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
-        end
-      elsif msg.is_a?(ClaudeAgentSDK::ResultMessage)
+      case msg
+      when ClaudeAgentSDK::AssistantMessage
+        puts msg.text
+      when ClaudeAgentSDK::ResultMessage
         puts "Cost: $#{msg.total_cost_usd}" if msg.total_cost_usd
       end
     end
@@ -928,10 +923,7 @@ Async do
       # Capture UUID for rewind capability
       user_message_uuids << message.uuid if message.uuid
     when ClaudeAgentSDK::AssistantMessage
-      # Handle assistant responses
-      message.content.each do |block|
-        puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
-      end
+      puts message.text
     when ClaudeAgentSDK::ResultMessage
       puts "Query completed (cost: $#{message.total_cost_usd})"
     end
@@ -1140,11 +1132,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 )
 
 ClaudeAgentSDK.query(prompt: "List files in /tmp", options: options) do |msg|
-  if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
-    msg.content.each do |block|
-      puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
-    end
-  end
+  puts msg.text if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
 end
 
 # For long-running apps, flush before exit:
@@ -1194,6 +1182,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:
@@ -1219,8 +1246,7 @@ class ChatAgentJob < ApplicationJob
         client.receive_response do |message|
           case message
           when ClaudeAgentSDK::AssistantMessage
-            text = extract_text(message)
-            ChatChannel.broadcast_to(chat_id, { type: 'chunk', content: text })
+            ChatChannel.broadcast_to(chat_id, { type: 'chunk', content: message.text })
 
           when ClaudeAgentSDK::ResultMessage
             ChatChannel.broadcast_to(chat_id, {
@@ -1235,15 +1261,6 @@ class ChatAgentJob < ApplicationJob
       end
     end.wait
   end
-
-  private
-
-  def extract_text(message)
-    message.content
-      .select { |b| b.is_a?(ClaudeAgentSDK::TextBlock) }
-      .map(&:text)
-      .join("\n\n")
-  end
 end
 ```
 

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

@@ -288,24 +288,32 @@ module ClaudeAgentSDK
       )
     end
 
+    # Accepts blocks with either symbol or string keys — live CLI messages
+    # arrive symbol-keyed (parsed via `symbolize_names: true`), session
+    # transcripts arrive string-keyed (parsed via `symbolize_names: false`).
+    # Uses a nil-aware fallback so `is_error: false` survives.
     def self.parse_content_block(block)
-      case block[:type]
+      get = lambda do |key|
+        v = block[key]
+        v.nil? ? block[key.to_s] : v
+      end
+      case get.call(:type)
       when 'text'
-        TextBlock.new(text: block[:text])
+        TextBlock.new(text: get.call(:text))
       when 'thinking'
-        ThinkingBlock.new(thinking: block[:thinking], signature: block[:signature])
+        ThinkingBlock.new(thinking: get.call(:thinking), signature: get.call(:signature))
       when 'tool_use'
-        ToolUseBlock.new(id: block[:id], name: block[:name], input: block[:input])
+        ToolUseBlock.new(id: get.call(:id), name: get.call(:name), input: get.call(:input))
       when 'tool_result'
         ToolResultBlock.new(
-          tool_use_id: block[:tool_use_id],
-          content: block[:content],
-          is_error: block[:is_error]
+          tool_use_id: get.call(:tool_use_id),
+          content: get.call(:content),
+          is_error: get.call(:is_error)
         )
       else
         # Forward-compatible: preserve unrecognized content block types (e.g., "document", "image")
         # so newer CLI versions don't crash older SDK versions.
-        UnknownBlock.new(type: block[:type], data: block)
+        UnknownBlock.new(type: get.call(:type), data: block)
       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/sessions.rb

@@ -38,6 +38,36 @@ module ClaudeAgentSDK
       @message = message
       @parent_tool_use_id = parent_tool_use_id
     end
+
+    # Concatenated text across every TextBlock in this message.
+    # Returns "" when the message has no text content (nil message,
+    # non-Hash message, empty content, or only non-text blocks).
+    def text
+      raw = @message.is_a?(Hash) ? (@message['content'] || @message[:content]) : nil
+      case raw
+      when String then raw
+      when Array  then content_blocks.grep(TextBlock).map(&:text).join("\n\n")
+      else ''
+      end
+    end
+
+    alias to_s text
+
+    # Typed content blocks for this message. Each entry is one of
+    # TextBlock, ThinkingBlock, ToolUseBlock, ToolResultBlock, or
+    # UnknownBlock (for forward-compatibility with newer CLI block types).
+    # Returns [] when the message has no array-of-blocks content (nil
+    # message, non-Hash message, String content, missing content).
+    def content_blocks
+      return [] unless @message.is_a?(Hash)
+
+      raw = @message['content'] || @message[:content]
+      return [] unless raw.is_a?(Array)
+
+      raw.filter_map do |block|
+        MessageParser.parse_content_block(block) if block.is_a?(Hash)
+      end
+    end
   end
 
   # Session browsing functions

data/lib/claude_agent_sdk/types.rb

@@ -123,6 +123,19 @@ module ClaudeAgentSDK
       @parent_tool_use_id = parent_tool_use_id
       @tool_use_result = tool_use_result # Tool result data when message is a tool response
     end
+
+    # Concatenated text of this message. Handles both String content
+    # (plain-text user prompt) and Array-of-blocks content (typed content).
+    # Returns "" when there is no text.
+    def text
+      case @content
+      when String then @content
+      when Array then @content.grep(TextBlock).map(&:text).join("\n\n")
+      else ''
+      end
+    end
+
+    alias to_s text
   end
 
   # Assistant message with content blocks
@@ -142,6 +155,14 @@ module ClaudeAgentSDK
       @session_id = session_id # Session the message belongs to
       @uuid = uuid # Unique message UUID in the session transcript
     end
+
+    # Concatenated text across every TextBlock in this message's content.
+    # Returns "" when the message has no text (e.g., a pure tool_use turn).
+    def text
+      Array(@content).grep(TextBlock).map(&:text).join("\n\n")
+    end
+
+    alias to_s text
   end
 
   # System message with metadata

data/lib/claude_agent_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '0.15.0'
+  VERSION = '0.16.0'
 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
@@ -67,11 +71,7 @@ module ClaudeAgentSDK
   #     permission_mode: 'acceptEdits'
   #   )
   #   ClaudeAgentSDK.query(prompt: "Create a hello.rb file", options: options) do |msg|
-  #     if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
-  #       msg.content.each do |block|
-  #         puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
-  #       end
-  #     end
+  #     puts msg.text if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
   #   end
   #
   # @example Streaming input
@@ -230,12 +230,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 +408,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.16.0
 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