@levnikolaevich/hex-line-mcp 1.3.0 → 1.3.1

package/README.md

@@ -18,10 +18,10 @@ Every line carries an FNV-1a content hash. Every edit must present those hashes
 | `read_file` | Read file with hash-annotated lines and range checksums | Partial reads via `offset`/`limit` |
 | `edit_file` | Hash-verified edits with anchor or text replacement | Returns compact diff via `diff` package |
 | `write_file` | Create new file or overwrite, auto-creates parent dirs | Path validation, no hash overhead |
-| `grep_search` | Search with ripgrep, returns hash-annotated matches | Edit-ready results -- search then edit directly |
+| `grep_search` | Search with ripgrep, 3 output modes, per-group checksums | Edit-ready: grep -> edit directly with checksums |
 | `outline` | AST-based structural overview via tree-sitter WASM | 95% token reduction (10 lines instead of 500) |
 | `verify` | Check if held range checksums are still valid | Single-line response avoids full re-read |
-| `directory_tree` | Compact directory tree with .gitignore support | Skips node_modules/.git, shows file sizes |
+| `directory_tree` | Compact directory tree with root .gitignore support | Skips node_modules/.git, shows file sizes |
 | `get_file_info` | File metadata without reading content | Size, lines, mtime, type, binary detection |
 | `setup_hooks` | Configure PreToolUse + PostToolUse hooks for Claude/Gemini/Codex | One call sets up everything, idempotent |
 | `changes` | Compare file against git ref, shows added/removed/modified symbols | AST-level semantic diff |
@@ -124,7 +124,7 @@ checksum: 1-50:f7e2a1b0
 
 ### edit_file
 
-Edit using hash-verified anchors or text replacement. Returns a unified diff.
+Edit using hash-verified anchors or text replacement. Returns diff + post-edit checksums for chaining edits.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -140,7 +140,8 @@ Edit operations (JSON array):
   {"set_line": {"anchor": "ab.12", "new_text": "replacement line"}},
   {"replace_lines": {"start_anchor": "ab.10", "end_anchor": "cd.15", "new_text": "..."}},
   {"insert_after": {"anchor": "ab.20", "text": "inserted line"}},
-  {"replace": {"old_text": "find this", "new_text": "replace with", "all": false}}
+  {"replace": {"old_text": "unique text", "new_text": "replacement"}},
+  {"replace": {"old_text": "find all", "new_text": "replace all", "all": true}}
 ]
 ```
 
@@ -155,20 +156,28 @@ Create a new file or overwrite an existing one. Creates parent directories autom
 
 ### grep_search
 
-Search file contents using ripgrep with hash-annotated results.
+Search file contents using ripgrep. Three output modes: `content` (hash-annotated with checksums), `files` (paths only), `count` (match counts).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `pattern` | string | yes | Regex search pattern |
+| `pattern` | string | yes | Search pattern (regex by default, literal if `literal:true`) |
 | `path` | string | no | Directory or file to search (default: cwd) |
 | `glob` | string | no | Glob filter, e.g. `"*.ts"` |
 | `type` | string | no | File type filter, e.g. `"js"`, `"py"` |
+| `output` | enum | no | Output format: `"content"` (default), `"files"`, `"count"` |
 | `case_insensitive` | boolean | no | Ignore case |
-| `smart_case` | boolean | no | Case-insensitive when pattern is all lowercase, case-sensitive if it has uppercase (`-S`) |
-| `context` | number | no | Context lines around matches |
+| `smart_case` | boolean | no | CI when lowercase, CS when uppercase (`-S`) |
+| `literal` | boolean | no | Literal string search, no regex (`-F`) |
+| `multiline` | boolean | no | Pattern can span multiple lines (`-U`) |
+| `context` | number | no | Symmetric context lines around matches (`-C`) |
+| `context_before` | number | no | Context lines BEFORE match (`-B`) |
+| `context_after` | number | no | Context lines AFTER match (`-A`) |
 | `limit` | number | no | Max matches per file (default: 100) |
+| `total_limit` | number | no | Total match events across all files; multiline matches count as 1 (0 = unlimited) |
 | `plain` | boolean | no | Omit hash tags, return `file:line:content` |
 
+**Content mode** returns per-group checksums enabling direct `replace_lines` from grep results without intermediate `read_file`.
+
 ### outline
 
 AST-based structural outline: functions, classes, interfaces with line ranges.
@@ -194,7 +203,7 @@ Returns a single-line confirmation or lists changed ranges.
 
 ### directory_tree
 
-Compact directory tree with .gitignore support and file sizes.
+Compact directory tree with root .gitignore support (path-based rules, negation, dir-only). Nested .gitignore files are not loaded.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -202,7 +211,7 @@ Compact directory tree with .gitignore support and file sizes.
 | `pattern` | string | no | Glob filter on names (e.g. `"*-mcp"`, `"*.mjs"`). Returns flat match list instead of tree |
 | `type` | string | no | `"file"`, `"dir"`, or `"all"` (default). Like `find -type f/d` |
 | `max_depth` | number | no | Max recursion depth (default: 3, or 20 in pattern mode) |
-| `gitignore` | boolean | no | Respect .gitignore patterns (default: true) |
+| `gitignore` | boolean | no | Respect root .gitignore patterns (default: true). Nested .gitignore not supported |
 | `format` | string | no | `"compact"` = names only, no sizes, depth 1. `"full"` = default with sizes |
 
 Skips `node_modules`, `.git`, `dist`, `build`, `__pycache__`, `.next`, `coverage` by default.
@@ -219,39 +228,43 @@ Returns: size, line count, modification time (absolute + relative), file type, b
 
 ## Hook
 
-The unified PostToolUse hook (`hook.mjs`) handles two concerns:
+The unified hook (`hook.mjs`) handles four events:
+
+### PreToolUse: Tool Redirect
 
-### Hex-line Reminder
+Blocks built-in `Read`, `Edit`, `Write`, `Grep` on text files and redirects to hex-line equivalents. Binary files (images, PDFs, notebooks, archives, executables, fonts, media) are excluded.
 
-Triggers on built-in `Read`, `Edit`, `Write`, `Grep` tool usage for text files. Outputs a short reminder to stderr (exit code 2) nudging the agent to use the corresponding hex-line tool instead.
+### PreToolUse: Bash Redirect + Dangerous Blocker
 
-Binary files (images, PDFs, notebooks, archives, executables, fonts, media) are excluded -- those should use built-in tools.
+Intercepts simple Bash commands (`cat`, `head`, `tail`, `ls`, `find`, `grep`, `sed -i`, etc.) and redirects to hex-line tools. Blocks dangerous commands (`rm -rf /`, `git push --force`, `git reset --hard`, `DROP TABLE`, `chmod 777`, `mkfs`, `dd`).
 
-### RTK Output Filter
+### PostToolUse: RTK Output Filter
 
 Triggers on `Bash` tool output exceeding 50 lines. Pipeline:
 
 1. **Detect command type** -- npm install, test, build, pip install, git verbose, or generic
-2. **Type-specific summary** -- extracts key metrics (e.g., `npm install: 42 added, 3 warnings`)
-3. **Normalize** -- replaces UUIDs, timestamps, IPs, hex values, large numbers with placeholders
-4. **Deduplicate** -- collapses identical normalized lines with `(xN)` counts
-5. **Truncate** -- keeps first 12 + last 12 lines, omits the middle
+2. **Normalize** -- replaces UUIDs, timestamps, IPs, hex values, large numbers with placeholders
+3. **Deduplicate** -- collapses identical normalized lines with `(xN)` counts
+4. **Truncate** -- keeps first 15 + last 15 lines, omits the middle
 
 Configuration constants in `hook.mjs`:
 
 | Constant | Default | Purpose |
-|----------|---------|---------|
+|----------|---------|--------|
 | `LINE_THRESHOLD` | 50 | Minimum lines to trigger filtering |
-| `TRUNCATE_LIMIT` | 30 | Lines below this are kept as-is after dedup |
-| `HEAD_LINES` | 12 | Lines to keep from start |
-| `TAIL_LINES` | 12 | Lines to keep from end |
+| `HEAD_LINES` | 15 | Lines to keep from start |
+| `TAIL_LINES` | 15 | Lines to keep from end |
+
+### SessionStart: Tool Preferences
+
+Injects hex-line tool preference list into agent context at session start.
 
 ## Architecture
 
 ```
 hex-line-mcp/
-  server.mjs          MCP server (stdio transport, 6 tools)
-  hook.mjs            PostToolUse hook (reminder + RTK filter)
+  server.mjs          MCP server (stdio transport, 11 tools)
+  hook.mjs            Unified hook (PreToolUse + PostToolUse + SessionStart)
   package.json
   lib/
     hash.mjs          FNV-1a hashing, 2-char tags, range checksums
@@ -260,6 +273,13 @@ hex-line-mcp/
     search.mjs        ripgrep wrapper with hash-annotated results
     outline.mjs       tree-sitter WASM AST outline
     verify.mjs        Range checksum verification
+    info.mjs          File metadata (size, lines, mtime, type)
+    tree.mjs          Directory tree with .gitignore support
+    changes.mjs       Semantic git diff via AST
+    bulk-replace.mjs  Multi-file search-and-replace
+    setup.mjs         Hook installation for Claude/Gemini/Codex
+    format.mjs        Output formatting utilities
+    coerce.mjs        Parameter alias mapping
     security.mjs      Path validation, binary detection, size limits
     normalize.mjs     Output normalization, deduplication, truncation
 ```
@@ -318,7 +338,7 @@ Outline works on code files only (15+ languages via tree-sitter WASM). For markd
 <details>
 <summary><b>How does the RTK filter reduce tokens?</b></summary>
 
-The PostToolUse hook normalizes Bash output (replaces UUIDs, timestamps, IPs with placeholders), deduplicates identical lines, and truncates to first 12 + last 12 lines. Average savings: 45% (flat) / 52% (weighted) across 18 benchmark scenarios.
+The PostToolUse hook normalizes Bash output (replaces UUIDs, timestamps, IPs with placeholders), deduplicates identical lines, and truncates to first 15 + last 15 lines. Average savings: 45% (flat) / 52% (weighted) across 18 benchmark scenarios.
 
 </details>
 

package/hook.mjs

@@ -23,7 +23,7 @@
  * Exit 2 = block (PreToolUse) or feedback via stderr (PostToolUse)
  */
 
-import { deduplicateLines, smartTruncate } from "./lib/normalize.mjs";
+import { normalizeOutput } from "./lib/normalize.mjs";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { homedir } from "node:os";
@@ -57,13 +57,13 @@ const TOOL_HINTS = {
     Read:  "mcp__hex-line__read_file (not Read). For writing: write_file (no prior Read needed)",
     Edit:  "mcp__hex-line__edit_file (not Edit, not sed -i). read_file first for hashes",
     Write: "mcp__hex-line__write_file (not Write). No prior Read needed",
-    Grep:  "mcp__hex-line__grep_search (not Grep). Params: case_insensitive, smart_case",
+    Grep:  "mcp__hex-line__grep_search (not Grep). Params: output, literal, context_before, context_after, multiline",
     cat:   "mcp__hex-line__read_file (not cat/head/tail/less/more)",
     head:  "mcp__hex-line__read_file with limit param (not head)",
     tail:  "mcp__hex-line__read_file with offset param (not tail)",
     ls:    "mcp__hex-line__directory_tree with pattern param (not ls/find/tree). E.g. pattern='*-mcp' type='dir'",
     stat:  "mcp__hex-line__get_file_info (not stat/wc/file)",
-    grep:  "mcp__hex-line__grep_search (not grep/rg). Params: case_insensitive, smart_case",
+    grep:  "mcp__hex-line__grep_search (not grep/rg). Params: output, literal, context_before, context_after, multiline",
     sed:   "mcp__hex-line__edit_file (not sed -i). read_file first for hashes",
     diff:  "mcp__hex-line__changes (not diff). Git-based semantic diff",
     outline: "mcp__hex-line__outline (before reading large code files)",
@@ -335,10 +335,8 @@ function handlePostToolUse(data) {
 
     const type = detectCommandType(command);
 
-    // Pipeline: deduplicate -> smart truncate
-    const deduped = deduplicateLines(lines);
-    const dedupedText = deduped.join("\n");
-    const filtered = smartTruncate(dedupedText, HEAD_LINES, TAIL_LINES);
+    // Pipeline: normalize -> deduplicate -> smart truncate
+    const filtered = normalizeOutput(lines.join("\n"), { headLines: HEAD_LINES, tailLines: TAIL_LINES });
     const filteredCount = filtered.split("\n").length;
 
     const header = `RTK FILTERED: ${type} (${originalCount} lines -> ${filteredCount} lines)`;
@@ -400,31 +398,36 @@ function handleSessionStart() {
 }
 
 // ---- Main: read stdin, route by hook_event_name ----
+// Guard: only run when executed directly, not when imported for testing
 
-let input = "";
-process.stdin.on("data", (chunk) => {
-    input += chunk;
-});
-process.stdin.on("end", () => {
-    try {
-        const data = JSON.parse(input);
-        const event = data.hook_event_name || "";
+import { fileURLToPath } from "node:url";
 
-        if (isHexLineDisabled()) {
-            // REVERSE MODE: block hex-line calls, approve everything else
-            if (event === "PreToolUse") handlePreToolUseReverse(data);
-            process.exit(0); // SessionStart, PostToolUse — silent exit
-        }
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    let input = "";
+    process.stdin.on("data", (chunk) => {
+        input += chunk;
+    });
+    process.stdin.on("end", () => {
+        try {
+            const data = JSON.parse(input);
+            const event = data.hook_event_name || "";
 
-        // NORMAL MODE
-        if (event === "SessionStart") handleSessionStart();
-        else if (event === "PreToolUse") handlePreToolUse(data);
-        else if (event === "PostToolUse") handlePostToolUse(data);
-        else process.exit(0);
-    } catch {
-        process.exit(0);
-    }
-});
+            if (isHexLineDisabled()) {
+                // REVERSE MODE: block hex-line calls, approve everything else
+                if (event === "PreToolUse") handlePreToolUseReverse(data);
+                process.exit(0); // SessionStart, PostToolUse — silent exit
+            }
+
+            // NORMAL MODE
+            if (event === "SessionStart") handleSessionStart();
+            else if (event === "PreToolUse") handlePreToolUse(data);
+            else if (event === "PostToolUse") handlePostToolUse(data);
+            else process.exit(0);
+        } catch {
+            process.exit(0);
+        }
+    });
+}
 
 // ---- Exports for testing ----
 export { isHexLineDisabled, _resetHexLineDisabledCache };

package/lib/bulk-replace.mjs

@@ -1,16 +1,18 @@
-import { readFileSync, writeFileSync } from "node:fs";
-import { execSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { resolve } from "node:path";
 import { simpleDiff } from "./edit.mjs";
+import { normalizePath } from "./security.mjs";
+import { readText, MAX_OUTPUT_CHARS } from "./format.mjs";
 
 export function bulkReplace(rootDir, globPattern, replacements, opts = {}) {
     const { dryRun = false, maxFiles = 100 } = opts;
-    const abs = resolve(rootDir);
+    const abs = resolve(normalizePath(rootDir));
 
     // Find files via ripgrep (respects .gitignore)
     let files;
     try {
-        const rgOut = execSync(`rg --files -g "${globPattern}" "${abs}"`, { encoding: "utf-8", timeout: 10000 });
+        const rgOut = execFileSync("rg", ["--files", "-g", globPattern, abs], { encoding: "utf-8", timeout: 10000 });
         files = rgOut.trim().split("\n").filter(Boolean);
     } catch (e) {
         if (e.status === 1) return "No files matched the glob pattern.";
@@ -23,12 +25,12 @@ export function bulkReplace(rootDir, globPattern, replacements, opts = {}) {
 
     const results = [];
     let changed = 0, skipped = 0, errors = 0;
-    const MAX_OUTPUT = 80000;
+    const MAX_OUTPUT = MAX_OUTPUT_CHARS;
     let totalChars = 0;
 
     for (const file of files) {
         try {
-            const original = readFileSync(file, "utf-8").replace(/\r\n/g, "\n");
+            const original = readText(file);
             let content = original;
 
             for (const { old: oldText, new: newText } of replacements) {

package/lib/changes.mjs

@@ -6,10 +6,11 @@
  * without temp files.
  */
 
-import { execSync } from "node:child_process";
-import { readFileSync, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { statSync } from "node:fs";
 import { extname } from "node:path";
 import { validatePath } from "./security.mjs";
+import { readText } from "./format.mjs";
 import { outlineFromContent } from "./outline.mjs";
 
 /**
@@ -50,7 +51,7 @@ function toSymbolMap(entries) {
  * Get relative path from git root for `git show`.
  */
 function gitRelativePath(absPath) {
-    const root = execSync("git rev-parse --show-toplevel", {
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
         cwd: absPath.replace(/[/\\][^/\\]+$/, ""),
         encoding: "utf-8",
         timeout: 5000,
@@ -79,7 +80,7 @@ export async function fileChanges(filePath, compareAgainst = "HEAD") {
     // Directory: return git diff --stat (compact file list, no content reads)
     if (statSync(real).isDirectory()) {
         try {
-            const stat = execSync(`git diff --stat "${compareAgainst}" -- .`, {
+            const stat = execFileSync("git", ["diff", "--stat", compareAgainst, "--", "."], {
                 cwd: real,
                 encoding: "utf-8",
                 timeout: 10000,
@@ -94,7 +95,7 @@ export async function fileChanges(filePath, compareAgainst = "HEAD") {
     const ext = extname(real).toLowerCase();
 
     // Check if outline supports this extension
-    const currentContent = readFileSync(real, "utf-8").replace(/\r\n/g, "\n");
+    const currentContent = readText(real);
     const currentResult = await outlineFromContent(currentContent, ext);
     if (!currentResult) {
         return `Cannot outline ${ext} files. Supported: .js .mjs .ts .py .go .rs .java .c .cpp .cs .rb .php .kt .swift .sh .bash`;
@@ -104,7 +105,7 @@ export async function fileChanges(filePath, compareAgainst = "HEAD") {
     const relPath = gitRelativePath(real);
     let gitContent;
     try {
-        gitContent = execSync(`git show "${compareAgainst}:${relPath}"`, {
+        gitContent = execFileSync("git", ["show", `${compareAgainst}:${relPath}`], {
             cwd: real.replace(/[/\\][^/\\]+$/, ""),
             encoding: "utf-8",
             timeout: 5000,

package/lib/coerce.mjs

@@ -12,12 +12,6 @@ const ALIASES = {
     // grep_search
     query: "pattern",
     search: "pattern",
-    max_results: "limit",
-    maxResults: "limit",
-    maxMatches: "limit",
-    max_matches: "limit",
-    contextLines: "context",
-    context_lines: "context",
     ignoreCase: "case_insensitive",
     ignore_case: "case_insensitive",
 

package/lib/edit.mjs

@@ -8,11 +8,12 @@
  * - dry_run preview, noop detection, diff output
  */
 
-import { readFileSync, writeFileSync } from "node:fs";
+import { writeFileSync } from "node:fs";
 import { diffLines } from "diff";
-import { fnv1a, lineTag, rangeChecksum, parseChecksum } from "./hash.mjs";
+import { fnv1a, lineTag, rangeChecksum, parseChecksum, parseRef } from "./hash.mjs";
 import { validatePath } from "./security.mjs";
 import { getGraphDB, blastRadius, getRelativePath } from "./graph-enrich.mjs";
+import { readText } from "./format.mjs";
 
 // Unicode characters visually similar to ASCII hyphen-minus (U+002D)
 const CONFUSABLE_HYPHENS = /[\u2010\u2011\u2012\u2013\u2014\u2212\uFE63\uFF0D]/g;
@@ -40,6 +41,24 @@ function restoreIndent(origLines, newLines) {
     });
 }
 
+/**
+ * Build hash-annotated snippet around a position for error messages.
+ * @param {string[]} lines - file lines
+ * @param {number} centerIdx - 0-based center index
+ * @param {number} radius - lines before/after center (default 5)
+ * @returns {{ start: number, end: number, text: string }}
+ */
+function buildErrorSnippet(lines, centerIdx, radius = 5) {
+    const start = Math.max(0, centerIdx - radius);
+    const end = Math.min(lines.length, centerIdx + radius + 1);
+    const text = lines.slice(start, end).map((line, i) => {
+        const num = start + i + 1;
+        const tag = lineTag(fnv1a(line));
+        return `${tag}.${num}\t${line}`;
+    }).join("\n");
+    return { start: start + 1, end, text };
+}
+
 /**
  * Build a hash index of all lines, keeping only unique tags.
  * 2-char tags have collisions — duplicates are excluded to avoid wrong relocations.
@@ -65,21 +84,11 @@ function buildHashIndex(lines) {
 function findLine(lines, lineNum, expectedTag, hashIndex) {
     const idx = lineNum - 1;
     if (idx < 0 || idx >= lines.length) {
-        const start = idx >= lines.length
-            ? Math.max(0, lines.length - 10)
-            : 0;
-        const end = idx >= lines.length
-            ? lines.length
-            : Math.min(lines.length, 10);
-        const snippet = lines.slice(start, end).map((line, i) => {
-            const num = start + i + 1;
-            const tag = lineTag(fnv1a(line));
-            return `${tag}.${num}\t${line}`;
-        }).join("\n");
-
+        const center = idx >= lines.length ? lines.length - 1 : 0;
+        const snip = buildErrorSnippet(lines, center);
         throw new Error(
             `Line ${lineNum} out of range (1-${lines.length}).\n\n` +
-            `Current content (lines ${start + 1}-${end}):\n${snippet}\n\n` +
+            `Current content (lines ${snip.start}-${snip.end}):\n${snip.text}\n\n` +
             `Tip: Use updated hashes above for retry.`
         );
     }
@@ -116,30 +125,14 @@ function findLine(lines, lineNum, expectedTag, hashIndex) {
         if (relocated !== undefined) return relocated;
     }
 
-    // Build snippet with fresh hashes so agent can retry without re-reading
-    const start = Math.max(0, idx - 5);
-    const end = Math.min(lines.length, idx + 6);
-    const snippet = lines.slice(start, end).map((line, i) => {
-        const num = start + i + 1;
-        const tag = lineTag(fnv1a(line));
-        return `${tag}.${num}\t${line}`;
-    }).join("\n");
-
+    const snip = buildErrorSnippet(lines, idx);
     throw new Error(
-        `Hash mismatch line ${lineNum}: expected ${expectedTag}, got ${actual}.\n\n` +
-        `Current content (lines ${start + 1}-${end}):\n${snippet}\n\n` +
+        `HASH_MISMATCH: line ${lineNum} expected ${expectedTag}, got ${actual}.\n\n` +
+        `Current content (lines ${snip.start}-${snip.end}):\n${snip.text}\n\n` +
         `Tip: Use updated hashes above for retry.`
     );
 }
 
-/**
- * Parse a ref string: "ab.12" → { tag: "ab", line: 12 }
- */
-function parseRef(ref) {
-    const m = ref.trim().match(/^([a-z2-7]{2})\.(\d+)$/);
-    if (!m) throw new Error(`Bad ref: "${ref}". Expected "ab.12"`);
-    return { tag: m[1], line: parseInt(m[2], 10) };
-}
 
 /**
  * Context diff via `diff` package (Myers O(ND) algorithm).
@@ -243,7 +236,20 @@ function textReplace(content, oldText, newText, all) {
     const normNew = newText.replace(/\r\n/g, "\n");
 
     if (!all) {
-        throw new Error("replace requires all:true (rename-all mode). For single replacements, use set_line or replace_lines with hash anchors.");
+        // Uniqueness check: count occurrences
+        const parts = norm.split(normOld);
+        const count = parts.length - 1;
+        if (count === 0) {
+            // Fall through to TEXT_NOT_FOUND below
+        } else if (count === 1) {
+            // Unique match — safe to replace single occurrence
+            return parts.join(normNew);
+        } else {
+            throw new Error(
+                `AMBIGUOUS_MATCH: "${normOld.slice(0, 80)}" found ${count} times. ` +
+                `Use all:true to replace all, or use set_line/replace_lines for a specific occurrence.`
+            );
+        }
     }
     let idx = norm.indexOf(normOld);
     let confusableMatch = false;
@@ -299,9 +305,10 @@ function textReplace(content, oldText, newText, all) {
  */
 export function editFile(filePath, edits, opts = {}) {
     const real = validatePath(filePath);
-    const original = readFileSync(real, "utf-8").replace(/\r\n/g, "\n");
+    const original = readText(real);
     const lines = original.split("\n");
     const origLines = [...lines];
+    const hadTrailingNewline = original.endsWith("\n");
 
     // Build hash index once for global relocation in findLine
     const hashIndex = buildHashIndex(lines);
@@ -313,7 +320,35 @@ export function editFile(filePath, edits, opts = {}) {
     for (const e of edits) {
         if (e.set_line || e.replace_lines || e.insert_after) anchored.push(e);
         else if (e.replace) texts.push(e);
-        else throw new Error(`Unknown edit type: ${JSON.stringify(e)}`);
+        else throw new Error(`BAD_INPUT: unknown edit type: ${JSON.stringify(e)}`);
+    }
+
+    // Overlap validation: reject duplicate/overlapping edit targets
+    const editTargets = [];
+    for (const e of anchored) {
+        if (e.set_line) {
+            const line = parseRef(e.set_line.anchor).line;
+            editTargets.push({ start: line, end: line });
+        } else if (e.replace_lines) {
+            const s = parseRef(e.replace_lines.start_anchor).line;
+            const en = parseRef(e.replace_lines.end_anchor).line;
+            editTargets.push({ start: s, end: en });
+        } else if (e.insert_after) {
+            const line = parseRef(e.insert_after.anchor).line;
+            editTargets.push({ start: line, end: line, insert: true });
+        }
+    }
+    for (let i = 0; i < editTargets.length; i++) {
+        for (let j = i + 1; j < editTargets.length; j++) {
+            const a = editTargets[i], b = editTargets[j];
+            if (a.insert || b.insert) continue; // insert_after doesn't overlap
+            if (a.start <= b.end && b.start <= a.end) {
+                throw new Error(
+                    `OVERLAPPING_EDITS: lines ${a.start}-${a.end} and ${b.start}-${b.end} overlap. ` +
+                    `Split into separate edit_file calls.`
+                );
+            }
+        }
     }
 
     // Sort anchor edits bottom-to-top
@@ -356,9 +391,11 @@ export function editFile(filePath, edits, opts = {}) {
             const actualStart = si + 1;
             const actualEnd = ei + 1;
             if (csStart > actualStart || csEnd < actualEnd) {
+                const snip = buildErrorSnippet(origLines, actualStart - 1);
                 throw new Error(
-                    `Checksum range ${csStart}-${csEnd} does not cover edit range ${actualStart}-${actualEnd}. ` +
-                    `Re-read lines ${actualStart}-${actualEnd} first.`
+                    `CHECKSUM_RANGE_GAP: range ${csStart}-${csEnd} does not cover edit range ${actualStart}-${actualEnd}.\n\n` +
+                    `Current content (lines ${snip.start}-${snip.end}):\n${snip.text}\n\n` +
+                    `Tip: Use updated hashes above for retry.`
                 );
             }
 
@@ -366,14 +403,24 @@ export function editFile(filePath, edits, opts = {}) {
             const csStartIdx = csStart - 1;
             const csEndIdx = csEnd - 1;
             if (csStartIdx < 0 || csEndIdx >= origLines.length) {
-                throw new Error(`Checksum range ${csStart}-${csEnd} out of bounds (file has ${origLines.length} lines). Re-read the file.`);
+                const snip = buildErrorSnippet(origLines, origLines.length - 1);
+                throw new Error(
+                    `CHECKSUM_OUT_OF_BOUNDS: range ${csStart}-${csEnd} exceeds file length ${origLines.length}.\n\n` +
+                    `Current content (lines ${snip.start}-${snip.end}):\n${snip.text}\n\n` +
+                    `Tip: Use updated hashes above for retry.`
+                );
             }
             const lineHashes = [];
             for (let i = csStartIdx; i <= csEndIdx; i++) lineHashes.push(fnv1a(origLines[i]));
             const actual = rangeChecksum(lineHashes, csStart, csEnd);
             const actualHex = actual.split(":")[1];
             if (csHex !== actualHex) {
-                throw new Error(`Range checksum mismatch: expected ${rc}, got ${actual}. File changed \u2014 re-read lines ${csStart}-${csEnd}.`);
+                const snip = buildErrorSnippet(origLines, csStartIdx);
+                throw new Error(
+                    `CHECKSUM_MISMATCH: expected ${rc}, got ${actual}. File changed \u2014 re-read lines ${csStart}-${csEnd}.\n\n` +
+                    `Current content (lines ${snip.start}-${snip.end}):\n${snip.text}\n\n` +
+                    `Retry with fresh checksum ${actual}, or use set_line with hashes above.`
+                );
             }
 
             const txt = e.replace_lines.new_text;
@@ -396,6 +443,8 @@ export function editFile(filePath, edits, opts = {}) {
 
     // Apply text replacements
     let content = lines.join("\n");
+    if (hadTrailingNewline && !content.endsWith("\n")) content += "\n";
+    if (!hadTrailingNewline && content.endsWith("\n")) content = content.slice(0, -1);
     for (const e of texts) {
         if (!e.replace.old_text) throw new Error("replace.old_text required");
         content = textReplace(content, e.replace.old_text, e.replace.new_text || "", e.replace.all || false);
@@ -442,5 +491,34 @@ export function editFile(filePath, edits, opts = {}) {
         }
     } catch { /* silent */ }
 
+    // Post-edit context: hash-annotated lines around changed region + checksums
+    const newLines = content.split("\n");
+    if (diff) {
+        const diffArr = diff.split("\n");
+        let minLine = Infinity, maxLine = 0;
+        for (const dl of diffArr) {
+            const m = dl.match(/^[+-](\d+)\|/);
+            if (m) { const n = +m[1]; if (n < minLine) minLine = n; if (n > maxLine) maxLine = n; }
+        }
+        if (minLine <= maxLine) {
+            const ctxStart = Math.max(0, minLine - 6);
+            const ctxEnd = Math.min(newLines.length, maxLine + 5);
+            const ctxLines = [];
+            const ctxHashes = [];
+            for (let i = ctxStart; i < ctxEnd; i++) {
+                const h = fnv1a(newLines[i]);
+                ctxHashes.push(h);
+                ctxLines.push(`${lineTag(h)}.${i + 1}\t${newLines[i]}`);
+            }
+            const ctxCs = rangeChecksum(ctxHashes, ctxStart + 1, ctxEnd);
+            msg += `\n\nPost-edit (lines ${ctxStart + 1}-${ctxEnd}):\n${ctxLines.join("\n")}\nchecksum: ${ctxCs}`;
+        }
+    }
+    // File-level checksum
+    const fileHashes = [];
+    for (let i = 0; i < newLines.length; i++) fileHashes.push(fnv1a(newLines[i]));
+    const fileCs = rangeChecksum(fileHashes, 1, newLines.length);
+    msg += `\nfile: ${fileCs}`;
+
     return msg;
 }