claude_agent 0.7.16 → 0.7.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df8d1374efdac7201f83dd2afc3b0042c44162b5ba58c650305b58c63c60397e
-  data.tar.gz: 957bd07189e6d3cf46771367088e9897ce993d2d2944d6108afd1352e2f19f01
+  metadata.gz: 564803b88efd1e1690c1d44078c2dc9ddf10e8d74fc48cbacee1705843a50ef8
+  data.tar.gz: 03e53177abed5def635fad5152f7ec9046e9d16280df70200b9f1b53d8bd647b
 SHA512:
-  metadata.gz: 8dc4b9ec494ac9337b7860f4250361366184f6ca983c3b5f9754ac5050966708f0d220a6b5975dff49ab4badd47e6f24b3104467b2a9e511cc3e95114f3cb5fc
-  data.tar.gz: fe0357e27da9036fe90a740fecaa64eb5ce95736e7c5566cef0e746080eb014e9a55adb17372b34520d1985fa5d838806cc57e395170c8e2e1766a95563c0336
+  metadata.gz: a376e0f0ae1f9089500495998a00859c309c24c9256705df1c0310990534881a3faa3b469c1787dbb48ebb30714e40da3444ac8a5229e04c1de85a25332df7db
+  data.tar.gz: 35ae9feec317af0aac43cb5557d756442138889e0ada2eeff55b5536843f6a47120a1bc841575ca137734a5335266707c8766b0baf26750cb1031fcba256ab60

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.18] - 2026-03-20
+
+### Added
+- `StopFailure` hook event with `StopFailureInput` type (`error`, `error_details`, `last_assistant_message` fields) for handling API error-triggered stops (TypeScript SDK v0.2.80 parity)
+- `on_stop_failure` DSL method on `HookRegistry` for the new event
+
+## [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.80 (npm package)
+- Python SDK: from GitHub (commit 13e119a)
 - Ruby SDK: This repository
 
-**Last Updated:** 2026-03-15
+**Last Updated:** 2026-03-20
 
 ---
 
@@ -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                    |
@@ -425,6 +436,7 @@ Event hooks for intercepting and modifying SDK behavior.
 | `SessionStart`       |     ✅      |   ✅    |  ✅   | Session starts                    |
 | `SessionEnd`         |     ✅      |   ❌    |  ✅   | Session ends                      |
 | `Stop`               |     ✅      |   ✅    |  ✅   | Agent stops                       |
+| `StopFailure`        |     ✅      |   ❌    |  ✅   | Agent stops due to API error      |
 | `SubagentStart`      |     ✅      |   ✅    |  ✅   | Subagent starts (Py v0.1.29)      |
 | `SubagentStop`       |     ✅      |   ✅    |  ✅   | Subagent stops                    |
 | `PreCompact`         |     ✅      |   ✅    |  ✅   | Before compaction                 |
@@ -452,6 +464,7 @@ Event hooks for intercepting and modifying SDK behavior.
 | `SessionStartHookInput`       |     ✅      |   ❌    |  ✅   |
 | `SessionEndHookInput`         |     ✅      |   ❌    |  ✅   |
 | `StopHookInput`               |     ✅      |   ✅    |  ✅   |
+| `StopFailureHookInput`        |     ✅      |   ❌    |  ✅   |
 | `SubagentStartHookInput`      |     ✅      |   ✅    |  ✅   |
 | `SubagentStopHookInput`       |     ✅      |   ✅    |  ✅   |
 | `PreCompactHookInput`         |     ✅      |   ✅    |  ✅   |
@@ -485,6 +498,14 @@ Event hooks for intercepting and modifying SDK behavior.
 | `stop_hook_active`       |     ✅      |   ✅    |  ✅   | Whether stop hook is active            |
 | `last_assistant_message` |     ✅      |   ❌    |  ✅   | Last assistant message text (v0.2.51+) |
 
+#### StopFailureHookInput Fields
+
+| Field                    | TypeScript | Python | Ruby | Notes                                  |
+|--------------------------|:----------:|:------:|:----:|----------------------------------------|
+| `error`                  |     ✅      |   ❌    |  ✅   | API error type (AssistantMessageError) |
+| `error_details`          |     ✅      |   ❌    |  ✅   | Additional error details               |
+| `last_assistant_message` |     ✅      |   ❌    |  ✅   | Last assistant message text            |
+
 #### SubagentStopHookInput Fields
 
 | Field                    | TypeScript | Python | Ruby | Notes                                  |
@@ -666,6 +687,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)      |
 
 ---
 
@@ -748,7 +771,7 @@ Session management and resumption.
 |------------------------|:----------:|:------:|:----:|--------------------------------------------------|
 | `listSessions()`       |     ✅      |   ✅    |  ✅   | List past sessions with metadata (v0.2.53)       |
 | `getSessionMessages()` |     ✅      |   ✅    |  ✅   | Read session transcript messages (v0.2.59)       |
-| `getSessionInfo()`     |     ✅      |   ❌    |  ✅   | Get single session metadata (v0.2.75)            |
+| `getSessionInfo()`     |     ✅      |   ✅    |  ✅   | Get single session metadata (v0.2.75)            |
 | `renameSession()`      |     ✅      |   ✅    |  ✅   | Rename a session (v0.2.74)                       |
 | `tagSession()`         |     ✅      |   ✅    |  ✅   | Tag a session (v0.2.75)                          |
 | `forkSession()`        |     ✅      |   ❌    |  ✅   | Fork/branch a session (v0.2.76)                  |
@@ -792,22 +815,22 @@ Session management and resumption.
 | `firstPrompt`  |     ✅      |   ✅    |  ✅   | First meaningful user prompt        |
 | `gitBranch`    |     ✅      |   ✅    |  ✅   | Git branch at end of session        |
 | `cwd`          |     ✅      |   ✅    |  ✅   | Working directory for session       |
-| `tag`          |     ✅      |   ❌    |  ✅   | User-set tag (v0.2.75)              |
-| `createdAt`    |     ✅      |   ❌    |  ✅   | Creation time in ms (v0.2.75)       |
+| `tag`          |     ✅      |   ✅    |  ✅   | User-set tag (v0.2.75)              |
+| `createdAt`    |     ✅      |   ✅    |  ✅   | Creation time in ms (v0.2.75)       |
 
 #### ForkSessionOptions
 
 | 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)
 
@@ -826,17 +849,18 @@ Custom subagent definitions.
 
 ### AgentDefinition
 
-| Field                                 | TypeScript | Python | Ruby | Notes                                      |
-|---------------------------------------|:----------:|:------:|:----:|--------------------------------------------|
-| `description`                         |     ✅      |   ✅    |  ✅   | When to use agent                          |
-| `prompt`                              |     ✅      |   ✅    |  ✅   | Agent system prompt                        |
-| `tools`                               |     ✅      |   ✅    |  ✅   | Allowed tools                              |
-| `disallowedTools`                     |     ✅      |   ❌    |  ✅   | Blocked tools                              |
-| `model`                               |     ✅      |   ✅    |  ✅   | Model override (sonnet/opus/haiku/inherit) |
-| `mcpServers`                          |     ✅      |   ❌    |  ✅   | Agent-specific MCP servers                 |
-| `criticalSystemReminder_EXPERIMENTAL` |     ✅      |   ❌    |  ✅   | Critical reminder (experimental)           |
-| `skills`                              |     ✅      |   ❌    |  ✅   | Skills to preload into agent context       |
-| `maxTurns`                            |     ✅      |   ❌    |  ✅   | Max agentic turns before stopping          |
+| Field                                 | TypeScript | Python | Ruby | Notes                                        |
+|---------------------------------------|:----------:|:------:|:----:|----------------------------------------------|
+| `description`                         |     ✅      |   ✅    |  ✅   | When to use agent                            |
+| `prompt`                              |     ✅      |   ✅    |  ✅   | Agent system prompt                          |
+| `tools`                               |     ✅      |   ✅    |  ✅   | Allowed tools                                |
+| `disallowedTools`                     |     ✅      |   ❌    |  ✅   | Blocked tools                                |
+| `model`                               |     ✅      |   ✅    |  ✅   | Model override (sonnet/opus/haiku/inherit)   |
+| `mcpServers`                          |     ✅      |   ✅    |  ✅   | Agent-specific MCP servers                   |
+| `criticalSystemReminder_EXPERIMENTAL` |     ✅      |   ❌    |  ✅   | Critical reminder (experimental)             |
+| `skills`                              |     ✅      |   ✅    |  ✅   | Skills to preload into agent context         |
+| `memory`                              |     ❌      |   ✅    |  ❌   | Memory scope for agent (Python-only v0.1.49) |
+| `maxTurns`                            |     ✅      |   ❌    |  ✅   | Max agentic turns before stopping            |
 
 ---
 
@@ -861,11 +885,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
 
@@ -922,7 +948,7 @@ Public API surface for SDK clients.
 |------------------------|:----------:|:------:|:----:|--------------------------------------------|
 | `listSessions()`       |     ✅      |   ✅    |  ✅   | List past sessions with metadata (v0.2.53) |
 | `getSessionMessages()` |     ✅      |   ✅    |  ✅   | Read session transcript (v0.2.59)          |
-| `getSessionInfo()`     |     ✅      |   ❌    |  ✅   | Get single session metadata (v0.2.75)      |
+| `getSessionInfo()`     |     ✅      |   ✅    |  ✅   | Get single session metadata (v0.2.75)      |
 | `renameSession()`      |     ✅      |   ✅    |  ✅   | Rename a session (v0.2.74)                 |
 | `tagSession()`         |     ✅      |   ✅    |  ✅   | Tag a session (v0.2.75)                    |
 | `forkSession()`        |     ✅      |   ❌    |  ✅   | Fork/branch a session (v0.2.76)            |
@@ -991,64 +1017,22 @@ Public API surface for SDK clients.
 ## Notes
 
 ### TypeScript SDK
-- Primary reference for API surface (most comprehensive)
-- Source is bundled/minified, but `sdk.d.ts` provides complete type definitions
-- Includes unstable V2 session API
+- Primary reference for API surface — `sdk.d.ts` provides complete type definitions
 - `executable`/`executableArgs` are JS-specific (`node`/`bun`/`deno`)
 - Does NOT have `user`, `init`/`initOnly`/`maintenance` as typed Options (use `extraArgs` or `settingSources`)
-- `ApiKeySource` includes `'oauth'`
-- v0.2.45: Added `TaskStartedMessage`, `RateLimitEvent` message types
-- v0.2.47: Added `promptSuggestions` option and `PromptSuggestionMessage`
-- 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`, `StopHookInput.last_assistant_message`, `SubagentStopHookInput.last_assistant_message`
-- 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.58: CLI parity updates (no new SDK-facing features)
-- v0.2.59: Added `getSessionMessages()` for reading session transcript history with pagination (limit/offset)
-- v0.2.61 – v0.2.62: CLI parity updates (no new SDK-facing features)
-- v0.2.63: Added `supportedAgents()` method on Query, fixed `pathToClaudeCodeExecutable` PATH resolution
-- v0.2.64 – v0.2.68: CLI parity updates (no new SDK-facing features)
-- v0.2.69: Added `toolConfig` option (askUserQuestion preview format), `supportsFastMode` in ModelInfo, `agent_id`/`agent_type` on BaseHookInput, `InstructionsLoaded` hook event
-- v0.2.70: Made `AgentToolInput.subagent_type` optional (defaults to general-purpose), fixed HTTP MCP servers
-- v0.2.71: CLI parity update; `settings` now a typed Option (string path or `Settings` object)
-- v0.2.72: Added `agentProgressSummaries` option for periodic AI-generated progress summaries
-- v0.2.73: Fixed `options.env` being overridden by `~/.claude/settings.json`
-- 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
-- Includes `Elicitation`/`ElicitationResult` hook events, `onElicitation` option, `ElicitationCompleteMessage`, `LocalCommandOutputMessage`, `FastModeState` (undocumented in changelog, present in types)
+- Some features present in types but undocumented in changelog: `StopFailure` hook, `Elicitation`/`ElicitationResult` hooks, `onElicitation` option, `ElicitationCompleteMessage`, `LocalCommandOutputMessage`, `FastModeState`
 
 ### Python SDK
-- Full source available with `Transport` abstract class
-- Partial control protocol: query and client support interrupt, setPermissionMode, setModel, rewindFiles, mcpStatus, reconnectMcpServer, toggleMcpServer, stopTask
-- Has `CLINotFoundError`, `CLIConnectionError`, `ProcessError`, `CLIJSONDecodeError`, `MessageParseError` error types
-- Has `TaskStartedMessage`, `TaskProgressMessage`, `TaskNotificationMessage` typed message classes (v0.1.46+)
-- Has `stop_reason` field on ResultMessage (v0.1.46+)
-- Has `SDKSessionInfo`, `SessionMessage` types with `list_sessions()`/`get_session_messages()` functions (v0.1.46+)
-- Has `McpServerStatus` with all fields (name, status, serverInfo, error, config, scope, tools) (v0.1.46+)
-- Has `agent_id`/`agent_type` on tool-lifecycle hook inputs (v0.1.46+)
-- Has `add_mcp_server()`/`remove_mcp_server()` client methods for runtime MCP management (v0.1.46+)
-- Has `include_worktrees` parameter on `list_sessions()` (v0.1.46+)
-- Missing hooks: SessionEnd, Setup, TeammateIdle, TaskCompleted, Elicitation, ElicitationResult, ConfigChange, WorktreeCreate, WorktreeRemove, InstructionsLoaded
-- Missing permission modes: `dontAsk`
-- Missing options: `allowDangerouslySkipPermissions`, `persistSession`, `resumeSessionAt`, `sessionId`, `strictMcpConfig`, `init`/`initOnly`/`maintenance`, `debug`/`debugFile`, `promptSuggestions`, `onElicitation`, `toolConfig`, `agentProgressSummaries`, `agent` (main thread agent)
-- `ToolPermissionContext` missing `blockedPath`, `decisionReason`, `toolUseID`, `agentID`, `description`
-- Has `rename_session()`/`tag_session()` for session mutation
-- Has `RateLimitEvent`/`RateLimitInfo` types with full field coverage
-- Has SDK MCP server support with `tool()` helper and annotations
-- Missing `getSessionInfo()`, `offset` on `list_sessions`, `tag`/`createdAt` on `SDKSessionInfo`
-- Added `thinking` config and `effort` option in v0.1.36
-- 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.45 – v0.1.48: Major catch-up with TypeScript SDK (task messages, session APIs, MCP control methods, stop_reason)
-- 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`
+- Partial control protocol: supports interrupt, setPermissionMode, setModel, rewindFiles, mcpStatus, reconnectMcp, toggleMcp, stopTask
+- Has `add_mcp_server()`/`remove_mcp_server()` client methods (not in TypeScript)
+- `AgentDefinition.memory` is Python-only (not in TypeScript or Ruby)
+- Missing hooks: SessionEnd, StopFailure, Setup, TeammateIdle, TaskCompleted, Elicitation, ElicitationResult, ConfigChange, WorktreeCreate, WorktreeRemove, InstructionsLoaded, PostCompact
+- Missing options: `allowDangerouslySkipPermissions`, `persistSession`, `resumeSessionAt`, `sessionId`, `strictMcpConfig`, `debug`/`debugFile`, `promptSuggestions`, `onElicitation`, `toolConfig`, `agentProgressSummaries`, `agent` (main thread agent), `dontAsk` permission mode
+- `ToolPermissionContext` missing `blockedPath`, `decisionReason`, `toolUseID`, `agentID`, `description`, `title`, `displayName`
+- Missing: `forkSession()`, `offset` on `list_sessions`, `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.80
 - Ruby-idiomatic patterns (Data.define, snake_case)
 - Complete control protocol, hook, and V2 Session API support
 - Dedicated Client class for multi-turn conversations

data/docs/hooks.md

@@ -64,11 +64,11 @@ When both global and per-conversation hooks are set, they are merged additively
 
 Each hook method accepts an optional first argument that filters which tool names trigger the callback. The matcher is passed as the first positional argument, before any keyword arguments.
 
-| Matcher type | Behavior | Example |
-|---|---|---|
-| `nil` (omitted) | Catch-all, fires for every tool | `h.before_tool_use { \|i, c\| ... }` |
-| `String` | Treated as a regex pattern | `h.before_tool_use("Bash") { \|i, c\| ... }` |
-| `Regexp` | Normalized to its `source` string | `h.before_tool_use(/Bash\|Write/) { \|i, c\| ... }` |
+| Matcher type    | Behavior                          | Example                                             |
+|-----------------|-----------------------------------|-----------------------------------------------------|
+| `nil` (omitted) | Catch-all, fires for every tool   | `h.before_tool_use { \|i, c\| ... }`                |
+| `String`        | Treated as a regex pattern        | `h.before_tool_use("Bash") { \|i, c\| ... }`        |
+| `Regexp`        | Normalized to its `source` string | `h.before_tool_use(/Bash\|Write/) { \|i, c\| ... }` |
 
 A `Regexp` is converted to its `.source` string internally so it can be serialized over the control protocol. This means flags like `Regexp::IGNORECASE` are not preserved.
 
@@ -133,7 +133,7 @@ end
 
 ## Event Mapping Table
 
-All 22 hook events with their Ruby DSL method, CLI event name, and description:
+All 23 hook events with their Ruby DSL method, CLI event name, and description:
 
 | Ruby method              | CLI event            | Description                                     |
 |--------------------------|----------------------|-------------------------------------------------|
@@ -145,6 +145,7 @@ All 22 hook events with their Ruby DSL method, CLI event name, and description:
 | `on_session_start`       | `SessionStart`       | When a session begins.                          |
 | `on_session_end`         | `SessionEnd`         | When a session ends.                            |
 | `on_stop`                | `Stop`               | When the agent stops.                           |
+| `on_stop_failure`        | `StopFailure`        | When the agent stops due to an API error.       |
 | `on_subagent_start`      | `SubagentStart`      | When a subagent is spawned.                     |
 | `on_subagent_stop`       | `SubagentStop`       | When a subagent stops.                          |
 | `before_compact`         | `PreCompact`         | Before context compaction.                      |
@@ -190,6 +191,7 @@ All input types inherit these fields from `BaseHookInput`:
 | `SessionStart`       | `SessionStartInput`       | `source`, `agent_type`, `model`                                                                                                         |
 | `SessionEnd`         | `SessionEndInput`         | `reason`                                                                                                                                |
 | `Stop`               | `StopInput`               | `stop_hook_active`, `last_assistant_message`                                                                                            |
+| `StopFailure`        | `StopFailureInput`        | `error`, `error_details`, `last_assistant_message`                                                                                      |
 | `SubagentStart`      | `SubagentStartInput`      | `agent_id`, `agent_type`                                                                                                                |
 | `SubagentStop`       | `SubagentStopInput`       | `stop_hook_active`, `agent_id`, `agent_transcript_path`, `agent_type`, `last_assistant_message`                                         |
 | `PreCompact`         | `PreCompactInput`         | `trigger`, `custom_instructions`                                                                                                        |

data/docs/messages.md

@@ -61,7 +61,7 @@ end
 
 ## Message Types
 
-22 message types, grouped by category.
+24 message types, grouped by category.
 
 ### Conversation Messages
 
@@ -223,6 +223,28 @@ Methods:
 - `trigger` -- compaction trigger type (`"manual"` or `"auto"`)
 - `pre_tokens` -- token count before compaction
 
+#### APIRetryMessage
+
+Emitted when an API request fails with a retryable error and will be retried.
+
+```ruby
+APIRetryMessage = Data.define(:uuid, :session_id, :attempt, :max_retries, :retry_delay_ms, :error_status, :error)
+```
+
+| Field            | Type           | Default |
+|------------------|----------------|---------|
+| `uuid`           | `String`       | `""`    |
+| `session_id`     | `String`       | `""`    |
+| `attempt`        | `Integer`      | `0`     |
+| `max_retries`    | `Integer`      | `0`     |
+| `retry_delay_ms` | `Integer`      | `0`     |
+| `error_status`   | `Integer, nil` | `nil`   |
+| `error`          | `String, nil`  | `nil`   |
+
+Methods:
+
+- `type` -- `:api_retry`
+
 #### StatusMessage
 
 Session status report (e.g., `"compacting"`).

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/hook_registry.rb

@@ -28,6 +28,7 @@ module ClaudeAgent
       on_session_start: "SessionStart",
       on_session_end: "SessionEnd",
       on_stop: "Stop",
+      on_stop_failure: "StopFailure",
       on_subagent_start: "SubagentStart",
       on_subagent_stop: "SubagentStop",
       before_compact: "PreCompact",

data/lib/claude_agent/hooks.rb

@@ -11,6 +11,7 @@ module ClaudeAgent
     SessionStart
     SessionEnd
     Stop
+    StopFailure
     SubagentStart
     SubagentStop
     PreCompact
@@ -175,6 +176,10 @@ module ClaudeAgent
   BaseHookInput.define_input "Stop",
     optional: { stop_hook_active: false, last_assistant_message: nil }
 
+  BaseHookInput.define_input "StopFailure",
+    required: [ :error ],
+    optional: { error_details: nil, last_assistant_message: nil }
+
   BaseHookInput.define_input "SubagentStart",
     required: [ :agent_id, :agent_type ]
 

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.18"
 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]
 
@@ -987,6 +1003,14 @@ module ClaudeAgent
     def initialize: (?stop_hook_active: bool, ?last_assistant_message: String?, **untyped) -> void
   end
 
+  class StopFailureInput < BaseHookInput
+    attr_reader error: String
+    attr_reader error_details: String?
+    attr_reader last_assistant_message: String?
+
+    def initialize: (error: String, ?error_details: String?, ?last_assistant_message: String?, **untyped) -> void
+  end
+
   class SubagentStartInput < BaseHookInput
     attr_reader agent_id: String
     attr_reader agent_type: String
@@ -1161,9 +1185,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.18
 platform: ruby
 authors:
 - Thomas Carr