claude_agent 0.7.16 → 0.7.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df8d1374efdac7201f83dd2afc3b0042c44162b5ba58c650305b58c63c60397e
-  data.tar.gz: 957bd07189e6d3cf46771367088e9897ce993d2d2944d6108afd1352e2f19f01
+  metadata.gz: 799129d416a271a9271c718286c10671db76af9c47d79e5c8c01c48601a64f5b
+  data.tar.gz: 9697cc7268eefc734e3d89bf1e03ccabfc97f7bfa827500bd04332990cfb168b
 SHA512:
-  metadata.gz: 8dc4b9ec494ac9337b7860f4250361366184f6ca983c3b5f9754ac5050966708f0d220a6b5975dff49ab4badd47e6f24b3104467b2a9e511cc3e95114f3cb5fc
-  data.tar.gz: fe0357e27da9036fe90a740fecaa64eb5ce95736e7c5566cef0e746080eb014e9a55adb17372b34520d1985fa5d838806cc57e395170c8e2e1766a95563c0336
+  metadata.gz: 1eb51e6dfad24b7b904e128b226e45aa1f30354343f44b1ffe99a4b3d211bb8359b58b54c8ad362288b563803cb3393d2a836add9d2831e37e94442b70e72a7e
+  data.tar.gz: 83a8fa50917c82011b54192d0d2d69d7473b4868d343fe569ceda3149de79e69c590511c188660eefbbd1658071af6b08c40221ebe80e741d23bb2c5b6a52469

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.17] - 2026-03-17
+
+### Added
+- `APIRetryMessage` system message type with `attempt`, `max_retries`, `retry_delay_ms`, `error_status`, and `error` fields (TypeScript SDK v0.2.77 parity)
+- `title` and `display_name` fields on `ToolPermissionContext` for richer permission prompt context (TypeScript SDK v0.2.77 parity)
+- `allow_read` and `allow_managed_read_paths_only` fields on `SandboxFilesystemConfig` for re-allowing reads within deny regions (TypeScript SDK v0.2.77 parity)
+
 ## [0.7.16] - 2026-03-15
 
 ## [0.7.15] - 2026-03-15

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.76 (npm package)
-- Python SDK: from GitHub (commit 302ceb6)
+- TypeScript SDK: v0.2.77 (npm package)
+- Python SDK: from GitHub (commit 971994c)
 - Ruby SDK: This repository
 
-**Last Updated:** 2026-03-15
+**Last Updated:** 2026-03-17
 
 ---
 
@@ -116,9 +116,20 @@ Messages exchanged between SDK and CLI.
 | `FilesPersistedEvent`        |     ✅      |   ❌    |  ✅   | File persistence confirmation      |
 | `ElicitationCompleteMessage` |     ✅      |   ❌    |  ✅   | MCP elicitation completed          |
 | `LocalCommandOutputMessage`  |     ✅      |   ❌    |  ✅   | Local command output               |
+| `APIRetryMessage`            |     ✅      |   ❌    |  ✅   | API retry notification (v0.2.77)   |
 
 ### Message Fields
 
+#### APIRetryMessage
+
+| Field             | TypeScript | Python | Ruby | Notes                                    |
+|-------------------|:----------:|:------:|:----:|------------------------------------------|
+| `attempt`         |     ✅      |   ❌    |  ✅   | Current retry attempt number             |
+| `max_retries`     |     ✅      |   ❌    |  ✅   | Maximum retry count                      |
+| `retry_delay_ms`  |     ✅      |   ❌    |  ✅   | Delay before retry in milliseconds       |
+| `error_status`    |     ✅      |   ❌    |  ✅   | HTTP status code (null for conn errors)  |
+| `error`           |     ✅      |   ❌    |  ✅   | Error type (AssistantMessageError)       |
+
 #### ResultMessage
 
 | Field                | TypeScript | Python | Ruby | Notes                    |
@@ -666,6 +677,8 @@ Permission handling and updates.
 | `toolUseID`      |     ✅      |   ❌    |  ✅   | Tool call ID                                     |
 | `agentID`        |     ✅      |   ❌    |  ✅   | Subagent ID if applicable                        |
 | `description`    |     ✅      |   ❌    |  ✅   | Human-readable tool description (v0.2.75)        |
+| `title`          |     ✅      |   ❌    |  ✅   | Full permission prompt sentence (v0.2.77)        |
+| `displayName`    |     ✅      |   ❌    |  ✅   | Short noun phrase for tool action (v0.2.77)      |
 
 ---
 
@@ -799,15 +812,15 @@ Session management and resumption.
 
 | Field            | TypeScript | Python | Ruby | Notes                                          |
 |------------------|:----------:|:------:|:----:|------------------------------------------------|
-| `dir`            |     ✅      |   ❌    |  ❌   | Project directory                              |
-| `upToMessageId`  |     ✅      |   ❌    |  ❌   | Slice transcript up to this UUID (inclusive)   |
-| `title`          |     ✅      |   ❌    |  ❌   | Custom title for the fork                      |
+| `dir`            |     ✅      |   ❌    |  ✅   | Project directory                              |
+| `upToMessageId`  |     ✅      |   ❌    |  ✅   | Slice transcript up to this UUID (inclusive)   |
+| `title`          |     ✅      |   ❌    |  ✅   | Custom title for the fork                      |
 
 #### ForkSessionResult
 
 | Field       | TypeScript | Python | Ruby | Notes                          |
 |-------------|:----------:|:------:|:----:|--------------------------------|
-| `sessionId` |     ✅      |   ❌    |  ❌   | New forked session UUID        |
+| `sessionId` |     ✅      |   ❌    |  ✅   | New forked session UUID        |
 
 ### V2 Session API (Unstable)
 
@@ -833,9 +846,10 @@ Custom subagent definitions.
 | `tools`                               |     ✅      |   ✅    |  ✅   | Allowed tools                              |
 | `disallowedTools`                     |     ✅      |   ❌    |  ✅   | Blocked tools                              |
 | `model`                               |     ✅      |   ✅    |  ✅   | Model override (sonnet/opus/haiku/inherit) |
-| `mcpServers`                          |     ✅      |   ❌    |  ✅   | Agent-specific MCP servers                 |
+| `mcpServers`                          |     ✅      |   ✅    |  ✅   | Agent-specific MCP servers                 |
 | `criticalSystemReminder_EXPERIMENTAL` |     ✅      |   ❌    |  ✅   | Critical reminder (experimental)           |
-| `skills`                              |     ✅      |   ❌    |  ✅   | Skills to preload into agent context       |
+| `skills`                              |     ✅      |   ✅    |  ✅   | Skills to preload into agent context       |
+| `memory`                              |     ❌      |   ✅    |  ❌   | Memory scope for agent (Python-only)       |
 | `maxTurns`                            |     ✅      |   ❌    |  ✅   | Max agentic turns before stopping          |
 
 ---
@@ -861,11 +875,13 @@ Sandbox configuration for command execution isolation.
 
 ### SandboxFilesystemConfig
 
-| Field        | TypeScript | Python | Ruby |
-|--------------|:----------:|:------:|:----:|
-| `allowWrite` |     ✅      |   ❌    |  ✅   |
-| `denyWrite`  |     ✅      |   ❌    |  ✅   |
-| `denyRead`   |     ✅      |   ❌    |  ✅   |
+| Field                       | TypeScript | Python | Ruby |
+|-----------------------------|:----------:|:------:|:----:|
+| `allowWrite`                |     ✅      |   ❌    |  ✅   |
+| `denyWrite`                 |     ✅      |   ❌    |  ✅   |
+| `denyRead`                  |     ✅      |   ❌    |  ✅   |
+| `allowRead`                 |     ✅      |   ❌    |  ✅   |
+| `allowManagedReadPathsOnly` |     ✅      |   ❌    |  ✅   |
 
 ### SandboxNetworkConfig
 
@@ -1017,6 +1033,7 @@ Public API surface for SDK clients.
 - v0.2.74: Added `renameSession()` for renaming session files
 - v0.2.75: Added `tag`/`createdAt` fields on `SDKSessionInfo`; `getSessionInfo()` for single-session lookup; `offset` on `listSessions` for pagination; `tagSession()` for tagging sessions; `supportsAutoMode` in `ModelInfo`; `description` on `SDKControlPermissionRequest`; `prompt` on `SDKTaskStartedMessage`; `fast_mode_state` on `SDKControlInitializeResponse`; `queued_to_running` status on `AgentToolOutput`
 - v0.2.76: Added `forkSession(sessionId, opts?)` for branching conversations from a point; `cancel_async_message` control subtype to drop queued user messages; `PostCompact` hook event with `compact_summary` field; `get_settings` control request for reading effective merged settings; `planFilePath` field on `ExitPlanMode` tool input
+- v0.2.77: Added `SDKAPIRetryMessage` (system subtype `api_retry`) exposing attempt count, max retries, delay, and error status for transient API error retries; added `title` and `displayName` fields on `SDKControlPermissionRequest`/`CanUseTool` options; added `allowRead` and `allowManagedReadPathsOnly` on `SandboxFilesystemConfig`
 - Includes `Elicitation`/`ElicitationResult` hook events, `onElicitation` option, `ElicitationCompleteMessage`, `LocalCommandOutputMessage`, `FastModeState` (undocumented in changelog, present in types)
 
 ### Python SDK
@@ -1045,10 +1062,11 @@ Public API surface for SDK clients.
 - v0.1.48: Fixed fine-grained tool streaming regression
 - Added `RateLimitEvent` message type with `RateLimitInfo`
 - Added `rename_session()` and `tag_session()` session management functions
-- Missing: `onElicitation`, `Elicitation`/`ElicitationResult` hooks, `ElicitationCompleteMessage`, `LocalCommandOutputMessage`, `FastModeState`, `InstructionsLoaded` hook, `agentProgressSummaries`, `getSessionInfo()`, `forkSession()`, `PostCompact` hook, `cancel_async_message`, `get_settings`
+- `AgentDefinition` now has `skills`, `mcpServers`, and `memory` (Python-only) fields
+- Missing: `onElicitation`, `Elicitation`/`ElicitationResult` hooks, `ElicitationCompleteMessage`, `LocalCommandOutputMessage`, `FastModeState`, `InstructionsLoaded` hook, `agentProgressSummaries`, `getSessionInfo()`, `forkSession()`, `PostCompact` hook, `cancel_async_message`, `get_settings`, `APIRetryMessage`
 
 ### Ruby SDK (This Repository)
-- Feature parity with TypeScript SDK v0.2.76
+- Feature parity with TypeScript SDK v0.2.77
 - Ruby-idiomatic patterns (Data.define, snake_case)
 - Complete control protocol, hook, and V2 Session API support
 - Dedicated Client class for multi-turn conversations

data/lib/claude_agent/control_protocol/request_handling.rb

@@ -64,6 +64,8 @@ module ClaudeAgent
           tool_use_id: request["tool_use_id"],
           agent_id: request["agent_id"],
           description: request["description"],
+          title: request["title"],
+          display_name: request["display_name"],
           signal: @abort_signal,
           request: perm_request
         )

data/lib/claude_agent/message_parser.rb

@@ -86,6 +86,7 @@ module ClaudeAgent
     register "system:task_progress",            :parse_task_progress_message
     register "system:elicitation_complete",    :parse_elicitation_complete_message
     register "system:local_command_output",    :parse_local_command_output_message
+    register "system:api_retry",              :parse_api_retry_message
 
     private
 
@@ -421,5 +422,17 @@ module ClaudeAgent
         suggestion: raw[:suggestion] || ""
       )
     end
+
+    def parse_api_retry_message(raw)
+      APIRetryMessage.new(
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        attempt: raw[:attempt] || 0,
+        max_retries: raw[:max_retries] || 0,
+        retry_delay_ms: raw[:retry_delay_ms] || 0,
+        error_status: raw[:error_status],
+        error: raw[:error]
+      )
+    end
   end
 end

data/lib/claude_agent/messages/system.rb

@@ -55,6 +55,33 @@ module ClaudeAgent
   #     status: "compacting"
   #   )
   #
+  # API retry message (TypeScript SDK v0.2.77 parity)
+  #
+  # Emitted when an API request fails with a retryable error and will be
+  # retried after a delay. Exposes attempt count, max retries, delay, and
+  # error status for observability.
+  #
+  # @example
+  #   msg = APIRetryMessage.new(
+  #     uuid: "msg-123",
+  #     session_id: "session-abc",
+  #     attempt: 1,
+  #     max_retries: 3,
+  #     retry_delay_ms: 5000,
+  #     error_status: 529,
+  #     error: "rate_limit"
+  #   )
+  #
+  APIRetryMessage = Data.define(:uuid, :session_id, :attempt, :max_retries, :retry_delay_ms, :error_status, :error) do
+    def initialize(uuid: "", session_id: "", attempt: 0, max_retries: 0, retry_delay_ms: 0, error_status: nil, error: nil)
+      super
+    end
+
+    def type
+      :api_retry
+    end
+  end
+
   StatusMessage = Data.define(:uuid, :session_id, :status, :permission_mode) do
     def initialize(uuid:, session_id:, status:, permission_mode: nil)
       super

data/lib/claude_agent/messages.rb

@@ -34,6 +34,7 @@ module ClaudeAgent
     PromptSuggestionMessage,
     ElicitationCompleteMessage,
     LocalCommandOutputMessage,
+    APIRetryMessage,
     GenericMessage
   ].freeze
 end

data/lib/claude_agent/permissions.rb

@@ -147,6 +147,8 @@ module ClaudeAgent
   #     decision_reason: "Path outside allowed directories",
   #     tool_use_id: "tool_123",
   #     agent_id: "agent_456",
+  #     title: "Claude wants to read /etc/passwd",
+  #     display_name: "Read file",
   #     signal: abort_signal
   #   )
   #
@@ -158,6 +160,8 @@ module ClaudeAgent
     :agent_id,
     :signal,
     :description,
+    :title,
+    :display_name,
     :request
   ) do
     def initialize(
@@ -168,6 +172,8 @@ module ClaudeAgent
       agent_id: nil,
       signal: nil,
       description: nil,
+      title: nil,
+      display_name: nil,
       request: nil
     )
       super

data/lib/claude_agent/sandbox_settings.rb

@@ -85,17 +85,19 @@ module ClaudeAgent
     end
   end
 
-  # Filesystem-specific configuration for sandbox mode (TypeScript SDK v0.2.49 parity)
+  # Filesystem-specific configuration for sandbox mode (TypeScript SDK v0.2.77 parity)
   #
   # @example
   #   filesystem = SandboxFilesystemConfig.new(
   #     allow_write: ["/tmp/*"],
   #     deny_write: ["/etc/*"],
-  #     deny_read: ["/secrets/*"]
+  #     deny_read: ["/secrets/*"],
+  #     allow_read: ["/secrets/public/*"],
+  #     allow_managed_read_paths_only: false
   #   )
   #
-  SandboxFilesystemConfig = Data.define(:allow_write, :deny_write, :deny_read) do
-    def initialize(allow_write: [], deny_write: [], deny_read: [])
+  SandboxFilesystemConfig = Data.define(:allow_write, :deny_write, :deny_read, :allow_read, :allow_managed_read_paths_only) do
+    def initialize(allow_write: [], deny_write: [], deny_read: [], allow_read: [], allow_managed_read_paths_only: false)
       super
     end
 
@@ -104,6 +106,8 @@ module ClaudeAgent
       result[:allowWrite] = allow_write unless allow_write.empty?
       result[:denyWrite] = deny_write unless deny_write.empty?
       result[:denyRead] = deny_read unless deny_read.empty?
+      result[:allowRead] = allow_read unless allow_read.empty?
+      result[:allowManagedReadPathsOnly] = allow_managed_read_paths_only if allow_managed_read_paths_only
       result
     end
   end

data/lib/claude_agent/version.rb

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

data/sig/claude_agent.rbs

@@ -314,8 +314,10 @@ module ClaudeAgent
     attr_reader allow_write: Array[String]
     attr_reader deny_write: Array[String]
     attr_reader deny_read: Array[String]
+    attr_reader allow_read: Array[String]
+    attr_reader allow_managed_read_paths_only: bool
 
-    def initialize: (?allow_write: Array[String], ?deny_write: Array[String], ?deny_read: Array[String]) -> void
+    def initialize: (?allow_write: Array[String], ?deny_write: Array[String], ?deny_read: Array[String], ?allow_read: Array[String], ?allow_managed_read_paths_only: bool) -> void
     def to_h: () -> Hash[Symbol, untyped]
   end
 
@@ -573,6 +575,20 @@ module ClaudeAgent
     def type: () -> :local_command_output
   end
 
+  # API retry message (TypeScript SDK v0.2.77 parity)
+  class APIRetryMessage
+    attr_reader uuid: String
+    attr_reader session_id: String
+    attr_reader attempt: Integer
+    attr_reader max_retries: Integer
+    attr_reader retry_delay_ms: Integer
+    attr_reader error_status: Integer?
+    attr_reader error: String?
+
+    def initialize: (?uuid: String, ?session_id: String, ?attempt: Integer, ?max_retries: Integer, ?retry_delay_ms: Integer, ?error_status: Integer?, ?error: String?) -> void
+    def type: () -> :api_retry
+  end
+
   class GenericMessage
     attr_reader message_type: String?
     attr_reader raw: Hash[Symbol, untyped]
@@ -584,7 +600,7 @@ module ClaudeAgent
   end
 
   # Message types
-  type message = UserMessage | UserMessageReplay | AssistantMessage | SystemMessage | ResultMessage | StreamEvent | CompactBoundaryMessage | StatusMessage | ToolProgressMessage | HookResponseMessage | AuthStatusMessage | TaskNotificationMessage | HookStartedMessage | HookProgressMessage | ToolUseSummaryMessage | FilesPersistedEvent | TaskStartedMessage | TaskProgressMessage | RateLimitEvent | PromptSuggestionMessage | ElicitationCompleteMessage | LocalCommandOutputMessage | GenericMessage
+  type message = UserMessage | UserMessageReplay | AssistantMessage | SystemMessage | ResultMessage | StreamEvent | CompactBoundaryMessage | StatusMessage | ToolProgressMessage | HookResponseMessage | AuthStatusMessage | TaskNotificationMessage | HookStartedMessage | HookProgressMessage | ToolUseSummaryMessage | FilesPersistedEvent | TaskStartedMessage | TaskProgressMessage | RateLimitEvent | PromptSuggestionMessage | ElicitationCompleteMessage | LocalCommandOutputMessage | APIRetryMessage | GenericMessage
 
   MESSAGE_TYPES: Array[Class]
 
@@ -1161,9 +1177,11 @@ module ClaudeAgent
     attr_reader agent_id: String?
     attr_reader signal: AbortSignal?
     attr_reader description: String?
+    attr_reader title: String?
+    attr_reader display_name: String?
     attr_reader request: PermissionRequest?
 
-    def initialize: (?permission_suggestions: untyped, ?blocked_path: String?, ?decision_reason: String?, ?tool_use_id: String?, ?agent_id: String?, ?signal: AbortSignal?, ?description: String?, ?request: PermissionRequest?) -> void
+    def initialize: (?permission_suggestions: untyped, ?blocked_path: String?, ?decision_reason: String?, ?tool_use_id: String?, ?agent_id: String?, ?signal: AbortSignal?, ?description: String?, ?title: String?, ?display_name: String?, ?request: PermissionRequest?) -> void
   end
 
   # Deferred permission request resolved from any thread

metadata

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