start_task
Start a detached BoteX task and return its task_id immediately.
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).
- allow_non_zdr: per-run consent to relax Zero Data Retention — needed
for free (:free) models whose endpoints may log or train on prompts.
Same semantics as in 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
TableJSON 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 | ||
| allow_non_zdr | 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
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||