Public API to observe agent/subagent chat session lifecycle & status from an extension
- Dominant language
- TypeScript
- Stars
- 193k
- Forks
- 42.4k
- PR merge metrics
- PR metrics pending
Description
### Problem
There is currently no public extension API to *observe* the lifecycle and status of the built-in Copilot agent's chat sessions and, in particular, its **subagent delegations**. The proposed `chatSessionsProvider` API only lets an extension *provide* its own session type (the "third-party" option in the Agents window) and report status on its own `ChatSessionItem`s. It does not expose an event stream for the built-in agent's sessions or the parent→subagent relationships created via the `agent`/`runSubagent` tool.
As a result, extensions that want to visualize or react to agent activity must resort to brittle workarounds (e.g. writing a signal file and injecting instructions into `copilot-instructions.md` so the model updates it on every delegation).
### Concrete use case
We maintain an extension that renders `.agent.md` agents as an interactive graph. We already derive the delegation topology from the native `agents:` frontmatter, but to animate *live* activity (which agent is processing, waiting for input, completed, or failed) we currently rely on a file-based "signal protocol" injected into the workspace instructions. This is fragile and pollutes the user's repo.
### What we'd like
A read-only, opt-in API to observe chat/agent sessions, e.g.:
```ts
export namespace chat {
// Fires when any session (built-in or provided) changes status.
export const onDidChangeChatSessionStatus: Event<{
readonly sessionId: string;
readonly parentSessionId?: string; // set for subagents
readonly agentName?: string; // e.g. the custom agent used
readonly status: ChatSessionStatus; // Failed | Completed | InProgress | NeedsInput
}>;
// Fires when a subagent is spawned / finishes.
export const onDidChangeSubagents: Event<{
readonly parentSessionId: string;
readonly subagentSessionId: string;
readonly agentName?: string;
readonly kind: 'started' | 'ended';
}>;
}
```
Reusing the existing `ChatSessionStatus` enum (`Failed`/`Completed`/`InProgress`/`NeedsInput`) would be ideal.
### Why not existing APIs
- `chatSessionsProvider` (proposed): only for extensions that *provide* sessions; it can't observe the built-in agent, and its `onDidChangeChatSessionItemState` reflects archived/pinned state, not run status.
- Chat participant / language model APIs: only see requests routed *to* the extension, not the built-in agent's autonomous delegations.
- The Agents window already surfaces this info in the UI (running-subagents chip, read-only subagent chats), so the data exists internally — we're asking to expose a minimal, read-only slice of it.
### Additional context
Privacy/opt-in: gated behind user consent like the Language Model API, read-only, no message content required — just lifecycle + status + parent/child links.
Contributor guide
Research direction
Start by reading the proposed chatSessionsProvider API, the existing ChatSessionStatus enum, and the chat participant and language model APIs described in the issue. Compare those surfaces with the Agents window's running-subagents and read-only subagent chat behavior. Done means a reviewed, privacy-conscious public API design and implementation that exposes lifecycle status and parent/child session relationships without message content.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, developer-experience
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100