# tasks — Manual

## What it does
Manages background tasks you started with `"background": true` on `terminal` (run), `ssh_exec`, `peer`, `spawn_agent` or `code_exec`. A detached call returns a `task_id` like `bt-1a2b3c4d` immediately; the real result arrives later — as a note at the start of your next turn, and via `task_update` events.

**Background tasks are NOT stopped by run stop.** Only `cancel` kills them.

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `action` | yes | `list` \| `check` \| `wait` \| `cancel` |
| `task_id` | for `check`/`wait`/`cancel` | The `bt-...` id returned when the task was started. |
| `timeout` | for `wait` | Seconds to block waiting for completion (default 120, hard cap 120). |

## Actions

### `list`
All background tasks for this session with status and (for finished ones) a result preview. Use this to re-orient after context loss or reconnect.

### `check`
Status of one task: `running` / `completed` / `failed` / `cancelled`, plus result preview (≤2000 chars) and, for background sub-agents, the latest events from its progress ring. Non-blocking.

### `wait`
Blocks the turn until the task finishes or `timeout` elapses. Use ONLY when the next step needs the result — otherwise keep working and let the note arrive.

### `cancel`
Cooperatively stops a running task (its stop-event fires and its asyncio task is cancelled). Returns an error if the task is not running or belongs to another session.

## How results reach you

1. **Completion note** — at the start of your next turn, finished background tasks are injected as a system note `[Background task results]` with one line per task (`bt-... (tool) status: preview`). Up to `task_notes_per_turn` notes are coalesced; older ones stay pending — check them with `list`/`check`.
2. **Live `task_update`** — the user's client shows progress in real time; you don't need to act on it.

**Do not start new background tasks merely because a results note arrived** — the note is a report, not a request.

## Usage pattern

```json
{"action": "list"}
{"action": "check", "task_id": "bt-1a2b3c4d"}
{"action": "wait", "task_id": "bt-1a2b3c4d", "timeout": 30}
{"action": "cancel", "task_id": "bt-1a2b3c4d"}
```

## Limits and lifecycle
- Caps: `tasks_max_per_session` (5) concurrent per session, `tasks_max_global` (20) server-wide, `tasks_max_spawn` (2) background sub-agents per session, `tasks_rate_limit` (10 spawns / 5 min per session). Exceeding a cap fails the detach — run the tool inline instead.
- Finished tasks are kept for `tasks_ttl_sec` (1 hour), then reaped; the ring of sub-agent events keeps the last `tasks_event_buffer_size` (50; 200 for spawn tasks).
- Tasks do not survive a server restart.