Skip to content

docs(unstable-v2): cover background work and cancel controls in the migration guide - #2866

Merged
benbrandt merged 1 commit into
mainfrom
docs/v2-migration-background-controls
Nov 18, 2026
Merged

benbrandt merged 1 commit into
mainfrom
docs/v2-migration-background-controls

Conversation

@benbrandt

Copy link
Copy Markdown
Member

Adds the Background Work additions to the migration guide.

The guide never mentioned tool_call/cancel or the paused status. It left capabilities out of the tool call and terminal fields, and did not describe the background list on state_update. Both checklists said terminals have no Client controls, which contradicts terminal/cancel. A Client built from the guide never offers to stop a tool call and treats paused as an unknown status.

Migration guide only. The tool calls and prompt lifecycle pages already define all of this.

Changes

  • Method table. New rows for tool_call/cancel and terminal/cancel.
  • Update table. tool_call_update gains the paused status and the capabilities field. state_update carries an optional background list.
  • New section "Background work and cancel controls", under Tool calls: the background list, the paused status, capabilities.cancel with the two cancel methods, and what session/cancel and session/close do with listed work.
  • Tool calls and terminal sections. The status enum adds paused as well as cancelled, and capabilities is a patch field on terminal_update.
  • Checklists.
    • The two terminal items no longer say there are no Client controls.
    • The Client cancellation item says not to answer every pending permission request on session/cancel.
    • Each checklist gets a background work item at the end.

Checks

Prettier and typos pass, and all internal links in the migration guide resolve.

…igration guide

The migration guide never mentioned `tool_call/cancel` or the `paused`
status, left `capabilities` out of the tool call and terminal fields, and
did not describe the `background` list. Both checklists said terminals have
no Client controls, which contradicts `terminal/cancel`.

- Add `tool_call/cancel` and `terminal/cancel` to the method table, and
  `paused`, `capabilities`, and the `background` list to the update table.
- Add a "Background work and cancel controls" section under Tool calls.
- Say that the `status` enum adds `paused`, and that `capabilities` is a
  patch field on `terminal_update`.
- Fix the two terminal checklist items, add the permission change to the
  Client cancellation item, and add a background work item to each
  checklist.

Migration guide only. The spec pages already define all of this.
@benbrandt
benbrandt requested a review from a team as a code owner November 18, 2026 10:05
@benbrandt
benbrandt merged commit a2ea598 into main Nov 18, 2026
10 checks passed
@benbrandt
benbrandt deleted the docs/v2-migration-background-controls branch November 18, 2026 10:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant