microsoft / microsoft/vscode

Public API to observe agent/subagent chat session lifecycle & status from an extension

Open
#325,507 8 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.