From 7bd40fa311c6df42a7856fde4d67cabccb768ce3 Mon Sep 17 00:00:00 2001
From: Levi Neely <141506390+lneely@users.noreply.github.com>
Date: Mon, 20 Apr 2026 22:06:10 +0200
Subject: [PATCH] prompts: tools-file clarify shell vs file_* boundary

---
 prompts/tools-file.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/prompts/tools-file.md b/prompts/tools-file.md
index afc1c5b..2bb9770 100644
--- a/prompts/tools-file.md
+++ b/prompts/tools-file.md
@@ -1,9 +1,9 @@
 # File Tools
 
-**Critical rule**: always use `file_*` tools for file manipulation. Never use shell commands (`cat`, `sed`, `awk`, `grep`, `find`, `echo >`) for reading, writing, or searching files.
+**Critical rule**: use `file_*` tools for reading, writing, editing, and searching files. Do not use shell commands (`cat`, `sed`, `awk`, `grep`, `find`, `echo >`) as a substitute for these operations.
 
 | Tool | Replaces |
-|------|---------|
+|------|----------|
 | `file_read` | `cat`, `head`, `tail` |
 | `file_write` | `echo >`, `tee`, `cat >` |
 | `file_edit` | `sed -i`, manual patch |
@@ -24,6 +24,7 @@ execute_code: steps=[{tool: "file_grep",  args: ["func.*Handler", "src/"]}]
 **Returns**: file contents / match results / write confirmation.
 
 **Constraints**:
-- Read before writing — always call `file_read` before `file_write` or `file_edit`.
-- Prefer `file_edit` over `file_write` for partial changes.
-- Capturing process output to a file (e.g. `make > make.log`) is fine — only hand-authored content must go through `file_write`.
+- `file_write` and `file_edit` require a prior `file_read` in the same session. `file_read` creates a sentinel (keyed by path hash, verified by content hash) that `file_write`/`file_edit` check before proceeding. If the file has been modified outside the session since it was read, the sentinel will not match and you must call `file_read` again before writing.
+- Shell is fine for *processing* the output of file tools — piping results, extracting fields, chaining with other commands. The restriction is on using shell as a substitute for the file tools themselves.
+- Always use absolute paths.
+- For large files, use `file_grep` or `file_glob` to locate the relevant section before reading the whole file.