Tools reference

Eleven tools cover the loop. Read-only tools run freely; mutating tools are gated. Test output is parsed to a pass/fail count, so both the agent and the stall detector track measured progress, not text. bash covers running code and your app; web_search / web_fetch add the web.

read_file

Read a file, paged for large files. read_file(path), optionally with a line range. Lines are numbered, and the header carries a short content tag: [api.py#a1b2: lines 1-120 of 340]. The numbers orient you and let an error name a location; the tag identifies the version you read.

search

Search the repo by content or by path glob. search(query) grounds a change without reading every file.

run_tests

Run the project's test suite and parse the pass/fail tally. run_tests(). The parsed count is what progress and stall detection are measured against.

write_file

Create a file, or replace one you have read. write_file(path, content). Overwriting a file that exists and has not been read this session is refused — it replaces the whole file, so anything the model did not know was there would be dropped silently. For creating a file, or when a rewrite genuinely is the whole change. It is the most expensive way to make a small edit, so it is no longer the fallback when an edit misses. gated

edit_file

Replace a unique substring. edit_file(path, old, new). The file must have been read this session — an anchor is a claim about what the file contains now, and a model that has not looked is guessing. An exact match is tried first. If that misses, old is retried ignoring trailing whitespace, then indentation, then quote and dash style, and with any N: line-number prefixes stripped. Each of those still requires exactly one matching site, so a relaxed comparison never resolves an ambiguity, and an inexact application says so in its result. Set edit_tolerance to false to require a byte-exact anchor. Repeated misses on one file send the agent back to read_file (see Robustness). gated

bash

Run a shell command with a bounded timeout. bash(command). Output is ANSI-stripped and truncated. gated

git

Run a read-only git subcommand. git(args), e.g. status, diff, log, show, blame. Anything that changes the repository — add, commit, checkout, reset, clean, push — is refused and must go through bash, which is gated. The tool is ungated and is mounted in the read-only plan preset, so an unrestricted git would have been a way to discard work with no prompt.

web_search

Search the web (DuckDuckGo). web_search(query) returns the top results as title, URL, and snippet, so the agent can look up docs, library usage, or an error message. Read-only, no approval.

web_fetch

Fetch an http(s) page and return its main text as markdown. web_fetch(url), typically after web_search to read a result in full. Read-only.

done

Declare the goal complete. done(summary) triggers a final test run; the summary is shown and recorded. Optional: a plain text reply with no tool call also ends the turn.