Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SteveSandersonMS merged 2 commits into from
Jul 28, 2026
+19 −6
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
710e20a
docs: document complete sub-agent event data fields
Jul 24, 2026
7dc169a
docs: complete subagent event references
SteveSandersonMS Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions docs/features/custom-agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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":
Expand Down
15 changes: 12 additions & 3 deletions docs/features/streaming-events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -733,6 +733,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`

Expand All @@ -743,6 +744,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`

Expand All @@ -754,6 +759,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`

Expand Down Expand Up @@ -958,9 +967,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?` |
Expand Down