claude-agent-sdk 0.7.3 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d17d03fa867e2779de155d6fba8a86fbc9edbc5662157ca3e21606016c81fb17
-  data.tar.gz: 949787994cd58eb5be72b8834a519a704697c61ecbfff9ca1d6f4e1fe921b18f
+  metadata.gz: b625dde6e1777c93be6e4bcfb6c9565087d798d414a03078f8de4184c39dfa7f
+  data.tar.gz: 30117f8eac89f94aabae5c37fdc12c012ed779a0f1c58062d70e9b727ee5ce3c
 SHA512:
-  metadata.gz: a99fdb7b2dcab7e0286763abfb1f6d0277423a7ef2198a040ef8c76a8959907009ebc21f6523c35ecff1409a66fd8c636648d1f594aaa481119ed3598eb1b06e
-  data.tar.gz: 8e3e7e26487dcfe993534d3d1b7f695ba5009ad18e9d173c9e1e0f1353ec54565905f3e74e81a39eb5789aa2df008536a2a5a191095e7d8604f36abd27bb6583
+  metadata.gz: 2a36e3ff75415bb4c2f42b27a8280b4828199af2972d20aa5fa4366a24daefd325e5a11c3e39ee9396144561c98e2ea1ddcc94157b80fc7aeef72f58a526e36b
+  data.tar.gz: f0fde6a0779679869bd4d6607f7220ea016c021896a97a421be650e169ef53719d5810cf614613c7cb52b24c19ebbf2f3908f3cc49f07bc5b13aa58f377e1a8b

data/CHANGELOG.md

@@ -5,6 +5,76 @@ 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.1] - 2026-03-08
+
+Python SDK parity fixes for one-shot `query()` control protocol and CLI transport.
+
+### Fixed
+
+#### One-Shot Query Control Protocol
+- **Hooks and `can_use_tool` in `query()`:** One-shot `query()` now passes `hooks`, `can_use_tool`, and SDK MCP servers through to the `Query` handler, matching the Python SDK (previously these were Client-only)
+- **`can_use_tool` validation:** String prompts with `can_use_tool` now raise `ArgumentError` (streaming mode required); conflicting `permission_prompt_tool_name` also raises early
+- **`session_id` parity:** One-shot queries now send `session_id: ''` (was `'default'`), matching Python SDK behavior
+- **Premature stdin close:** Added `wait_for_result_and_end_input` that holds stdin open until the first result when hooks or SDK MCP servers need control message exchange
+- **`stream_input` stdin leak:** Moved `end_input` to `ensure` block so stdin is always closed even when the stream enumerator raises
+- **`Async::Condition` race:** Added `@first_result_received` flag guard to prevent lost signals when result arrives before `wait` is called
+
+#### CLI Transport Parity
+- **File checkpointing:** Moved from deprecated `--enable-file-checkpointing` CLI flag to `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` environment variable
+- **Partial messages:** Now also sets `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1` environment variable when `include_partial_messages` is enabled
+- **Tools preset:** `ToolsPreset` objects and preset hashes now map to `--tools default` (was `--tools <json>`)
+- **Plugins:** Changed from `--plugins <json>` to `--plugin-dir <path>` per-plugin, matching current CLI interface
+- **Plugin type:** `SdkPluginConfig` now defaults to `type: 'local'` (was `'plugin'`), normalizes legacy `'plugin'` type
+- **Rewind control request:** Changed key from `userMessageUuid` to `user_message_id` for Python SDK parity
+- **Settings file with sandbox:** When sandbox is enabled and settings is a file path, now reads and parses the file to merge sandbox settings (raises on missing/invalid files instead of silently dropping settings)
+
+#### Hook Input Parsing
+- **Falsy value preservation:** `parse_hook_input` now uses `key?`-based lookup instead of `||`, correctly preserving `false` and `nil` values (e.g., `stop_hook_active: false`)
+- **Empty hooks normalization:** `query()` now skips empty matcher lists and normalizes hooks to `nil` when no matchers survive, preventing unnecessary 60s close-wait timeout
+
+### Changed
+- **`build_command` refactored:** Extracted `build_settings_args`, `build_tools_args`, `build_output_format_args`, `build_mcp_servers_args`, `build_plugins_args` private helpers to reduce method complexity
+
+## [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

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.3'
+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
 ```
@@ -774,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:
@@ -966,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
@@ -987,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)
@@ -1111,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 |
@@ -1126,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

@@ -22,6 +22,8 @@ module ClaudeAgentSDK
 
     CONTROL_REQUEST_TIMEOUT_ENV_VAR = 'CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS'
     DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS = 1200.0
+    STREAM_CLOSE_TIMEOUT_ENV_VAR = 'CLAUDE_CODE_STREAM_CLOSE_TIMEOUT'
+    DEFAULT_STREAM_CLOSE_TIMEOUT_SECONDS = 60.0
 
     def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil, agents: nil)
       @transport = transport
@@ -42,6 +44,8 @@ module ClaudeAgentSDK
 
       # Message stream
       @message_queue = Async::Queue.new
+      @first_result_received = false
+      @first_result_condition = Async::Condition.new
       @task = nil
       @initialized = false
       @closed = false
@@ -124,6 +128,16 @@ module ClaudeAgentSDK
       DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS
     end
 
+    def stream_close_timeout_seconds
+      raw_value = ENV.fetch(STREAM_CLOSE_TIMEOUT_ENV_VAR, nil)
+      return DEFAULT_STREAM_CLOSE_TIMEOUT_SECONDS if raw_value.nil? || raw_value.strip.empty?
+
+      value = Float(raw_value) / 1000.0
+      value.positive? ? value : DEFAULT_STREAM_CLOSE_TIMEOUT_SECONDS
+    rescue ArgumentError
+      DEFAULT_STREAM_CLOSE_TIMEOUT_SECONDS
+    end
+
     def read_messages
       @transport.read_messages do |message|
         break if @closed
@@ -150,6 +164,10 @@ module ClaudeAgentSDK
           task&.stop
           next
         else
+          if message[:type] == 'result' && !@first_result_received
+            @first_result_received = true
+            @first_result_condition.signal
+          end
           # Regular SDK messages go to the queue
           @message_queue.enqueue(message)
         end
@@ -164,6 +182,10 @@ module ClaudeAgentSDK
       # Put error in queue so iterators can handle it
       @message_queue.enqueue({ type: 'error', error: e })
     ensure
+      unless @first_result_received
+        @first_result_received = true
+        @first_result_condition.signal
+      end
       # Always signal end of stream
       @message_queue.enqueue({ type: 'end' })
     end
@@ -308,7 +330,13 @@ 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] }
+      fetch = lambda do |key|
+        if input_data.key?(key)
+          input_data[key]
+        elsif input_data.key?(key.to_s)
+          input_data[key.to_s]
+        end
+      end
       base_args = {
         session_id: fetch.call(:session_id),
         transcript_path: fetch.call(:transcript_path),
@@ -316,13 +344,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 +364,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 +373,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 +411,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 +696,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
@@ -669,20 +732,42 @@ module ClaudeAgentSDK
     def rewind_files(user_message_uuid)
       send_control_request({
                              subtype: 'rewind_files',
-                             userMessageUuid: user_message_uuid
+                             user_message_id: user_message_uuid
                            })
     end
 
+    # Wait for the first result before closing stdin when hooks or SDK MCP
+    # servers may still need to exchange control messages with the CLI.
+    def wait_for_result_and_end_input
+      if !@first_result_received &&
+         ((@sdk_mcp_servers && !@sdk_mcp_servers.empty?) || (@hooks && !@hooks.empty?))
+        Async::Task.current.with_timeout(stream_close_timeout_seconds) do
+          @first_result_condition.wait unless @first_result_received
+        end
+      end
+    rescue Async::TimeoutError
+      nil
+    ensure
+      @transport.end_input
+    end
+
     # Stream input messages to transport
     def stream_input(stream)
       stream.each do |message|
         break if @closed
-        @transport.write(JSON.generate(message) + "\n")
+        serialized = if message.is_a?(Hash)
+                       JSON.generate(message) + "\n"
+                     else
+                       message.to_s
+                     end
+        serialized += "\n" unless serialized.end_with?("\n")
+        @transport.write(serialized)
       end
-      @transport.end_input
     rescue StandardError => e
       # Log error but don't raise
       warn "Error streaming input: #{e.message}"
+    ensure
+      wait_for_result_and_end_input
     end
 
     # Receive SDK messages (not control messages)