anthropics / anthropics/claude-agent-sdk-typescript
feat: expose backgroundTask(taskId) control request for mid-flight subagent detachment
- Dominant language
- Shell
- Stars
- 1.8k
- Forks
- 226
- PR merge metrics
- No merged PRs in 30d
Description
## 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`:
```typescript
// 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 {
// ... existing methods ...
stopTask(taskId: string): Promise; // exists
backgroundTask(taskId: string): Promise; // 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
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.