claude-agent-sdk 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4b8c3f8f0eefdfe38747d264f5d89148e1e589f12c200796dd2c37e821b3f61
-  data.tar.gz: 60252ef9c5f8679526a1f76b1be4216138e8bc7d91deb7bc1235b94d04a8481d
+  metadata.gz: db31632430bb28dc8f07903bfc8634a8c437da9dc988f2237606948ecc71f7e0
+  data.tar.gz: e7574810137063aef37a0a78fb9d855645a0a479ba0b909b63a491f0ea7060f6
 SHA512:
-  metadata.gz: a95797df469fa0acede9c2187d0e8dd9420582e856853552dcc4b0c09b7e4564ca7371478624a904090366d06880a2e7457f71910b88e815fbbe12d8f210f255
-  data.tar.gz: 77354e6852d2f86b060ac0e4948006ed1c28311f7481e4efa7cdc2f57864448ab0d656244559da43094cde1ac409ae25fd4aad13228640001b0e453d7d9fc753
+  metadata.gz: e394102a18bace179f7745b2b10cc721393ff25e8dcbc75f9492e6822aa6a80afa1455eb168b6567857cbf10a7d1d2e96e7293e43b043ad69ac2b41f95a3eb99
+  data.tar.gz: 03b94423b5d2369eb974e9cf82b2523e36aea4a09d05181e86528da11b3432d8685256705989210941b644333b5f9d3173b2efa0fd3b5f1b74e5e5aea3705bc6

data/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.4.2] - 2026-02-07
+
+### Fixed
+- **MCP response fidelity:** Non-text content (images, binary data) is now preserved in SDK MCP tool responses instead of being silently dropped
+- **MCP error key:** Tool error flag is now sent as `isError` (camelCase) matching the JSON-RPC spec, instead of `is_error` which the CLI ignored
+- **MCP structured content:** `structuredContent` is now passed through in tool responses
+- **ENV pollution:** `query()` and `Client.connect` no longer mutate the global `ENV`; entrypoint is passed via transport options
+- **Symbol key env:** Fixed symbol keys in `env` option causing spawn failures (PR #7)
+
+### Added
+- `ClaudeAgentSDK.flexible_fetch` helper for tolerant hash key lookup (symbol/string, camelCase/snake_case)
+- Gated real CLI integration tests (`RUN_REAL_INTEGRATION=1`) with budget cap
+- `CLAUDE.md` architecture guide for contributors
+
+## [0.4.1] - 2026-02-05
+
+### Added
+
+#### Hook Parity
+- Added hook event support for `PostToolUseFailure`, `Notification`, `SubagentStart`, and `PermissionRequest`
+- Expanded `SubagentStop` hook inputs with `agent_id`, `agent_transcript_path`, and `agent_type`
+- Added hook-specific outputs for new hook events
+- Added `updatedMCPToolOutput` support to `PostToolUse` hook outputs
+
+#### MCP Status APIs
+- `get_mcp_status` on `Query` and `Client` for live MCP connection status (streaming mode)
+- `get_server_info` on `Client` as a parity alias for server initialization info
+
+### Fixed
+- Hook input parsing now supports both symbol and string keys
+- Hook callback timeouts are enforced and control request cancellation is handled cleanly
+
 ## [0.4.0] - 2026-01-06
 
 ### Added
@@ -54,7 +86,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Improved
 - Better long-term maintenance by leveraging official SDK updates
 - Aligned with Python SDK implementation pattern (using official MCP library)
-- All 86 tests passing with full backward compatibility maintained
+- All tests passing with full backward compatibility maintained
 
 ### Technical Details
 - Creates dynamic `MCP::Tool`, `MCP::Resource`, and `MCP::Prompt` classes from block-based definitions
@@ -75,7 +107,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Critical:** Replaced `Async::Process` with Ruby's built-in `Open3` for subprocess management
 - Fixed "uninitialized constant Async::Process" error that prevented the gem from working
 - Process management now uses standard Ruby threads instead of async tasks
-- All 86 tests passing
+- All tests passing
 
 ## [0.1.1] - 2025-10-14
 
@@ -84,7 +116,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed issue where SDK couldn't find Claude Code when accessed via shell alias
 
 ### Added
-- Comprehensive test suite with 86 passing tests
+- Comprehensive test suite (RSpec)
 - Test documentation in spec/README.md
 
 ### Changed

data/README.md

@@ -22,6 +22,7 @@
 - [Tools Configuration](#tools-configuration)
 - [Sandbox Settings](#sandbox-settings)
 - [File Checkpointing & Rewind](#file-checkpointing--rewind)
+- [Rails Integration](#rails-integration)
 - [Types](#types)
 - [Error Handling](#error-handling)
 - [Examples](#examples)
@@ -33,6 +34,10 @@
 Add this line to your application's Gemfile:
 
 ```ruby
+# Recommended: Use the latest from GitHub for newest features
+gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
+
+# Or use a stable version from RubyGems
 gem 'claude-agent-sdk', '~> 0.4.0'
 ```
 
@@ -42,7 +47,7 @@ And then execute:
 bundle install
 ```
 
-Or install it yourself as:
+Or install directly from RubyGems:
 
 ```bash
 gem install claude-agent-sdk
@@ -53,6 +58,16 @@ gem install claude-agent-sdk
 - Node.js
 - Claude Code 2.0.0+: `npm install -g @anthropic-ai/claude-code`
 
+### Agentic Coding Skill
+
+If you're using [Claude Code](https://claude.ai/claude-code) or another agentic coding tool that supports [skills](https://skills.sh), you can install the SDK skill:
+
+```bash
+npx skills add https://github.com/ya-luotao/claude-agent-sdk-ruby --skill claude-agent-sdk-ruby
+```
+
+This skill teaches your AI coding assistant about the SDK's APIs, patterns, and best practices, making it easier to get help writing code that uses this SDK.
+
 ## Quick Start
 
 ```ruby
@@ -204,10 +219,18 @@ Async do
   # Change AI model during conversation
   client.set_model('claude-sonnet-4-5')
 
+  # Get MCP server connection status
+  status = client.get_mcp_status
+  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}"
+
   client.disconnect
 end.wait
 ```
@@ -365,6 +388,21 @@ For complete examples, see [examples/mcp_calculator.rb](examples/mcp_calculator.
 
 A **hook** is a Ruby proc/lambda that the Claude Code *application* (*not* Claude) invokes at specific points of the Claude agent loop. Hooks can provide deterministic processing and automated feedback for Claude. Read more in [Claude Code Hooks Reference](https://docs.anthropic.com/en/docs/claude-code/hooks).
 
+### Supported Events
+
+All hook input objects include common fields like `session_id`, `transcript_path`, `cwd`, and `permission_mode`.
+
+- `PreToolUse` → `PreToolUseHookInput` (`tool_name`, `tool_input`)
+- `PostToolUse` → `PostToolUseHookInput` (`tool_name`, `tool_input`, `tool_response`)
+- `PostToolUseFailure` → `PostToolUseFailureHookInput` (`tool_name`, `tool_input`, `tool_use_id`, `error`, `is_interrupt`)
+- `UserPromptSubmit` → `UserPromptSubmitHookInput` (`prompt`)
+- `Stop` → `StopHookInput` (`stop_hook_active`)
+- `SubagentStop` → `SubagentStopHookInput` (`stop_hook_active`, `agent_id`, `agent_transcript_path`, `agent_type`)
+- `PreCompact` → `PreCompactHookInput` (`trigger`, `custom_instructions`)
+- `Notification` → `NotificationHookInput` (`message`, `title`, `notification_type`)
+- `SubagentStart` → `SubagentStartHookInput` (`agent_id`, `agent_type`)
+- `PermissionRequest` → `PermissionRequestHookInput` (`tool_name`, `tool_input`, `permission_suggestions`)
+
 ### Example
 
 ```ruby
@@ -373,13 +411,12 @@ require 'async'
 
 Async do
   # Define a hook that blocks dangerous bash commands
-  bash_hook = lambda do |input, tool_use_id, context|
-    tool_name = input[:tool_name]
-    tool_input = input[:tool_input]
-
-    return {} unless tool_name == 'Bash'
+  bash_hook = lambda do |input, _tool_use_id, _context|
+    # Hook inputs are typed objects (e.g., PreToolUseHookInput) with Ruby-style accessors
+    return {} unless input.respond_to?(:tool_name) && input.tool_name == 'Bash'
 
-    command = tool_input[:command] || ''
+    tool_input = input.tool_input || {}
+    command = tool_input[:command] || tool_input['command'] || ''
     block_patterns = ['rm -rf', 'foo.sh']
 
     block_patterns.each do |pattern|
@@ -677,11 +714,164 @@ Async do
   end
 
   client.disconnect
-end
+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.
 
+## Rails Integration
+
+The SDK integrates well with Rails applications. Here are common patterns:
+
+### ActionCable Streaming
+
+Stream Claude responses to the frontend in real-time:
+
+```ruby
+# app/jobs/chat_agent_job.rb
+class ChatAgentJob < ApplicationJob
+  queue_as :claude_agents
+
+  def perform(chat_id, message_content)
+    Async do
+      options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+        system_prompt: { type: 'preset', preset: 'claude_code' },
+        permission_mode: 'bypassPermissions'
+      )
+
+      client = ClaudeAgentSDK::Client.new(options: options)
+
+      begin
+        client.connect
+        client.query(message_content)
+
+        client.receive_response do |message|
+          case message
+          when ClaudeAgentSDK::AssistantMessage
+            text = extract_text(message)
+            ChatChannel.broadcast_to(chat_id, { type: 'chunk', content: text })
+
+          when ClaudeAgentSDK::ResultMessage
+            ChatChannel.broadcast_to(chat_id, {
+              type: 'complete',
+              content: message.result,
+              cost: message.total_cost_usd
+            })
+          end
+        end
+      ensure
+        client.disconnect
+      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
+```
+
+### Session Resumption
+
+Persist Claude sessions for multi-turn conversations:
+
+```ruby
+# app/models/chat_session.rb
+class ChatSession < ApplicationRecord
+  # Columns: id, claude_session_id, user_id, created_at, updated_at
+
+  def send_message(content)
+    options = build_options
+    client = ClaudeAgentSDK::Client.new(options: options)
+
+    Async do
+      client.connect
+      client.query(content, session_id: claude_session_id ? nil : generate_session_id)
+
+      client.receive_response do |message|
+        if message.is_a?(ClaudeAgentSDK::ResultMessage)
+          # Save session ID for next message
+          update!(claude_session_id: message.session_id)
+        end
+      end
+    ensure
+      client.disconnect
+    end.wait
+  end
+
+  private
+
+  def build_options
+    opts = {
+      permission_mode: 'bypassPermissions',
+      setting_sources: []
+    }
+    opts[:resume] = claude_session_id if claude_session_id.present?
+    ClaudeAgentSDK::ClaudeAgentOptions.new(**opts)
+  end
+
+  def generate_session_id
+    "chat_#{id}_#{Time.current.to_i}"
+  end
+end
+```
+
+### Background Jobs with Error Handling
+
+```ruby
+class ClaudeAgentJob < ApplicationJob
+  queue_as :claude_agents
+  retry_on ClaudeAgentSDK::ProcessError, wait: :polynomially_longer, attempts: 3
+
+  def perform(task_id)
+    task = Task.find(task_id)
+
+    Async do
+      execute_agent(task)
+    end.wait
+
+  rescue ClaudeAgentSDK::CLINotFoundError => e
+    task.update!(status: 'failed', error: 'Claude CLI not installed')
+    raise
+  end
+
+  private
+
+  def execute_agent(task)
+    # ... agent execution
+  end
+end
+```
+
+### HTTP MCP Servers
+
+Connect to remote tool services:
+
+```ruby
+mcp_servers = {
+  'api_tools' => ClaudeAgentSDK::McpHttpServerConfig.new(
+    url: ENV['MCP_SERVER_URL'],
+    headers: { 'Authorization' => "Bearer #{ENV['MCP_TOKEN']}" }
+  ).to_h
+}
+
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  mcp_servers: mcp_servers,
+  permission_mode: 'bypassPermissions'
+)
+```
+
+For complete examples, see:
+- [examples/rails_actioncable_example.rb](examples/rails_actioncable_example.rb)
+- [examples/rails_background_job_example.rb](examples/rails_background_job_example.rb)
+- [examples/session_resumption_example.rb](examples/session_resumption_example.rb)
+- [examples/http_mcp_server_example.rb](examples/http_mcp_server_example.rb)
+
 ## Types
 
 See [lib/claude_agent_sdk/types.rb](lib/claude_agent_sdk/types.rb) for complete type definitions.
@@ -926,22 +1116,48 @@ See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-co
 
 ## Examples
 
+### Core Examples
+
 | Example | Description |
 |---------|-------------|
 | [examples/quick_start.rb](examples/quick_start.rb) | Basic `query()` usage with options |
 | [examples/client_example.rb](examples/client_example.rb) | Interactive Client usage |
 | [examples/streaming_input_example.rb](examples/streaming_input_example.rb) | Streaming input for multi-turn conversations |
+| [examples/session_resumption_example.rb](examples/session_resumption_example.rb) | Multi-turn conversations with session persistence |
+| [examples/structured_output_example.rb](examples/structured_output_example.rb) | JSON schema structured output |
+| [examples/error_handling_example.rb](examples/error_handling_example.rb) | Error handling with `AssistantMessage.error` |
+
+### MCP Server Examples
+
+| Example | Description |
+|---------|-------------|
 | [examples/mcp_calculator.rb](examples/mcp_calculator.rb) | Custom tools with SDK MCP servers |
 | [examples/mcp_resources_prompts_example.rb](examples/mcp_resources_prompts_example.rb) | MCP resources and prompts |
+| [examples/http_mcp_server_example.rb](examples/http_mcp_server_example.rb) | HTTP/SSE MCP server configuration |
+
+### Hooks & Permissions
+
+| Example | Description |
+|---------|-------------|
 | [examples/hooks_example.rb](examples/hooks_example.rb) | Using hooks to control tool execution |
+| [examples/advanced_hooks_example.rb](examples/advanced_hooks_example.rb) | Typed hook inputs/outputs |
 | [examples/permission_callback_example.rb](examples/permission_callback_example.rb) | Dynamic tool permission control |
-| [examples/structured_output_example.rb](examples/structured_output_example.rb) | JSON schema structured output |
+
+### Advanced Features
+
+| Example | Description |
+|---------|-------------|
 | [examples/budget_control_example.rb](examples/budget_control_example.rb) | Budget control with `max_budget_usd` |
 | [examples/fallback_model_example.rb](examples/fallback_model_example.rb) | Fallback model configuration |
-| [examples/advanced_hooks_example.rb](examples/advanced_hooks_example.rb) | Typed hook inputs/outputs |
-| [examples/error_handling_example.rb](examples/error_handling_example.rb) | Error handling with `AssistantMessage.error` |
 | [examples/extended_thinking_example.rb](examples/extended_thinking_example.rb) | Extended thinking (API parity) |
 
+### Rails Integration
+
+| Example | Description |
+|---------|-------------|
+| [examples/rails_actioncable_example.rb](examples/rails_actioncable_example.rb) | ActionCable streaming to frontend |
+| [examples/rails_background_job_example.rb](examples/rails_background_job_example.rb) | Background jobs with session resumption |
+
 ## Development
 
 After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rspec` to run the tests.

data/lib/claude_agent_sdk/query.rb

@@ -30,8 +30,10 @@ module ClaudeAgentSDK
       @pending_control_responses = {}
       @pending_control_results = {}
       @hook_callbacks = {}
+      @hook_callback_timeouts = {}
       @next_callback_id = 0
       @request_counter = 0
+      @inflight_control_request_tasks = {}
 
       # Message stream
       @message_queue = Async::Queue.new
@@ -59,6 +61,7 @@ module ClaudeAgentSDK
               callback_id = "hook_#{@next_callback_id}"
               @next_callback_id += 1
               @hook_callbacks[callback_id] = callback
+              @hook_callback_timeouts[callback_id] = matcher[:timeout] if matcher[:timeout]
               callback_ids << callback_id
             end
             hooks_config[event] << {
@@ -103,9 +106,19 @@ module ClaudeAgentSDK
         when 'control_response'
           handle_control_response(message)
         when 'control_request'
-          Async { handle_control_request(message) }
+          request_id = message[:request_id]
+          task = Async do
+            begin
+              handle_control_request(message)
+            ensure
+              @inflight_control_request_tasks.delete(request_id) if request_id
+            end
+          end
+          @inflight_control_request_tasks[request_id] = task if request_id
         when 'control_cancel_request'
-          # TODO: Implement cancellation support
+          request_id = message[:request_id] || message[:requestId]
+          task = request_id ? @inflight_control_request_tasks[request_id] : nil
+          task&.stop
           next
         else
           # Regular SDK messages go to the queue
@@ -163,6 +176,17 @@ module ClaudeAgentSDK
         }
       }
       @transport.write(JSON.generate(success_response) + "\n")
+    rescue Async::Stop
+      # Cancellation requested; respond with an error so the CLI can unblock.
+      cancelled_response = {
+        type: 'control_response',
+        response: {
+          subtype: 'error',
+          request_id: request_id,
+          error: 'Cancelled'
+        }
+      }
+      @transport.write(JSON.generate(cancelled_response) + "\n")
     rescue StandardError => e
       # Send error response
       error_response = {
@@ -228,7 +252,17 @@ module ClaudeAgentSDK
         hook_input,
         request_data[:tool_use_id],
         context
-      )
+      ) unless @hook_callback_timeouts[callback_id]
+
+      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
+          )
+        end
+      end
 
       # Convert Ruby-safe field names to CLI-expected names
       convert_hook_output_for_cli(hook_output)
@@ -236,46 +270,79 @@ module ClaudeAgentSDK
 
     def parse_hook_input(input_data)
       event_name = input_data[:hook_event_name] || input_data['hook_event_name']
+      fetch = ->(key) { input_data[key] || input_data[key.to_s] }
       base_args = {
-        session_id: input_data[:session_id],
-        transcript_path: input_data[:transcript_path],
-        cwd: input_data[:cwd],
-        permission_mode: input_data[:permission_mode]
+        session_id: fetch.call(:session_id),
+        transcript_path: fetch.call(:transcript_path),
+        cwd: fetch.call(:cwd),
+        permission_mode: fetch.call(:permission_mode)
       }
 
       case event_name
       when 'PreToolUse'
         PreToolUseHookInput.new(
-          tool_name: input_data[:tool_name],
-          tool_input: input_data[:tool_input],
+          tool_name: fetch.call(:tool_name),
+          tool_input: fetch.call(:tool_input),
           **base_args
         )
       when 'PostToolUse'
         PostToolUseHookInput.new(
-          tool_name: input_data[:tool_name],
-          tool_input: input_data[:tool_input],
-          tool_response: input_data[:tool_response],
+          tool_name: fetch.call(:tool_name),
+          tool_input: fetch.call(:tool_input),
+          tool_response: fetch.call(:tool_response),
+          **base_args
+        )
+      when 'PostToolUseFailure'
+        PostToolUseFailureHookInput.new(
+          tool_name: fetch.call(:tool_name),
+          tool_input: fetch.call(:tool_input),
+          tool_use_id: fetch.call(:tool_use_id),
+          error: fetch.call(:error),
+          is_interrupt: fetch.call(:is_interrupt),
           **base_args
         )
       when 'UserPromptSubmit'
         UserPromptSubmitHookInput.new(
-          prompt: input_data[:prompt],
+          prompt: fetch.call(:prompt),
           **base_args
         )
       when 'Stop'
         StopHookInput.new(
-          stop_hook_active: input_data[:stop_hook_active],
+          stop_hook_active: fetch.call(:stop_hook_active),
           **base_args
         )
       when 'SubagentStop'
         SubagentStopHookInput.new(
-          stop_hook_active: input_data[:stop_hook_active],
+          stop_hook_active: fetch.call(:stop_hook_active),
+          agent_id: fetch.call(:agent_id),
+          agent_transcript_path: fetch.call(:agent_transcript_path),
+          agent_type: fetch.call(:agent_type),
+          **base_args
+        )
+      when 'Notification'
+        NotificationHookInput.new(
+          message: fetch.call(:message),
+          title: fetch.call(:title),
+          notification_type: fetch.call(:notification_type),
+          **base_args
+        )
+      when 'SubagentStart'
+        SubagentStartHookInput.new(
+          agent_id: fetch.call(:agent_id),
+          agent_type: fetch.call(:agent_type),
+          **base_args
+        )
+      when 'PermissionRequest'
+        PermissionRequestHookInput.new(
+          tool_name: fetch.call(:tool_name),
+          tool_input: fetch.call(:tool_input),
+          permission_suggestions: fetch.call(:permission_suggestions),
           **base_args
         )
       when 'PreCompact'
         PreCompactHookInput.new(
-          trigger: input_data[:trigger],
-          custom_instructions: input_data[:custom_instructions],
+          trigger: fetch.call(:trigger),
+          custom_instructions: fetch.call(:custom_instructions),
           **base_args
         )
       else
@@ -455,19 +522,14 @@ module ClaudeAgentSDK
 
       # Call the tool
       result = server.call_tool(tool_name, arguments)
+      content = ClaudeAgentSDK.flexible_fetch(result, 'content', 'content') || []
+      response_data = { content: content }
 
-      # Format response
-      content = []
-      if result[:content]
-        result[:content].each do |item|
-          if item[:type] == 'text'
-            content << { type: 'text', text: item[:text] }
-          end
-        end
-      end
+      is_error = ClaudeAgentSDK.flexible_fetch(result, 'isError', 'is_error')
+      response_data[:isError] = !!is_error unless is_error.nil?
 
-      response_data = { content: content }
-      response_data[:is_error] = true if result[:is_error]
+      structured_content = ClaudeAgentSDK.flexible_fetch(result, 'structuredContent', 'structured_content')
+      response_data[:structuredContent] = structured_content unless structured_content.nil?
 
       {
         jsonrpc: '2.0',
@@ -530,6 +592,12 @@ module ClaudeAgentSDK
 
     public
 
+    # Get current MCP server connection status (only works with streaming mode)
+    # @return [Hash] MCP status information, including mcpServers list
+    def get_mcp_status
+      send_control_request({ subtype: 'mcp_status' })
+    end
+
     # Send interrupt control request
     def interrupt
       send_control_request({ subtype: 'interrupt' })

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -172,15 +172,19 @@ module ClaudeAgentSDK
               # Filter out server_context and pass remaining args to handler
               result = @tool_def.handler.call(args)
 
-              # Convert result to MCP::Tool::Response format
-              content = result[:content].map do |item|
-                {
-                  type: item[:type],
-                  text: item[:text]
-                }
+              content = ClaudeAgentSDK.flexible_fetch(result, 'content', 'content')
+              unless result.is_a?(Hash) && content
+                raise "Tool '#{@tool_def.name}' must return a hash with :content key"
               end
 
-              MCP::Tool::Response.new(content)
+              is_error = ClaudeAgentSDK.flexible_fetch(result, 'isError', 'is_error')
+              structured_content = ClaudeAgentSDK.flexible_fetch(result, 'structuredContent', 'structured_content')
+
+              MCP::Tool::Response.new(
+                content,
+                error: !!is_error,
+                structured_content: structured_content
+              )
             end
 
             private

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -64,10 +64,17 @@ module ClaudeAgentSDK
       if @options.system_prompt
         if @options.system_prompt.is_a?(String)
           cmd.concat(['--system-prompt', @options.system_prompt])
-        elsif @options.system_prompt.is_a?(Hash) &&
-              @options.system_prompt[:type] == 'preset' &&
-              @options.system_prompt[:append]
-          cmd.concat(['--append-system-prompt', @options.system_prompt[:append]])
+        elsif @options.system_prompt.is_a?(SystemPromptPreset)
+          cmd.concat(['--system-prompt-preset', @options.system_prompt.preset]) if @options.system_prompt.preset
+          cmd.concat(['--append-system-prompt', @options.system_prompt.append]) if @options.system_prompt.append
+        elsif @options.system_prompt.is_a?(Hash)
+          prompt_type = @options.system_prompt[:type] || @options.system_prompt['type']
+          if prompt_type == 'preset'
+            preset = @options.system_prompt[:preset] || @options.system_prompt['preset']
+            append = @options.system_prompt[:append] || @options.system_prompt['append']
+            cmd.concat(['--system-prompt-preset', preset]) if preset
+            cmd.concat(['--append-system-prompt', append]) if append
+          end
         end
       end
 
@@ -246,10 +253,10 @@ module ClaudeAgentSDK
       cmd = build_command
 
       # Build environment
-      process_env = ENV.to_h.merge(@options.env).merge(
-        'CLAUDE_CODE_ENTRYPOINT' => 'sdk-rb',
-        'CLAUDE_AGENT_SDK_VERSION' => VERSION
-      )
+      # Convert symbol keys to strings for spawn compatibility
+      custom_env = @options.env.transform_keys { |k| k.to_s }
+      process_env = ENV.to_h.merge('CLAUDE_AGENT_SDK_VERSION' => VERSION).merge(custom_env)
+      process_env['CLAUDE_CODE_ENTRYPOINT'] ||= 'sdk-rb'
       process_env['PWD'] = @cwd.to_s if @cwd
 
       # Determine stderr handling
@@ -446,7 +453,8 @@ module ClaudeAgentSDK
 
     def check_claude_version
       begin
-        output = `#{@cli_path} -v 2>&1`.strip
+        stdout, stderr, = Open3.capture3(@cli_path.to_s, '-v')
+        output = (stdout.to_s + stderr.to_s).strip
         if match = output.match(/([0-9]+\.[0-9]+\.[0-9]+)/)
           version = match[1]
           version_parts = version.split('.').map(&:to_i)

data/lib/claude_agent_sdk/types.rb

@@ -14,7 +14,18 @@ module ClaudeAgentSDK
   PERMISSION_BEHAVIORS = %w[allow deny ask].freeze
 
   # Type constants for hook events
-  HOOK_EVENTS = %w[PreToolUse PostToolUse UserPromptSubmit Stop SubagentStop PreCompact].freeze
+  HOOK_EVENTS = %w[
+    PreToolUse
+    PostToolUse
+    PostToolUseFailure
+    UserPromptSubmit
+    Stop
+    SubagentStop
+    PreCompact
+    Notification
+    SubagentStart
+    PermissionRequest
+  ].freeze
 
   # Type constants for assistant message errors
   ASSISTANT_MESSAGE_ERRORS = %w[authentication_failed billing_error rate_limit invalid_request server_error unknown].freeze
@@ -305,12 +316,71 @@ module ClaudeAgentSDK
 
   # SubagentStop hook input
   class SubagentStopHookInput < BaseHookInput
-    attr_accessor :hook_event_name, :stop_hook_active
+    attr_accessor :hook_event_name, :stop_hook_active, :agent_id, :agent_transcript_path, :agent_type
 
-    def initialize(hook_event_name: 'SubagentStop', stop_hook_active: false, **base_args)
+    def initialize(hook_event_name: 'SubagentStop', stop_hook_active: false, agent_id: nil,
+                   agent_transcript_path: nil, agent_type: nil, **base_args)
       super(**base_args)
       @hook_event_name = hook_event_name
       @stop_hook_active = stop_hook_active
+      @agent_id = agent_id
+      @agent_transcript_path = agent_transcript_path
+      @agent_type = agent_type
+    end
+  end
+
+  # PostToolUseFailure hook input
+  class PostToolUseFailureHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :tool_name, :tool_input, :tool_use_id, :error, :is_interrupt
+
+    def initialize(hook_event_name: 'PostToolUseFailure', tool_name: nil, tool_input: nil, tool_use_id: nil,
+                   error: nil, is_interrupt: nil, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @tool_name = tool_name
+      @tool_input = tool_input
+      @tool_use_id = tool_use_id
+      @error = error
+      @is_interrupt = is_interrupt
+    end
+  end
+
+  # Notification hook input
+  class NotificationHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :message, :title, :notification_type
+
+    def initialize(hook_event_name: 'Notification', message: nil, title: nil, notification_type: nil, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @message = message
+      @title = title
+      @notification_type = notification_type
+    end
+  end
+
+  # SubagentStart hook input
+  class SubagentStartHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :agent_id, :agent_type
+
+    def initialize(hook_event_name: 'SubagentStart', agent_id: nil, agent_type: nil, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @agent_id = agent_id
+      @agent_type = agent_type
+    end
+  end
+
+  # PermissionRequest hook input
+  class PermissionRequestHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :tool_name, :tool_input, :permission_suggestions
+
+    def initialize(hook_event_name: 'PermissionRequest', tool_name: nil, tool_input: nil, permission_suggestions: nil,
+                   **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @tool_name = tool_name
+      @tool_input = tool_input
+      @permission_suggestions = permission_suggestions
     end
   end
 
@@ -348,10 +418,28 @@ module ClaudeAgentSDK
 
   # PostToolUse hook specific output
   class PostToolUseHookSpecificOutput
+    attr_accessor :hook_event_name, :additional_context, :updated_mcp_tool_output
+
+    def initialize(additional_context: nil, updated_mcp_tool_output: nil)
+      @hook_event_name = 'PostToolUse'
+      @additional_context = additional_context
+      @updated_mcp_tool_output = updated_mcp_tool_output
+    end
+
+    def to_h
+      result = { hookEventName: @hook_event_name }
+      result[:additionalContext] = @additional_context if @additional_context
+      result[:updatedMCPToolOutput] = @updated_mcp_tool_output if @updated_mcp_tool_output
+      result
+    end
+  end
+
+  # PostToolUseFailure hook specific output
+  class PostToolUseFailureHookSpecificOutput
     attr_accessor :hook_event_name, :additional_context
 
     def initialize(additional_context: nil)
-      @hook_event_name = 'PostToolUse'
+      @hook_event_name = 'PostToolUseFailure'
       @additional_context = additional_context
     end
 
@@ -378,6 +466,54 @@ module ClaudeAgentSDK
     end
   end
 
+  # Notification hook specific output
+  class NotificationHookSpecificOutput
+    attr_accessor :hook_event_name, :additional_context
+
+    def initialize(additional_context: nil)
+      @hook_event_name = 'Notification'
+      @additional_context = additional_context
+    end
+
+    def to_h
+      result = { hookEventName: @hook_event_name }
+      result[:additionalContext] = @additional_context if @additional_context
+      result
+    end
+  end
+
+  # SubagentStart hook specific output
+  class SubagentStartHookSpecificOutput
+    attr_accessor :hook_event_name, :additional_context
+
+    def initialize(additional_context: nil)
+      @hook_event_name = 'SubagentStart'
+      @additional_context = additional_context
+    end
+
+    def to_h
+      result = { hookEventName: @hook_event_name }
+      result[:additionalContext] = @additional_context if @additional_context
+      result
+    end
+  end
+
+  # PermissionRequest hook specific output
+  class PermissionRequestHookSpecificOutput
+    attr_accessor :hook_event_name, :decision
+
+    def initialize(decision: nil)
+      @hook_event_name = 'PermissionRequest'
+      @decision = decision
+    end
+
+    def to_h
+      result = { hookEventName: @hook_event_name }
+      result[:decision] = @decision if @decision
+      result
+    end
+  end
+
   # SessionStart hook specific output
   class SessionStartHookSpecificOutput
     attr_accessor :hook_event_name, :additional_context

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -14,6 +14,16 @@ require 'securerandom'
 
 # Claude Agent SDK for Ruby
 module ClaudeAgentSDK
+  # Look up a value in a hash that may use symbol or string keys in camelCase or snake_case.
+  # Returns the first non-nil value found, preserving false as a meaningful value.
+  def self.flexible_fetch(hash, camel_key, snake_key)
+    val = hash[camel_key.to_sym]
+    val = hash[camel_key.to_s] if val.nil?
+    val = hash[snake_key.to_sym] if val.nil?
+    val = hash[snake_key.to_s] if val.nil?
+    val
+  end
+
   # Query Claude Code for one-shot or unidirectional streaming interactions
   #
   # This function is ideal for simple, stateless queries where you don't need
@@ -51,7 +61,7 @@ module ClaudeAgentSDK
     return enum_for(:query, prompt: prompt, options: options) unless block
 
     options ||= ClaudeAgentOptions.new
-    ENV['CLAUDE_CODE_ENTRYPOINT'] = 'sdk-rb'
+    options = options.dup_with(env: (options.env || {}).merge('CLAUDE_CODE_ENTRYPOINT' => 'sdk-rb'))
 
     Async do
       transport = SubprocessCLITransport.new(prompt, options)
@@ -126,36 +136,37 @@ module ClaudeAgentSDK
       @transport = nil
       @query_handler = nil
       @connected = false
-      ENV['CLAUDE_CODE_ENTRYPOINT'] = 'sdk-rb-client'
     end
 
-    # Connect to Claude with optional initial prompt
+    # Connect to Claude with optional initial prompt.
+    #
+    # Client always uses streaming mode for bidirectional communication. If you
+    # pass a String, it will be sent as an initial user message after the
+    # connection is established. If you pass an Enumerator, it should yield
+    # JSONL messages (e.g., from ClaudeAgentSDK::Streaming.user_message).
+    #
     # @param prompt [String, Enumerator, nil] Initial prompt or message stream
     def connect(prompt = nil)
       return if @connected
 
+      raise ArgumentError, "prompt must be a String, an Enumerator, or nil (got #{prompt.class})" unless prompt.nil? || prompt.is_a?(String) || prompt.respond_to?(:each)
+
       # Validate and configure permission settings
       configured_options = @options
       if @options.can_use_tool
-        # can_use_tool requires streaming mode
-        if prompt.is_a?(String)
-          raise ArgumentError, 'can_use_tool callback requires streaming mode'
-        end
-
         # can_use_tool and permission_prompt_tool_name are mutually exclusive
-        if @options.permission_prompt_tool_name
-          raise ArgumentError, 'can_use_tool callback cannot be used with permission_prompt_tool_name'
-        end
+        raise ArgumentError, 'can_use_tool callback cannot be used with permission_prompt_tool_name' if @options.permission_prompt_tool_name
 
         # Set permission_prompt_tool_name to stdio for control protocol
         configured_options = @options.dup_with(permission_prompt_tool_name: 'stdio')
       end
 
-      # Auto-connect with empty enumerator if no prompt is provided
-      # This matches the Python SDK pattern where ClaudeSDKClient always uses streaming mode
-      # An empty enumerator keeps stdin open for bidirectional communication
-      actual_prompt = prompt || [].to_enum
-      @transport = SubprocessCLITransport.new(actual_prompt, configured_options)
+      configured_options = configured_options.dup_with(
+        env: (configured_options.env || {}).merge('CLAUDE_CODE_ENTRYPOINT' => 'sdk-rb-client')
+      )
+
+      # Client always uses streaming mode; keep stdin open for bidirectional communication.
+      @transport = SubprocessCLITransport.new([].to_enum, configured_options)
       @transport.connect
 
       # Extract SDK MCP servers
@@ -183,6 +194,20 @@ module ClaudeAgentSDK
       @query_handler.initialize_protocol
 
       @connected = true
+
+      # Optionally send initial prompt/messages after connection is ready.
+      case prompt
+      when nil
+        nil
+      when String
+        query(prompt)
+      else
+        prompt.each do |message_json|
+          message_json = message_json.to_s
+          message_json += "\n" unless message_json.end_with?("\n")
+          @transport.write(message_json)
+        end
+      end
     end
 
     # Send a query to Claude
@@ -259,6 +284,20 @@ module ClaudeAgentSDK
       @query_handler&.instance_variable_get(:@initialization_result)
     end
 
+    # Get current MCP server connection status (only works with streaming mode)
+    # @return [Hash] MCP status information, including mcpServers list
+    def get_mcp_status
+      raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+      @query_handler.get_mcp_status
+    end
+
+    # Get server initialization info including available commands and output styles
+    # @return [Hash] Server info
+    def get_server_info
+      raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+      server_info
+    end
+
     # Disconnect from Claude
     def disconnect
       return unless @connected
@@ -278,10 +317,12 @@ module ClaudeAgentSDK
       hooks.each do |event, matchers|
         internal_hooks[event.to_s] = []
         matchers.each do |matcher|
-          internal_hooks[event.to_s] << {
+          config = {
             matcher: matcher.matcher,
             hooks: matcher.hooks
           }
+          config[:timeout] = matcher.timeout if matcher.timeout
+          internal_hooks[event.to_s] << config
         end
       end
       internal_hooks

metadata

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