claude-agent-sdk 0.32.0 → 0.33.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04f9cdf2c66d67b2af3a2a8c8dd14ee7fd418ccc7a7b4be727f73d70d02a8446
-  data.tar.gz: 7d8990d6720a47d104c59cc03d2288feefc55854d10badc19bdbc1d42a6dca04
+  metadata.gz: 6994a2674fc098001857cff72a21c3d804744c6fa25cb866f2a133ee1a2ec876
+  data.tar.gz: 349b7ce2314eac4c315e3c3d03ef0e466926fe3abb0f8823d1780f1486a8ce0d
 SHA512:
-  metadata.gz: d441ee7bfe0f1bb98a1ea2088bb908601ae16b545cd8e05928addb0966d746ae6c0de137b48bc7e3949d8e040d1eec58551e5775886a3658d6f9e9265be54b05
-  data.tar.gz: 1ef545a581c38233903ef7da689fcdc93776d6a764c5b1754f1ea77adbd775275c67eb817a4494ca83f8768218ea281bed96507f429c7880380ceb995723b197
+  metadata.gz: 0442feb3be095e8be7903e55e51f5620607b682cb0ed57f1ded989f01f6bf04bf22cee36556b52fd8cb4072d2e3bf4a2400c459b8cad231a83590d75b1010403
+  data.tar.gz: e287cd5825a5e16f1c8d7ce8295d0f3fba07ee15c5e4502be2dbfefcd223cf061c6e20afe5e5e6349e7ee2729c8c70e77aea152c6b95dc997978bc5ef358f68e

data/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.33.1] - 2026-09-21
+
+Compatibility with `json` 3.x and `mcp` 1.x. Upgrade if your bundle resolves `json` 3.x — `rename_session` / `tag_session` raise on 0.33.0.
+
+### Changed
+- `mcp` dependency is now `>= 0.20, < 2` (was `>= 0.6, < 1`). The floor moves to 0.20 because `mcp` 0.19 and older validate through the `json-schema` gem, which breaks under `json` 3.x and fails every SDK MCP `tools/call`; with `json` 2.x those versions still pass, so this only forces an `mcp` upgrade on bundles pinned below 0.20. The suite passes against every 1.x release through 1.6.0, and `initialize` / `tools/list` / `tools/call` / `resources/*` / `prompts/*` wire output is byte-identical to 0.2x.
+- SDK MCP tool handler exceptions now reach the model as the bare exception message (matching Python's `str(e)` and `SdkMcpServer#call_tool`) instead of the gem's `Internal error calling tool X: msg`. The exception is rescued inside the SDK's tool class, so the text no longer depends on the `mcp` gem version — `mcp` 1.2+ redacts the message from its own wrapper, which would otherwise have left the model with no error text to self-correct from. Still in-band `isError: true`.
+
+### Fixed
+- `rename_session` / `tag_session` raised `ArgumentError: unknown keyword: space_size` under `json` 3.x, which takes generator options as strict keywords. The option was a no-op on `json` 2.x (output unchanged), so it is simply gone. A fresh end-user bundle resolves `json` 3.x through `async → console → json`; CI missed it only because the dev-only RuboCop pin holds `json` at 2.x.
+
+## [0.33.0] - 2026-09-21
+
+Subagent capabilities for UI builders: metadata reads, background snapshots, cooperative callback cancellation, and the task/background/permission signals the CLI already emits — all raw data and controls, no status model. Ruby-ahead of the Python SDK (0.2.153).
+
+### Added
+- `get_subagent_metadata` / `get_subagent_metadata_from_store`: read optional subagent metadata with original string keys, including type, spawning tool ID, parent agent, depth, and future CLI fields. Disk reads reuse transcript scoping without parsing the transcript; store reads select the latest metadata entry even before messages arrive. These are historical reads, not live-status queries.
+- `background_tasks` and `session_crons` on `StopHookInput` / `SubagentStopHookInput`. Raw snapshots preserve unavailable (`nil`) versus explicitly empty (`[]`) and describe the parent session, not all foreground/background agents.
+- Cooperative permission cancellation through `ToolPermissionContext#signal` (`CancellationSignal#cancelled?` / `#wait`) and the associated `request_id`. CLI cancellation, disconnect, EOF, and failed dispatch invalidate pending requests, including callbacks running on worker threads; normal decisions do not. User threads are not forcibly stopped, and late decisions after observed cancellation cannot become allow responses.
+- `HookContext#signal` / `#request_id` use the same per-invocation cancellation contract, including hook timeouts. Thread callbacks can cooperate with cancellation; late hook output is discarded.
+- A minimal subagent event subscription example and capability reference covering lifecycle events, metadata, background snapshots, and permission cancellation. UI and application status aggregation remain outside the SDK.
+- Opt-in real-CLI subagent contract tests for ID/metadata/text correlation, permission cancellation on interrupt, and background completion/stop after a parent result. They self-skip without CLI credentials.
+- Subagent UI signals the CLI already emits, read from the schema embedded in Claude Code CLI 2.1.278 (the Python SDK has none of these as of Python SDK 0.2.153; only partly verified live — a smoke run against CLI 2.1.278 confirmed the `task_started` fields and the targeted-miss `background_tasks` response; the rest is schema-derived). The SDK exposes raw data and controls only — no status aggregation.
+  - `TaskStartedMessage#subagent_type` / `#is_backgrounded` / `#spawn_depth`, `TaskProgressMessage#subagent_type`, `TaskNotificationMessage#reason` / `#resource_links` (raw Array, symbol keys with the wire spelling), the `#skip_transcript` / `#ambient` display flags on both `TaskStartedMessage` and `TaskNotificationMessage` (hints for the host — the SDK never filters frames or computes activity), and `TaskUpdatedMessage#is_backgrounded` / `#error` / `#end_time` / `#total_paused_ms` / `#description` derived from `patch` like `status`. `is_backgrounded` keeps `nil` (not reported) distinct from an explicit `false` (foreground, spawning tool call blocking). `TaskUpdatedMessage` now also reads a string-keyed `patch` on hand-built messages.
+  - `BackgroundTasksChangedMessage` (`background_tasks_changed`): the full set of live background tasks, a level signal with REPLACE semantics. The SDK's own stdin-close bookkeeping still deliberately ignores this frame.
+  - `PermissionDeniedMessage` (`permission_denied`): a tool call auto-denied without an interactive prompt, with `agent_id` for subagent routing (not a permission `request_id`). A best-effort advisory, not a complete denial feed — `ResultMessage#permission_denials` stays authoritative.
+  - `Client#background_tasks(tool_use_id: nil)` / `Query#background_tasks`: send in-flight foreground tasks to the background (Ctrl+B). Keyed by the spawning `tool_use_id`, not `task_id` / `agent_id`. The targeted form returns `{ backgrounded: true }` or `{ backgrounded: false }` — a definitive miss, after which no event is coming; `nil` is the explicit all-tasks form and returns `{}`. Because the CLI treats `''` as "all tasks", anything other than `nil` or a non-empty String raises `ArgumentError` before a request is written. `TaskUpdatedMessage#is_backgrounded` / `BackgroundTasksChangedMessage` report the lifecycle state that follows.
+  - `ClaudeAgentOptions#agent_progress_summaries`: request model-generated progress summaries for subagents; `TaskProgressMessage#summary` may then be present, and stays optional. Tri-state; `nil` omits `agentProgressSummaries` from the `initialize` request and `true` / `false` are forwarded verbatim. An enable switch, not a live toggle: CLI 2.1.278 only acts on a truthy value, so `false` is equivalent to unset.
+  - **Compatibility:** `background_tasks_changed` and `permission_denied` frames previously parsed as a generic `SystemMessage`. Both new classes subclass it, so `when SystemMessage` and `#data` consumers are unaffected; code matching on `message.class == SystemMessage` will no longer see them.
+
+### Fixed
+- Best-effort control error/cancellation replies no longer leak a secondary connection error when the CLI has already exited. Original transport read errors still propagate to the consumer.
+- Control-request tracking is identity-guarded: if the CLI ever reused an in-flight request ID, the first handler finishing no longer untracks the later request's cancellation signal or task, so EOF, disconnect, and `control_cancel_request` still invalidate it and its late decision cannot be sent as a success.
+- `ClaudeAgentSDK.configure` defaults now merge by option, not by literal key spelling. `ClaudeAgentOptions` accepts symbol/string and snake_case/camelCase names, but the defaults merge compared raw keys, so a differently spelled per-call key rode along as a second entry: `'permissionMode' => nil` wiped a configured `permission_mode:` instead of inheriting it, and a Hash option such as `'env' => {...}` replaced the configured `env:` instead of merging into it. Unknown option names are still reported with the caller's own spelling.
+
 ## [0.32.0] - 2026-09-17
 
 Syncs the gem with Python SDK **0.2.153** (previously 0.2.147). The intervening Python releases 0.2.148–0.2.152 only bump the CLI binary Python bundles; this gem does not vendor a CLI, so they carry no Ruby-side change.

data/README.md

@@ -27,7 +27,7 @@ A Ruby SDK for the [Claude Code](https://docs.claude.com/en/docs/claude-code-ove
 
 ```ruby
 # Gemfile
-gem 'claude-agent-sdk', '~> 0.32.0'
+gem 'claude-agent-sdk', '~> 0.33.1'
 ```
 
 Then `bundle install`, or install directly with `gem install claude-agent-sdk`. To track unreleased changes, point the Gemfile at GitHub: `gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'`.
@@ -146,6 +146,7 @@ See [docs/hooks-and-permissions.md](docs/hooks-and-permissions.md) for the full
 | All hook events, typed inputs, permission callbacks | [docs/hooks-and-permissions.md](docs/hooks-and-permissions.md) |
 | Structured output, thinking, budget, fallback and advisor models, sandbox, bare mode, checkpointing | [docs/configuration.md](docs/configuration.md) |
 | Session listing, reading, renaming, tagging, forking, resume-at-message | [docs/sessions.md](docs/sessions.md) |
+| Subagent capabilities, event contracts, and minimal example | [docs/subagents.md](docs/subagents.md) |
 | OpenTelemetry tracing, Langfuse, custom observers | [docs/observability.md](docs/observability.md) |
 | Rails: fiber safety, solid_queue fiber workers, ActionCable, jobs, initializer | [docs/rails.md](docs/rails.md) |
 | Vendoring a pinned CLI binary and CLI discovery order | [docs/cli-installer.md](docs/cli-installer.md) |
@@ -180,7 +181,7 @@ All three SDKs drive the same CLI over the same protocol, so capabilities line u
 | Hooks (all 27 events) | ✅ | ✅ | ✅ |
 | Permission callbacks | ✅ | ✅ | ✅ |
 | Structured output | ✅ | ✅ | ✅ |
-| All 25 message types | ✅ | partial | ✅ |
+| All 28 message types | ✅ | partial | ✅ |
 | [Sandbox](https://github.com/anthropic-experimental/sandbox-runtime) settings | ✅ | partial | ✅ |
 | Bare mode (`--bare`) | ✅ | ✅ | ✅ |
 | File checkpointing & rewind | ✅ | ✅ | ✅ |

data/docs/client.md

@@ -44,6 +44,10 @@ Async do
   client.reconnect_mcp_server('my-server')      # Reconnect a failed MCP server
   client.toggle_mcp_server('my-server', false)  # Enable/disable an MCP server
   client.stop_task('task_abc123')               # Stop a running background task
+  client.background_tasks                       # Background every foreground task (Ctrl+B) => {}
+  client.background_tasks(tool_use_id: 'toolu_01') # Only the task spawned by that tool_use block
+                                                # => { backgrounded: true } | { backgrounded: false } (definitive miss)
+                                                # '' or a non-String raises ArgumentError; nil is the all-tasks form
 
   client.disconnect
 end.wait

data/docs/configuration.md

@@ -262,6 +262,39 @@ Matches the TypeScript SDK's `forwardSubagentText`. The capability is
 negotiated on the control-protocol handshake, so it applies to both
 `ClaudeAgentSDK.query` and `Client`.
 
+## Subagent Progress Summaries
+
+Set `agent_progress_summaries` to **request** model-generated one-line progress
+summaries for subagent (`local_agent`) tasks. While the CLI has generation
+enabled, a subagent's `TaskProgressMessage#summary` **may** be present; the
+field stays optional on the wire, so not every progress frame carries one —
+read it nil-safely:
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(agent_progress_summaries: true)
+
+# ...
+when ClaudeAgentSDK::TaskProgressMessage
+  puts "#{message.task_id}: #{message.summary}" if message.summary
+```
+
+`false` and `nil` do not enable generation. They do not promise suppression
+either: a process that already enabled summaries keeps producing them, and a
+backgrounded `mcp_task` reports its own status in `summary` regardless of this
+option.
+
+The option is tri-state: `nil` (the default) omits the key from the `initialize`
+control request, while `true` and `false` are forwarded verbatim as
+`agentProgressSummaries`. It is an **enable switch, not a live toggle**: CLI
+2.1.278 only acts on a truthy value, so `false` is schema-valid but equivalent
+to leaving the option unset — it does not switch summaries off on a process that
+already enabled them. With `ClaudeAgentSDK.configure` defaults, a per-call
+`false` overrides a global `true`, and an unset per-call value inherits the
+global one. It applies to both `ClaudeAgentSDK.query` and `Client`. The key was
+read from the schema embedded in Claude Code CLI 2.1.278 and has not been
+verified against a live run. See
+[subagent capabilities](subagents.md).
+
 ## File Checkpointing & Rewind
 
 Enable file checkpointing to revert file changes to a previous state:

data/docs/hooks-and-permissions.md

@@ -12,8 +12,8 @@ All hook input objects include common fields like `session_id`, `transcript_path
 - `PostToolUse` → `PostToolUseHookInput` (`tool_name`, `tool_input`, `tool_response`, `tool_use_id`)
 - `PostToolUseFailure` → `PostToolUseFailureHookInput` (`tool_name`, `tool_input`, `tool_use_id`, `error`, `is_interrupt`)
 - `UserPromptSubmit` → `UserPromptSubmitHookInput` (`prompt`)
-- `Stop` → `StopHookInput` (`stop_hook_active`)
-- `SubagentStop` → `SubagentStopHookInput` (`stop_hook_active`, `agent_id`, `agent_transcript_path`, `agent_type`)
+- `Stop` → `StopHookInput` (`stop_hook_active`, `last_assistant_message`, `background_tasks`, `session_crons`)
+- `SubagentStop` → `SubagentStopHookInput` (`stop_hook_active`, `agent_id`, `agent_transcript_path`, `agent_type`, `last_assistant_message`, `background_tasks`, `session_crons`)
 - `PreCompact` → `PreCompactHookInput` (`trigger`, `custom_instructions`)
 - `Notification` → `NotificationHookInput` (`message`, `title`, `notification_type`)
 - `SubagentStart` → `SubagentStartHookInput` (`agent_id`, `agent_type`)
@@ -21,6 +21,14 @@ All hook input objects include common fields like `session_id`, `transcript_path
 
 All 27 hook events have typed input classes. See [`ClaudeAgentSDK::HOOK_EVENTS`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/lib/claude_agent_sdk/types.rb) and [examples/lifecycle_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb).
 
+`background_tasks` and `session_crons` are optional arrays of raw CLI hashes.
+`nil` means the CLI did not provide a snapshot; `[]` means it provided an empty
+one. Nested keys are passed through unchanged (Symbols on the live transport).
+Both snapshots belong to the **parent session**, even on `SubagentStop`; they
+are not a complete list of foreground and background agents. A task disappearing
+from a background snapshot does not establish its terminal status, and a
+SubagentStop hook can itself keep the subagent running. See [subagent capabilities](subagents.md).
+
 ### Example: Blocking Dangerous Commands
 
 ```ruby
@@ -69,6 +77,21 @@ end.wait
 
 See [examples/hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/hooks_example.rb), [examples/advanced_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/advanced_hooks_example.rb), and [examples/lifecycle_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb).
 
+### Hook cancellation
+
+Dispatched hooks receive `HookContext#request_id` and `HookContext#signal`, using
+the same [cooperative cancellation API](#permission-request-cancellation) as
+permission callbacks. The request ID identifies this invocation, not the hook's
+registered callback ID or the tool invocation.
+
+CLI cancellation, EOF, disconnect, callback failure, and `HookMatcher#timeout`
+invalidate the signal. Successful hook completion does not. A default `:thread`
+hook waiting on external work must poll `signal.cancelled?` or use a bounded
+wait; timeout does not forcibly stop its thread. Late hook output is discarded.
+Inline hooks may unwind before the signal is marked cancelled on timeout, so
+always clean up in `ensure`, regardless of the signal's value there. Do not
+swallow cancellation exceptions. Observe the signal; `cancel` is SDK-internal.
+
 ## Permission Callbacks
 
 A **permission callback** is a Ruby proc/lambda that allows you to programmatically control tool execution. This gives you fine-grained control over what tools Claude can use and with what inputs.
@@ -108,6 +131,47 @@ end.wait
 
 See [examples/permission_callback_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/permission_callback_example.rb).
 
+### Permission request cancellation
+
+Dispatched `can_use_tool` callbacks receive `context.request_id` (the control
+request ID, distinct from `tool_use_id`) and `context.signal`, a
+`ClaudeAgentSDK::CancellationSignal`:
+
+- `signal.cancelled?` checks whether the request is no longer actionable.
+- `signal.wait(timeout: seconds)` waits for cancellation, returning `true` on
+  cancellation or `false` on timeout. Omit the timeout to wait indefinitely.
+  Multiple waiters and callers arriving after cancellation all observe it.
+- The SDK signals cancellation on a CLI `control_cancel_request`, disconnect,
+  EOF/transport failure, or an unsuccessful callback dispatch. Normal allow/deny
+  completion does not cancel the signal. Stop waiting once the callback returns.
+
+The signal is safe on worker threads and Async fibers. Cancellation is
+cooperative: default `:thread` callbacks are **not** forcibly terminated. Poll
+the signal while waiting for an application's decision and remove the pending
+request in `ensure`. Inline callbacks may instead unwind via `Async::Stop`;
+let it propagate. The SDK never sends a late callback decision as an allow
+response after it has observed cancellation.
+
+For example, if the host has registered a separate `Thread::Queue` for this
+request and its decision handler pushes a `PermissionResultAllow` or
+`PermissionResultDeny` into it:
+
+```ruby
+begin
+  loop do
+    break ClaudeAgentSDK::PermissionResultDeny.new(message: 'Request cancelled') if context.signal.cancelled?
+    decision = decision_queue.pop(timeout: 0.1)
+    break decision if decision
+  end
+ensure
+  # Unregister context.request_id from the host's pending decisions here.
+end
+```
+
+Do not use an unbounded blocking `gets`/queue wait for a human decision without
+observing cancellation, or auto-approve when the decision service disconnects.
+Hooks have the same signal API; see [hook cancellation](#hook-cancellation).
+
 ### Shadowing: when `can_use_tool` never runs
 
 `can_use_tool` is only consulted when the CLI's permission ladder lands on

data/docs/sessions.md

@@ -51,6 +51,34 @@ With `directory:` given, only that project and its git worktrees are searched (n
 
 > Each returned `SessionMessage` carries `parent_tool_use_id` — the id of the Agent `tool_use` block in the parent session that spawned this subagent — and `parent_agent_id`, the spawning subagent's id for nested subagents. Both are read from the `agent-<id>.meta.json` sidecar beside the transcript (or the `agent_metadata` entry in a `SessionStore`), and are `nil` when it is missing or unusable.
 
+### Reading Subagent Metadata
+
+```ruby
+meta = ClaudeAgentSDK.get_subagent_metadata(session_id: session_id, agent_id: agent_id, directory: project)
+meta = ClaudeAgentSDK.get_subagent_metadata_from_store(
+  session_store: store, session_id: session_id, agent_id: agent_id, directory: project
+)
+meta&.dig('toolUseId')    # spawning Agent tool call; not task_id
+meta&.dig('parentAgentId')
+meta&.dig('agentType')
+meta&.dig('spawnDepth')
+```
+
+Returns a **string-keyed Hash with the original CLI field spelling**, preserving
+unknown fields. All fields are optional. `nil` means unavailable; `{}` is a valid
+empty sidecar. The disk reader uses the same project/worktree scope and sorted
+first-match rule as `get_subagent_messages`, but does not parse the transcript.
+It locates the sidecar beside `agent-<id>.jsonl`, so it returns `nil` until that
+transcript file exists, even if the sidecar has already been written.
+Missing, unreadable, non-regular, corrupt, or invalid-UTF-8 sidecars return `nil`.
+
+The store reader resolves nested subpaths with `list_subkeys` when available,
+otherwise tries the direct path. It returns the **last** `agent_metadata` entry
+without the synthetic `type` marker, even before any conversation messages have
+arrived. Adapter errors propagate, like other store reads. These APIs do not
+return live status, and reading metadata does not resume an agent. See
+[subagent capabilities](subagents.md) for correlating metadata with events.
+
 ## Renaming a Session
 
 ```ruby

data/docs/subagents.md

@@ -0,0 +1,198 @@
+# Subagent capabilities
+
+This repository provides SDK capabilities and minimal usage examples. UI,
+application status aggregation, event persistence, and recovery policy belong
+to the consuming application, not this SDK.
+
+## Available data and controls
+
+| Capability | SDK surface | Contract |
+|---|---|---|
+| Define subagents | `ClaudeAgentOptions#agents`, `AgentDefinition` | Configure description, prompt, tools, model, and other agent options |
+| Task lifecycle | `TaskStartedMessage`, `TaskProgressMessage`, `TaskUpdatedMessage`, `TaskNotificationMessage` | Task IDs identify tasks, including non-agent tasks; `task_type: 'local_agent'` identifies subagents |
+| Activity and usage | Task progress / notification fields | Usage is cumulative, not a delta; optional fields depend on the CLI |
+| Card fields | `TaskStartedMessage#subagent_type` / `#is_backgrounded` / `#spawn_depth`, `TaskProgressMessage#subagent_type` | All optional. `is_backgrounded` is tri-state: `true` background, `false` foreground (spawning tool call blocking), `nil` not reported |
+| Display flags | `#skip_transcript` / `#ambient` on `TaskStartedMessage` and `TaskNotificationMessage` | Optional booleans (`nil` absent, `false` preserved). Hints for the host; the SDK never filters frames or computes activity |
+| Progress summaries | `agent_progress_summaries: true`, `TaskProgressMessage#summary` | `true` requests model-generated one-line statuses for `local_agent` tasks; `summary` may then be present but stays optional. An enable switch, not a live toggle. Unset omits the key from `initialize` |
+| Patch fields | `TaskUpdatedMessage#is_backgrounded` / `#error` / `#end_time` / `#total_paused_ms` / `#description` | Derived from `patch`; `nil` means "not in this patch", not a value. `is_backgrounded == true` is a move to the background |
+| Settle details | `TaskNotificationMessage#reason` / `#resource_links` | `reason` is `'worker_restart'` or `nil`; `resource_links` is a raw Array for completed `mcp_task` tasks |
+| Live background set | `BackgroundTasksChangedMessage#tasks` | Level signal with REPLACE semantics: swap your set for each payload. Background tasks only |
+| Auto-denied tool calls | `PermissionDeniedMessage` | Advisory; `agent_id` routes a denial to a subagent. `ResultMessage#permission_denials` stays authoritative |
+| Child output | `forward_subagent_text: true`, `AssistantMessage#parent_tool_use_id` | Forward child text/thinking; the parent tool ID identifies the spawning tool call |
+| Agent identity | `SubagentStartHookInput`, `SubagentStopHookInput`, `get_subagent_metadata[_from_store]` | Metadata can link `agent_id` to `toolUseId`, `agentType`, `parentAgentId`, and `spawnDepth` |
+| Historical transcripts | `list_subagents[_from_store]`, `get_subagent_messages[_from_store]` | Historical reads, not proof that an agent is currently alive |
+| Background snapshots | `StopHookInput` / `SubagentStopHookInput` | Optional `background_tasks` and `session_crons`; `nil` means absent, `[]` means explicitly empty |
+| Permissions | `can_use_tool`, `ToolPermissionContext` | `request_id`, `agent_id`, `tool_use_id`, and cooperative cancellation via `signal.cancelled?` / `signal.wait` |
+| Hook cancellation | `HookContext#signal`, `HookContext#request_id` | Per-invocation cancellation on CLI cancel, disconnect, failure, or hook timeout; successful completion does not cancel |
+| Stop a task | `Client#stop_task(task_id)` | Acknowledgement is not completion; observe a terminal event |
+| Send to background | `Client#background_tasks(tool_use_id: nil)` | Keyed by the spawning `tool_use_id`, not `task_id` / `agent_id`. Targeted: returns `{ backgrounded: true }` or `{ backgrounded: false }` (a definitive miss). `nil`: every foreground task, returns `{}`. `''` / non-String raises `ArgumentError` |
+
+Task updates expose raw statuses such as `pending`, `running`, `paused`,
+`completed`, `failed`, and `killed`. Notifications use `completed`, `failed`,
+and `stopped`. A terminal state can arrive through **either** event type;
+`TERMINAL_TASK_STATUSES` covers both vocabularies. Receiving `paused` does not
+imply a public per-agent pause/resume control exists.
+
+### Foreground, background, and the live set
+
+A subagent registered in the **foreground** reports `TaskStartedMessage#is_backgrounded`
+as `false`: the spawning Agent tool call blocks the turn. Test `== false`, not
+falsiness — `nil` means the CLI did not report the field (it is set only for
+`local_agent` and `local_bash` tasks). A later move to the background does not
+re-emit `task_started`; it arrives as a `TaskUpdatedMessage` whose
+`is_backgrounded` is `true`. The patch readers (`is_backgrounded`, `error`,
+`end_time`, `total_paused_ms`, `description`) mirror how `status` is derived: a
+patch carries only what changed, so merge patches into your own task map instead
+of reading one as the task's full state.
+
+`Client#background_tasks` is the control-request equivalent of pressing Ctrl+B:
+each targeted blocking tool call returns a "running in the background"
+tool_result, the turn continues, and the task still emits a
+`TaskNotificationMessage` when it settles.
+
+```ruby
+client.background_tasks                          # every foreground task => {}
+client.background_tasks(tool_use_id: 'toolu_01') # one task => { backgrounded: true } or { backgrounded: false }
+```
+
+`tool_use_id` is the id of the `tool_use` block that **spawned** the task
+(`TaskStartedMessage#tool_use_id`, or `AssistantMessage#parent_tool_use_id` on
+forwarded child output) — not a `task_id` or `agent_id`.
+
+- **Targeted** (`tool_use_id:` given): the reply is the outcome.
+  `{ backgrounded: true }` means the matching foreground task was backgrounded.
+  `{ backgrounded: false }` is a **definitive miss** — the CLI found no
+  matching foreground task. Do not wait for an event after a miss.
+- **All tasks** (`nil`, the explicit all-tasks form): the reply is `{}`, which
+  says nothing about whether any foreground task existed.
+
+Event observation — `TaskUpdatedMessage#is_backgrounded` and
+`BackgroundTasksChangedMessage` — is for the lifecycle state that follows, not a
+substitute for reading the targeted reply.
+
+`tool_use_id` must be `nil` or a non-empty String; anything else raises
+`ArgumentError` before a request is written. The CLI itself treats `''` as "all
+tasks", so a selector built from a missing id (`started.tool_use_id.to_s`) would
+release every blocking tool call — and `TaskStartedMessage#tool_use_id` is
+optional on the wire. Never substitute `nil` or `''` for a per-card id you do
+not have yet: disable the per-task control until a real id arrives.
+
+`skip_transcript` and `ambient` (on `TaskStartedMessage` and
+`TaskNotificationMessage`) are the CLI's display hints. `skip_transcript` marks
+an ambient/housekeeping task: hide it from the inline transcript, though it may
+still appear in a tasks panel. `ambient` marks tasks that are not activity —
+every `skip_transcript` task plus every live-update watcher, requested or
+auto-started — which hosts should exclude from activity indicators. Both are
+`nil` when absent and keep an explicit `false`. The SDK surfaces every frame
+regardless and computes no activity state from them.
+
+`BackgroundTasksChangedMessage#tasks` is the full set of live **background**
+tasks after a membership change, as raw symbol-keyed Hashes
+(`{ task_id:, task_type:, description:, ambient: }`, `ambient` optional — `true`
+marks housekeeping tasks to exclude from activity indicators). It is a level
+signal with **REPLACE semantics**: replace your set with each payload rather
+than pairing start/notification edges, so a missed edge cannot leave a stale
+"running" badge. A frame is emitted on membership changes and also when an
+entry's `ambient` flag flips. REPLACE alone does not prevent a stale badge; the
+CLI's contract also says:
+
+- Ordering relative to the edge frames is unspecified, so do not correlate the
+  two streams.
+- The level is per CLI process. Nothing is emitted at startup, so reset to the
+  empty set whenever the process (re)starts — otherwise the previous process's
+  last payload shows running work forever while the new one sits idle.
+- `tasks: []` is an authoritative empty snapshot for that process.
+- A repeated `initialize` on an already-running process is answered with a
+  snapshot (even an empty one) right behind its success response; older CLIs
+  may send nothing there. This SDK initializes once per connection.
+- A foreground subagent is absent from the set until it is backgrounded.
+
+The SDK does not consume this frame for its own bookkeeping, and does not
+aggregate it into a status model.
+
+`PermissionDeniedMessage` reports a tool call that was auto-denied without an
+interactive prompt (`tool_name`, `tool_use_id`, `message`, and optionally
+`agent_id`, `decision_reason_type`, `decision_reason`). It is a **best-effort
+advisory, not a complete denial feed**: `ResultMessage#permission_denials` is
+the authoritative record, and in rare races a booked denial has no frame or a
+frame has no booked denial — do not derive badge counts or permission state
+from it. Not covered at all: PreToolUse hook denies, deny-rule overrides of a
+hook's allow/ask decision, Read/Edit/Write calls refused by a path-scoped deny
+rule, and the MCP `--permission-prompt-tool` surface. `decision_reason_type` is
+an open string (`'classifier'`, `'asyncAgent'`, `'mode'`, `'rule'` are
+examples, not an enum), and `agent_id` is a subagent id for routing — not a
+permission `request_id`. With a `can_use_tool` callback an "ask"
+decision goes to the callback instead; without one nobody can answer it, so that
+implicit denial is reported here too.
+
+`TaskNotificationMessage#resource_links` passes the CLI's array through
+untouched: symbol-keyed Hashes with the wire spelling preserved — `:uri` and
+`:name` always, plus optional `:title`, `:description`, `:mimeType`, `:size` (a
+number, not necessarily an integer) and `:annotations`. Elements carry no
+`type: 'resource_link'` discriminator. The CLI describes its output as at most
+50 links / 64 KiB; that is a producer-side note the SDK does not enforce.
+
+Other frames the CLI marks internal (`agents_killed`, `task_summary`, and
+`permission_denied`'s `decision_reason_code`) arrive as a generic
+`SystemMessage` / through `#data` with no stability promise.
+
+**Provenance.** The fields, messages, control request, and option in this
+section were read from the schema embedded in Claude Code CLI 2.1.278. They are
+covered by protocol unit tests, but only partly verified against a live CLI: a
+smoke run against 2.1.278 confirmed `task_started`'s `subagent_type` /
+`is_backgrounded` / `spawn_depth` and the `{ backgrounded: false }` answer to a
+targeted miss. Actually backgrounding a task, `background_tasks_changed` and
+`permission_denied` frames, and progress summaries are schema-derived only.
+Every new reader is `nil` whenever the CLI does not send its field. The
+Python SDK exposes none of them as of Python SDK 0.2.153.
+
+`task_id`, `agent_id`, and `tool_use_id` are different identifiers. The metadata
+field `toolUseId` links an agent to its spawning tool call, not to an inner tool
+call awaiting permission. Metadata may be unavailable at the start hook; retry
+on later events or history reads. See [metadata APIs](sessions.md#reading-subagent-metadata).
+
+Both Stop snapshots describe the **parent session's background work**, even on
+SubagentStop. They are not a complete agent registry, and absence from a snapshot
+does not establish completion. A SubagentStop hook can itself prevent stopping.
+See [hook fields and permission cancellation](hooks-and-permissions.md).
+
+## Minimal example
+
+[`examples/subagent_status_example.rb`](../examples/subagent_status_example.rb)
+defines a tool-free reviewer, registers lifecycle hooks, reads metadata, and
+prints task events and forwarded child text without building a status model:
+
+```sh
+bundle exec ruby examples/subagent_status_example.rb
+```
+
+It requires an authenticated Claude Code CLI and makes a real model request.
+The example limits the parent to the Agent tool and gives the reviewer no tools.
+Events and optional metadata depend on the CLI version and actual execution;
+not every run emits every event type. Output can contain prompts and transcripts.
+
+The example reads with `Client#receive_messages` for a bounded 60-second window,
+then disconnects. `receive_response` stops at the next parent result, which is
+not the end of background work. The demo deadline is not a task status. Use the
+store-backed metadata API when the CLI filesystem is remote; see
+[permission cancellation](hooks-and-permissions.md#permission-request-cancellation)
+for a minimal cancellation-aware callback wait.
+
+The SDK does not provide an authoritative live-agent registry, a UI status
+machine, or direct per-agent pause/resume controls. Reading metadata or restoring
+transcripts does not reconnect to a running subagent.
+
+## CLI contract checks
+
+The real-CLI suite includes subagent ID/metadata/text correlation, permission
+cancellation on interrupt, and background completion/stop after a parent result:
+
+```sh
+RUN_INTEGRATION=1 bundle exec rspec spec/integration/real_cli_integration_spec.rb --example 'subagent contracts'
+```
+
+These checks use disposable settings/transcripts and cap each run at $0.50 and
+120 seconds. They require `claude` on PATH and `ANTHROPIC_API_KEY`; without either
+they are **skipped**, not verified. They exercise the installed CLI, not every
+supported CLI version. Protocol unit tests cover both callback scheduling modes
+and terminal event variants deterministically.

data/docs/types.md

@@ -50,26 +50,56 @@ end
 
 # Typed subclasses (all inherit from SystemMessage, so is_a?(SystemMessage) still works)
 class TaskStartedMessage < SystemMessage
-  attr_accessor :task_id, :description, :uuid, :session_id, :tool_use_id, :task_type, :workflow_name, :prompt
+  attr_accessor :task_id, :description, :uuid, :session_id, :tool_use_id, :task_type, :workflow_name, :prompt,
+                :subagent_type,    # String | nil
+                :is_backgrounded,  # true (background) | false (foreground, tool call blocking) | nil (not reported)
+                :spawn_depth,      # Integer | nil (1 = top-level subagent)
+                :skip_transcript,  # true | false | nil — hide from the inline transcript (a tasks panel may still show it)
+                :ambient           # true | false | nil — not activity; exclude from activity indicators
 end
 
 class TaskProgressMessage < SystemMessage
-  attr_accessor :task_id, :description, :usage, :uuid, :session_id, :tool_use_id, :last_tool_name, :summary
+  attr_accessor :task_id, :description, :usage, :uuid, :session_id, :tool_use_id, :last_tool_name, :summary,
+                :subagent_type     # String | nil
 end
 
 class TaskNotificationMessage < SystemMessage
-  attr_accessor :task_id, :status, :output_file, :summary, :uuid, :session_id, :tool_use_id, :usage
+  attr_accessor :task_id, :status, :output_file, :summary, :uuid, :session_id, :tool_use_id, :usage,
+                :reason,           # 'worker_restart' | nil
+                :resource_links,   # Array<Hash> | nil — raw, symbol keys with wire spelling (:uri, :name, :mimeType, ...)
+                :skip_transcript,  # true | false | nil — same meaning as on TaskStartedMessage
+                :ambient           # true | false | nil — the SDK never filters on either flag
 end
 
 # Background task lifecycle state change. `status` is derived from patch["status"].
 # A terminal task can arrive *only* as a TaskUpdatedMessage (no TaskNotificationMessage) —
 # e.g. a TaskStop-killed task reports status "killed" here. Clear tracked task IDs on a
 # terminal status (see TERMINAL_TASK_STATUSES) from *either* message.
+# The other patch readers are derived the same way; nil means "not in this patch".
 class TaskUpdatedMessage < SystemMessage
-  attr_accessor :task_id, :patch, :status, :uuid, :session_id
+  attr_accessor :task_id, :patch, :status, :uuid, :session_id,
+                :description, :error, :end_time, :total_paused_ms,
+                :is_backgrounded   # true = moved to the background | false | nil (patch does not mention it)
+end
+
+# Full set of live background tasks; REPLACE semantics (swap your set for each payload).
+class BackgroundTasksChangedMessage < SystemMessage
+  attr_accessor :tasks,            # Array<Hash> — raw { task_id:, task_type:, description:, ambient: }
+                :uuid, :session_id
+end
+
+# A tool call auto-denied without an interactive prompt. Best-effort advisory, not a
+# complete denial feed; ResultMessage#permission_denials is the authoritative record.
+class PermissionDeniedMessage < SystemMessage
+  attr_accessor :tool_name, :tool_use_id, :message, :uuid, :session_id,
+                :agent_id,              # String | nil — subagent id for routing (NOT a permission request_id)
+                :decision_reason_type,  # String | nil — open string ('classifier', 'asyncAgent', 'mode', 'rule', ...)
+                :decision_reason        # String | nil
 end
 ```
 
+See [subagent capabilities](subagents.md) for the contracts behind these fields.
+
 ### ResultMessage
 
 Final result message with cost and usage information.

data/lib/claude_agent_sdk/cancellation_signal.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ClaudeAgentSDK
+  # Cooperative cancellation of a permission or hook request. Safe to observe from
+  # worker threads and Async fibers. Cancellation does not kill user threads.
+  class CancellationSignal
+    def initialize
+      @queue = Thread::Queue.new
+    end
+
+    def cancelled?
+      @queue.closed?
+    end
+
+    # Wait for cancellation, returning true when cancelled, false on timeout.
+    # Level-triggered: late callers and multiple waiters all observe cancellation.
+    # @param timeout [Numeric, nil] Seconds; nil waits without a deadline
+    def wait(timeout: nil) # rubocop:disable Naming/PredicateMethod -- blocking wait, not a state predicate
+      @queue.pop(timeout: timeout)
+      cancelled?
+    end
+
+    # @api private Called by the SDK when the request is no longer actionable.
+    def cancel
+      @queue.close
+    end
+  end
+end

data/lib/claude_agent_sdk/message_parser.rb

@@ -133,7 +133,9 @@ module ClaudeAgentSDK
       # like every other system subtype. `data` is always symbol-keyed here:
       # `parse` rejects any message lacking a `:type` symbol key, so a
       # string-keyed hash never reaches these classes.
-      'task_updated' => TaskUpdatedMessage
+      'task_updated' => TaskUpdatedMessage,
+      'background_tasks_changed' => BackgroundTasksChangedMessage,
+      'permission_denied' => PermissionDeniedMessage
     }.freeze
 
     def self.parse_system_message(data)