claude-agent-sdk 0.15.1 → 0.16.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a037f9cca486fc8d6e94269b9f5f7b686574665ff403457761db764f9f50f07
-  data.tar.gz: 01bff518e3306d1fb23b8bc1e9b11b72785a98aecf3636a1096c5522f4720444
+  metadata.gz: 784f87932778dac72fe69ebbe3236e62a7df31f9671b52150fae392aa3d57f05
+  data.tar.gz: cd743d1cabb8bd151457f0a4b18be725f25b5de684ba2430df8a76037900dd98
 SHA512:
-  metadata.gz: 253df532bcdc4a6e0b13e0d4438944bcf9c6018b5d1062b4831efc6dac7a332c1759f85137e6de4fc44de0e8b1eb7ccfd0033698392c8faf6ca40f7e237b2e51
-  data.tar.gz: 143d4ee8780d1a675e1531edc944de1756bff03faa9c42513b9672a3f37ac670dc17929a936cf0f1520d1cfdc45c53042d8f8fa07ad5a559e4b59439e79848f5
+  metadata.gz: 68b582ef69fec09c0487d6d5600c76ac5d5a8420264f2b151cc7f52f95c7fb975339d6afa9fe519d4e75b48781c4f6132446fb03b2e9995decc3088ccd66c0f1
+  data.tar.gz: d119aaba15cb76997ceb58abbc43176a82df9ad4b697089a6b26ffbe342fb50ea10173890dddb03d5dc13397989abb774b617f140b1f92b3fdb0a8d16e3298d2

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.1] - 2026-04-21
+
+### Fixed
+- `Client#receive_response` no longer raises `LocalJumpError: break from proc-closure` when called inside `Async { }`. The 0.15.1 thread-hop severed `break`'s unwind target; replaced with a flag so the loop exits via the natural `end` marker after `ResultMessage`.
+
+## [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

data/README.md

@@ -1,5 +1,7 @@
 # Claude Agent SDK for Ruby
 
+![Claude Agent SDK for Ruby banner](assets/claude-agent-sdk-ruby-banner.png)
+
 [![Gem Version](https://badge.fury.io/rb/claude-agent-sdk.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/claude-agent-sdk)
 
 An **unofficial, community-maintained** Ruby SDK for the [Claude Code](https://docs.claude.com/en/docs/claude-code-overview) agent runtime. Not affiliated with or supported by Anthropic.
@@ -106,7 +108,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.1'
+gem 'claude-agent-sdk', '~> 0.16.1'
 ```
 
 And then execute:
@@ -159,11 +161,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 +258,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 +925,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 +1134,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:
@@ -1258,8 +1248,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, {
@@ -1274,15 +1263,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/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/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.1'
+  VERSION = '0.16.1'
 end

data/lib/claude_agent_sdk.rb

@@ -71,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
@@ -422,9 +418,15 @@ module ClaudeAgentSDK
     def receive_response(&block)
       return enum_for(:receive_response) unless block
 
+      # Flag-based rather than `break`: `receive_messages` hops this
+      # block onto a plain thread via `FiberBoundary.invoke`, which
+      # severs break's unwind target.
+      result_seen = false
       receive_messages do |message|
+        next if result_seen
+
         block.call(message)
-        break if message.is_a?(ResultMessage)
+        result_seen = true if message.is_a?(ResultMessage)
       end
     end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.16.1
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2026-04-21 00:00:00.000000000 Z
+date: 2026-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async