feat: expose backgroundTask(taskId) control request for mid-flight subagent detachment

[leiyangyou]

Problem

The Claude Code CLI internally supports backgrounding foreground subagents mid-flight via Ctrl+B (using backgroundAgentTask() which resolves a backgroundSignal promise and transitions the agent to async execution). However, this capability is not exposed through the Agent SDK's control request protocol.

SDK consumers (e.g. custom UIs built on @anthropic-ai/claude-agent-sdk) can only:

• At spawn time: influence run_in_background: true (but this is the model's decision via tool params, not the application's)
• After spawn: stopTask(taskId) to kill a task, or interrupt() / abortController to kill everything

There is no way to detach a running foreground subagent and let it continue in the background.

This applies to both Agent and Bash tool tasks — both have internal backgrounding machinery in the CLI process, neither is exposed via the SDK.

Proposed Solution

Add a backgroundTask control request alongside the existing stop_task:

// New control request (mirrors existing SDKControlStopTaskRequest)
declare type SDKControlBackgroundTaskRequest = {
    subtype: 'background_task';
    task_id: string;
};

// New method on Query interface (mirrors existing stopTask)
export declare interface Query extends AsyncGenerator<SDKMessage, void> {
    // ... existing methods ...
    stopTask(taskId: string): Promise<void>;       // exists
    backgroundTask(taskId: string): Promise<void>; // new
}

Internally, this would map to the existing backgroundAgentTask() / backgroundTask() functions that already handle the state transition in the CLI process.

Use Case

SDK consumers building custom UIs need to let users background long-running subagents that the model chose to run in the foreground. Currently the only workaround is prompt engineering to make the model use run_in_background: true more aggressively, which is unreliable.

Related Issues

• #9905 — Background Agent Execution (Task tool async support) — addressed run_in_background at spawn time
• #7069 — Native Background Task Management System
• #29011 — No way to list active background tasks programmatically
• #22034 — Background mode in agent frontmatter