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

`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.
include_free=True also admits ':free' variants (non-ZDR — prompts may be
logged/trained on); they require allow_non_zdr or the openrouter-free
provider to actually run.

[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.
include_free=True dopuszcza warianty ':free' (non-ZDR — prompty mogą być
logowane/trenowane); do uruchomienia wymagają allow_non_zdr albo
providera openrouter-free.

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.

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 (<workspace_dir>/.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. Empty = engine.default_workspace
           from the config, else the server's 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 (<workspace_dir>/.botex/memory/)
by keyword query, tag, or entry kind (context, decision, handoff, lesson).

Args:
    workspace_dir: Workspace root directory. Empty = engine.default_workspace
           from the config, else the server's 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. Empty = engine.default_workspace
           from the config, else the server's 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).