# File Tools

Tools that find, read, edit, open and track files.

| Tool | Description |
|---|---|
| `find_files` | Locate files (`queries: [{dir, pattern, file_pattern, recursive}]`). `mode=list` returns a directory's entries (alphabetical), `mode=glob` matches paths against a filename pattern and, since v1.0.23, returns them most recently modified first, `mode=search` greps file contents by RE2 regex. Mode is inferred when omitted: `pattern` + `file_pattern` → search, `pattern` alone → glob, neither → list. Glob patterns must carry a literal — all-wildcard (`**/*`) is rejected. Matches merge and deduplicate across queries. `mode=list` and `mode=glob` are capped at 128 KiB in total and the tail reports how many entries were dropped. Since v1.0.11 `mode=search` is paged instead of truncated: `output=files` (the default) returns one `{path, count, lines}` row per matching file — since v1.0.23 `lines` carries the row numbers of its first five matches, ready for `read_files` `around` — `output=content` returns the matching lines with their line numbers, `multiline=true` (v1.0.23) matches the regex against whole files so `.` crosses newlines and reports every row a match spans, `offset` / `limit` (default 256) walk the pages, and `context` adds surrounding lines — marked `context: true` and not counted toward `offset` / `limit`. A single match line is cut at 512 bytes. Every page ends with `[files a-b of N ...]` / `[lines a-b of N ...]` carrying the next `offset`, or `last page`; the queries and `output` must stay identical between pages |
| `read_files` | Batched read of one or more files (`files: [{path, offset, limit, around, context}]`); text, PDF, DOCX, PPTX, CSV/TSV, image, or audio/video — a media file comes back as a verbatim transcript through the configured speech-to-text model, so there is no separate transcription tool. Reads up to 2048 lines by default (1 MiB cap for documents, 10 MiB for images); `offset`/`limit` page through larger files — page for PDF, slide for PPTX, row for CSV. Since v1.0.23 `around` takes 1-based rows of a plain-text file and reads `context` lines (default 20, `0` = the rows alone) on each side, merging overlapping windows and marking skipped text with a `...` line (`offset`/`limit` are then ignored), and the same path may appear more than once in `files`, its results joined in order. Since v1.0.11 a truncated text read ends with `[lines a-b of N; call again with offset=... for more]`, so the continuation offset never has to be guessed. Text lines arrive as `"<row>\t<line>"`; the number is added by the reader and is not in the file, so it must be stripped before a line is reused as an `edit_file` anchor. Must be called before `edit_file` changes an existing file: since v1.0.23 the edit is refused unless the file was read in this run and its modification time is unchanged since that read. **Sensitive file guard**: SSH keys, `.pem`, `.key`, `.env` always require confirmation regardless of sudo or allowlist |
| `edit_file` | Every change to a file on disk. `mode=write` creates a first version or deliberately replaces one wholesale; `mode=patch` edits regions via a `targets` array — each target is `{old_string, new_string}` plus optional `replace_all`, and every anchor is located against the original file content before anything is applied. Two targets covering the same region, or a target whose `old_string` occurs inside an earlier target's `new_string`, reject the whole call with nothing written. An empty `new_string` deletes; an insert is expressed by repeating `old_string` at the start of `new_string`. The line-anchored `row` / `insert_string` form was removed — row numbers counted the earlier targets in the same call, which are not yet on disk; `mode=remove` moves the file aside, still restorable; `mode=restore` puts a recorded version back by `version` id, or undoes a whole task via `task_id` (`current` = the task running now). Mode is inferred from `content` → write and `targets` → patch; remove and restore are never inferred. Since v1.0.23 `write` over an existing file and every `patch` pass a read-freshness guard: the file must have been read with `read_files` in this run and not changed on disk since (by the user, a formatter or another command), otherwise nothing is written and the error asks for a fresh read; a successful write counts as a fresh read for the next edit. A `patch` anchor that only differs from the file in curly vs straight quotes still matches, and the replacement keeps the file's quote style. The tool description sends a file made for the user with no location asked for to the output directory |
| `file_history` | Recorded versions of every file the tools changed — when each changed, what the task was after, and what the content was. `mode=list` returns versions newest-first, filterable by `path`, `task_id`, `from`/`to` local time, and `limit` (capped at 24); `mode=read` diffs the newest recorded version of each path against what is on disk now. This is the snapshot layer `edit_file(mode=restore)` restores from |
| `open_file` | Open a file with the OS default application (play a video, view an image, open a PDF viewer). Replaces `run_command` `open`/`xdg-open`, which the sandbox cannot reach. 10 s cap |