Add background work to chat state for shells and subagents

[Anthony Kim (anthonykim1)]

Replaces: #475, following the discussion there.
Related: #473. Its interoperability audit found a background task catalog that copilotd exposes only through _meta; this makes background work typed chat state.
Related: microsoft/vscode#336348, microsoft/vscode#337684
Used by: microsoft/vscode#338723

• Add ChatState.backgroundWork: work that keeps running after the tool call that started it returns and will resume the chat when it finishes. Like changesets, it stays off ChatSummary, so it isn't broadcast to every session subscriber; clients read it by subscribing to the chat.
• Model entries as a non-exhaustive BackgroundWork union keyed by kind, with two kinds:
  • shell: its plain-text command, plus an optional terminal URI for its output. Hosts SHOULD set terminal whenever they can show that output. It stays optional because some hosts can't point at a live terminal yet.
  • subagent: its chat, the same chat the spawning tool call's ToolResultSubagentContent.resource points to, instead of repeating the subagent's state.
• Share id, label, startedAt, and _meta across kinds. Shells can be attached (tied to the agent's lifetime) or detached (outliving it). That's provider-specific, so it goes in the shell's _meta rather than a shared field, and other kinds, subagents included, don't carry it.
• Leave out a status. Every entry is unfinished work, and hosts remove entries when the work finishes instead of marking them done.
• Add server-only chat/backgroundWorkSet (upsert by id) and chat/backgroundWorkRemoved (remove by id, no-op when absent), introduced in 0.9.0. id is opaque and unique within the chat across kinds, like inputNeeded entries.
• Keep the list independent of turns. An entry stays listed whether or not the turn that started it is still open, since attached shells can keep that turn open, and turn completion, cancellation, steering, and truncation don't clear it.
• Register both kinds in all five client generators, and update each client's hand-written reducer. Every client keeps entries of kinds it doesn't recognize, and can replace or remove them by id. Go's ChatState.BackgroundWork is a pointer, so a list emptied by removals still encodes as [].
• Regenerate the schema and clients, and add reducer fixtures for adding a shell and a subagent, replacing an entry (which adds its terminal), removing one entry while keeping the other, absent remove, and an unknown kind being kept, replaced, and removed.
• Document the list in the state model guide, and add a change fragment.

Validation

• npm run generate and npm test at dc9ff6b0: passed (505 tests, 100% reducer coverage). Every npm run generate:<lang> step that CI runs (schema, typescript, go, rust, swift, kotlin, dotnet, docs, metadata) then produced no diff.
• gofmt -l, go vet ./..., and go test ./... in clients/go: passed. Without the Go fix, the two unknown-kind fixtures fail.
• cargo fmt --all -- --check and cargo test -p ahp in clients/rust: passed. Kotlin and .NET weren't built locally.
• The CI workflow on dc9ff6b0 passed every job, including the generated-code, formatting, and test checks for Go, Rust, Swift, Kotlin, .NET, and TypeScript.

---

Inspirations from

• The union shape, *Kind discriminant, unexported base interface, and opaque cross-kind id follow SessionInputRequest, SessionInputRequestKind, and SessionInputRequestBase.
• The client reducers' id helpers are copied semantically from sessionInputRequestID and its counterparts in the other clients. Reading id from unrecognized kinds follows the Rust session_input_request_id and .NET SessionInputRequestId helpers.
• terminal is the same subscribable terminal URI as ToolResultTerminalContent.resource, and clients tell plain-text output from a pty by TerminalState.isPty. Keeping it optional follows the doctrine's preference for optional fields.
• A subagent's chat is the spawn edge that ToolResultSubagentContent.resource already exposes and the worker's ChatOrigin records in reverse.
• Keeping the list off ChatSummary follows ChatState.changesets, which clients also only get by subscribing to the chat.
• Removing finished work instead of marking it done follows SessionState.inputNeeded, whose entries are removed once the underlying request resolves.
• Set / Removed naming and reducer behavior follow the keyed-collection convention in general-instructions.instructions.md.
• Putting provider-specific details, like a shell's attached or detached mode, in _meta follows customizations.md and the doctrine's explicit escape hatches.
• The list's scope, work that will resume the chat, comes from what starts a Copilot turn in VS Code today: shell completions, attached or detached, and background agents going idle or finishing.

[Anthony Kim (anthonykim1)]

Wondering if we can use this for the attached/detached badge, e.g. "vscode.copilot.shellAttachment": "detached".

[roblourens]

Would be worth doing a review of the UI across various apps, especially copilot app, and ensure it fits their needs.

It's been a bit since I did that and I'm not sure what the latest is

[Anthony Kim (anthonykim1)]

Would be worth doing a review of the UI across various apps, especially copilot app, and ensure it fits their needs.

roblourens I agree , it seems like copilot app already has ui for listing background activities where at least background shell and subagent shows up:

[Matt Ellis (ellismg)]

From the Copilot App side, I think we could adopt this model for AHP sessions as an active background-work inventory. With the proposal as written, we should be able to:

• show currently active shells and subagents in our background activity UI;
• preserve that inventory across navigation and reconnects through ChatSummary.backgroundWork;
• open a shell terminal when terminal is available;
• open a subagent chat and use its chat state for details such as current activity.

This would be a useful improvement over what we can represent for AHP sessions today. I do not think the remaining items need to block this PR, but matching the full experience we currently provide for local sessions would require some additive protocol extensions in future versions:

• Attached versus detached shells: This affects more than presentation in the App. Running attached shells keep a session in the Working state, while detached shells remain visible but do not. It would be helpful to eventually standardize an attachmentMode-style field rather than relying on a provider-specific _meta key.
• Idle subagents: We show a distinct Idle state for multi-turn agents waiting for another message. We may be able to derive this from the referenced child chat, but the contract should clarify that an idle-but-addressable subagent remains in backgroundWork until it completes or is no longer participating.
• Originating tool-call correlation: Our local UI associates background work with the transcript row that started it. An optional { turnId, toolCallId } origin would let clients make that association without scanning historical tool results and matching resource URIs.
• Completion information: The local UI retains completed, failed, stopped, and cancelled work, including duration and shell exit code. backgroundWorkRemoved currently tells us only that an item disappeared. A future optional completion payload containing the outcome, completion timestamp, and exit code would let clients retain an accurate completed-work row while keeping backgroundWork itself active-only.
• Controls: Local sessions can stop or cancel active work and clear completed entries. This proposal explicitly does not add process controls, so those could be introduced separately through capabilities and an operation keyed by the background-work ID.

Overall, this proposal looks sufficient for us to build the active inventory and navigation portions for AHP sessions. The items above would be follow-up work needed for closer parity with the local-session experience, and they appear compatible with the current design as additive protocol changes.