RubyGems - claude_agent - Versions diffs - 0.5.0 → 0.7.0 - Mend

claude_agent 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

checksums.yaml +4 -4
data/.claude/skills/spec/SKILL.md +45 -0
data/.claude/{commands/spec → skills/spec/commands}/complete.md +14 -41
data/.claude/skills/spec/commands/update.md +48 -0
data/CHANGELOG.md +20 -0
data/CLAUDE.md +1 -30
data/README.md +90 -1
data/SPEC.md +67 -46
data/lib/claude_agent/mcp/server.rb +2 -2
data/lib/claude_agent/mcp/tool.rb +7 -3
data/lib/claude_agent/message_parser.rb +13 -1
data/lib/claude_agent/messages.rb +39 -1
data/lib/claude_agent/version.rb +1 -1
data/sig/claude_agent.rbs +16 -3
metadata +4 -3
data/.claude/commands/spec/update.md +0 -95

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47641ba77d22b8a0f150ddad47d58593e05027355f278d233fa3905e9463ff0b
-  data.tar.gz: 8615b423941943ec78c76100e4acbf313f2f038033fe1dd21ff85df3ffbd7a11
+  metadata.gz: 72db3aeea7a724d0271a3fc8bb0bd7900425a34e7114e526e9bfe8bbbe26e19f
+  data.tar.gz: a31e9321dc56507d0a05d8319e50fded02aaa420a9709a0970a298826ea2f4ad
 SHA512:
-  metadata.gz: f683a79341de2cfd99db5a287562bc93d4cb9c8c46c1378e997d5c1ef6eff55d5aeed4596d74388d62bb6235484f7ddb9ffc75ff967fa6e716da971293fc64f0
-  data.tar.gz: 0dca9c4ce8ea188c9dbab54637c03ce9f291dfb7b60a81594f2098acf64253609e9a3150c1397a16cdb2e7f255d67f753409f6676cf17803a5b081813b73e8e5
+  metadata.gz: 54d586a6a4e368adf4b64ec8afdbf4b04ad165473e81bcf8e0c244c7c04ac5c524b6c1186e34dd7bf6c31cc3b521da6d5526b187a30d147c3839ba5b708056ae
+  data.tar.gz: 4af34d4756c9559570ea9c8d0ed9819ae98827773eed4332d9cc7bc50c8b5edc6584c0ee25fbfa197c3bc79513acace10ee88ec3bf1674141afcfe213ead2f02

data/.claude/skills/spec/SKILL.md ADDED Viewed

@@ -0,0 +1,45 @@
+---
+name: spec
+description: Manage the SDK feature parity specification. Use 'update' to regenerate SPEC.md from current implementations, or 'complete' to implement missing features.
+argument-hint: [update|complete]
+disable-model-invocation: true
+allowed-tools: Bash, Read, Glob, Grep, Write, Edit, TodoWrite, Task, AskUserQuestion, EnterPlanMode
+---
+# SDK Feature Parity Management
+Manage the feature parity specification for the TypeScript, Python, and Ruby Claude Agent SDKs.
+## Reference SDKs
+Ensure reference SDKs are current before starting any workflow:
+```bash
+bin/update-reference-sdks
+```
+This clones/updates:
+- Python SDK from GitHub -> `vendor/claude-agent-sdk-python`
+- TypeScript SDK from npm -> `vendor/claude-agent-sdk-npm`
+- TypeScript SDK repo from GitHub -> `vendor/claude-agent-sdk-typescript` (changelog/releases)
+## Key Source Files
+**TypeScript SDK (Primary Reference)**
+- `vendor/claude-agent-sdk-npm/sdk.d.ts` - Complete API surface with all types
+- `vendor/claude-agent-sdk-typescript/CHANGELOG.md` - Release changelog
+**Python SDK**
+- `vendor/claude-agent-sdk-python/src/claude_agent_sdk/types.py` - Type definitions
+- `vendor/claude-agent-sdk-python/src/claude_agent_sdk/_internal/` - Internal implementation
+**Ruby SDK (This Repository)**
+- `lib/claude_agent/` - All implementation files
+## Mode Selection
+Based on the first argument:
+- **update**: Follow the workflow in [commands/update.md](commands/update.md)
+- **complete**: Follow the workflow in [commands/complete.md](commands/complete.md)
+- If no argument or unrecognized: ask the user which mode they want

data/.claude/{commands/spec → skills/spec/commands}/complete.md RENAMED Viewed

@@ -1,21 +1,12 @@
----
-description: Implement missing Ruby SDK features identified in SPEC.md to achieve full parity with TypeScript/Python SDKs
-allowed-tools: Bash, Read, Glob, Grep, Write, Edit, TodoWrite, Task, AskUserQuestion, EnterPlanMode
----
 # Complete SDK Feature Parity
-You are implementing missing features in the Ruby SDK to achieve full parity with the official TypeScript and Python Claude Agent SDKs.
+Implement missing features in the Ruby SDK to achieve full parity with the official TypeScript and Python Claude Agent SDKs.
 ## Step 1: Identify Missing Features
-Read SPEC.md and identify all features where the Ruby SDK shows ❌ (not implemented):
-```
-Read SPEC.md
-```
+Read SPEC.md and identify all features where the Ruby SDK is not implemented.
-Create a prioritized list of missing features:
+Create a prioritized list:
 1. **High Priority** - Features implemented in BOTH TypeScript and Python SDKs
 2. **Medium Priority** - Features only in TypeScript SDK (Python also missing)
 3. **Low Priority** - TypeScript-only features that may be JS-specific
@@ -24,31 +15,23 @@ Use TodoWrite to track the features to implement.
 ## Step 2: Research Each Feature
-For each missing feature, gather complete context before planning:
+Gather complete context before planning:
 ### 2a. Official Documentation
-Use the `claude-code-guide` agent to understand the feature's intended behavior:
+Use the `claude-code-guide` agent to understand each feature's intended behavior:
 ```
 Task(subagent_type: "claude-code-guide", prompt: "How does [feature] work in the Claude Agent SDK? What are all the options, behaviors, and edge cases?")
 ```
-### 2b. TypeScript Implementation
-Read the TypeScript type definitions to understand the API surface:
-- `vendor/claude-agent-sdk-npm/sdk.d.ts`
-### 2c. Python Implementation (if available)
+### 2b. Reference Implementations
-If Python has the feature, read their implementation for patterns:
-- `vendor/claude-agent-sdk-python/src/claude_agent_sdk/types.py`
-- `vendor/claude-agent-sdk-python/src/claude_agent_sdk/_internal/`
+Read the TypeScript type definitions and changelog listed in SKILL.md to understand the API surface and when features were added. If Python has the feature, read their implementation for patterns.
 ## Step 3: Clarify Requirements
-Use AskUserQuestion to resolve any ambiguities:
+Use AskUserQuestion to resolve ambiguities:
 - Implementation approach choices
 - Ruby-specific design decisions
 - Whether certain features should be skipped (e.g., JS-specific)
@@ -56,15 +39,9 @@ Use AskUserQuestion to resolve any ambiguities:
 ## Step 4: Enter Plan Mode
-Enter plan mode to design the implementation:
-```
-EnterPlanMode
-```
-The plan should include:
+Enter plan mode to design the implementation. The plan should include:
 - Which files to create or modify
-- Data structures (use `Data.define` for immutable types)
+- Data structures
 - Public API design
 - Test coverage requirements
 - Any breaking changes or deprecations
@@ -80,26 +57,22 @@ After plan approval, implement each feature:
 5. Update RBS type signatures in `sig/` directory
 6. Write unit tests in `test/claude_agent/`
 7. Write integration tests in `test/integration/` for features that interact with CLI/API
-8. Update SPEC.md to mark feature as ✅
+8. Update SPEC.md to mark feature as complete
 ### Testing Requirements
 - **Unit tests** - For all new types, data structures, and internal logic
-- **Integration tests** - Required for anything that:
-  - Spawns the CLI subprocess
-  - Sends/receives messages via the control protocol
-  - Interacts with MCP servers
-  - Uses file checkpointing or session management
+- **Integration tests** - Required for anything that spawns the CLI subprocess, sends/receives messages via the control protocol, interacts with MCP servers, or uses file checkpointing/session management
 ## Step 6: Update Specification
-After implementing features, run `/spec:update` to refresh SPEC.md with the new implementation status.
+After implementing features, run `/spec update` to refresh SPEC.md with the new implementation status.
 ## Output
 Provide a summary of:
 - Features implemented
-- Any features skipped (with reasons)
+- Features skipped (with reasons)
 - Breaking changes introduced
 - Test coverage added
 - Remaining gaps (if any)

data/.claude/skills/spec/commands/update.md ADDED Viewed

@@ -0,0 +1,48 @@
+# Update SDK Specification
+Update SPEC.md to reflect the current feature parity between the TypeScript, Python, and Ruby Claude Agent SDKs.
+## Step 1: Update Reference SDKs
+Run `bin/update-reference-sdks` to ensure all reference SDKs are current.
+## Step 2: Research Official Documentation
+Use the `claude-code-guide` agent to check for new or updated SDK features:
+```
+Task(subagent_type: "claude-code-guide", prompt: "What are all the features and options in the Claude Agent SDK? Include configuration options, hooks, permissions, MCP support, and control protocol methods.")
+```
+This helps catch features documented but not yet in SDK source files.
+## Step 3: Analyze All Three SDKs
+Read and compare the key source files listed in SKILL.md. Pay special attention to:
+- TypeScript `sdk.d.ts` as the authoritative API surface
+- TypeScript `CHANGELOG.md` for recently added features
+- Python `types.py` for implementation patterns
+- All Ruby SDK files for current implementation status
+## Step 4: Update SPEC.md
+1. **Reference Versions** - Update TypeScript SDK version and Python SDK commit
+2. **Feature Tables** - Update all markers based on current implementations
+3. **New Features** - Add any new features found in the TypeScript SDK
+4. **Removed Features** - Remove any deprecated features
+## Guidelines
+- Check every field and option in each SDK
+- TypeScript sdk.d.ts is the authoritative reference
+- Preserve the existing table structure and markdown formatting
+- Always update the reference version info at the top
+- Note significant changes after updating
+## Output
+Provide a brief summary of:
+- SDK versions checked
+- New features added to the spec
+- Features removed from the spec
+- Notable gaps in the Ruby SDK

data/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [0.7.0] - 2026-01-31
+### Added
+- MCP tool annotations support (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, `title`) on `MCP::Tool` and `MCP.tool` convenience method (TypeScript SDK v0.2.27 parity)
+- README documentation for `UserMessageReplay`, `HookStartedMessage`, `HookProgressMessage`, `ToolUseSummaryMessage`, `FilesPersistedEvent` message types
+- README documentation for `mcp_reconnect` and `mcp_toggle` client methods
+- README documentation for MCP tool annotations
+### Changed
+- Updated SPEC.md to reference TypeScript SDK v0.2.27 and Python SDK v0.1.26
+## [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/CLAUDE.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # ClaudeAgent Ruby SDK
-Ruby SDK for building autonomous AI agents that interact with Claude Code CLI.
+Ruby SDK for building autonomous AI agents that interact with Claude Code CLI. See [README.md](README.md) for API usage, message types, configuration, and examples.
 ## Stack
@@ -32,16 +32,6 @@ bin/rbs-validate                   # Validate RBS signatures
 bin/release VERSION                # Release gem (e.g., bin/release 1.2.0)
 ```
-## Architecture
-| Component                   | Purpose                                            |
-|-----------------------------|----------------------------------------------------|
-| `Query`                     | One-shot stateless prompts                         |
-| `Client`                    | Multi-turn bidirectional conversations             |
-| `ControlProtocol`           | Handles handshake, hooks, permissions, MCP routing |
-| `Transport::Subprocess`     | Spawns CLI, manages stdin/stdout                   |
-| `MCP::Tool` / `MCP::Server` | Custom tool definitions                            |
 ## Conventions
 - **Immutable data types**: All messages and options use `Data.define`
@@ -50,25 +40,6 @@ bin/release VERSION                # Release gem (e.g., bin/release 1.2.0)
 - **Error hierarchy**: All errors inherit from `ClaudeAgent::Error` with context (exit code, stderr, etc.)
 - **Protocol flow**: Transport → ControlProtocol → MessageParser → typed message objects
-## Key Patterns
-```ruby
-# One-shot query
-result = ClaudeAgent.query("prompt", model: "sonnet")
-# Interactive client
-client = ClaudeAgent::Client.new(options)
-client.send_message("prompt") { |msg| handle(msg) }
-# Content blocks are polymorphic
-message.content.each do |block|
-  case block
-  when ClaudeAgent::TextBlock then ...
-  when ClaudeAgent::ToolUseBlock then ...
-  end
-end
-```
 ## Testing Notes
 - Unit tests in `test/claude_agent/` - run without Claude CLI

data/README.md CHANGED Viewed

@@ -5,7 +5,7 @@ Ruby gem for building AI-powered applications with the [Claude Agent SDK](https:
 ## Requirements
 - Ruby 3.2+ (uses `Data.define`)
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/getting-started) v2.0.0+
+- [Claude Code CLI](https://code.claude.com/docs/en/getting-started) v2.0.0+
 ## Installation
@@ -226,6 +226,19 @@ result.errors          # Array of error messages (if any)
 result.permission_denials  # Array of SDKPermissionDenial (if any)
 ```
+### UserMessageReplay
+Replayed user messages when resuming a session with existing history:
+```ruby
+replay.content             # Message content
+replay.uuid                # Message UUID
+replay.session_id          # Session identifier
+replay.parent_tool_use_id  # Parent tool use ID (if tool result)
+replay.replay?             # true if this is a replayed message
+replay.synthetic?          # true if this is a synthetic message
+```
 ### SystemMessage
 Internal system events:
@@ -289,6 +302,48 @@ hook_response.stderr     # Hook stderr
 hook_response.exit_code  # Exit code
 ```
+### HookStartedMessage
+Hook execution start notification:
+```ruby
+hook_started.hook_id    # Hook identifier
+hook_started.hook_name  # Hook name
+hook_started.hook_event # Hook event type
+```
+### HookProgressMessage
+Progress during hook execution:
+```ruby
+hook_progress.hook_id    # Hook identifier
+hook_progress.hook_name  # Hook name
+hook_progress.hook_event # Hook event type
+hook_progress.stdout     # Hook stdout so far
+hook_progress.stderr     # Hook stderr so far
+hook_progress.output     # Combined output
+```
+### ToolUseSummaryMessage
+Summary of tool use for collapsed display:
+```ruby
+summary.summary                  # Human-readable summary text
+summary.preceding_tool_use_ids   # Tool use IDs this summarizes
+```
+### FilesPersistedEvent
+Files persisted to storage during a session:
+```ruby
+persisted.files        # Array of successfully persisted file paths
+persisted.failed       # Array of files that failed to persist
+persisted.processed_at # Timestamp of persistence
+```
 ### AuthStatusMessage
 Authentication status during login:
@@ -413,6 +468,33 @@ schema: {
 }
 ```
+### Tool Annotations
+Annotate tools with hints about their behavior:
+```ruby
+tool = ClaudeAgent::MCP::Tool.new(
+  name: "search",
+  description: "Search the web",
+  schema: { query: String },
+  annotations: {
+    readOnlyHint: true,       # Tool only reads data, no side effects
+    destructiveHint: false,   # Tool does not destroy/delete data
+    idempotentHint: true,     # Repeated calls with same args have same effect
+    openWorldHint: true,      # Tool interacts with external systems
+    title: "Web Search"       # Human-readable display name
+  }
+) { |args| "Results for #{args['query']}" }
+# Or with the convenience method
+tool = ClaudeAgent::MCP.tool(
+  "search", "Search the web", { query: String },
+  annotations: { readOnlyHint: true, openWorldHint: true }
+) { |args| "Results" }
+```
+All annotation fields are optional hints — omit any that don't apply.
 ### Tool Return Values
 Tools can return various formats:
@@ -622,6 +704,13 @@ result = client.set_mcp_servers({
 })
 puts "Added: #{result.added}, Removed: #{result.removed}"
+# Reconnect a disconnected MCP server
+client.mcp_reconnect("my-server")
+# Enable or disable an MCP server
+client.mcp_toggle("my-server", enabled: false)  # Disable
+client.mcp_toggle("my-server", enabled: true)   # Re-enable
 # Query capabilities
 client.supported_commands.each { |cmd| puts "#{cmd.name}: #{cmd.description}" }
 client.supported_models.each { |model| puts "#{model.value}: #{model.display_name}" }

data/SPEC.md CHANGED Viewed

@@ -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.27 (npm package)
+- Python SDK: v0.1.26 from GitHub (commit 438ddf7)
 - Ruby SDK: This repository
-**Last Updated:** 2025-01-25
+**Last Updated:** 2026-01-31
 ---
@@ -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
@@ -423,7 +424,7 @@ Permission handling and updates.
 |------------------|:----------:|:------:|:----:|---------------------------|
 | `signal`         |     ✅      |   ✅    |  ✅   | Abort signal              |
 | `suggestions`    |     ✅      |   ✅    |  ✅   | Permission suggestions    |
-| `blockedPath`    |     ✅      |   ✅    |  ✅   | Blocked file path         |
+| `blockedPath`    |     ✅      |   ❌    |  ✅   | Blocked file path         |
 | `decisionReason` |     ✅      |   ❌    |  ✅   | Why permission triggered  |
 | `toolUseID`      |     ✅      |   ❌    |  ✅   | Tool call ID              |
 | `agentID`        |     ✅      |   ❌    |  ✅   | Subagent ID if applicable |
@@ -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
@@ -472,11 +474,12 @@ Model Context Protocol server support.
 ### SDK MCP Server
-| Feature              | TypeScript | Python |         Ruby         | Notes                  |
-|----------------------|:----------:|:------:|:--------------------:|------------------------|
-| `createSdkMcpServer` |     ✅      |   ❌    |          ✅           | Create SDK server      |
-| `tool()` helper      |     ✅      |   ❌    |          ✅           | Create tool definition |
-| Tool input schema    |  ✅ (Zod)   |   ❌    | ✅ (Hash/JSON Schema) | Schema definition      |
+| Feature              | TypeScript | Python |         Ruby         | Notes                    |
+|----------------------|:----------:|:------:|:--------------------:|--------------------------|
+| `createSdkMcpServer` |     ✅      |   ❌    |          ✅           | Create SDK server        |
+| `tool()` helper      |     ✅      |   ❌    |          ✅           | Create tool definition   |
+| Tool input schema    |  ✅ (Zod)   |   ❌    | ✅ (Hash/JSON Schema) | Schema definition        |
+| Tool annotations     |     ✅      |   ❌    |          ✅           | MCP tool hints (v0.2.27) |
 ---
@@ -595,41 +598,43 @@ 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    |
+| `reconnectMcpServer()`   |     ✅      |   ❌    |  ✅   | Reconnect MCP server   |
+| `toggleMcpServer()`      |     ✅      |   ❌    |  ✅   | Enable/disable MCP     |
+| `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 +664,37 @@ 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
+- v0.2.21 adds `reconnectMcpServer()` and `toggleMcpServer()` query methods
+- v0.2.21 adds `config`, `scope`, `tools` fields and `disabled` status to `McpServerStatus`
+- v0.2.27 adds optional `annotations` support to `tool()` helper for MCP tool hints
 ### 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.26)
+- 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`
+- v0.1.26 bumps bundled CLI to v2.1.27 (no new SDK features beyond PostToolUseFailure)
+- `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)
+- Added: MCP tool `annotations` support (new in TS v0.2.27)

data/lib/claude_agent/mcp/server.rb CHANGED Viewed

@@ -150,8 +150,8 @@ module ClaudeAgent
     #     "Hello, #{args['name']}!"
     #   end
     #
-    def self.tool(name, description, schema = {}, &handler)
-      Tool.new(name: name, description: description, schema: schema, &handler)
+    def self.tool(name, description, schema = {}, annotations: nil, &handler)
+      Tool.new(name: name, description: description, schema: schema, annotations: annotations, &handler)
     end
     # Convenience method to create a server

data/lib/claude_agent/mcp/tool.rb CHANGED Viewed

@@ -34,16 +34,18 @@ module ClaudeAgent
     #   end
     #
     class Tool
-      attr_reader :name, :description, :schema, :handler
+      attr_reader :name, :description, :schema, :annotations, :handler
       # @param name [String] Tool name (must be unique within server)
       # @param description [String] Description of what the tool does
       # @param schema [Hash] Input schema (simple Ruby types or JSON Schema)
+      # @param annotations [Hash, nil] MCP tool annotations (readOnlyHint, destructiveHint, etc.)
       # @param handler [Proc] Block to execute when tool is called
-      def initialize(name:, description:, schema: {}, &handler)
+      def initialize(name:, description:, schema: {}, annotations: nil, &handler)
         @name = name.to_s
         @description = description.to_s
         @schema = normalize_schema(schema)
+        @annotations = annotations
         @handler = handler || ->(args) { raise "No handler defined for tool #{name}" }
       end
@@ -60,11 +62,13 @@ module ClaudeAgent
       # Convert to MCP tool definition format
       # @return [Hash]
       def to_mcp_definition
-        {
+        definition = {
           name: @name,
           description: @description,
           inputSchema: @schema
         }
+        definition[:annotations] = @annotations if @annotations.present?
+        definition
       end
       private

data/lib/claude_agent/message_parser.rb CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

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

data/sig/claude_agent.rbs CHANGED Viewed

@@ -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
@@ -955,15 +967,16 @@ module ClaudeAgent
   # MCP module
   module MCP
-    def self.tool: (String name, String description, ?Hash[Symbol, untyped] schema) { (Hash[String, untyped]) -> untyped } -> Tool
+    def self.tool: (String name, String description, ?Hash[Symbol, untyped] schema, ?annotations: Hash[Symbol, untyped]?) { (Hash[String, untyped]) -> untyped } -> Tool
     def self.create_server: (name: String, ?tools: Array[Tool]) -> Server
     class Tool
       attr_reader name: String
       attr_reader description: String
       attr_reader schema: Hash[Symbol, untyped]
+      attr_reader annotations: Hash[Symbol, untyped]?
-      def initialize: (name: String, description: String, ?schema: Hash[Symbol, untyped]) { (Hash[String, untyped]) -> untyped } -> void
+      def initialize: (name: String, description: String, ?schema: Hash[Symbol, untyped], ?annotations: Hash[Symbol, untyped]?) { (Hash[String, untyped]) -> untyped } -> void
       def call: (Hash[String, untyped] arguments) -> Hash[Symbol, untyped]
       def to_mcp_definition: () -> Hash[Symbol, untyped]
     end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_agent
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Thomas Carr
@@ -34,14 +34,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".claude/commands/spec/complete.md"
-- ".claude/commands/spec/update.md"
 - ".claude/rules/conventions.md"
 - ".claude/rules/git.md"
 - ".claude/rules/pull-requests.md"
 - ".claude/rules/releases.md"
 - ".claude/rules/testing.md"
 - ".claude/settings.json"
+- ".claude/skills/spec/SKILL.md"
+- ".claude/skills/spec/commands/complete.md"
+- ".claude/skills/spec/commands/update.md"
 - CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt

data/.claude/commands/spec/update.md DELETED Viewed

@@ -1,95 +0,0 @@
----
-description: Update SPEC.md with latest feature parity comparison across TypeScript, Python, and Ruby SDKs
-allowed-tools: Bash, Read, Glob, Grep, Write, Edit, TodoWrite, Task
----
-# Update SDK Specification Document
-You are updating the SPEC.md file to reflect the current feature parity between the TypeScript, Python, and Ruby Claude Agent SDKs.
-## Step 1: Update Reference SDKs
-First, ensure the reference SDKs are up to date:
-```bash
-bin/update-reference-sdks
-```
-This clones/updates:
-- Python SDK from GitHub → `vendor/claude-agent-sdk-python`
-- TypeScript SDK from npm → `vendor/claude-agent-sdk-npm`
-## Step 2: Research Official Documentation
-Use the `claude-code-guide` agent to check for any new or updated SDK features:
-```
-Task(subagent_type: "claude-code-guide", prompt: "What are all the features and options in the Claude Agent SDK? Include configuration options, hooks, permissions, MCP support, and control protocol methods.")
-```
-This helps catch features that may be documented but not yet in the SDK source files.
-## Step 3: Analyze All Three SDKs
-Read and compare the following files:
-### TypeScript SDK (Primary Reference)
-- `vendor/claude-agent-sdk-npm/sdk.d.ts` - Complete API surface with all types
-### Python SDK
-- `vendor/claude-agent-sdk-python/src/claude_agent_sdk/types.py` - Type definitions
-### Ruby SDK (This Repository)
-Key files to check:
-- `lib/claude_agent/options.rb` - Configuration options
-- `lib/claude_agent/messages.rb` - Message types
-- `lib/claude_agent/content_blocks.rb` - Content block types
-- `lib/claude_agent/types.rb` - Additional types
-- `lib/claude_agent/hooks.rb` - Hook types
-- `lib/claude_agent/permissions.rb` - Permission types
-- `lib/claude_agent/control_protocol.rb` - Control protocol
-- `lib/claude_agent/sandbox_settings.rb` - Sandbox config
-- `lib/claude_agent/mcp/server.rb` - MCP server
-- `lib/claude_agent/mcp/tool.rb` - MCP tools
-- `lib/claude_agent/client.rb` - Client class
-- `lib/claude_agent/errors.rb` - Error types
-## Step 4: Update SPEC.md
-Update the existing SPEC.md file with:
-1. **Reference Versions** - Update TypeScript SDK version and Python SDK commit
-2. **Feature Tables** - Update all ✅/❌ markers based on current implementations
-3. **New Features** - Add any new features found in the TypeScript SDK
-4. **Removed Features** - Remove any deprecated features
-### Categories to Compare
-1. Options/Configuration
-2. Message Types
-3. Content Blocks
-4. Control Protocol
-5. Hooks
-6. Permissions
-7. MCP Support
-8. Sessions
-9. Subagents
-10. Sandbox Settings
-11. Error Handling
-12. Client API
-## Guidelines
-- **Be thorough** - Check every field and option in each SDK
-- **TypeScript is authoritative** - The TypeScript sdk.d.ts is the most complete reference
-- **Preserve format** - Keep the existing table structure and markdown formatting
-- **Update versions** - Always update the reference version info at the top
-- **Note changes** - If significant changes are found, mention them after updating
-## Output
-After updating SPEC.md, provide a brief summary of:
-- SDK versions checked
-- Any new features added to the spec
-- Any features removed from the spec
-- Any notable gaps in the Ruby SDK