From 82e4a564aa2b7b108b87aa93d87fbfd82092e8a5 Mon Sep 17 00:00:00 2001 From: Hunter Bown Date: Sat, 25 Apr 2026 13:44:43 -0500 Subject: [PATCH] refactor(#35): tighten agent prompt tool descriptions, drop alias dupes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tool-surface audit pass: - FILE OPERATIONS rewritten so each line states the niche, not just the verb. read_file mentions PDF auto-extraction + `pages` slicing. - New SEARCH section consolidates grep_files / file_search / web_search / fetch_url so the model sees them next to each other and picks the right one. fetch_url (#33) added; previously absent from the prompt. - request_user_input pulled out of FILE OPERATIONS into its own USER section — it never belonged there. - SUB-AGENTS list shrinks by 3: drops `spawn_agent` (use `agent_spawn`), `close_agent` (use `agent_cancel`), and the `agent_assign / assign_agent` dual-name. The underlying dispatchers still resolve those names, so existing sessions don't break — they just no longer pollute the model's tool list. Adds `docs/TOOL_SURFACE.md` with the rationale, the v0.5.1 final surface, and the dropped aliases. Calls out that grep_files is pure-Rust (no rg/grep shell-out, so the "fall back to grep" AC from #35 is vacuously satisfied — the tool has no shell dependency to fall back from). Closes #35. --- crates/tui/src/prompts/agent.txt | 51 +++++++++--------- docs/TOOL_SURFACE.md | 91 ++++++++++++++++++++++++++++++++ 2 files changed, 118 insertions(+), 24 deletions(-) create mode 100644 docs/TOOL_SURFACE.md diff --git a/crates/tui/src/prompts/agent.txt b/crates/tui/src/prompts/agent.txt index 5fc93bf3..2debf56a 100644 --- a/crates/tui/src/prompts/agent.txt +++ b/crates/tui/src/prompts/agent.txt @@ -35,15 +35,21 @@ Step budgeting: Available tools: -FILE OPERATIONS: -- list_dir: List directory contents -- read_file: Read file contents -- write_file: Create or overwrite a file -- edit_file: Search and replace text in a file -- apply_patch: Apply a unified diff patch to a file -- grep_files: Search files by regex -- web_search: Quick web search (fallback when citations are not needed) -- request_user_input: Ask the user short multiple-choice questions +FILE OPERATIONS (prefer these over `exec_shell` equivalents — they return structured output): +- read_file: Read a file. PDFs are auto-extracted via pdftotext; pass `pages: "1-5"` to slice. +- list_dir: List directory contents (structured, gitignore-aware). +- write_file: Create or overwrite a file. +- edit_file: Search-and-replace inside a single file. Cheaper than rewriting. +- apply_patch: Apply a unified diff patch — the right tool for multi-hunk edits. + +SEARCH: +- grep_files: Regex search file contents within the workspace; returns matches + context lines. +- file_search: Fuzzy-match filenames (NOT contents). Use to locate a file when you know roughly the name. +- web_search: DuckDuckGo/Bing search; returns ranked snippets with ref_ids for citation. +- fetch_url: Direct HTTP GET on a known URL (faster than web_search when the link is already known). HTML is stripped to text by default. + +USER: +- request_user_input: Ask the user a short multiple-choice question. PARALLEL TOOL USE: - Issue independent tool calls in parallel by emitting multiple tool_calls in one assistant turn (the model API supports this natively). Do not wrap them in any meta-tool or pseudo-XML. @@ -79,21 +85,18 @@ TASK MANAGEMENT: - note: Record important information SUB-AGENTS: -- spawn_agent: Spawn a background sub-agent (agent_type, message/items) -- agent_spawn: Spawn a background sub-agent (type, prompt, allowed_tools) -- spawn_agents_on_csv: Batch-process CSV rows with one worker sub-agent per row -- report_agent_job_result: Worker-only job row report tool for spawn_agents_on_csv -- agent_swarm: Spawn a dependency-aware swarm of sub-agents (tasks, shared_context) -- swarm_status: Check status for a previously started swarm (swarm_id) -- swarm_result: Get full results for a previously started swarm (swarm_id, optional block/timeout) -- agent_result: Get result from a sub-agent (agent_id, block, timeout_ms) -- send_input: Send input to a running sub-agent (agent_id, message/items, interrupt) -- agent_assign / assign_agent: Update assignment objective/role and optionally push immediate guidance -- wait: Wait for one or more sub-agents to complete (ids optional, wait_mode:any|all, timeout_ms) -- agent_cancel: Cancel a running sub-agent (agent_id) -- close_agent: Close a running sub-agent (alias for cancel) -- resume_agent: Resume a previously closed/completed sub-agent -- agent_list: List all sub-agents and their status +- agent_spawn: Spawn a background sub-agent (type, prompt, allowed_tools). +- spawn_agents_on_csv: Batch-process CSV rows with one worker sub-agent per row. +- report_agent_job_result: Worker-only job row report tool for spawn_agents_on_csv. +- agent_swarm: Spawn a dependency-aware swarm of sub-agents (tasks, shared_context). +- swarm_status / swarm_result: Inspect a swarm by swarm_id (status; or full results, with optional block/timeout). +- agent_result: Get result from a sub-agent (agent_id, block, timeout_ms). +- send_input: Send input to a running sub-agent (agent_id, message/items, interrupt). +- agent_assign: Update assignment objective/role and optionally push immediate guidance. +- wait: Wait for one or more sub-agents to complete (ids optional, wait_mode:any|all, timeout_ms). +- agent_cancel: Cancel a running sub-agent (agent_id). +- resume_agent: Resume a previously closed/completed sub-agent. +- agent_list: List all sub-agents and their status. Delegation protocol: - Delegate only bounded, parallelizable work with a clear input, expected output, and tool limits. - Prefer multiple sub-agents for independent steps to maximize parallelism. diff --git a/docs/TOOL_SURFACE.md b/docs/TOOL_SURFACE.md new file mode 100644 index 00000000..69125007 --- /dev/null +++ b/docs/TOOL_SURFACE.md @@ -0,0 +1,91 @@ +# 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. + +## Final surface (v0.5.1) + +### File operations + +| Tool | Niche | +|---|---| +| `read_file` | Read a UTF-8 file. PDFs auto-extracted via `pdftotext` (poppler) when available; `pages: "1-5"` slices large docs. | +| `list_dir` | Structured, gitignore-aware listing. Preferred over `exec_shell("ls")`. | +| `write_file` | Create or overwrite a file. | +| `edit_file` | Search-and-replace inside a single file. Cheaper than a full rewrite. | +| `apply_patch` | Apply a unified diff. The right tool for multi-hunk edits. | + +### Search + +| Tool | Niche | +|---|---| +| `grep_files` | Regex search file contents within the workspace; structured matches + context lines. Pure-Rust (`regex` crate), no `rg`/`grep` shell-out. | +| `file_search` | Fuzzy-match filenames (not contents). Use when you know roughly the name. | +| `web_search` | DuckDuckGo (with Bing fallback); ranked snippets + `ref_id` for citation. | +| `fetch_url` | Direct HTTP GET on a known URL. Faster than `web_search` when the link is already known. HTML stripped to text by default. | + +### Shell + +| Tool | Niche | +|---|---| +| `exec_shell` | Run a shell command. Foreground or background (`background: true` returns a `task_id`). | +| `exec_shell_wait` | Poll a background task for incremental output. | +| `exec_shell_interact` | Send stdin to a running background task and read incremental output. | + +### Git / diagnostics / testing + +| Tool | Niche | +|---|---| +| `git_status` | Inspect repo status without running shell. | +| `git_diff` | Inspect working-tree or staged diffs. | +| `diagnostics` | Workspace, git, sandbox, and toolchain info in one call. | +| `run_tests` | `cargo test` with optional args. | + +### Task management + +| Tool | Niche | +|---|---| +| `todo_write` | Granular per-item progress. | +| `update_plan` | Structured checklist for complex multi-step work. | +| `note` | One-off important fact for later. | + +### Sub-agents + +`agent_spawn`, `agent_swarm`, `spawn_agents_on_csv`, plus the supporting +tools (`agent_result` / `swarm_result` / `wait` / `send_input` / +`agent_assign` / `agent_cancel` / `resume_agent` / `agent_list` / +`report_agent_job_result` / `swarm_status`). See `agent.txt` for the +delegation protocol. + +## 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`. + +## 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.