claude-agent-sdk 0.7.1 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 303a5cd2321bb9c04f17d68990abfb8f72c6a88624874f199afaf7769befca33
-  data.tar.gz: 3831d1fdec75b38072083d231dcf03a87407244bda805e51661d771be23105ac
+  metadata.gz: d17d03fa867e2779de155d6fba8a86fbc9edbc5662157ca3e21606016c81fb17
+  data.tar.gz: 949787994cd58eb5be72b8834a519a704697c61ecbfff9ca1d6f4e1fe921b18f
 SHA512:
-  metadata.gz: 569f331952bcef9c7426fc61bd1c36f082acf721e9ab5a899783ea06fdee5accfcb2f903c536ba9cf99ee50e96aceb254d9305751631643f532c549b39b48ff6
-  data.tar.gz: 2c22f2cde6cf7c5e059ebbdfe515f559979b4cd273b28e1d7113cf55e9e739a201725f81f2ee602623242c12f7c557edbb0b5ade8a1088e997d4ddd01566561c
+  metadata.gz: a99fdb7b2dcab7e0286763abfb1f6d0277423a7ef2198a040ef8c76a8959907009ebc21f6523c35ecff1409a66fd8c636648d1f594aaa481119ed3598eb1b06e
+  data.tar.gz: 8e3e7e26487dcfe993534d3d1b7f695ba5009ad18e9d173c9e1e0f1353ec54565905f3e74e81a39eb5789aa2df008536a2a5a191095e7d8604f36abd27bb6583

data/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.3] - 2026-02-26
+
+### Fixed
+- **String-keyed JSON schema crash:** Libraries like [RubyLLM](https://github.com/crmne/ruby_llm) that deep-stringify schema keys (e.g., `{ 'type' => 'object', 'properties' => { ... } }`) were misidentified as simple type-mapping schemas, causing each top-level key to be treated as a parameter name instead of passing the schema through. Now both symbol-keyed and string-keyed schemas are detected and normalized correctly. (PR #9 by [@iuhoay](https://github.com/iuhoay))
+- **Shallow key symbolization:** `convert_schema` used `transform_keys` (shallow) which left nested property keys as strings, breaking downstream `MCP::Tool::InputSchema` construction. Now uses deep symbolization recursively.
+- **Guard ordering crash:** `convert_schema` and `convert_input_schema` accessed `schema[:type]` before the `schema.is_a?(Hash)` guard, which would raise `NoMethodError` on `nil` input.
+- **Schema detection tightened:** Pre-built schema detection now requires `type == 'object'` and `properties.is_a?(Hash)`, preventing false positives when a simple schema happens to have parameters named `type` and `properties`.
+
+### Added
+- `ClaudeAgentSDK.deep_symbolize_keys` utility method for recursive hash key symbolization
+
+## [0.7.2] - 2026-02-21
+
+### Fixed
+- **Unknown content block crash:** Unrecognized content block types (e.g., `document` blocks from PDF reading) now return `UnknownBlock` instead of raising `MessageParseError`, aligning with the Python SDK's forward-compatible design
+- **Unknown message type crash:** Unrecognized message types now return `nil` (skipped by callers) instead of raising
+- **Empty input schema crash:** Tools with no parameters (`input_schema: {}`) caused `MCP::Tool::InputSchema` validation failure (`required` array must have at least 1 item per JSON Schema draft-04). Now omits `required` when empty.
+
+### Added
+- `UnknownBlock` type that preserves raw data for unrecognized content block types
+
+### Changed
+- **Breaking (minor):** `MessageParser.parse` no longer raises `MessageParseError` for unknown message types — returns `nil` instead. If you were rescuing `MessageParseError` to handle unknown types, check for `nil` return values instead.
+- **Breaking (minor):** `MessageParser.parse_content_block` no longer raises `MessageParseError` for unknown content block types — returns `UnknownBlock` instead. Content block iteration using `is_a?` filtering (e.g., `block.is_a?(TextBlock)`) is unaffected.
+
 ## [0.7.1] - 2026-02-21
 
 ### Fixed

data/README.md

@@ -39,7 +39,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.7.0'
+gem 'claude-agent-sdk', '~> 0.7.3'
 ```
 
 And then execute:
@@ -282,6 +282,26 @@ Async do
 end.wait
 ```
 
+### Pre-built JSON Schemas
+
+If your schemas come from another library (e.g., [RubyLLM](https://github.com/crmne/ruby_llm)) that deep-stringifies keys, the SDK handles them transparently — both symbol-keyed and string-keyed schemas are accepted and normalized:
+
+```ruby
+# Symbol keys (standard Ruby)
+tool = ClaudeAgentSDK.create_tool('save', 'Save a fact', {
+  type: 'object',
+  properties: { fact: { type: 'string' } },
+  required: ['fact']
+}) { |args| { content: [{ type: 'text', text: "Saved: #{args[:fact]}" }] } }
+
+# String keys (e.g., from RubyLLM or JSON.parse)
+tool = ClaudeAgentSDK.create_tool('save', 'Save a fact', {
+  'type' => 'object',
+  'properties' => { 'fact' => { 'type' => 'string' } },
+  'required' => ['fact']
+}) { |args| { content: [{ type: 'text', text: "Saved: #{args[:fact]}" }] } }
+```
+
 ### Benefits Over External MCP Servers
 
 - **No subprocess management** - Runs in the same process as your application
@@ -978,7 +998,7 @@ end
 
 ```ruby
 # Union type of all content blocks
-ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
+ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock | UnknownBlock
 ```
 
 #### TextBlock
@@ -1026,6 +1046,17 @@ class ToolResultBlock
 end
 ```
 
+#### UnknownBlock
+
+Generic content block for types the SDK doesn't explicitly handle (e.g., `document` for PDFs, `image` for inline images). Preserves the raw data for forward compatibility with newer CLI versions.
+
+```ruby
+class UnknownBlock
+  attr_accessor :type,  # String — the original block type (e.g., "document")
+                :data   # Hash — the full raw block hash
+end
+```
+
 ### Error Types
 
 ```ruby

data/lib/claude_agent_sdk/message_parser.rb

@@ -25,9 +25,9 @@ module ClaudeAgentSDK
         parse_stream_event(data)
       when 'rate_limit_event'
         parse_rate_limit_event(data)
-      else
-        raise MessageParseError.new("Unknown message type: #{message_type}", data: data)
       end
+      # Forward-compatible: returns nil for unrecognized message types so
+      # newer CLI versions don't crash older SDK versions.
     rescue KeyError => e
       raise MessageParseError.new("Missing required field: #{e.message}", data: data)
     end
@@ -115,7 +115,9 @@ module ClaudeAgentSDK
           is_error: block[:is_error]
         )
       else
-        raise MessageParseError.new("Unknown content block type: #{block[:type]}")
+        # 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)
       end
     end
   end

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -3,6 +3,15 @@
 require 'mcp'
 
 module ClaudeAgentSDK
+  # Recursively convert all hash keys to symbols
+  def self.deep_symbolize_keys(obj)
+    case obj
+    when Hash then obj.transform_keys(&:to_sym).transform_values { |v| deep_symbolize_keys(v) }
+    when Array then obj.map { |v| deep_symbolize_keys(v) }
+    else obj
+    end
+  end
+
   # SDK MCP Server - wraps official MCP::Server with block-based API
   #
   # Unlike external MCP servers that run as separate processes, SDK MCP servers
@@ -164,10 +173,9 @@ module ClaudeAgentSDK
 
             def input_schema_value
               schema = convert_schema(@tool_def.input_schema)
-              MCP::Tool::InputSchema.new(
-                properties: schema[:properties] || {},
-                required: schema[:required] || []
-              )
+              opts = { properties: schema[:properties] || {} }
+              opts[:required] = schema[:required] if schema[:required]&.any?
+              MCP::Tool::InputSchema.new(**opts)
             end
 
             def call(server_context: nil, **args)
@@ -192,9 +200,12 @@ module ClaudeAgentSDK
             private
 
             def convert_schema(schema)
-              # If it's already a proper JSON schema, return it
-              if schema.is_a?(Hash) && schema[:type] && schema[:properties]
-                return schema
+              # If it's already a proper JSON schema (symbol or string keys), normalize
+              # to symbol keys so downstream code (schema[:properties]) works uniformly.
+              if schema.is_a?(Hash)
+                type_val = schema[:type] || schema['type']
+                props_val = schema[:properties] || schema['properties']
+                return ClaudeAgentSDK.deep_symbolize_keys(schema) if type_val == 'object' && props_val.is_a?(Hash)
               end
 
               # Simple schema: hash mapping parameter names to types
@@ -204,11 +215,10 @@ module ClaudeAgentSDK
                   properties[param_name] = type_to_json_schema(param_type)
                 end
 
-                return {
-                  type: 'object',
-                  properties: properties,
-                  required: properties.keys.map(&:to_s)
-                }
+                result = { type: 'object', properties: properties }
+                required_keys = properties.keys.map(&:to_s)
+                result[:required] = required_keys unless required_keys.empty?
+                return result
               end
 
               # Default fallback
@@ -320,9 +330,12 @@ module ClaudeAgentSDK
     end
 
     def convert_input_schema(schema)
-      # If it's already a proper JSON schema, return it
-      if schema.is_a?(Hash) && schema[:type] && schema[:properties]
-        return schema
+      # If it's already a proper JSON schema (symbol or string keys), normalize
+      # to symbol keys for consistent output.
+      if schema.is_a?(Hash)
+        type_val = schema[:type] || schema['type']
+        props_val = schema[:properties] || schema['properties']
+        return ClaudeAgentSDK.deep_symbolize_keys(schema) if type_val == 'object' && props_val.is_a?(Hash)
       end
 
       # Simple schema: hash mapping parameter names to types
@@ -332,11 +345,9 @@ module ClaudeAgentSDK
           properties[param_name] = type_to_json_schema(param_type)
         end
 
-        return {
-          type: 'object',
-          properties: properties,
-          required: properties.keys
-        }
+        result = { type: 'object', properties: properties }
+        result[:required] = properties.keys unless properties.empty?
+        return result
       end
 
       # Default fallback

data/lib/claude_agent_sdk/types.rb

@@ -77,6 +77,17 @@ module ClaudeAgentSDK
     end
   end
 
+  # Generic content block for types the SDK doesn't explicitly handle (e.g., "document", "image").
+  # Preserves the raw hash data for forward compatibility with newer CLI versions.
+  class UnknownBlock
+    attr_accessor :type, :data
+
+    def initialize(type:, data:)
+      @type = type
+      @data = data
+    end
+  end
+
   # Message Types
 
   # User message

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -119,7 +119,7 @@ module ClaudeAgentSDK
         # Read and yield messages from the query handler (filters out control messages)
         query_handler.receive_messages do |data|
           message = MessageParser.parse(data)
-          block.call(message)
+          block.call(message) if message
         end
       ensure
         # query_handler.close stops the background read task and closes the transport
@@ -275,7 +275,7 @@ module ClaudeAgentSDK
 
       @query_handler.receive_messages do |data|
         message = MessageParser.parse(data)
-        block.call(message)
+        block.call(message) if message
       end
     end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.3
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2026-02-20 00:00:00.000000000 Z
+date: 2026-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async