anthropics / anthropics/claude-agent-sdk-typescript

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

Open
#275 1 comment 1 reaction 0 assignees View on GitHub
enhancement
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.