start_task
Launch a background coding task and get a task ID for immediate polling. Retrieve full engine results later, with queue limits and rollback tracking.
Instructions
Start a detached BoteX task and return its task_id immediately.
Runs the same engine as run_subagent, but returns instantly with a
task_id for polling via get_task_status. Concurrency is bounded by
engine.max_concurrent_tasks and the queue by engine.max_queued_tasks —
a full queue returns status TOO_MANY_QUEUED.
The capability/limits arguments are identical to run_subagent —
same contracts, same pre-authorization semantics:
mode: capability preset — 'readonly' (read tools only; the contract is an analysis report), 'edit' (read + write; default), 'destructive' (+ delete/move), 'full' (+ run_command). Empty = engine.default_mode.
allow_destructive / allow_exec / allow_net only ever WIDEN the preset, never narrow it — a readonly task cannot gain file writes. allow_exec additionally requires exec.enabled=true in the config. None of these is a sandbox: grant them only with the user's consent.
output_path makes the contract file_output: DONE requires the file to exist, be non-empty, and pass the syntax gate (mutating mode).
verify_command is an allowlisted command that must pass before DONE is accepted — it runs even when the task made no writes. Requires exec authorization.
recipe: Optional operational persona / workflow prompt (e.g. 'planner', 'code-explorer', 'reviewer', 'security-reviewer', 'build-resolver', 'tdd').
max_turns / max_tokens / max_duration_s / budget_limit_usd: 0 (negative for budget) = config value; a non-positive max_turns is clamped to 1.
net_allowed_hosts / net_allowed_urls narrow or replace the net scope per run according to net.policy (see run_subagent).
Returns:
{"task_id": str, "status": "QUEUED"} — poll with get_task_status.
The finished task's result_data carries the full engine result
(status, failure_kind, ok, files_touched, exec_ran,
rollback_verified, attempts[], cost_usd, ...).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| task | Yes | ||
| files | No | ||
| model | No | ||
| recipe | No | ||
| api_key | No | ||
| profile | No | ||
| provider | No | ||
| allow_net | No | ||
| max_turns | No | ||
| allow_exec | No | ||
| max_tokens | No | ||
| output_path | No | ||
| workspace_dir | No | . | |
| max_duration_s | No | ||
| verify_command | No | ||
| budget_limit_usd | No | ||
| net_allowed_urls | No | ||
| allow_destructive | No | ||
| net_allowed_hosts | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||