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

Return status and result for a task started with start_task.

status is the task lifecycle (QUEUED | RUNNING | DONE | FAILED | CANCELLED) — DONE here means "finished", not "succeeded"; check result_data.status / result_data.ok for the engine outcome. result is the pretty-text report; result_data is the structured engine result (status, failure_kind, ok, files_touched, exec_ran, rollback_verified, attempts[], cost_usd, ...).

Fetch one public http(s) text document for caller-side research.

This tool is intentionally separate from BoteX's internal read_url: the orchestrating agent chooses the URL, so arbitrary public hosts do not have to be configured in net.allowed_hosts. SSRF protections, redirect revalidation, content-type checks, byte limits, and secret masking still apply. In net.policy='allowlist', only configured hosts may be fetched.

[EN] Fetches the most cost-effective and capable models from OpenRouter based on live benchmarks. USE THIS TOOL BEFORE calling run_subagent if you are unsure which model ID to use or want to optimize for cost/quality.

[PL] Pobiera rekomendacje modeli z OpenRouter na podstawie benchmarków. Użyj tego narzędzia ZANIM wywołasz run_subagent, jeśli nie znasz dokładnego ID modelu.

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.

Returns a lightweight file skeleton (classes, methods, functions, headers, line numbers) without reading the whole file. Saves ~90% of tokens.

Saves a persistent context note, architectural decision, task handoff, or lesson into the workspace Memory Vault (/.botex/memory/). Masks secrets and provides directory isolation.

Args: title: Short descriptive title of the memory entry. content: Detailed markdown notes, architectural rationale, or handoff context. workspace_dir: Workspace root directory (defaults to current directory). kind: Entry category ('context' | 'decision' | 'handoff' | 'lesson'). tags: Optional list of keyword tags for filtering and discovery. memory_id: Optional custom identifier (alphanumeric/hyphen/underscore). Auto-generated if omitted.

Searches the workspace Memory Vault (/.botex/memory/) by keyword query, tag, or entry kind (context, decision, handoff, lesson).

Args: workspace_dir: Workspace root directory (defaults to current directory). query: Free-text search string matched against title, content, and tags. tag: Filter by specific tag. kind: Filter by entry kind ('context', 'decision', 'handoff', 'lesson').

Reads the full content and metadata of a specific memory entry by ID from the workspace Memory Vault.

Args: memory_id: The ID of the memory entry to retrieve (e.g. 'mem_a1b2c3d4'). workspace_dir: Workspace root directory (defaults to current directory).

Returns an analytics summary of executed BoteX tasks (USD costs, token usage, code-line balance). Args: period: 'week' (last 7 days) or 'month' (last 30 days).

Checks BoteX environment readiness (provider keys, snapshot dir, disk).

Purges old or excess backup snapshots from disk.