run_subagent
Delegate multi-step coding or refactoring tasks to an autonomous engine that edits local workspace files, validates patches, and returns verified structured results with rollback and cost tracking.
Instructions
Runs BoteX — an autonomous code execution engine (agent-agnostic harness).
BoteX performs multi-step tasks on local files inside workspace_dir.
TIP: If the user didn't specify a model, DO NOT guess. Use the `recommend_models` tool first to find the best model for this task!
Key engine features:
- Outline-First and Context Pruning: ~90% token savings.
- Pre-write Syntax Check: in-memory code validation before touching disk.
- Multi-tier Fuzzy Patching: tolerant of CRLF/LF and indentation drift.
- Hard Zero-Retention on OpenRouter (provider: data_collection=deny)
and DLP secret censoring.
- Automatic Snapshot Rollback on loops or critical failures.
Args:
task: Precise description of the coding or refactoring task.
files: Optional list of primary files affected by the task.
workspace_dir: Project directory path. Empty = engine.default_workspace
from the config, else the server's current directory.
model: Any model from the provider's catalog. Empty = model from config
(see 'profile' and botex.config.json).
profile: Model profile from botex.config.json (e.g. 'default', 'coding',
'auto-beta', 'fast'). When both 'model' and 'profile' are empty,
the capability mode picks the tier via engine.mode_profiles
(readonly -> 'fast', destructive/full -> 'coding'). Ignored when
'model' is given explicitly.
provider: API provider from the 'providers' section of botex.config.json
('openrouter', 'nvidia', 'google', 'openrouter-free', 'ollama').
Empty = provider marked 'default: true' in the configuration.
mode: Capability preset: 'readonly' (read only — the contract is an
analysis report, DONE requires non-empty findings), 'edit'
(read + edit — default), 'destructive' (+delete/move),
'full' (+run_command). Empty = engine.default_mode from
config. Explicit allow_* flags may only WIDEN a preset —
they never narrow it (readonly can never gain file writes).
In headless mode this is pre-authorization — grant it
consciously.
max_turns: Maximum tool-loop steps (0 = config value).
max_tokens: Per-turn completion cap (0 = config value; reasoning
models need ~8000+ since thinking shares this budget).
max_duration_s: Total wall-clock limit in seconds (0 = config value,
0 disables only when config is also 0). Checked between turns.
budget_limit_usd: Daily spend limit in USD (negative = config value,
0 = no limit).
allow_destructive: Authorize destructive operations (delete_file/
move_file) for this task. Headless mode cannot confirm
mid-run — grant ONLY with the user's consent.
allow_exec: Authorize run_command for this task (also requires
exec.enabled=true in config). WARNING: this is NOT a sandbox —
commands run with operator privileges. Grant only for trusted
workspaces with the user's consent.
api_key: Optional provider API key passed per-request (highest
priority — overrides env/.env/config). Empty = resolved
internally by the harness.
output_path: Optional required output file (workspace-relative).
Sets the file_output contract: DONE is accepted only when
the file exists on disk, is non-empty, and passes the
syntax gate; a DONE response carrying the payload as text
is salvaged to disk. Requires a mutating mode.
allow_net: Explicitly authorizes the read-only public web tool for
this run. It is never enabled by a capability mode.
net_allowed_hosts: Optional per-run host authorization. In
net.policy='caller' these replace config defaults; in 'public'
they narrow public access; in 'allowlist' they must stay inside
net.allowed_hosts.
net_allowed_urls: Optional per-run URL authorization rules. A URL
ending in '/' authorizes that subtree; otherwise it authorizes
the exact URL including its query string.
verify_command: Optional allowlisted command that must pass before
DONE is accepted — it runs against the workspace as it
stands, including when the task made no writes (a passing
verifier validates a legitimate no-change result). Requires
exec.enabled=true in config and exec authorization.
recipe: Optional operational persona / workflow prompt (e.g. 'planner',
'code-explorer', 'reviewer', 'security-reviewer', 'build-resolver', 'tdd').
allow_non_zdr: Per-run consent to relax the Zero Data Retention
gate. Required for free (:free) models whose endpoints may
log or train on prompts — it also switches the wire
provider.data_collection flag to 'allow'. Grant only with
the operator's consent; the result carries
zdr_enforced=false. The openrouter-free provider preset is
the persistent config-level alternative.
approval_policy: Operator approval policy for risky operations: 'none',
'high_risk' (default), 'mutations', 'all_risky'.
Returns:
A pretty-text report in the text content (unchanged format for legacy
clients) plus the full engine result as structuredContent (status,
failure_kind, ok, files_touched, exec_ran, rollback_verified,
attempts[], cost_usd, ...). `ok` is true only when status == DONE —
i.e. the task contract was verified, not merely claimed by the model.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"task": "<task>"
},
"name": "run_subagent"
}
}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 | ||
| allow_non_zdr | No | ||
| workspace_dir | No | ||
| max_duration_s | No | ||
| verify_command | No | ||
| approval_policy | No | ||
| budget_limit_usd | No | ||
| net_allowed_urls | No | ||
| allow_destructive | No | ||
| net_allowed_hosts | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | No | ||
| steps | No | ||
| status | No | ||
| message | No | ||
| summary | No | ||
| task_id | No | ||
| attempts | No | ||
| cost_usd | No | ||
| exec_ran | No | ||
| duration_s | No | ||
| lines_added | No | ||
| memory_keys | No | ||
| failure_kind | No | ||
| zdr_enforced | No | ||
| artifact_refs | No | ||
| fallback_from | No | ||
| files_touched | No | ||
| lines_removed | No | ||
| applied_skills | No | ||
| blocking_reason | No | ||
| vault_memory_id | No | ||
| rollback_verified | No |