v2 Background Work

​

Elevator pitch

What are you proposing to change?

• Terminals and tool calls can outlive the foreground work that started them. A backgrounded shell is a terminal that keeps running after control returns to the model. A watcher or a scheduled wakeup is a tool call that stays pending or in_progress after the session becomes idle.
• Terminals and tool calls can be cancelled individually. Either can advertise capabilities.cancel, and the Client cancels it with a new terminal/cancel or tool_call/cancel request, without cancelling the session’s foreground work.
• State snapshots list the background work. Every state_update can carry a background list referencing the terminals, tool calls, and subagent sessions that are running independently of foreground work. Clients use it to show that something is still running, to warn before closing, and to tell background work apart from stale tool calls and terminals.

​

Status quo

How do things work today and what problems does this cause? Why would we change things?

• Claude Code / Claude Agent SDK:
  • Bash with run_in_background, Ctrl+B, or a command that hits its timeout keeps running after the turn.
  • Subagents run in the background by default.
  • Monitor watches a script or WebSocket.
  • Workflow runs local or remote multi-agent scripts. A workflow can be paused, which stops its agents but keeps its journal so it can be resumed later.
  • ScheduleWakeup and CronCreate start new turns later.
  • The SDK reports these as tasks (task_started, task_updated, task_notification) and sends the full live set in background_tasks_changed. Task statuses include paused.
  • The SDK also reports housekeeping that Claude Code starts on its own, such as memory consolidation, the auto-mode scan, and auto-started WebSocket watchers, and marks those tasks ambient so hosts leave them out of activity indicators. Work the model requests, including Monitor, is not ambient.
• Codex:
  • Unified-exec commands keep running as background terminals after the turn, and collab subagents can outlive the root turn.
  • ThreadStatus has no flag for background terminals, so a thread reports idle while terminals run.
  • Codex has experimental thread/backgroundTerminals/list, /terminate, and /clean requests, and its TUI has /ps and /stop for them.
• Others: Gemini CLI (is_background shells), Cursor (is_background terminal commands), and Cline (“Proceed While Running”) have similar features. opencode’s session status only has idle, busy, and retry.

• Clients can’t tell whether the session is quiet. idle means ready for a new prompt, not “nothing is running”. Clients can’t safely show a session as done, close it to save resources, or warn the user that closing will stop a dev server.
• Unfinished tool calls are ambiguous. Agents often leave stale pending or in_progress tool calls behind, so many Clients mark every unfinished tool call as finished when work ends. That cleanup is wrong for a tool call that is still running in the background, and without that cleanup stale tool calls stay unfinished.
• Background work can’t be stopped individually. v2 terminals are display-only by design. session/cancel only targets the session’s current work, and agents differ on whether it stops background work. Only subagents can be cancelled one at a time.
• Close and resume are underspecified. session/close cancels “any ongoing work”, but nothing says Clients will learn what was stopped. After session/resume, the Client gets a foreground snapshot but no record of background work that is still running.

​

What we propose to do about it

What are you proposing to improve the situation?

​

Background work is terminals, tool calls, and subagents

• Terminals. A process that keeps running after its tool call returns control to the model, such as a backgrounded shell or dev server, is a terminal. It is live until its terminal_update reports exitStatus. The tool call that started it keeps referencing the terminal so the Client can show its output in place, and reports status as the agent’s own tool lifecycle does: it may complete once the process has been handed off, as Claude Code’s Bash tool does, or stay in_progress until the process exits, as Codex’s command items do. Either way, the terminal is what is listed. While a terminal is listed, the Agent SHOULD keep its output current with terminal_output_chunk or replacement snapshots whenever it can read the process output. An Agent that can’t read the output may report only the terminal’s command and, later, its exitStatus. Output is not a liveness signal: a Client MUST NOT treat a terminal as hung or exited because its output is missing or stale. Only the background list and exitStatus say whether it is still running.
• Tool calls. Work that continues without a process of its own, such as a watcher, a workflow, or a scheduled wakeup, keeps reporting status on the same toolCallId. Its output stays in tool call content.
• Subagent sessions. A background child keeps reporting through its subagent association and state.

​

Tool call statuses for background work

• Statuses never go back to pending. When a scheduled tool call fires, the work it triggers is new foreground work, not the tool call running:
  • A scheduled wakeup goes pending → completed when it fires.
  • A recurring cron job stays pending until the job is deleted or the session closes, then becomes completed or cancelled.
• in_progress and paused may alternate any number of times. A paused tool call reaches a final status when it is cancelled, fails, or is discarded.
• How work is paused and resumed is up to the Agent, for example a tool the model calls. This RFD does not add Client-initiated pause or resume.

​

Cancellable tool calls

{
  "sessionUpdate": "tool_call_update",
  "toolCallId": "call_012",
  "title": "Watch deploy logs",
  "kind": "other",
  "status": "in_progress",
  "capabilities": {
    "cancel": {}
  }
}

• capabilities is a nullable patch: omitted leaves it unchanged, null clears it, and an object replaces the whole previous value.
• cancel is an optional, nullable capability object. Omitted or null means unsupported, and {} advertises support. It may carry _meta. A pending or paused tool call may advertise it too, for example to delete a scheduled job or discard a paused workflow.
• An agent SHOULD clear or stop advertising cancel once the tool call reaches a final status.

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tool_call/cancel",
  "params": {
    "sessionId": "sess_abc123",
    "toolCallId": "call_012"
  }
}

• The Client MUST NOT send it unless the tool call currently advertises capabilities.cancel.
• The Agent responds with an empty result once it has accepted the cancellation. The response does not mean the work has stopped. The Agent confirms that with a tool_call_update to a final status, normally cancelled, and may send completed or failed if the work finished first.
• The Agent responds with -32602 (Invalid params) if the tool call is unknown, already final, or not cancellable.
• Cancelling a tool call does not change the foreground state by itself. The Agent decides what, if anything, to tell the model about it.

​

Cancellable terminals

{
  "sessionUpdate": "terminal_update",
  "terminalId": "term_003",
  "command": "npm run dev",
  "cwd": "/workspace/project",
  "capabilities": {
    "cancel": {}
  }
}

• capabilities and cancel follow the same rules as on tool calls. A terminal has no status, so the Agent SHOULD clear or stop advertising cancel once it reports exitStatus.

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "terminal/cancel",
  "params": {
    "sessionId": "sess_abc123",
    "terminalId": "term_003"
  }
}

• The Client MUST NOT send it unless the terminal currently advertises capabilities.cancel.
• The Agent responds with an empty result once it has accepted the cancellation. The response does not mean the process has stopped. The Agent confirms that with a terminal_update that sets exitStatus, for example with the signal used to stop it.
• The Agent responds with -32602 (Invalid params) if the terminal is unknown, has already exited, or is not cancellable.
• Cancellation stops the process. It does not release the terminal: its output remains available for display and replay.
• Cancelling a terminal does not change the foreground state or the status of any tool call that references it. If foreground work is waiting on the process, the Agent reports the tool call’s outcome as it would for any other process exit.

​

The background list on state snapshots

{
  "sessionUpdate": "state_update",
  "state": "idle",
  "stopReason": "end_turn",
  "background": [
    { "type": "terminal", "terminalId": "term_003" },
    { "type": "tool_call", "toolCallId": "call_012" },
    { "type": "tool_call", "toolCallId": "call_019" },
    { "type": "subagent", "sessionId": "sess_child_4" }
  ]
}

• It is a snapshot. Each state_update is a complete snapshot, so background is too. A concrete list replaces the previous one, and [] means no background work is running.
• Omitted or null means the agent is not reporting background work. It does not mean “nothing is running”. An agent that reports background work MUST include background on every state_update for the session. If a later snapshot omits it anyway, or it is malformed, the Client treats background work as unknown until a list is reported again: it does not keep the previous list, consider the session quiet, or treat unfinished tool calls or running terminals as abandoned.
• The agent re-sends the state when the list changes. When background work starts or ends, the Agent SHOULD send a repeated state_update with the current state and the updated list. A repeated snapshot is not a state transition (State Transitions), and a repeated idle without a new stop reason is not a new completion.
• Items are announced before they are listed and finalized before they are removed. The Agent MUST send a terminal_update for a terminal, a tool_call or tool_call_update for a tool call, or a subagent_update for a child, before the first snapshot that lists it. When a terminal exits or a tool call ends, the Agent MUST send its exitStatus or final status before the snapshot that removes it from the list, so a Client never treats finished work as abandoned.
• Follow-up work is reported with the removal. When the end of background work starts new foreground work, for example a follow-up response to a finished background task, the Agent SHOULD report running in the same snapshot that removes the item, or earlier. It SHOULD NOT send idle with an empty list followed immediately by running.
• Items reference existing entities. terminal items reference a terminal by terminalId in this session. tool_call items reference a tool call by toolCallId in this session. subagent items reference a child session associated with this session through subagent_update. The list is extensible through the usual enum variant extension rules.
• Unknown items still count. An item with an unknown type does not invalidate the list. It still means background work is running, even when the Client cannot show what it is, so a list of only unknown items is not empty.
• Paused and pending tool calls stay listed. A pending or paused tool call is live background work: closing the session discards it, and the Client should not treat it as abandoned.
• Only background work is listed. A terminal, tool call, or child session that foreground work is currently waiting on is foreground work and is not listed. Work moves into the list when it detaches, for example when a shell is backgrounded mid-turn and its terminal is listed.
• A background child is listed while it has anything running. Subagent sessions are reusable, and idle does not end them. A detached child is listed while its state is not idle, or while its own background list is non-empty or not reported. An idle child with no background work of its own is not listed, even though it remains associated.
• Each piece of work is listed once. Process-backed work is listed as its terminal. The Agent MUST NOT also list a tool call whose only live work is a listed terminal, so a Client counting items never shows one shell as two tasks.

• Whether the session is quiet. The session has nothing running when the state is idle and background is []. When background only contains pending or paused tool calls, the session is idle with work scheduled or suspended, and nothing is running right now. Because listed children stay listed while their own background work runs, this also covers descendants. Quiet describes the session at that snapshot, not a promise that it will stay quiet. An Agent may not know ahead of time that finished work will start a follow-up. A Client that frees resources when a session becomes quiet SHOULD wait a short grace period after the snapshot that empties the list.
• What closing will stop. The Client can warn before session/close, for example “Closing will stop 2 background tasks”.
• Which unfinished tool calls and terminals are still live. A Client MAY treat a pending, in_progress, or paused tool call, or a terminal without exitStatus, that is not in the latest reported background list as abandoned once the session is idle. A tool call that references a listed terminal is live, even though it is not listed itself. A Client MUST NOT treat anything as abandoned when background is not reported.

​

Cancellation, close, and resume

• When the Client preemptively marks non-finished tool calls as cancelled after sending session/cancel, it SHOULD skip tool calls in the latest background list and tool calls that reference a listed terminal.
• Pending permission requests for listed work stay open. Today the Client MUST answer every pending permission request in the session with cancelled on session/cancel. This RFD narrows that to requests for the cancelled foreground work, which is how elicitations already work: the Agent cancels any other request that no longer applies with $/cancel_request.
• The Client tells the two apart through the request’s subject. A permission request for listed work SHOULD reference the listed item in subject, by toolCallId or terminalId, and the Agent MUST list that work before sending the request. On session/cancel, the Client answers with cancelled every pending request whose subject does not reference work in the latest background list, including requests without a subject. At worst, the Agent asks again for background work it failed to reference.
• Requests from a background subagent arrive under the child’s session id, so session/cancel on the parent does not affect them.
• When foreground work fails with the error stop reason, the unfinished tool calls the Agent gives a final status are those of the failed work. Listed background terminals and tool calls, and tool calls that reference a listed terminal, keep running.
• Background work is stopped individually with terminal/cancel, tool_call/cancel, or by cancelling the subagent’s session, or all at once with session/close.

• After a successful close, the Client SHOULD treat every listed tool call, and every tool call that references a listed terminal, that has not reported a final status as cancelled, and every listed terminal that has not reported exitStatus as exited with no known exit status. It MUST answer any pending permission request for listed work with cancelled.
• The Agent MAY send final updates for listed work before responding, but doesn’t have to. This matches the subagents RFD, where closing a parent cancels background children without requiring new notifications for them.
• Work that is deliberately not owned by the session and survives its close, such as a durable cron job saved in the project, is out of scope and is not listed.

• Before that snapshot, the Agent MUST send a current terminal_update for each listed terminal, a current tool_call_update for each listed tool call, and a current subagent_update for each listed child, that the requested replay did not already deliver at its current state. When no replay was requested, this means sending all of them, so a Client with no history still knows what each item is.

​

Shiny future

How will things will play out once this feature exists?

​

Implementation details and plan

Tell me more about your implementation. What is your detailed implementation plan?

​

Schema

• ToolCallStatus::Pending: update the doc comment to “hasn’t started running yet”, listing streaming input, pending approval, and scheduling as examples.
• ToolCallStatus::Paused: add a variant for work that has started and is suspended until resumed. Older v2 Clients receive it through the existing Other fallback.
• ToolCallUpdate.capabilities: add MaybeUndefined<ToolCallCapabilities>. ToolCallCapabilities has cancel: Option<ToolCallCancelCapability> and _meta, mirroring SubagentSessionCapabilities. It is display-only metadata, so a malformed value falls back to unsupported (DefaultOnError).
• tool_call/cancel: add CancelToolCallRequest { session_id, tool_call_id, _meta } and CancelToolCallResponse { _meta }, client-to-agent. The trait method is cancel_tool_call and the method names entry is tool_call_cancel.
• TerminalUpdate.capabilities: add MaybeUndefined<TerminalCapabilities>, with cancel: Option<TerminalCancelCapability> and _meta, handled like ToolCallCapabilities.
• terminal/cancel: add CancelTerminalRequest { session_id, terminal_id, _meta } and CancelTerminalResponse { _meta }, client-to-agent. The trait method is cancel_terminal and the method names entry is terminal_cancel. This is separate from the v1 Client terminal methods, which v2 removes.
• background on state updates: add background: Option<Vec<BackgroundWork>> to RunningStateUpdate, RequiresActionStateUpdate, and IdleStateUpdate, and to UnknownStateUpdate under unstable_subagents. An Agent that can’t tell what its foreground work is doing may still know what is running in the background.
  • BackgroundWork is an internally tagged enum on type: Terminal { terminal_id, _meta }, ToolCall { tool_call_id, _meta }, Subagent { session_id, _meta }, and an Other fallback that rejects known discriminators.
  • The Client acts on this list when it cleans up tool calls and terminals and warns before close. Unknown variants are handled by the Other fallback and do not invalidate the list. They still indicate background work, even when the Client cannot interpret their details. If an item with a recognized type fails validation, the entire background field is treated as unreported. That way a damaged list never makes running work look abandoned.
• Subagents: SubagentUpdate.state mirrors the child’s StateUpdate, so the child’s own background list shows up there too. No separate change is needed.

​

Documentation

• prompt-lifecycle.mdx: in Foreground and Background Work, describe terminals, tool calls, and subagents as the representation of background work, and add the background list to Session States. In Cancellation, say that session/cancel does not stop listed work and that Clients skip it when they preemptively mark tool calls as cancelled.
• tool-calls.mdx: the generalized pending definition, the paused status, tool calls that outlive foreground work, capabilities, and tool_call/cancel. In the terminal section, terminals that outlive their tool call, keeping their output current, terminal capabilities, and terminal/cancel.
• tool-calls.mdx, in Requesting Permission: a request for background work references the listed item in subject.
• Terminal Output RFD: note that terminals are display-only except for the opt-in cancellation added here.
• tool-calls.mdx and cancellation.mdx: on session/cancel, Clients answer pending permission requests for the cancelled foreground work with cancelled, not every pending permission request in the session.
• session-setup.mdx: what session/close does with listed work, how resume restores the list, and that session/fork doesn’t copy it.
• migration.mdx: mention the background list where it describes idle and background activity, and that session/cancel no longer cancels permission requests for background work.
• Subagents RFD: the Client’s optimistic cancellation of a cancelled session’s unfinished tool calls skips tool calls in that session’s background list.
• Each change also goes into the matching docs/protocol/v2/draft/ page.

​

Adapters

​

Phases

1. Land the schema changes behind unstable_protocol_v2 with draft docs.
2. Implement in claude-agent-acp and codex-acp, and in at least one Client.
3. Adjust from that experience before v2 is stabilized.

​

Frequently asked questions

What questions have arisen over the course of authoring this document or during subsequent discussions?

​

Why not a single “background activity” boolean on the idle state?

​

Why not a new background task entity?

​

Why list the terminal instead of the launching tool call?

​

Why does terminal/cancel say “cancel” instead of “kill”?

​

Doesn’t this make terminals more than a display surface?

​

Why put the list on state_update instead of a separate update?

​

Why can’t Clients work out background work from tool call and terminal statuses alone?

​

Why are terminal/cancel and tool_call/cancel requests instead of notifications like session/cancel?

​

Why doesn’t session/cancel stop background work?

​

What about work that outlives the session?

​

Should an agent that only writes output to a file use a tool call instead of a terminal?

​

Why is there no ambient flag on list items?

​

Why add paused instead of using pending or _meta?

​

Do we need a “time of next run” for scheduled tool calls?

​

Should the list say whether finishing the work will start a new agent turn?

​

Is there a v1 form?

​

Revision history

• 2026-10-27: Added a paused tool call status. Defined background work as work the user can reason about, so agent-internal housekeeping is not listed. Unknown item types still count as background work. Agents keep listed terminals’ output current. Permission requests for background work reference the listed item, and session/cancel answers every other request. Noted that claude-agent-acp must declare perTaskStopAffordance.
• 2026-10-26: Terminals are background work in their own right. A backgrounded process is listed as its terminal, whether its launching tool call completes or stays in_progress, and terminals can advertise capabilities.cancel and be stopped with terminal/cancel. Added ordering rules: items are announced before they are listed, final statuses come before removal, and follow-up work reports running with the removal. Defined when background subagents are listed, how Clients handle a list that stops being reported, and a grace period before releasing quiet sessions. Added a v1 FAQ.
• 2026-10-21: Initial draft.