docs: document complete sub-agent event data fields (#2072)

* docs: document complete sub-agent event data fields

The event table for sub-agent lifecycle events was missing several
fields that are available in the typed event interfaces:

- subagent.started: add \model?\
- subagent.completed: add \model?\, \durationMs?\, \	otalTokens?\, \	otalToolCalls?\
- subagent.failed: add \model?\, \durationMs?\, \	otalTokens?\, \	otalToolCalls?\

Also update the Node.js code example to demonstrate accessing
the performance metrics (duration, tokens, tool calls) from
completed/failed events.

* docs: complete subagent event references

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: j-zhangyiyuan <j-zhangyiyuan@microsoft.com>
Co-authored-by: Steve Sanderson <1101362+SteveSandersonMS@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 4 people

docs/features/custom-agents.md

@@ -445,9 +445,9 @@ Sub-agent-originated session events share the parent session stream and include
 | Event | Emitted when | Data |
 |-------|-------------|------|
 | `subagent.selected` | Runtime selects an agent for the task | `agentName`, `agentDisplayName`, `tools` |
-| `subagent.started` | Sub-agent begins execution | `toolCallId`, `agentName`, `agentDisplayName`, `agentDescription` |
-| `subagent.completed` | Sub-agent finishes successfully | `toolCallId`, `agentName`, `agentDisplayName` |
-| `subagent.failed` | Sub-agent encounters an error | `toolCallId`, `agentName`, `agentDisplayName`, `error` |
+| `subagent.started` | Sub-agent begins execution | `toolCallId`, `agentName`, `agentDisplayName`, `agentDescription`, `model?` |
+| `subagent.completed` | Sub-agent finishes successfully | `toolCallId`, `agentName`, `agentDisplayName`, `model?`, `durationMs?`, `totalTokens?`, `totalToolCalls?` |
+| `subagent.failed` | Sub-agent encounters an error | `toolCallId`, `agentName`, `agentDisplayName`, `error`, `model?`, `durationMs?`, `totalTokens?`, `totalToolCalls?` |
 | `subagent.deselected` | Runtime switches away from the sub-agent |—|
 
 ### Subscribing to events
@@ -466,11 +466,15 @@ session.on((event) => {
 
         case "subagent.completed":
             console.log(`✅ Sub-agent completed: ${event.data.agentDisplayName}`);
+            if (event.data.durationMs !== undefined) console.log(`  Duration: ${event.data.durationMs}ms`);
+            if (event.data.totalTokens !== undefined) console.log(`  Tokens: ${event.data.totalTokens}`);
+            if (event.data.totalToolCalls !== undefined) console.log(`  Tool calls: ${event.data.totalToolCalls}`);
             break;
 
         case "subagent.failed":
             console.log(`❌ Sub-agent failed: ${event.data.agentDisplayName}`);
             console.log(`  Error: ${event.data.error}`);
+            if (event.data.durationMs !== undefined) console.log(`  Duration: ${event.data.durationMs}ms`);
             break;
 
         case "subagent.selected":

docs/features/streaming-events.md

@@ -741,6 +741,7 @@ A custom agent was invoked as a sub-agent.
 | `agentName` | `string` | ✅ | Internal name of the sub-agent |
 | `agentDisplayName` | `string` | ✅ | Human-readable display name |
 | `agentDescription` | `string` | ✅ | Description of what the sub-agent does |
+| `model` | `string` | | Model the sub-agent will run with, when known at start |
 
 ### `subagent.completed`
 
@@ -751,6 +752,10 @@ A sub-agent finished successfully.
 | `toolCallId` | `string` | ✅ | Matches the corresponding `subagent.started` |
 | `agentName` | `string` | ✅ | Internal name |
 | `agentDisplayName` | `string` | ✅ | Display name |
+| `model` | `string` | | Model used by the sub-agent |
+| `durationMs` | `number` | | Wall-clock execution duration in milliseconds |
+| `totalTokens` | `number` | | Total input and output tokens consumed |
+| `totalToolCalls` | `number` | | Total tool calls made |
 
 ### `subagent.failed`
 
@@ -762,6 +767,10 @@ A sub-agent encountered an error.
 | `agentName` | `string` | ✅ | Internal name |
 | `agentDisplayName` | `string` | ✅ | Display name |
 | `error` | `string` | ✅ | Error message |
+| `model` | `string` | | Model selected for the sub-agent, when known |
+| `durationMs` | `number` | | Wall-clock execution duration in milliseconds |
+| `totalTokens` | `number` | | Total input and output tokens consumed before failure |
+| `totalToolCalls` | `number` | | Total tool calls made before failure |
 
 ### `subagent.selected`
 
@@ -966,9 +975,9 @@ This table lists key `data` payload fields. Common envelope fields are documente
 | `user_input.completed` | ✅ | User Input | `requestId` |
 | `elicitation.requested` | ✅ | User Input | `requestId`, `message`, `requestedSchema` |
 | `elicitation.completed` | ✅ | User Input | `requestId` |
-| `subagent.started` | | Sub-Agent | `toolCallId`, `agentName`, `agentDisplayName` |
-| `subagent.completed` | | Sub-Agent | `toolCallId`, `agentName`, `agentDisplayName` |
-| `subagent.failed` | | Sub-Agent | `toolCallId`, `agentName`, `error` |
+| `subagent.started` | | Sub-Agent | `toolCallId`, `agentName`, `agentDisplayName`, `model?` |
+| `subagent.completed` | | Sub-Agent | `toolCallId`, `agentName`, `agentDisplayName`, `model?`, `durationMs?`, `totalTokens?`, `totalToolCalls?` |
+| `subagent.failed` | | Sub-Agent | `toolCallId`, `agentName`, `error`, `model?`, `durationMs?`, `totalTokens?`, `totalToolCalls?` |
 | `subagent.selected` | | Sub-Agent | `agentName`, `agentDisplayName`, `tools` |
 | `subagent.deselected` | | Sub-Agent | *(empty)* |
 | `skill.invoked` | | Skill | `name`, `path`, `content`, `allowedTools?` |