[benbrandt]

Implements phase 1 of the v2 Background Work RFD: the schema changes from its "Schema" section and the draft docs. It's v2-only, so it's covered by unstable_protocol_v2 and has no feature flag of its own. The subagent list item and background on the unknown state also need unstable_subagents.

Schema

ToolCallStatus = "pending" | "in_progress" | "paused" | "completed" | "failed" | "cancelled" | string

ToolCallUpdate / TerminalUpdate {
  ...,
  capabilities?: { cancel?: { _meta? } | null, _meta? } | null   // patch: omitted = unchanged, null = clear
}

// client → agent, empty results
tool_call/cancel { sessionId, toolCallId, _meta? }
terminal/cancel  { sessionId, terminalId, _meta? }

// on running / requires_action / idle (and unknown) state snapshots
background?: BackgroundWork[] | null
BackgroundWork =
  | { type: "terminal",  terminalId, _meta? }
  | { type: "tool_call", toolCallId, _meta? }
  | { type: "subagent",  sessionId,  _meta? }   // unstable_subagents
  | { type: string, ... }                       // custom or future

• paused: a new ToolCallStatus variant. Older v2 Clients receive it through the existing Other fallback. pending now means "hasn't started running yet", with scheduling as one example.
• capabilities: follows the subagent capability pattern (SubagentSessionCapabilities), as the RFD specifies. The types are ToolCallCapabilities/ToolCallCancelCapabilities and TerminalCapabilities/TerminalCancelCapabilities. The RFD named the cancel types in the singular, but they're plural here to match every other capability type, including SessionCancelCapabilities. They're display hints, so a malformed value falls back to unsupported.
• background:
  • Unknown items: the custom-item fallback (OtherBackgroundWork) rejects known type values, the same way OtherStateUpdate does. A malformed terminal or tool_call item can't fall through to it.
  • Malformed lists: following the RFD, the field is DefaultOnError with no per-item skipping, so a malformed list counts as not reported rather than as an empty list.
• Accessor: StateUpdate::background() reads the list without matching on each state. It returns None for custom states.
• Item type names: the RFD named the variants but not their types. They're BackgroundTerminal, BackgroundToolCall, BackgroundSubagent and OtherBackgroundWork. I added a revision history entry to the RFD saying so.

Docs

Each change is made in the stable v2 page and its draft/ copy. The subagent details only go in the draft copies, since only the draft pages describe subagents.

• prompt-lifecycle:
  • New "Background work" section: what counts as background work, the background list and its rules, and what Clients learn from it.
  • Session states: points to the list.
  • Cancellation: listed work keeps running, preemptive marking skips it, and permission requests are told apart by subject.
  • Failures: listed work isn't part of the failed work.
• tool-calls: the paused status and its display and transition guidance, a "Cancelling tool calls" section, a "Cancelling terminals" section, and the rule that permission requests for background work reference the listed item in subject.
• cancellation: session/cancel only answers permission requests for foreground work.
• session-setup: close stops listed work and tells the Client how to finalize it, resume restores the list after announcing each item, and (draft only) a fork starts with no background work.
• migration: a sentence on the background list and the narrower cancel rule, and an update to the line saying terminals have no control semantics, since they now have opt-in cancellation.
• RFDs:
  • Subagents RFD: optimistic cancellation skips listed work.
  • v2 overview RFD: the change list includes background work.
  • Background Work RFD: a phase 1 entry in its revision history.

Phases 2 and 3 of the RFD (adapters and a Client implementation, then adjustments) aren't part of this PR.