claude_agent 0.7.7 → 0.7.9

data/SPEC.md

@@ -3,11 +3,11 @@
 This document provides a comprehensive specification of the Claude Agent SDK, comparing feature parity across the official TypeScript and Python SDKs with this Ruby implementation.
 
 **Reference Versions:**
-- TypeScript SDK: v0.2.49 (npm package)
-- Python SDK: v0.1.39 from GitHub (commit 146e3d6)
+- TypeScript SDK: v0.2.56 (npm package)
+- Python SDK: v0.1.43 from GitHub (commit 9d758dd)
 - Ruby SDK: This repository
 
-**Last Updated:** 2026-02-20
+**Last Updated:** 2026-02-25
 
 ---
 
@@ -111,6 +111,7 @@ Messages exchanged between SDK and CLI.
 | `TaskNotificationMessage` |     ✅      |   ❌    |  ✅   | Background task completion         |
 | `ToolUseSummaryMessage`   |     ✅      |   ❌    |  ✅   | Summary of tool use (collapsed)    |
 | `TaskStartedMessage`      |     ✅      |   ❌    |  ✅   | Subagent task registered (v0.2.45) |
+| `TaskProgressMessage`     |     ✅      |   ❌    |  ✅   | Background task progress (v0.2.51) |
 | `RateLimitEvent`          |     ✅      |   ❌    |  ✅   | Rate limit status changes          |
 | `PromptSuggestionMessage` |     ✅      |   ❌    |  ✅   | Suggested next prompt (v0.2.47)    |
 | `FilesPersistedEvent`     |     ✅      |   ❌    |  ✅   | File persistence confirmation      |
@@ -232,9 +233,12 @@ Bidirectional control protocol for SDK-CLI communication.
 | `mcp_reconnect`           |     ✅      |   ❌    |  ✅   | Reconnect to MCP server           |
 | `mcp_toggle`              |     ✅      |   ❌    |  ✅   | Enable/disable MCP server         |
 | `stop_task`               |     ✅      |   ❌    |  ✅   | Stop a running background task    |
+| `mcp_authenticate`        |     ✅      |   ❌    |  ✅   | Authenticate MCP server (v0.2.52) |
+| `mcp_clear_auth`          |     ✅      |   ❌    |  ✅   | Clear MCP server auth (v0.2.52)   |
 | `supported_commands`      |     ✅      |   ❌    |  ✅   | Get available slash commands      |
 | `supported_models`        |     ✅      |   ❌    |  ✅   | Get available models              |
 | `account_info`            |     ✅      |   ❌    |  ✅   | Get account information           |
+| `apply_flag_settings`     |     ✅      |   ❌    |  ✅   | Merge settings into flag layer    |
 
 ### Return Types
 
@@ -274,6 +278,8 @@ Event hooks for intercepting and modifying SDK behavior.
 | `TeammateIdle`       |     ✅      |   ❌    |  ✅   | Teammate idle (v0.2.33)           |
 | `TaskCompleted`      |     ✅      |   ❌    |  ✅   | Task completed (v0.2.33)          |
 | `ConfigChange`       |     ✅      |   ❌    |  ✅   | Config file changed (v0.2.49)     |
+| `WorktreeCreate`     |     ✅      |   ❌    |  ✅   | Worktree creation (v0.2.50)       |
+| `WorktreeRemove`     |     ✅      |   ❌    |  ✅   | Worktree removal (v0.2.50)        |
 
 ### Hook Input Types
 
@@ -295,6 +301,8 @@ Event hooks for intercepting and modifying SDK behavior.
 | `TeammateIdleHookInput`       |     ✅      |   ❌    |  ✅   |
 | `TaskCompletedHookInput`      |     ✅      |   ❌    |  ✅   |
 | `ConfigChangeHookInput`       |     ✅      |   ❌    |  ✅   |
+| `WorktreeCreateHookInput`     |     ✅      |   ❌    |  ✅   |
+| `WorktreeRemoveHookInput`     |     ✅      |   ❌    |  ✅   |
 
 ### Hook Output Types
 
@@ -514,6 +522,25 @@ Session management and resumption.
 | Persist session      |     ✅      |   ❌    |  ✅   | `persistSession` option |
 | Continue most recent |     ✅      |   ✅    |  ✅   | `continue` option       |
 
+### Session Discovery
+
+| Feature          | TypeScript | Python | Ruby | Notes                                      |
+|------------------|:----------:|:------:|:----:|--------------------------------------------|
+| `listSessions()` |     ✅      |   ❌    |  ✅   | List past sessions with metadata (v0.2.53) |
+
+#### SDKSessionInfo Fields
+
+| Field          | TypeScript | Python | Ruby | Notes                               |
+|----------------|:----------:|:------:|:----:|-------------------------------------|
+| `sessionId`    |     ✅      |   ❌    |  ✅   | Session UUID                        |
+| `summary`      |     ✅      |   ❌    |  ✅   | Display title/summary               |
+| `lastModified` |     ✅      |   ❌    |  ✅   | Last modified time (ms since epoch) |
+| `fileSize`     |     ✅      |   ❌    |  ✅   | Session file size in bytes          |
+| `customTitle`  |     ✅      |   ❌    |  ✅   | User-set title via /rename          |
+| `firstPrompt`  |     ✅      |   ❌    |  ✅   | First meaningful user prompt        |
+| `gitBranch`    |     ✅      |   ❌    |  ✅   | Git branch at end of session        |
+| `cwd`          |     ✅      |   ❌    |  ✅   | Working directory for session       |
+
 ### V2 Session API (Unstable)
 
 | Feature                     | TypeScript | Python | Ruby | Notes                     |
@@ -593,11 +620,11 @@ Error types and hierarchy.
 |----------------------|:----------:|:------:|:----:|--------------------------------|
 | Base Error           |     ✅      |   ✅    |  ✅   | `Error` / `ClaudeAgent::Error` |
 | `AbortError`         |     ✅      |   ❌    |  ✅   | Operation cancelled            |
-| `CLINotFoundError`   |     ❌      |   ❌    |  ✅   | CLI not found                  |
+| `CLINotFoundError`   |     ❌      |   ✅    |  ✅   | CLI not found                  |
 | `CLIVersionError`    |     ❌      |   ❌    |  ✅   | CLI version too old            |
-| `CLIConnectionError` |     ❌      |   ❌    |  ✅   | Connection failed              |
-| `ProcessError`       |     ❌      |   ❌    |  ✅   | CLI process failed             |
-| `JSONDecodeError`    |     ❌      |   ❌    |  ✅   | JSON parsing failed            |
+| `CLIConnectionError` |     ❌      |   ✅    |  ✅   | Connection failed              |
+| `ProcessError`       |     ❌      |   ✅    |  ✅   | CLI process failed             |
+| `JSONDecodeError`    |     ❌      |   ✅    |  ✅   | JSON parsing failed            |
 | `MessageParseError`  |     ❌      |   ❌    |  ✅   | Message parsing failed         |
 | `TimeoutError`       |     ❌      |   ❌    |  ✅   | Control request timeout        |
 | `ConfigurationError` |     ❌      |   ❌    |  ✅   | Invalid configuration          |
@@ -620,6 +647,12 @@ Error types and hierarchy.
 
 Public API surface for SDK clients.
 
+### Standalone Functions
+
+| Feature          |    TypeScript    | Python | Ruby | Notes                                      |
+|------------------|:----------------:|:------:|:----:|--------------------------------------------|
+| `listSessions()` | ✅ `listSessions` |   ❌    |  ✅   | List past sessions with metadata (v0.2.53) |
+
 ### Query Interface
 
 | Feature                 | TypeScript  |   Python    |          Ruby           | Notes              |
@@ -629,24 +662,24 @@ Public API surface for SDK clients.
 
 ### Query Control Methods
 
-| Method                   | TypeScript | Python | Ruby | Notes                  |
-|--------------------------|:----------:|:------:|:----:|------------------------|
-| `interrupt()`            |     ✅      |   ✅    |  ✅   | Interrupt execution    |
-| `setPermissionMode()`    |     ✅      |   ✅    |  ✅   | Change permission mode |
-| `setModel()`             |     ✅      |   ✅    |  ✅   | Change model           |
-| `setMaxThinkingTokens()` |     ✅      |   ❌    |  ✅   | Set thinking limit     |
-| `supportedCommands()`    |     ✅      |   ❌    |  ✅   | Get slash commands     |
-| `supportedModels()`      |     ✅      |   ❌    |  ✅   | Get available models   |
-| `mcpServerStatus()`      |     ✅      |   ✅    |  ✅   | Get MCP status         |
-| `accountInfo()`          |     ✅      |   ❌    |  ✅   | Get account info       |
-| `rewindFiles()`          |     ✅      |   ✅    |  ✅   | Rewind file changes    |
-| `setMcpServers()`        |     ✅      |   ❌    |  ✅   | Dynamic MCP servers    |
-| `reconnectMcpServer()`   |     ✅      |   ❌    |  ✅   | Reconnect MCP server   |
-| `toggleMcpServer()`      |     ✅      |   ❌    |  ✅   | Enable/disable MCP     |
-| `stopTask()`             |     ✅      |   ❌    |  ✅   | Stop running task      |
-| `streamInput()`          |     ✅      |   ✅    |  ✅   | Stream user input      |
-| `initializationResult()` |     ✅      |   ❌    |  ✅   | Full init response     |
-| `close()`                |     ✅      |   ✅    |  ✅   | Close query/session    |
+| Method                   | TypeScript | Python | Ruby | Notes                                        |
+|--------------------------|:----------:|:------:|:----:|----------------------------------------------|
+| `interrupt()`            |     ✅      |   ✅    |  ✅   | Interrupt execution                          |
+| `setPermissionMode()`    |     ✅      |   ✅    |  ✅   | Change permission mode                       |
+| `setModel()`             |     ✅      |   ✅    |  ✅   | Change model                                 |
+| `setMaxThinkingTokens()` |     ✅      |   ❌    |  ✅   | Set thinking limit                           |
+| `supportedCommands()`    |     ✅      |   ❌    |  ✅   | Get slash commands                           |
+| `supportedModels()`      |     ✅      |   ❌    |  ✅   | Get available models                         |
+| `mcpServerStatus()`      |     ✅      |   ✅    |  ✅   | Get MCP status                               |
+| `accountInfo()`          |     ✅      |   ❌    |  ✅   | Get account info                             |
+| `rewindFiles()`          |     ✅      |   ✅    |  ✅   | Rewind file changes                          |
+| `setMcpServers()`        |     ✅      |   ❌    |  ✅   | Dynamic MCP servers                          |
+| `reconnectMcpServer()`   |     ✅      |   ❌    |  ✅   | Reconnect MCP server                         |
+| `toggleMcpServer()`      |     ✅      |   ❌    |  ✅   | Enable/disable MCP                           |
+| `stopTask()`             |     ✅      |   ❌    |  ✅   | Stop running task                            |
+| `streamInput()`          |     ✅      |   ✅    |  ✅   | Stream user input                            |
+| `initializationResult()` |     ✅      |   ✅    |  ✅   | Full init response (Py: `get_server_info()`) |
+| `close()`                |     ✅      |   ✅    |  ✅   | Close query/session                          |
 
 ### Client Class
 
@@ -689,23 +722,30 @@ Public API surface for SDK clients.
 - `executable`/`executableArgs` are JS-specific (`node`/`bun`/`deno`)
 - v0.2.45: Added `TaskStartedMessage`, `RateLimitEvent` message types
 - v0.2.47: Added `promptSuggestions` option and `PromptSuggestionMessage`
-- v0.2.49: Added `ConfigChange` hook event, `SandboxFilesystemConfig`
+- v0.2.49: Added `ConfigChange` hook event, `SandboxFilesystemConfig`, ModelInfo capability fields
+- v0.2.50: Added `WorktreeCreate`/`WorktreeRemove` hook events, `apply_flag_settings` control request
+- v0.2.51: Added `TaskProgressMessage` for real-time background agent progress reporting
+- v0.2.52: Added `mcp_authenticate`/`mcp_clear_auth` control requests for MCP server authentication
+- v0.2.53: Added `listSessions()` for discovering and listing past sessions with `SDKSessionInfo` metadata
+- v0.2.54 – v0.2.56: CLI parity updates (no new SDK-facing features)
 
 ### Python SDK
 - Full source available with `Transport` abstract class
 - Partial control protocol: query and client support interrupt, setPermissionMode, setModel, rewindFiles, mcpStatus
-- Missing hooks: SessionStart, SessionEnd, Setup, TeammateIdle, TaskCompleted, ConfigChange
+- Has `CLINotFoundError`, `CLIConnectionError`, `ProcessError`, `CLIJSONDecodeError` error types
+- Missing hooks: SessionStart, SessionEnd, Setup, TeammateIdle, TaskCompleted, ConfigChange, WorktreeCreate, WorktreeRemove
 - Missing permission modes: `dontAsk`
 - Missing options: `allowDangerouslySkipPermissions`, `persistSession`, `resumeSessionAt`, `sessionId`, `strictMcpConfig`, `init`/`initOnly`/`maintenance`, `debug`/`debugFile`, `promptSuggestions`
 - `ToolPermissionContext` missing `blockedPath`, `decisionReason`, `toolUseID`, `agentID`, `description`
 - Has SDK MCP server support with `tool()` helper and annotations
 - Added `thinking` config and `effort` option in v0.1.36
-- Handles `rate_limit_event` and unknown message types gracefully (v0.1.39)
+- Handles `rate_limit_event` and unknown message types gracefully (v0.1.40)
+- Client has `get_server_info()` for accessing the initialization result (v0.1.31+)
+- v0.1.42 – v0.1.43: CLI parity updates (no new SDK-facing features)
 
 ### Ruby SDK (This Repository)
-- Feature parity with TypeScript SDK v0.2.42
+- Feature parity with TypeScript SDK v0.2.56
 - Ruby-idiomatic patterns (Data.define, snake_case)
 - Complete control protocol, hook, and V2 Session API support
 - Dedicated Client class for multi-turn conversations
 - `executable`/`executableArgs` marked N/A (JS runtime options)
-- Gaps from TS v0.2.43-v0.2.49: `promptSuggestions`, `TaskStartedMessage`, `RateLimitEvent`, `PromptSuggestionMessage`, `ConfigChange` hook, `SandboxFilesystemConfig`

data/lib/claude_agent/client.rb

@@ -32,7 +32,7 @@ module ClaudeAgent
   #   end
   #
   class Client
-    attr_reader :options, :transport, :server_info
+    attr_reader :options, :transport, :server_info, :cumulative_usage, :event_handler, :permission_queue
 
     # Open a client with automatic cleanup
     #
@@ -61,6 +61,9 @@ module ClaudeAgent
       @protocol = nil
       @server_info = nil
       @connected = false
+      @cumulative_usage = CumulativeUsage.new
+      @event_handler = EventHandler.new
+      @permission_queue = PermissionQueue.new
     end
 
     # Connect to the CLI
@@ -74,6 +77,7 @@ module ClaudeAgent
 
       logger.info("client") { "Connecting" }
       @protocol = ControlProtocol.new(transport: @transport, options: @options)
+      @protocol.permission_queue = @permission_queue
       @server_info = @protocol.start(streaming: true)
       @connected = true
       logger.info("client") { "Connected" }
@@ -88,6 +92,7 @@ module ClaudeAgent
       return unless @connected
 
       logger.info("client") { "Disconnecting" }
+      @permission_queue.drain!(reason: "Client disconnected")
       @protocol&.stop
       @protocol = nil
       @connected = false
@@ -119,20 +124,133 @@ module ClaudeAgent
     #
     # @yield [Message] Received messages
     # @return [Enumerator<Message>] If no block given
-    def receive_messages(&block)
+    def receive_messages
       require_connection!
 
-      @protocol.each_message(&block)
+      if block_given?
+        @protocol.each_message do |message|
+          @cumulative_usage.track(message)
+          yield message
+        end
+      else
+        enum_for(:receive_messages)
+      end
     end
 
     # Receive messages until a ResultMessage is received
     #
     # @yield [Message] Received messages
     # @return [Enumerator<Message>] If no block given
-    def receive_response(&block)
+    def receive_response
       require_connection!
 
-      @protocol.receive_response(&block)
+      if block_given?
+        @protocol.receive_response do |message|
+          @cumulative_usage.track(message)
+          yield message
+        end
+      else
+        enum_for(:receive_response)
+      end
+    end
+
+    # Register an event handler
+    #
+    # Handlers persist across turns and fire automatically during
+    # {#receive_turn} and {#send_and_receive}.
+    #
+    # @param event [Symbol] Event name (:message, :text, :thinking, :tool_use, :tool_result, :result)
+    # @yield Event-specific arguments
+    # @return [self]
+    #
+    # @example
+    #   client.on(:text) { |text| print text }
+    #   client.on(:tool_use) { |tool| show_spinner(tool) }
+    #
+    def on(event, &block)
+      @event_handler.on(event, &block)
+      self
+    end
+
+    # @!method on_text(&block)
+    #   Register a handler for assistant text content
+    #   @yield [String] Text from the AssistantMessage
+    #   @return [self]
+
+    # @!method on_thinking(&block)
+    #   Register a handler for assistant thinking content
+    #   @yield [String] Thinking from the AssistantMessage
+    #   @return [self]
+
+    # @!method on_tool_use(&block)
+    #   Register a handler for tool use requests
+    #   @yield [ToolUseBlock, ServerToolUseBlock] The tool use block
+    #   @return [self]
+
+    # @!method on_tool_result(&block)
+    #   Register a handler for tool results, paired with the original request
+    #   @yield [ToolResultBlock, ToolUseBlock|nil] Result block and matched tool use
+    #   @return [self]
+
+    # @!method on_result(&block)
+    #   Register a handler for the final ResultMessage
+    #   @yield [ResultMessage] The result
+    #   @return [self]
+
+    # @!method on_message(&block)
+    #   Register a handler for every message (catch-all)
+    #   @yield [message] Any message object
+    #   @return [self]
+
+    %i[message text thinking tool_use tool_result result].each do |event|
+      define_method(:"on_#{event}") { |&block| on(event, &block) }
+    end
+
+    # Receive messages until a ResultMessage, accumulating into a TurnResult
+    #
+    # Dispatches events to registered handlers (see {#on}).
+    #
+    # @yield [Message] Each message as it arrives (optional)
+    # @return [TurnResult] The completed turn
+    def receive_turn
+      require_connection!
+
+      turn = TurnResult.new
+      receive_response do |message|
+        turn << message
+        @event_handler.handle(message)
+        yield message if block_given?
+      end
+      @event_handler.reset!
+      turn
+    end
+
+    # Send a message and receive the complete turn result
+    #
+    # Combines {#send_message} and {#receive_turn} into a single call.
+    #
+    # @param content [String, Array] Message content
+    # @param session_id [String] Session ID
+    # @param uuid [String, nil] Message UUID for file checkpointing
+    # @yield [Message] Each message as it arrives (optional)
+    # @return [TurnResult] The completed turn
+    #
+    # @example Simple
+    #   turn = client.send_and_receive("Fix the bug")
+    #   puts turn.text
+    #   puts "Cost: $#{turn.cost}"
+    #
+    # @example With streaming
+    #   turn = client.send_and_receive("Fix the bug") do |msg|
+    #     case msg
+    #     when ClaudeAgent::AssistantMessage
+    #       print msg.text
+    #     end
+    #   end
+    #
+    def send_and_receive(content, session_id: "default", uuid: nil, &block)
+      send_message(content, session_id: session_id, uuid: uuid)
+      receive_turn(&block)
     end
 
     # Stream user input from an enumerable (TypeScript SDK parity)
@@ -161,11 +279,14 @@ module ClaudeAgent
     #     end
     #   end
     #
-    def stream_input(stream, session_id: "default", &block)
+    def stream_input(stream, session_id: "default")
       require_connection!
 
       if block_given?
-        @protocol.stream_conversation(stream, session_id: session_id, &block)
+        @protocol.stream_conversation(stream, session_id: session_id) do |message|
+          @cumulative_usage.track(message)
+          yield message
+        end
       else
         @protocol.stream_input(stream, session_id: session_id)
       end
@@ -191,6 +312,7 @@ module ClaudeAgent
     def abort!(reason = nil)
       return unless @connected
 
+      @permission_queue.drain!(reason: reason || "Operation aborted")
       @options.abort_controller&.abort(reason)
       @protocol&.abort!
     end
@@ -298,6 +420,22 @@ module ClaudeAgent
       @protocol.stop_task(task_id)
     end
 
+    # Apply flag settings (TypeScript SDK v0.2.50 parity)
+    #
+    # Merges the provided settings into the flag settings layer.
+    #
+    # @param settings [Hash] Settings to merge into the flag layer
+    # @return [Hash] Response from the CLI
+    #
+    # @example
+    #   client.apply_flag_settings({ "model" => "claude-sonnet-4-5-20250514" })
+    #
+    def apply_flag_settings(settings)
+      require_connection!
+
+      @protocol.apply_flag_settings(settings)
+    end
+
     # Dynamically set MCP servers for this session (TypeScript SDK parity)
     #
     # This replaces the current set of dynamically-added MCP servers.
@@ -355,6 +493,58 @@ module ClaudeAgent
       @protocol.mcp_toggle(server_name, enabled: enabled)
     end
 
+    # Initiate OAuth authentication for an MCP server (TypeScript SDK v0.2.52 parity)
+    #
+    # @param server_name [String] Name of the MCP server to authenticate
+    # @return [Hash] Response from the CLI
+    #
+    # @example
+    #   client.mcp_authenticate("my-remote-server")
+    #
+    def mcp_authenticate(server_name)
+      require_connection!
+
+      @protocol.mcp_authenticate(server_name)
+    end
+
+    # Clear stored auth credentials for an MCP server (TypeScript SDK v0.2.52 parity)
+    #
+    # @param server_name [String] Name of the MCP server to clear auth for
+    # @return [Hash] Response from the CLI
+    #
+    # @example
+    #   client.mcp_clear_auth("my-remote-server")
+    #
+    def mcp_clear_auth(server_name)
+      require_connection!
+
+      @protocol.mcp_clear_auth(server_name)
+    end
+
+    # Non-blocking poll for the next pending permission request.
+    #
+    # Returns the next {PermissionRequest} from the queue, or nil if
+    # no requests are pending. Call {PermissionRequest#allow!} or
+    # {PermissionRequest#deny!} to resolve it.
+    #
+    # @return [PermissionRequest, nil] The next pending request, or nil
+    #
+    # @example UI poll loop
+    #   if request = client.pending_permission
+    #     show_permission_dialog(request)
+    #   end
+    #
+    def pending_permission
+      @permission_queue.poll
+    end
+
+    # Check if there are any pending permission requests.
+    #
+    # @return [Boolean]
+    def pending_permissions?
+      !@permission_queue.empty?
+    end
+
     private
 
     def logger