claude-agent-sdk 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bb953f4036b0f107f4afe0bfb8d89281bb3d496cf15f89a6c5607e7b3b5e210
-  data.tar.gz: 84081e6b7aa1ebbe580b0e900f4142829278c3a458dc706807e4d141a0af70ff
+  metadata.gz: 2c723c3e660d135ab87311e27be6a80b8d13127f9e42789a66b1d30ec0395278
+  data.tar.gz: 0652f808dd792a6bef8db32afc567567fe9f016abdf095f1d13ae0ac07af0d03
 SHA512:
-  metadata.gz: eda57b17c43f2efa673e31cba432db7022af999e8c8de82065bc4e21c13325a07480cc632004226847d383881916605218332b129f0524d2b3a1c0b291dee3d1
-  data.tar.gz: e5e9f25bb361ecaaf84a9972e55d94ed1eb18e5ae50c7abc8831f9a3a01c36e510835a8d253f71c0ba0df7f88de04ca024125ac4627a4274c84629e56ba3f57c
+  metadata.gz: 399925ff55a9a23ab54cbe97adb18fea804be6c92cf21aa3ca3fdcd4cbe54693dfc8b77b85f15ed2eaf1517acaecd09935701d0248fb99a23be6325d151c99aa
+  data.tar.gz: dd14802c444f4d6609cbb8215e79c3f5d8c4d9453e20d0d3af40cd853d653625c93e117082118beee2c5fb0ad29447a170687a44d56f88be6785affb8d118060

data/CHANGELOG.md

@@ -5,11 +5,70 @@ 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.8.0] - 2026-03-05
+
+Port of Python SDK v0.1.46 features.
+
+### Added
+
+#### Task Message Types
+- `TaskStartedMessage`, `TaskProgressMessage`, `TaskNotificationMessage` — typed `SystemMessage` subclasses for background task lifecycle events
+- `TASK_NOTIFICATION_STATUSES` constant (`completed`, `failed`, `stopped`)
+- `MessageParser` dispatches on `subtype` within `system` messages, falling back to generic `SystemMessage` for unknown subtypes
+
+#### MCP Server Control
+- `reconnect_mcp_server(server_name)` on `Query` and `Client` — retry failed MCP server connections
+- `toggle_mcp_server(server_name, enabled)` on `Query` and `Client` — enable/disable MCP servers live
+- `stop_task(task_id)` on `Query` and `Client` — stop a running background task
+
+#### Subagent Context on Hook Inputs
+- `agent_id` and `agent_type` attributes on `PreToolUseHookInput`, `PostToolUseHookInput`, `PostToolUseFailureHookInput`, `PermissionRequestHookInput`
+- Populated when hooks fire inside subagents, allowing attribution of tool calls to specific agents
+
+#### Result Message
+- `stop_reason` attribute on `ResultMessage` (e.g., `'end_turn'`, `'max_tokens'`, `'stop_sequence'`)
+
+#### Typed MCP Status Response
+- `McpServerInfo`, `McpToolAnnotations`, `McpToolInfo`, `McpServerStatus`, `McpStatusResponse` types
+- `.parse` class methods for hydrating from raw CLI response hashes
+- `MCP_SERVER_CONNECTION_STATUSES` constant (`connected`, `failed`, `needs-auth`, `pending`, `disabled`)
+
+#### Session Browsing
+- `ClaudeAgentSDK.list_sessions(directory:, limit:, include_worktrees:)` — list sessions from `~/.claude/projects/` JSONL files
+- `ClaudeAgentSDK.get_session_messages(session_id:, directory:, limit:, offset:)` — reconstruct conversation chain from session transcript
+- `SDKSessionInfo` type with `session_id`, `summary`, `last_modified`, `file_size`, `custom_title`, `first_prompt`, `git_branch`, `cwd`
+- `SessionMessage` type with `type`, `uuid`, `session_id`, `message`
+- Pure filesystem operations — no CLI subprocess required
+- Git worktree-aware session scanning
+- `parentUuid` chain walking with cycle detection for robust conversation reconstruction
+
+### Fixed
+- **`McpToolAnnotations.parse` losing `false` values:** `readOnly: false` was evaluated as `false || nil → nil` due to `||` short-circuiting. Now uses `.key?` to check presence before falling back to snake_case keys.
+
+## [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.
-- **RuboCop offense:** Removed redundant `else` clause in `MessageParser.parse`
+
+### 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
 

data/README.md

@@ -6,6 +6,119 @@
 
 [![Gem Version](https://badge.fury.io/rb/claude-agent-sdk.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/claude-agent-sdk)
 
+### Feature Parity with Python SDK (v0.1.46)
+
+| Feature | Python | Ruby |
+|---------|:------:|:----:|
+| One-shot `query()` | `query()` | `query()` |
+| Bidirectional `Client` | `ClaudeSDKClient` | `Client` |
+| Streaming input | `AsyncIterable` | `Enumerator` |
+| Custom tools (SDK MCP servers) | `@tool` decorator | `create_tool` block |
+| MCP resources & prompts | ✅ | ✅ |
+| Hooks (all 10 events) | ✅ | ✅ |
+| Permission callbacks (`can_use_tool`) | ✅ | ✅ |
+| Structured output | ✅ | ✅ |
+| Thinking config (adaptive/enabled/disabled) | ✅ | ✅ |
+| Effort levels | ✅ | ✅ |
+| Programmatic subagents | ✅ | ✅ |
+| Sandbox settings | ✅ | ✅ |
+| Beta features (1M context) | ✅ | ✅ |
+| File checkpointing & rewind | ✅ | ✅ |
+| Session browsing (`list_sessions`, `get_session_messages`) | ✅ | ✅ |
+| Task message types (started/progress/notification) | ✅ | ✅ |
+| MCP server control (reconnect/toggle/stop) | ✅ | ✅ |
+| Subagent context on hook inputs | ✅ | ✅ |
+| Typed MCP status response | ✅ | ✅ |
+| `stop_reason` on `ResultMessage` | ✅ | ✅ |
+| Fallback model | ✅ | ✅ |
+| Plugin support | ✅ | ✅ |
+| Rails integration (configure block, ActionCable) | — | ✅ |
+| Bundled CLI binary | ✅ | — |
+
+<details>
+<summary><strong>Usage & Implementation Differences</strong></summary>
+
+#### Async model
+
+Python uses `async`/`await` with `anyio` (works with both asyncio and Trio). Ruby uses the [`async`](https://github.com/socketry/async) gem with fibers — no `await` keyword needed, blocking calls yield automatically.
+
+```python
+# Python
+async with ClaudeSDKClient(options) as client:
+    await client.query("Hello")
+    async for msg in client.receive_messages():
+        print(msg)
+```
+
+```ruby
+# Ruby
+Async do
+  client = ClaudeAgentSDK::Client.new(options: options)
+  client.connect
+  client.query("Hello")
+  client.receive_messages { |msg| puts msg }
+  client.disconnect
+end.wait
+```
+
+#### Custom tools
+
+Python uses a `@tool` decorator. Ruby uses `create_tool` with a block.
+
+```python
+# Python
+@tool(name="add", description="Add numbers", input_schema={...})
+def add(a: int, b: int) -> str:
+    return str(a + b)
+```
+
+```ruby
+# Ruby
+add = ClaudeAgentSDK.create_tool("add", "Add numbers", { a: :number, b: :number }) do |args|
+  { content: [{ type: "text", text: (args[:a] + args[:b]).to_s }] }
+end
+```
+
+#### Streaming input
+
+Python uses `AsyncIterable`. Ruby uses `Enumerator` or any `#each`-able.
+
+```python
+# Python
+async def messages():
+    yield {"type": "user", "message": {"role": "user", "content": "Hello"}}
+
+async for msg in query(prompt=messages(), options=options):
+    print(msg)
+```
+
+```ruby
+# Ruby
+messages = ClaudeAgentSDK::Streaming.from_array(["Hello", "Follow up"])
+ClaudeAgentSDK.query(prompt: messages) { |msg| puts msg }
+```
+
+#### Types
+
+Python uses `dataclass` with type annotations and `TypedDict`. Ruby uses plain classes with `attr_accessor` and keyword args — no runtime type checking, but the same structure.
+
+#### Configuration defaults
+
+Python passes options directly. Ruby adds `ClaudeAgentSDK.configure` for global defaults that merge with per-call options — handy for Rails initializers.
+
+```ruby
+# Ruby-only: global defaults
+ClaudeAgentSDK.configure do |config|
+  config.default_options = { model: "sonnet", permission_mode: "bypassPermissions" }
+end
+```
+
+#### Subprocess transport
+
+Both SDKs spawn `claude` CLI as a subprocess with stream-JSON over stdin/stdout. Python uses `anyio.open_process`; Ruby uses `Open3.popen3` with a background `Thread` for stderr. The wire protocol is identical.
+
+</details>
+
 ## Table of Contents
 
 - [Installation](#installation)
@@ -23,6 +136,7 @@
 - [Tools Configuration](#tools-configuration)
 - [Sandbox Settings](#sandbox-settings)
 - [File Checkpointing & Rewind](#file-checkpointing--rewind)
+- [Session Browsing](#session-browsing)
 - [Rails Integration](#rails-integration)
 - [Types](#types)
 - [Error Handling](#error-handling)
@@ -39,7 +153,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.2'
+gem 'claude-agent-sdk', '~> 0.8.0'
 ```
 
 And then execute:
@@ -225,13 +339,18 @@ Async do
   puts "MCP status: #{status}"
 
   # Get server initialization info
-  info = client.server_info
-  puts "Available commands: #{info}"
-
-  # (Parity alias) Get server initialization info
   info = client.get_server_info
   puts "Available commands: #{info}"
 
+  # Reconnect a failed MCP server
+  client.reconnect_mcp_server('my-server')
+
+  # Enable or disable an MCP server
+  client.toggle_mcp_server('my-server', false)
+
+  # Stop a running background task
+  client.stop_task('task_abc123')
+
   client.disconnect
 end.wait
 ```
@@ -282,6 +401,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
@@ -754,6 +893,47 @@ end.wait
 
 > **Note:** The `uuid` field on `UserMessage` is populated by the CLI and represents checkpoint identifiers. Rewinding to a UUID restores file state to what it was at that point in the conversation.
 
+## Session Browsing
+
+Browse and inspect previous Claude Code sessions directly from Ruby — no CLI subprocess required.
+
+### Listing Sessions
+
+```ruby
+# List all sessions (sorted by most recent first)
+sessions = ClaudeAgentSDK.list_sessions
+sessions.each do |session|
+  puts "#{session.session_id}: #{session.summary} (#{session.git_branch})"
+end
+
+# List sessions for a specific directory
+sessions = ClaudeAgentSDK.list_sessions(directory: '/path/to/project', limit: 10)
+
+# Include git worktree sessions
+sessions = ClaudeAgentSDK.list_sessions(directory: '.', include_worktrees: true)
+```
+
+Each `SDKSessionInfo` includes:
+- `session_id`, `summary`, `last_modified`, `file_size`
+- `custom_title`, `first_prompt`, `git_branch`, `cwd`
+
+### Reading Session Messages
+
+```ruby
+# Get the full conversation from a session
+messages = ClaudeAgentSDK.get_session_messages(session_id: 'abc-123-...')
+messages.each do |msg|
+  puts "[#{msg.type}] #{msg.message}"
+end
+
+# Paginate through messages
+page = ClaudeAgentSDK.get_session_messages(session_id: 'abc-123-...', offset: 10, limit: 20)
+```
+
+Each `SessionMessage` includes `type` (`"user"` or `"assistant"`), `uuid`, `session_id`, and `message` (raw API dict).
+
+> **Note:** Session browsing reads `~/.claude/projects/` JSONL files directly. It respects the `CLAUDE_CONFIG_DIR` environment variable and automatically detects git worktrees.
+
 ## Rails Integration
 
 The SDK integrates well with Rails applications. Here are common patterns:
@@ -946,13 +1126,26 @@ end
 
 #### SystemMessage
 
-System message with metadata.
+System message with metadata. Task lifecycle events are typed subclasses.
 
 ```ruby
 class SystemMessage
-  attr_accessor :subtype,  # String ('init', etc.)
+  attr_accessor :subtype,  # String ('init', 'task_started', 'task_progress', 'task_notification', etc.)
                 :data      # Hash
 end
+
+# Typed subclasses (all inherit from SystemMessage, so is_a?(SystemMessage) still works)
+class TaskStartedMessage < SystemMessage
+  attr_accessor :task_id, :description, :uuid, :session_id, :tool_use_id, :task_type
+end
+
+class TaskProgressMessage < SystemMessage
+  attr_accessor :task_id, :description, :usage, :uuid, :session_id, :tool_use_id, :last_tool_name
+end
+
+class TaskNotificationMessage < SystemMessage
+  attr_accessor :task_id, :status, :output_file, :summary, :uuid, :session_id, :tool_use_id, :usage
+end
 ```
 
 #### ResultMessage
@@ -967,6 +1160,7 @@ class ResultMessage
                 :is_error,          # Boolean
                 :num_turns,         # Integer
                 :session_id,        # String
+                :stop_reason,       # String | nil ('end_turn', 'max_tokens', 'stop_sequence')
                 :total_cost_usd,    # Float | nil
                 :usage,             # Hash | nil
                 :result,            # String | nil (final text result)
@@ -978,7 +1172,7 @@ end
 
 ```ruby
 # Union type of all content blocks
-ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
+ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock | UnknownBlock
 ```
 
 #### TextBlock
@@ -1026,6 +1220,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
@@ -1080,6 +1285,13 @@ end
 | `McpSSEServerConfig` | MCP server config for SSE transport |
 | `McpHttpServerConfig` | MCP server config for HTTP transport |
 | `SdkPluginConfig` | SDK plugin configuration |
+| `McpServerStatus` | Status of a single MCP server connection (with `.parse`) |
+| `McpStatusResponse` | Response from `get_mcp_status` containing all server statuses (with `.parse`) |
+| `McpServerInfo` | MCP server name and version |
+| `McpToolInfo` | MCP tool name, description, and annotations |
+| `McpToolAnnotations` | MCP tool annotation hints (`read_only`, `destructive`, `open_world`) |
+| `SDKSessionInfo` | Session metadata from `list_sessions` |
+| `SessionMessage` | Single message from `get_session_messages` |
 | `SandboxSettings` | Sandbox settings for isolated command execution |
 | `SandboxNetworkConfig` | Network configuration for sandbox |
 | `SandboxIgnoreViolations` | Configure which sandbox violations to ignore |
@@ -1095,6 +1307,8 @@ end
 | `SETTING_SOURCES` | Available setting sources |
 | `HOOK_EVENTS` | Available hook events |
 | `ASSISTANT_MESSAGE_ERRORS` | Possible error types in AssistantMessage |
+| `TASK_NOTIFICATION_STATUSES` | Task lifecycle notification statuses (`completed`, `failed`, `stopped`) |
+| `MCP_SERVER_CONNECTION_STATUSES` | MCP server connection states (`connected`, `failed`, `needs-auth`, `pending`, `disabled`) |
 
 ## Error Handling
 

data/lib/claude_agent_sdk/message_parser.rb

@@ -66,10 +66,32 @@ module ClaudeAgentSDK
     end
 
     def self.parse_system_message(data)
-      SystemMessage.new(
-        subtype: data[:subtype],
-        data: data
-      )
+      case data[:subtype]
+      when 'task_started'
+        TaskStartedMessage.new(
+          subtype: data[:subtype], data: data,
+          task_id: data[:task_id], description: data[:description],
+          uuid: data[:uuid], session_id: data[:session_id],
+          tool_use_id: data[:tool_use_id], task_type: data[:task_type]
+        )
+      when 'task_progress'
+        TaskProgressMessage.new(
+          subtype: data[:subtype], data: data,
+          task_id: data[:task_id], description: data[:description],
+          usage: data[:usage], uuid: data[:uuid], session_id: data[:session_id],
+          tool_use_id: data[:tool_use_id], last_tool_name: data[:last_tool_name]
+        )
+      when 'task_notification'
+        TaskNotificationMessage.new(
+          subtype: data[:subtype], data: data,
+          task_id: data[:task_id], status: data[:status],
+          output_file: data[:output_file], summary: data[:summary],
+          uuid: data[:uuid], session_id: data[:session_id],
+          tool_use_id: data[:tool_use_id], usage: data[:usage]
+        )
+      else
+        SystemMessage.new(subtype: data[:subtype], data: data)
+      end
     end
 
     def self.parse_result_message(data)
@@ -80,10 +102,11 @@ module ClaudeAgentSDK
         is_error: data[:is_error],
         num_turns: data[:num_turns],
         session_id: data[:session_id],
+        stop_reason: data[:stop_reason],
         total_cost_usd: data[:total_cost_usd],
         usage: data[:usage],
         result: data[:result],
-        structured_output: data[:structured_output] # Structured output when output_format is specified
+        structured_output: data[:structured_output]
       )
     end
 

data/lib/claude_agent_sdk/query.rb

@@ -316,13 +316,19 @@ module ClaudeAgentSDK
         permission_mode: fetch.call(:permission_mode)
       }
 
+      # Subagent context fields shared by tool-lifecycle hooks
+      subagent_args = {
+        agent_id: fetch.call(:agent_id),
+        agent_type: fetch.call(:agent_type)
+      }
+
       case event_name
       when 'PreToolUse'
         PreToolUseHookInput.new(
           tool_name: fetch.call(:tool_name),
           tool_input: fetch.call(:tool_input),
           tool_use_id: fetch.call(:tool_use_id),
-          **base_args
+          **subagent_args, **base_args
         )
       when 'PostToolUse'
         PostToolUseHookInput.new(
@@ -330,7 +336,7 @@ module ClaudeAgentSDK
           tool_input: fetch.call(:tool_input),
           tool_response: fetch.call(:tool_response),
           tool_use_id: fetch.call(:tool_use_id),
-          **base_args
+          **subagent_args, **base_args
         )
       when 'PostToolUseFailure'
         PostToolUseFailureHookInput.new(
@@ -339,7 +345,7 @@ module ClaudeAgentSDK
           tool_use_id: fetch.call(:tool_use_id),
           error: fetch.call(:error),
           is_interrupt: fetch.call(:is_interrupt),
-          **base_args
+          **subagent_args, **base_args
         )
       when 'UserPromptSubmit'
         UserPromptSubmitHookInput.new(
@@ -377,7 +383,7 @@ module ClaudeAgentSDK
           tool_name: fetch.call(:tool_name),
           tool_input: fetch.call(:tool_input),
           permission_suggestions: fetch.call(:permission_suggestions),
-          **base_args
+          **subagent_args, **base_args
         )
       when 'PreCompact'
         PreCompactHookInput.new(
@@ -662,6 +668,35 @@ module ClaudeAgentSDK
                            })
     end
 
+    # Reconnect a failed MCP server
+    # @param server_name [String] Name of the MCP server to reconnect
+    def reconnect_mcp_server(server_name)
+      send_control_request({
+                             subtype: 'mcp_reconnect',
+                             serverName: server_name
+                           })
+    end
+
+    # Enable or disable an MCP server
+    # @param server_name [String] Name of the MCP server
+    # @param enabled [Boolean] Whether to enable or disable
+    def toggle_mcp_server(server_name, enabled)
+      send_control_request({
+                             subtype: 'mcp_toggle',
+                             serverName: server_name,
+                             enabled: enabled
+                           })
+    end
+
+    # Stop a running background task
+    # @param task_id [String] The ID of the task to stop
+    def stop_task(task_id)
+      send_control_request({
+                             subtype: 'stop_task',
+                             task_id: task_id
+                           })
+    end
+
     # Rewind files to a previous checkpoint (v0.1.15+)
     # Restores file state to what it was at the given user message
     # Requires enable_file_checkpointing to be true in options

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
@@ -191,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
@@ -318,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