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 are what replace_lines addresses; the tag is what makes that safe.
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 or overwrite a file. write_file(path, content). 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). 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 point the agent at replace_lines (see Robustness). gated
replace_lines
Replace an inclusive line range. replace_lines(path, start, end, new, hash), using the numbers read_file printed. The model sends only the lines it is changing, never the surrounding context and never the text it is deleting, which is what keeps a small change small. Set end to start - 1 to insert without deleting; leave new empty to delete.
Line numbers only mean anything against one version of a file, so pass the #TAG from the read_file header as hash. If the file has changed since, the edit is refused and you are told to read it again rather than having the wrong lines rewritten. gated
bash
Run a shell command with a bounded timeout. bash(command). Output is ANSI-stripped and truncated. gated
git
Run a git subcommand. git(args), e.g. status, diff, log. gated
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.