From 0341812555d0ac57ec6f2eedf9520b40b6145b12 Mon Sep 17 00:00:00 2001 From: examon Date: Thu, 30 Jul 2026 16:27:52 +0000 Subject: [PATCH] docs: correct the ephemeral labels on four persisted session events docs/features/streaming-events.md marks permission.requested, permission.completed, external_tool.requested and external_tool.completed as "Ephemeral.", which that file defines as not persisted to the session event log and not replayed on session resume. All four are persisted: sessions record them in the event log, and they are still present in a resumed session's history. The labels were accurate when the guide was written in #717. #1177 regenerated the event types so that none of these four still declares a required `ephemeral: true`, but the prose was not updated with them. Remove the classification from the four event sections, the two permission entries in the turn-flow diagram, and the four summary-table rows, matching the convention the file already uses for persisted events, which carry no marker. --- docs/features/streaming-events.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/features/streaming-events.md b/docs/features/streaming-events.md index 69e12e6dc..91b58439e 100644 --- a/docs/features/streaming-events.md +++ b/docs/features/streaming-events.md @@ -661,7 +661,7 @@ These events are emitted when the agent needs approval or input from the user be ### `permission.requested` -Ephemeral. The agent needs permission to perform an action (run a command, write a file, etc.). +The agent needs permission to perform an action (run a command, write a file, etc.). | Data Field | Type | Required | Description | |------------|------|----------|-------------| @@ -684,7 +684,7 @@ All `kind` variants also include an optional `toolCallId` linking back to the to ### `permission.completed` -Ephemeral. A permission request was resolved. +A permission request was resolved. | Data Field | Type | Required | Description | |------------|------|----------|-------------| @@ -835,7 +835,7 @@ A system or developer prompt was injected into the conversation. ### `external_tool.requested` -Ephemeral. The agent wants to invoke an external tool (one provided by the SDK consumer). +The agent wants to invoke an external tool (one provided by the SDK consumer). | Data Field | Type | Required | Description | |------------|------|----------|-------------| @@ -847,7 +847,7 @@ Ephemeral. The agent wants to invoke an external tool (one provided by the SDK c ### `external_tool.completed` -Ephemeral. An external tool request was resolved. +An external tool request was resolved. | Data Field | Type | Required | Description | |------------|------|----------|-------------| @@ -925,8 +925,8 @@ assistant.turn_start → Turn begins ├── assistant.usage → Token usage for this API call (ephemeral) │ ├── [If tools were requested:] -│ ├── permission.requested → Needs user approval (ephemeral) -│ ├── permission.completed → Approval result (ephemeral) +│ ├── permission.requested → Needs user approval +│ ├── permission.completed → Approval result │ ├── tool.execution_start → Tool begins │ ├── tool.execution_partial_result → Streaming tool output (ephemeral, repeated) │ ├── tool.execution_progress → Progress updates (ephemeral, repeated) @@ -969,8 +969,8 @@ This table lists key `data` payload fields. Common envelope fields are documente | `session.usage_checkpoint` | | Session | `totalNanoAiu`, `totalPremiumRequests?` | | `session.task_complete` | | Session | `summary?` | | `session.shutdown` | | Session | `shutdownType`, `codeChanges`, `modelMetrics` | -| `permission.requested` | ✅ | Permission | `requestId`, `permissionRequest` | -| `permission.completed` | ✅ | Permission | `requestId`, `result.kind` | +| `permission.requested` | | Permission | `requestId`, `permissionRequest` | +| `permission.completed` | | Permission | `requestId`, `result.kind` | | `user_input.requested` | ✅ | User Input | `requestId`, `question`, `choices?` | | `user_input.completed` | ✅ | User Input | `requestId` | | `elicitation.requested` | ✅ | User Input | `requestId`, `message`, `requestedSchema` | @@ -984,8 +984,8 @@ This table lists key `data` payload fields. Common envelope fields are documente | `abort` | | Control | `reason` | | `user.message` | | User | `content`, `attachments?`, `agentMode?` | | `system.message` | | System | `content`, `role` | -| `external_tool.requested` | ✅ | External Tool | `requestId`, `toolName`, `arguments?` | -| `external_tool.completed` | ✅ | External Tool | `requestId` | +| `external_tool.requested` | | External Tool | `requestId`, `toolName`, `arguments?` | +| `external_tool.completed` | | External Tool | `requestId` | | `command.queued` | ✅ | Command | `requestId`, `command` | | `command.completed` | ✅ | Command | `requestId` | | `session_limits_exhausted.requested` | ✅ | Session | `requestId`, `maxAiCredits`, `usedAiCredits` |