run_subagent
Delegate multi-step coding and refactoring tasks to an autonomous engine that edits local files, verifies results, and rolls back on failure with 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 (defaults to 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'). 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').
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.
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 |
|---|---|---|---|
| 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 | ||
| failure_kind | No | ||
| fallback_from | No | ||
| files_touched | No | ||
| lines_removed | No | ||
| rollback_verified | No |