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.

Timeout of detached tool calls

When terminal (run), code_exec or ssh_exec is detached and you did not pass timeout, the executor lifts it to 300 s for the detached run only. A shorter default (20-60 s) would mark long commands "completed" before they actually end. If your command can legitimately run longer than 300 s, pass timeout explicitly (max 300) — or prefer a persistent terminal (action: "open" + streaming output) for truly long jobs.

Parameters

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

{"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.