claude_agent 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47641ba77d22b8a0f150ddad47d58593e05027355f278d233fa3905e9463ff0b
-  data.tar.gz: 8615b423941943ec78c76100e4acbf313f2f038033fe1dd21ff85df3ffbd7a11
+  metadata.gz: 4d11f6fa8fa6ecc4b00e0bb6f7913582d0ac8675f649f2d5b423306660a44247
+  data.tar.gz: 1c7259588ea2b823ad06c7f263830418a590b5488c7db3d9d825b3e46b31495a
 SHA512:
-  metadata.gz: f683a79341de2cfd99db5a287562bc93d4cb9c8c46c1378e997d5c1ef6eff55d5aeed4596d74388d62bb6235484f7ddb9ffc75ff967fa6e716da971293fc64f0
-  data.tar.gz: 0dca9c4ce8ea188c9dbab54637c03ce9f291dfb7b60a81594f2098acf64253609e9a3150c1397a16cdb2e7f255d67f753409f6676cf17803a5b081813b73e8e5
+  metadata.gz: e57643b8293c0cba79fb96322daa1c8fd08a068664f63bad5a6787f9731e60232ff0ee806698ff79707c4a000dd600bfc1e459ea9a0933e7685e5b5fefd87911
+  data.tar.gz: 6ac435262b2489ef696db91db6440e8df9f8000e09a46b97cc80decdda1b04cedfcd561a6d56e8b09aa8d373fa223f1ecdad2ff08f82ba9ea350375dd5772eed

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-01-30
+
+### Added
+- `FilesPersistedEvent` message type for file persistence confirmation (TypeScript SDK v0.2.25 parity)
+- `claudeai-proxy` MCP server type support via Hash-based config passthrough
+
+### Changed
+- Updated SPEC.md to reference TypeScript SDK v0.2.25 and Python SDK v0.1.25
+
 ## [0.5.0] - 2026-01-25
 
 ### Added

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.19 (npm package)
-- Python SDK: v0.1.22 from GitHub (commit 6a0140a)
+- TypeScript SDK: v0.2.25 (npm package)
+- Python SDK: v0.1.25 from GitHub (commit 1bf665c)
 - Ruby SDK: This repository
 
-**Last Updated:** 2025-01-25
+**Last Updated:** 2026-01-30
 
 ---
 
@@ -65,7 +65,7 @@ Configuration options for SDK queries and clients.
 | `additionalDirectories`           |     ✅      |   ✅    |  ✅   | Extra allowed directories                                    |
 | `env`                             |     ✅      |   ✅    |  ✅   | Environment variables                                        |
 | `sandbox`                         |     ✅      |   ✅    |  ✅   | Sandbox settings                                             |
-| `settings`                        |     ✅      |   ❌    |  ✅   | Settings file path or JSON string (e.g., plansDirectory)     |
+| `settings`                        |     ✅      |   ✅    |  ✅   | Settings file path or JSON string (e.g., plansDirectory)     |
 | `settingSources`                  |     ✅      |   ✅    |  ✅   | Which settings to load                                       |
 | `plugins`                         |     ✅      |   ✅    |  ✅   | Plugin configurations                                        |
 | `betas`                           |     ✅      |   ✅    |  ✅   | Beta features (e.g., context-1m-2025-08-07)                  |
@@ -104,6 +104,7 @@ Messages exchanged between SDK and CLI.
 | `AuthStatusMessage`       |     ✅      |   ❌    |  ✅   | Authentication status              |
 | `TaskNotificationMessage` |     ✅      |   ❌    |  ✅   | Background task completion         |
 | `ToolUseSummaryMessage`   |     ✅      |   ❌    |  ✅   | Summary of tool use (collapsed)    |
+| `FilesPersistedEvent`     |     ✅      |   ❌    |  ✅   | File persistence confirmation      |
 
 ### Message Fields
 
@@ -212,12 +213,12 @@ Bidirectional control protocol for SDK-CLI communication.
 | `can_use_tool`            |     ✅      |   ✅    |  ✅   | Permission callback               |
 | `hook_callback`           |     ✅      |   ✅    |  ✅   | Execute hook callback             |
 | `set_permission_mode`     |     ✅      |   ✅    |  ✅   | Change permission mode            |
-| `set_model`               |     ✅      |   ❌    |  ✅   | Change model                      |
+| `set_model`               |     ✅      |   ✅    |  ✅   | Change model                      |
 | `set_max_thinking_tokens` |     ✅      |   ❌    |  ✅   | Change thinking tokens limit      |
 | `rewind_files`            |     ✅      |   ✅    |  ✅   | Rewind file checkpoints           |
 | `mcp_message`             |     ✅      |   ✅    |  ✅   | Route MCP message                 |
 | `mcp_set_servers`         |     ✅      |   ❌    |  ✅   | Dynamically set MCP servers       |
-| `mcp_status`              |     ✅      |   ❌    |  ✅   | Get MCP server status             |
+| `mcp_status`              |     ✅      |   ✅    |  ✅   | Get MCP server status             |
 | `mcp_reconnect`           |     ✅      |   ❌    |  ✅   | Reconnect to MCP server           |
 | `mcp_toggle`              |     ✅      |   ❌    |  ✅   | Enable/disable MCP server         |
 | `supported_commands`      |     ✅      |   ❌    |  ✅   | Get available slash commands      |
@@ -247,7 +248,7 @@ Event hooks for intercepting and modifying SDK behavior.
 |----------------------|:----------:|:------:|:----:|---------------------------|
 | `PreToolUse`         |     ✅      |   ✅    |  ✅   | Before tool execution     |
 | `PostToolUse`        |     ✅      |   ✅    |  ✅   | After tool execution      |
-| `PostToolUseFailure` |     ✅      |   ❌    |  ✅   | After tool failure        |
+| `PostToolUseFailure` |     ✅      |   ✅    |  ✅   | After tool failure        |
 | `Notification`       |     ✅      |   ❌    |  ✅   | System notifications      |
 | `UserPromptSubmit`   |     ✅      |   ✅    |  ✅   | User message submitted    |
 | `SessionStart`       |     ✅      |   ❌    |  ✅   | Session starts            |
@@ -265,7 +266,7 @@ Event hooks for intercepting and modifying SDK behavior.
 |-------------------------------|:----------:|:------:|:----:|
 | `PreToolUseHookInput`         |     ✅      |   ✅    |  ✅   |
 | `PostToolUseHookInput`        |     ✅      |   ✅    |  ✅   |
-| `PostToolUseFailureHookInput` |     ✅      |   ❌    |  ✅   |
+| `PostToolUseFailureHookInput` |     ✅      |   ✅    |  ✅   |
 | `NotificationHookInput`       |     ✅      |   ❌    |  ✅   |
 | `UserPromptSubmitHookInput`   |     ✅      |   ✅    |  ✅   |
 | `SessionStartHookInput`       |     ✅      |   ❌    |  ✅   |
@@ -300,7 +301,7 @@ Event-specific fields returned via `hookSpecificOutput`:
 | Field                      | TypeScript | Python | Ruby | Notes                              |
 |----------------------------|:----------:|:------:|:----:|------------------------------------|
 | `permissionDecision`       |     ✅      |   ✅    |  ✅   | `allow`, `deny`, or `ask`          |
-| `permissionDecisionReason` |     ✅      |   ❌    |  ✅   | Reason for permission decision     |
+| `permissionDecisionReason` |     ✅      |   ✅    |  ✅   | Reason for permission decision     |
 | `updatedInput`             |     ✅      |   ✅    |  ✅   | Modified tool input                |
 | `additionalContext`        |     ✅      |   ❌    |  ✅   | Context string returned to model   |
 
@@ -315,7 +316,7 @@ Event-specific fields returned via `hookSpecificOutput`:
 
 | Field               | TypeScript | Python | Ruby | Notes                            |
 |---------------------|:----------:|:------:|:----:|----------------------------------|
-| `additionalContext` |     ✅      |   ❌    |  ✅   | Context string returned to model |
+| `additionalContext` |     ✅      |   ✅    |  ✅   | Context string returned to model |
 
 #### SessionStartHookSpecificOutput
 
@@ -436,12 +437,13 @@ Model Context Protocol server support.
 
 ### MCP Server Types
 
-| Type    | TypeScript | Python | Ruby | Notes                 |
-|---------|:----------:|:------:|:----:|-----------------------|
-| `stdio` |     ✅      |   ✅    |  ✅   | Subprocess with stdio |
-| `sse`   |     ✅      |   ✅    |  ✅   | Server-sent events    |
-| `http`  |     ✅      |   ✅    |  ✅   | HTTP transport        |
-| `sdk`   |     ✅      |   ✅    |  ✅   | In-process SDK server |
+| Type             | TypeScript | Python | Ruby | Notes                            |
+|------------------|:----------:|:------:|:----:|----------------------------------|
+| `stdio`          |     ✅      |   ✅    |  ✅   | Subprocess with stdio            |
+| `sse`            |     ✅      |   ✅    |  ✅   | Server-sent events               |
+| `http`           |     ✅      |   ✅    |  ✅   | HTTP transport                   |
+| `sdk`            |     ✅      |   ✅    |  ✅   | In-process SDK server            |
+| `claudeai-proxy` |     ✅      |   ❌    |  ✅   | Claude.ai proxy server (managed) |
 
 ### MCP Server Config Fields
 
@@ -595,41 +597,41 @@ Public API surface for SDK clients.
 | One-shot query function | ✅ `query()` | ✅ `query()` | ✅ `ClaudeAgent.query()` | Simple prompts     |
 | Returns async generator |      ✅      |      ✅      |     ✅ (Enumerator)      | Streaming messages |
 
-### Query Control Methods (TypeScript)
+### Query Control Methods
 
 | Method                   | TypeScript | Python | Ruby | Notes                  |
 |--------------------------|:----------:|:------:|:----:|------------------------|
-| `interrupt()`            |     ✅      |   ❌    |  ✅   | Interrupt execution    |
-| `setPermissionMode()`    |     ✅      |   ❌    |  ✅   | Change permission mode |
-| `setModel()`             |     ✅      |   ❌    |  ✅   | Change model           |
+| `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         |
+| `mcpServerStatus()`      |     ✅      |   ✅    |  ✅   | Get MCP status         |
 | `accountInfo()`          |     ✅      |   ❌    |  ✅   | Get account info       |
 | `rewindFiles()`          |     ✅      |   ✅    |  ✅   | Rewind file changes    |
 | `setMcpServers()`        |     ✅      |   ❌    |  ✅   | Dynamic MCP servers    |
-| `streamInput()`          |     ✅      |   ❌    |  ✅   | Stream user input      |
-| `close()`                |     ✅      |   ❌    |  ✅   | Close query/session    |
+| `streamInput()`          |     ✅      |   ✅    |  ✅   | Stream user input      |
+| `close()`                |     ✅      |   ✅    |  ✅   | Close query/session    |
 
 ### Client Class
 
-| Feature              | TypeScript |       Python        |          Ruby           | Notes                          |
-|----------------------|:----------:|:-------------------:|:-----------------------:|--------------------------------|
-| Multi-turn client    |     ❌      | ✅ `ClaudeSDKClient` | ✅ `ClaudeAgent::Client` | Interactive sessions           |
-| `connect()`          |    N/A     |          ✅          |            ✅            | Start session                  |
-| `disconnect()`       |    N/A     |          ✅          |            ✅            | End session                    |
-| `send_message()`     |    N/A     |          ✅          |            ✅            | Send user message              |
-| `receive_response()` |    N/A     |          ✅          |            ✅            | Receive until result           |
-| `stream_input()`     |    N/A     |          ❌          |            ✅            | Stream input messages          |
-| `abort!()`           |    N/A     |          ❌          |            ✅            | Abort operations               |
-| Control methods      |    N/A     |       Partial       |            ✅            | All TypeScript control methods |
+| Feature              | TypeScript |       Python        |          Ruby           | Notes                                                                            |
+|----------------------|:----------:|:-------------------:|:-----------------------:|----------------------------------------------------------------------------------|
+| Multi-turn client    |     ❌      | ✅ `ClaudeSDKClient` | ✅ `ClaudeAgent::Client` | Interactive sessions                                                             |
+| `connect()`          |    N/A     |          ✅          |            ✅            | Start session                                                                    |
+| `disconnect()`       |    N/A     |          ✅          |            ✅            | End session                                                                      |
+| `send_message()`     |    N/A     |          ✅          |            ✅            | Send user message                                                                |
+| `receive_response()` |    N/A     |          ✅          |            ✅            | Receive until result                                                             |
+| `stream_input()`     |    N/A     |          ❌          |            ✅            | Stream input messages                                                            |
+| `abort!()`           |    N/A     |          ❌          |            ✅            | Abort operations                                                                 |
+| Control methods      |    N/A     |       Partial       |            ✅            | interrupt, setPermissionMode, setModel, rewindFiles (Python); all methods (Ruby) |
 
 ### Transport
 
 | Feature               | TypeScript | Python | Ruby | Notes                    |
 |-----------------------|:----------:|:------:|:----:|--------------------------|
-| `Transport` interface |     ✅      |   ❌    |  ✅   | Transport abstraction    |
+| `Transport` interface |     ✅      |   ✅    |  ✅   | Transport abstraction    |
 | Process transport     |     ✅      |   ✅    |  ✅   | Subprocess communication |
 | Custom spawn          |     ✅      |   ❌    |  ✅   | VM/container support     |
 
@@ -659,21 +661,32 @@ Public API surface for SDK clients.
 - v0.2.12+ adds `user` option to SDKSessionOptions
 - v0.2.19 adds `mcp_reconnect` and `mcp_toggle` control requests
 - v0.2.19 adds `HookStartedMessage`, `HookProgressMessage`, and `ToolUseSummaryMessage`
+- v0.2.25 adds `SDKFilesPersistedEvent` message type for file persistence confirmation
+- v0.2.25 adds `McpClaudeAIProxyServerConfig` (`claudeai-proxy` type) for managed proxy servers
 
 ### Python SDK
-- Full source available (v0.1.22)
-- Fewer control protocol features than TypeScript
-- Does not support SessionStart/SessionEnd/Notification hooks due to setup limitations
+- Full source available (v0.1.25)
+- Now has `Transport` abstract class and several query control methods
+- Supports `interrupt()`, `set_permission_mode()`, `set_model()`, `rewind_files()`, `stream_input()`, `close()`, `get_mcp_status()` in query
+- Client also supports `interrupt()`, `set_permission_mode()`, `set_model()`, `rewind_files()`
+- Does not support SessionStart/SessionEnd/Notification/SubagentStart/PermissionRequest/Setup hooks
 - Missing several permission modes (delegate, dontAsk)
+- Missing `allowDangerouslySkipPermissions`, `persistSession`, `resumeSessionAt`, `strictMcpConfig`
+- Missing `init`/`initOnly`/`maintenance` Setup hook options
 - `excludedCommands` in sandbox now supported
-- `tool_use_id` now included in PreToolUseHookInput
-- `additionalContext` now supported in UserPromptSubmitHookSpecificOutput
+- v0.1.25 adds `PostToolUseFailure` hook event support
+- v0.1.25 adds `permissionDecisionReason` to `PreToolUseHookSpecificOutput`
+- `additionalContext` supported in `UserPromptSubmitHookSpecificOutput`
+- `PreToolUseHookInput` does not include `tool_use_id` (unlike TypeScript)
+- `ToolPermissionContext` missing `blockedPath`, `decisionReason`, `toolUseID`, `agentID`
 
 ### Ruby SDK (This Repository)
-- Complete TypeScript SDK feature parity
+- Full TypeScript SDK feature parity
 - Ruby-idiomatic patterns (Data.define, snake_case)
 - Complete control protocol support
 - Dedicated Client class for multi-turn conversations
 - Full hook event support including all 13 events
 - Full V2 Session API support (unstable)
 - `executable`/`executableArgs` marked N/A (JS runtime options not applicable to Ruby)
+- Added: `FilesPersistedEvent` message type (new in TS v0.2.25)
+- `claudeai-proxy` MCP server type handled transparently via Hash-based config passthrough (new in TS v0.2.25)

data/lib/claude_agent/message_parser.rb

@@ -11,7 +11,7 @@ module ClaudeAgent
     # Parse a raw message hash into a typed message object
     #
     # @param raw [Hash] Raw message from CLI
-    # @return [UserMessage, UserMessageReplay, AssistantMessage, SystemMessage, ResultMessage, StreamEvent, CompactBoundaryMessage, StatusMessage, ToolProgressMessage, HookResponseMessage, AuthStatusMessage, TaskNotificationMessage, HookStartedMessage, HookProgressMessage, ToolUseSummaryMessage]
+    # @return [UserMessage, UserMessageReplay, AssistantMessage, SystemMessage, ResultMessage, StreamEvent, CompactBoundaryMessage, StatusMessage, ToolProgressMessage, HookResponseMessage, AuthStatusMessage, TaskNotificationMessage, HookStartedMessage, HookProgressMessage, ToolUseSummaryMessage, FilesPersistedEvent]
     # @raise [MessageParseError] If message cannot be parsed
     def parse(raw)
       type = raw["type"]
@@ -36,6 +36,8 @@ module ClaudeAgent
           parse_hook_started_message(raw)
         when "hook_progress"
           parse_hook_progress_message(raw)
+        when "files_persisted"
+          parse_files_persisted_event(raw)
         else
           parse_system_message(raw)
         end
@@ -312,5 +314,15 @@ module ClaudeAgent
         preceding_tool_use_ids: fetch_dual(raw, :preceding_tool_use_ids, [])
       )
     end
+
+    def parse_files_persisted_event(raw)
+      FilesPersistedEvent.new(
+        uuid: raw["uuid"] || "",
+        session_id: fetch_dual(raw, :session_id, ""),
+        files: raw["files"] || [],
+        failed: raw["failed"] || [],
+        processed_at: fetch_dual(raw, :processed_at)
+      )
+    end
   end
 end

data/lib/claude_agent/messages.rb

@@ -614,6 +614,43 @@ module ClaudeAgent
     end
   end
 
+  # Files persisted event (TypeScript SDK v0.2.25 parity)
+  #
+  # Sent when files are persisted to storage during a session.
+  # Contains lists of successfully persisted files and any failures.
+  #
+  # @example
+  #   msg = FilesPersistedEvent.new(
+  #     uuid: "msg-123",
+  #     session_id: "session-abc",
+  #     files: [{ "filename" => "test.rb", "file_id" => "file-456" }],
+  #     failed: [],
+  #     processed_at: "2026-01-30T12:00:00Z"
+  #   )
+  #   msg.files.first["filename"]  # => "test.rb"
+  #
+  FilesPersistedEvent = Data.define(
+    :uuid,
+    :session_id,
+    :files,
+    :failed,
+    :processed_at
+  ) do
+    def initialize(
+      uuid:,
+      session_id:,
+      files: [],
+      failed: [],
+      processed_at: nil
+    )
+      super
+    end
+
+    def type
+      :files_persisted
+    end
+  end
+
   # All message types
   MESSAGE_TYPES = [
     UserMessage,
@@ -630,6 +667,7 @@ module ClaudeAgent
     TaskNotificationMessage,
     HookStartedMessage,
     HookProgressMessage,
-    ToolUseSummaryMessage
+    ToolUseSummaryMessage,
+    FilesPersistedEvent
   ].freeze
 end

data/lib/claude_agent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgent
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/sig/claude_agent.rbs

@@ -393,7 +393,7 @@ module ClaudeAgent
   CONTENT_BLOCK_TYPES: Array[Class]
 
   # Message types
-  type message = UserMessage | UserMessageReplay | AssistantMessage | SystemMessage | ResultMessage | StreamEvent | CompactBoundaryMessage | StatusMessage | ToolProgressMessage | HookResponseMessage | AuthStatusMessage | TaskNotificationMessage | HookStartedMessage | HookProgressMessage | ToolUseSummaryMessage
+  type message = UserMessage | UserMessageReplay | AssistantMessage | SystemMessage | ResultMessage | StreamEvent | CompactBoundaryMessage | StatusMessage | ToolProgressMessage | HookResponseMessage | AuthStatusMessage | TaskNotificationMessage | HookStartedMessage | HookProgressMessage | ToolUseSummaryMessage | FilesPersistedEvent
 
   MESSAGE_TYPES: Array[Class]
 
@@ -616,6 +616,18 @@ module ClaudeAgent
     def type: () -> :tool_use_summary
   end
 
+  # Files persisted event (TypeScript SDK v0.2.25 parity)
+  class FilesPersistedEvent
+    attr_reader uuid: String
+    attr_reader session_id: String
+    attr_reader files: Array[Hash[String, String]]
+    attr_reader failed: Array[Hash[String, String]]
+    attr_reader processed_at: String?
+
+    def initialize: (uuid: String, session_id: String, ?files: Array[Hash[String, String]], ?failed: Array[Hash[String, String]], ?processed_at: String?) -> void
+    def type: () -> :files_persisted
+  end
+
   # Message parser
   class MessageParser
     def initialize: () -> void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_agent
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Thomas Carr