run_subagent

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'). 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.

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.