docs: add streaming session events field-level reference guide

[patniko]

Summary

Adds docs/guides/streaming-events.md — a comprehensive field-level reference for all streaming session event types.

Motivation

From a user request: the Data class on session events has many fields (arguments, tool_name, tool_call_id, tool_requests, etc.) but there's no documentation telling you which fields are actually populated on which event types. The only way to find out today is to read SDK source code.

What's included

• Per-event field tables for all ~40 event types with required/optional markers and descriptions
• Ephemeral vs persisted classification for every event
• Agentic turn flow diagram (Mermaid) showing the typical event ordering
• Quick reference summary table — all events at a glance with key fields
• Multi-language subscription examples (TypeScript, Python, Go, .NET)
• Permission request breakdown — the discriminated union across all 7 kind variants
• SDK type difference notes (unified Data in Python/Go vs per-event types in .NET vs discriminated union in TS)

Validation

All code blocks pass just validate-docs (213 blocks, 0 failures).

[Copilot]

Pull request overview

Adds a new documentation guide that aims to provide a field-level reference for Copilot SDK streaming session event types, including example subscriptions and per-event data payload field tables.

Changes:

• Introduces a new guide: docs/guides/streaming-events.md.
• Documents the session event envelope, event categories, and an agentic turn flow diagram.
• Provides per-event data field tables and a quick-reference table of event types.

Comments suppressed due to low confidence (5)

docs/guides/streaming-events.md:621

• exit_plan_mode.requested.requestId references session.respondToExitPlanMode(), but there is no public respondToExitPlanMode API in the SDKs. Please remove/replace this reference and document the real way to handle this request event (or clarify that the event is informational-only for SDK consumers).

| Data Field | Type | Required | Description |
|------------|------|----------|-------------|
| `requestId` | `string` | ✅ | Use this to respond via `session.respondToExitPlanMode()` |
| `summary` | `string` | ✅ | Summary of the plan |
| `planContent` | `string` | ✅ | Full plan file content |
| `actions` | `string[]` | ✅ | Available user actions (e.g., approve, edit, reject) |
| `recommendedAction` | `string` | ✅ | Suggested action |

docs/guides/streaming-events.md:638

• command.queued.requestId references session.respondToQueuedCommand(), but there is no public respondToQueuedCommand API in the SDKs. Please update the description to avoid pointing to a nonexistent method and clarify how SDK consumers are expected to handle/acknowledge queued commands (or that it’s informational).

| Data Field | Type | Required | Description |
|------------|------|----------|-------------|
| `requestId` | `string` | ✅ | Use this to respond via `session.respondToQueuedCommand()` |
| `command` | `string` | ✅ | The slash command text (e.g., `/help`, `/clear`) |

docs/guides/streaming-events.md:429

• permission.requested.requestId says to respond via session.respondToPermission(), but none of the SDKs expose a respondToPermission API. Permission requests are handled via the session’s permission callback configured at session creation (e.g., onPermissionRequest / OnPermissionRequest / on_permission_request). The description should be updated to reflect the actual public API so users aren’t sent looking for a nonexistent method.

| Data Field | Type | Required | Description |
|------------|------|----------|-------------|
| `requestId` | `string` | ✅ | Use this to respond via `session.respondToPermission()` |
| `permissionRequest` | `PermissionRequest` | ✅ | Details of the permission being requested |

docs/guides/streaming-events.md:463

• user_input.requested.requestId says to respond via session.respondToUserInput(), but the SDKs don’t expose such a method. User input requests are answered through the user input handler configured at session creation (onUserInputRequest / OnUserInputRequest / on_user_input_request), so the field description should point at that mechanism instead.

| Data Field | Type | Required | Description |
|------------|------|----------|-------------|
| `requestId` | `string` | ✅ | Use this to respond via `session.respondToUserInput()` |
| `question` | `string` | ✅ | The question to present to the user |
| `choices` | `string[]` | | Predefined choices for the user |
| `allowFreeform` | `boolean` | | Whether free-form text input is allowed |

docs/guides/streaming-events.md:482

• elicitation.requested.requestId says to respond via session.respondToElicitation(), but there is no corresponding public API in the SDKs. Please adjust the wording to avoid referencing nonexistent methods (e.g., describe requestId as a correlation ID, or document the actual response mechanism if one exists).

| Data Field | Type | Required | Description |
|------------|------|----------|-------------|
| `requestId` | `string` | ✅ | Use this to respond via `session.respondToElicitation()` |
| `message` | `string` | ✅ | Description of what information is needed |
| `mode` | `"form"` | | Elicitation mode (currently only `"form"`) |
| `requestedSchema` | `{ type: "object", properties, required? }` | ✅ | JSON Schema describing the form fields |

[Copilot]

external_tool.requested.requestId says to respond via session.respondToExternalTool(), but the SDKs don’t expose such a method. In the Node/Go/Python/.NET SDKs, external tool calls are handled by registering tool handlers (session config tools/Tools) and the SDK replies over RPC automatically. Update this description to reflect the actual API.

This issue also appears in the following locations of the same file:

• line 615
• line 635
• line 426
• line 458
• line 477

[Copilot]

The guide claims to be a comprehensive reference for “all” session event types, but several event types defined in the SDK-generated session event enums/schemas are missing from both the per-event sections and this “All Event Types” table (e.g. hook.start/hook.end, pending_messages.modified, session.start, session.resume, session.snapshot_rewind, session.mode_changed, session.model_change, session.plan_changed, session.warning, session.truncation, session.workspace_file_changed, session.info, session.handoff). This is likely to mislead readers into thinking these events don’t exist. Either add the missing event types (and their field tables) or explicitly narrow the scope (e.g., “common streaming turn events”) and link to the generated event type list for the full set.