File Tools
Last updated
Tools that find, read, edit, remove, restore, 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. Since v1.3.11, with a decision model set, a file of 4096 characters or more judged unrelated to the current request (confidence 0.7 or higher, the same check chat_history mode=read uses) is withheld: its entry becomes a one-line File withheld note instead of the content. The same file is withheld at most once per session, so a second read returns the content; entries read with around are not checked, and without a decision model, or when the check fails, the content comes back unchanged. 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. So does an old_string that matches more than once without replace_all, a patch that would leave a non-empty file empty, the history placeholder pasted back as content, or a file over 1 MiB. 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. Only mode=write and mode=patch remain, and path is required: mode=remove and mode=restore were Removed in v1.3.11 (use remove_file / restore_file). Mode is inferred from content → write and targets → patch. 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 named in the system prompt, as a full path; a blank path is rejected rather than landing there. path is absolute or relative to the work directory |
remove_file | Added in v1.3.11, replacing edit_file(mode=remove). Moves one file (path, required; absolute or relative to the work directory) aside into ~/.config/agenvoy/.store/temp/ instead of deleting it, records the move in file history, and returns where it went; restore_file puts it back. Every call asks for confirmation unless the user already allowed every call for this turn. Used only on an explicit request or a Skill step; a skill or script tool is removed with edit_skill / edit_tool mode=remove. Not available to subagent legs. The tool-call line reads Remove(<path>) |
restore_file | Added in v1.3.11, replacing edit_file(mode=restore). Puts a recorded version back by version (an id from a file_history row, which names both the file and the state; takes precedence over task_id), or undoes a whole task with task_id (a task id from chat_history, or current for the task running now), returning every file that task touched to before it ran; path together with task_id narrows the undo to that one file. One of version / task_id is required. It also brings back a file remove_file moved aside. Every call asks for confirmation unless the user already allowed every call for this turn. Not available to subagent legs. The tool-call line reads Restore(...) with the path, version N or the task id |
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 restore_file restores from |
open_file | Open a file or URL with the OS default handler (play a video, view an image, open a PDF viewer; since v1.2.1 also a link or a system settings pane such as x-apple.systempreferences:...). A URL always asks the user to confirm. Replaces run_command open/xdg-open, which the sandbox cannot reach. 10 s cap |