# Background Tasks

Long-running work can run in the background so the conversation stays responsive. Two execution surfaces support this: **background shell tasks** and **detached subagents**.

## Background Shell Tasks

Pass `background: true` to the `bash` tool to detach a shell command from the foreground turn. The tool returns a `task_id` immediately and the conversation continues.

```
User: run the full test suite
AI: [calls bash with background=true]
     → task_id: abc12345, status: running
AI: Tests are running in the background. I'll check on them shortly.
```

Use `bash_background_status` to poll progress and `bash_task_output` to retrieve full stdout/stderr once complete. Both are READ-tier tools (auto-allowed).

See [Built-in Tools](tools.md) for the full parameter reference.

## Detached Subagents

Pass `detach: true` to the `run_agent` tool to launch an isolated AI session that runs independently. The parent turn ends immediately with a run ID.

Use `agent_run_status` to check progress or wait for the completion notification. Detached agents are not available in exec mode or nested subagents.

See [Built-in Tools](tools.md) for the full parameter reference.

## Completion Notifications

Both surfaces announce completion automatically. The CLI renders a one-line notice:

- **Shell tasks**: `[bg] Task <id> completed (exit 0, 45s)`
- **Detached agents**: `[agent] Run <id> completed (12 calls, 90s)`

The web UI surfaces the same events via SSE.

## Execution Surface Routing

Anteroom advises the AI on which surface to use based on expected task duration:

| Duration | Suggested surface |
|---|---|
| < `background_suggest_seconds` | Inline (foreground) |
| >= `background_suggest_seconds` | Background shell task |
| >= `detach_suggest_seconds` | Detached subagent |

## Configuration

```yaml
cli:
  background_suggest_seconds: 30   # suggest background for tasks >= 30s
  detach_suggest_seconds: 120      # suggest detached subagent for tasks >= 2min
```

Set either to `0` to disable the suggestion for that surface.
