Tools reference

Eight 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.

read_file

Read a file, paged for large files. read_file(path), optionally with a line range. Returns the contents with a line count.

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). The fallback when an exact-match edit is not worth it. gated

edit_file

Apply an exact-match edit. edit_file(path, old, new). old must match verbatim. Repeated misses on one file nudge a full-file rewrite (see Robustness). 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

done

Declare the goal complete. done(summary) triggers a final test run; the summary is shown and recorded.