上游文档原文（英文）

Tool surface

Why these specific tools, in this groupings, and how each one is meant to be chosen over the available shell equivalent. Companion to crates/tui/src/prompts/agent.txt.

Design stance

• Dedicated tools over exec_shell whenever the dedicated tool returns structured output. Bash escaping is error-prone and platform behavior varies (GNU vs BSD grep, rg is not always installed). Structured output also frees the model from re-parsing free-form text.
• exec_shell for everything else. Build, test, format, lint, ad-hoc commands, anything platform-specific. We don't try to wrap the long tail.
• Drop tools that don't beat their shell equivalent. Two-tool aliases for the same backing operation are a model trap — the LLM will alternate between them and the cache hit rate suffers.

Current surface (v0.7.5)

File operations

Search

Shell

When a foreground shell command times out, the process is not continued silently. The tool result tells the model to rerun long work with task_shell_start or exec_shell with background = true, then poll with task_shell_wait or exec_shell_wait.

Interactive shell jobs are also visible through /jobs. The TUI job center is fed by the same shell manager as exec_shell/task_shell_start, and shows the command, cwd, elapsed time, status, output tail, process-local shell id, and linked durable task id when available. /jobs show, /jobs poll, /jobs wait, /jobs stdin, and /jobs cancel provide inspect, polling, stdin, and cancel controls for live jobs. Jobs are process-local; after restart, live process state is not reattached, and any remembered detached entries must be marked stale rather than presented as live processes.

MCP manager and palette discovery

MCP server configuration is surfaced in the TUI through /mcp and the mcp_config_path row in /config. /mcp shows the resolved config path, server enabled/disabled state, transport, command or URL, timeouts, connection errors, and discovered tools/resources/prompts. It supports narrow manager actions for init, add, enable, disable, remove, validate, and reload/reconnect. Config edits are written immediately, but the model-visible MCP tool pool is restart-required after edits.

The command palette includes MCP entries grouped by server. Disabled and failed servers stay visible, and discovered tools/prompts use the runtime names shown to the model, such as mcp_<server>_<tool>.

Git / diagnostics / testing

Task management and durable work

Verification gates and artifacts

Large logs and command outputs should be artifacts with compact summaries in the transcript. task_gate_run handles this automatically for active durable tasks.

GitHub context and guarded writes

PR attempts

Automations

Sub-agents

agent_spawn plus the supporting tools (agent_result / wait / send_input / agent_assign / agent_cancel / resume_agent / agent_list). See agent.txt for the delegation protocol and SUBAGENTS.md for the role taxonomy (general / explore / plan / review / implementer / verifier / custom).

Parallel fan-out: cost-class caps

Two tools offer parallel fan-out with different concurrency limits that reflect very different cost classes:

The caps appear in each tool's description and error messages so the model (and the user) can choose the right tool for the job. If one sub-agent is enough but you need parallel lookups, prefer rlm with llm_query_batched; if each task needs its own tool-carrying agent loop, use agent_spawn (and cancel completed ones to free slots).

Recently consolidated (v0.5.1)

Removed from the prompt as duplicates of equivalent tools (the underlying dispatchers still resolve them, so existing sessions don't break — they just no longer pollute the model's tool list):

• spawn_agent → use agent_spawn.
• close_agent → use agent_cancel.
• assign_agent → use agent_assign.

Deprecation schedule (v0.6.2 → v0.8.0)

The alias tools below still execute successfully but now attach a _deprecation block to every result they return. Models should migrate to the canonical name before v0.8.0, when the aliases will be removed.

The _deprecation block shape:

{
  "_deprecation": {
    "this_tool": "spawn_agent",
    "use_instead": "agent_spawn",
    "removed_in": "0.8.0",
    "message": "Tool 'spawn_agent' is deprecated; switch to 'agent_spawn' before v0.8.0."
  }
}

This block is merged into the tool result's metadata object alongside any other metadata keys (e.g. status, timed_out) so it does not displace existing metadata. A one-line deprecation warning is also emitted to the audit log at tracing::warn level every time an alias is invoked.

Why we don't ship a single bash tool

Single-bash agents (Claude Code's design) are powerful but hand the model all the foot-guns of shell scripting: quoting, platform divergence, side-effects from misread cwd, cd not persisting between calls, etc. Our file tools are also significantly cheaper to render in the transcript (structured JSON-shaped output collapses better than ls -la walls of text).

The model can always fall back to exec_shell when something is missing. The dedicated tools just take the common 80% off the shell escape-hatch.

回到顶部