@levnikolaevich/hex-line-mcp 1.3.5 → 1.4.0

package/README.md

@@ -42,7 +42,7 @@ Advanced / occasional:
 | `get_file_info` | File metadata without reading content | Size, lines, mtime, type, binary detection |
 | `setup_hooks` | Configure Claude hooks + install output style | Gemini/Codex get guidance only; no hooks |
 | `changes` | Compare file against git ref, shows added/removed/modified symbols | AST-level semantic diff |
-| `bulk_replace` | Search-and-replace across multiple files by glob | Per-file diffs, dry_run, max_files safety |
+| `bulk_replace` | Search-and-replace across multiple files by glob | Compact summary (default) or capped diffs via `format`, dry_run, max_files |
 
 ### Hooks (PreToolUse + PostToolUse)
 
@@ -90,45 +90,33 @@ The `setup_hooks` tool automatically installs the output style to `~/.claude/out
 
 ## Benchmarking
 
-`hex-line-mcp` now distinguishes:
+Two-tier benchmark architecture:
 
-- `tests` — correctness and regression safety
-- `benchmarks` — comparative workflow efficiency against built-in tools
-- `diagnostics` — modeled tool-level measurements for engineering inspection
-
-Public benchmark mode reports only comparative multi-step workflows:
+- `/benchmark-compare` — real 1:1 comparison (runs inside Claude Code, calls BOTH built-in and hex-line tools on same files)
+- `npm run benchmark` — hex-line standalone metrics (Node.js, all real library calls, no simulations)
 
 ```bash
 npm run benchmark -- --repo /path/to/repo
-```
-
-Optional diagnostics stay available separately:
-
-```bash
 npm run benchmark:diagnostic -- --repo /path/to/repo
-npm run benchmark:diagnostic:graph -- --repo /path/to/repo
 ```
 
-The diagnostics output includes synthetic tool-level comparisons such as read, grep, verify, and graph-enrichment helpers. Those numbers are useful for inspecting output shape and token behavior, but they are not the public workflow benchmark score.
-
-Current sample run on the `hex-line-mcp` repo with session-derived workflows:
-
-| ID | Workflow | Built-in | hex-line | Savings | Ops |
-|----|----------|---------:|---------:|--------:|----:|
-| W1 | Debug hook file-listing redirect | 23,143 chars | 882 chars | 96% | 3→2 |
-| W2 | Adjust `setup_hooks` guidance and verify | 24,877 chars | 1,637 chars | 93% | 3→3 |
-| W3 | Repo-wide benchmark wording refresh | 137,796 chars | 38,918 chars | 72% | 15→1 |
-| W4 | Inspect large smoke test before edit | 49,566 chars | 2,104 chars | 96% | 3→3 |
+Current hex-line workflow metrics on the `hex-line-mcp` repo (all real library calls):
 
-Workflow summary: `89%` average token savings, `24→9` tool calls (`63%` fewer).
+| # | Workflow | Hex-line output | Ops |
+|---|----------|---------:|----:|
+| W1 | Debug hook file-listing redirect | 882 chars | 2 |
+| W2 | Adjust `setup_hooks` guidance and verify | 1,719 chars | 3 |
+| W3 | Repo-wide benchmark wording refresh | 213 chars | 1 |
+| W4 | Inspect large smoke test before edit | 2,322 chars | 3 |
+| W5 | Follow-up edit after unrelated line shift | 1,267 chars | 3 |
 
-These workflows are derived from recent real Claude sessions, but executed against local reproducible fixtures in the repository. They should be read as workflow-efficiency measurements, not as correctness or semantic-quality claims.
+Workflow total: `6,403` chars across `12` ops. Run `/benchmark-compare` in Claude Code for full built-in vs hex-line comparison with real tool calls on both sides.
 
 ### Optional Graph Enrichment
 
-If a project already has `.codegraph/index.db`, `hex-line` can add lightweight graph hints to `read_file`, `outline`, `grep_search`, and `edit_file`.
+If a project already has `.hex-skills/codegraph/index.db`, `hex-line` can add lightweight graph hints to `read_file`, `outline`, `grep_search`, and `edit_file`.
 
-- Graph enrichment is optional. If `.codegraph/index.db` is missing, `hex-line` falls back to standard behavior silently.
+- Graph enrichment is optional. If `.hex-skills/codegraph/index.db` is missing, `hex-line` falls back to standard behavior silently.
 - `better-sqlite3` is optional. If it is unavailable, `hex-line` still works without graph hints.
 - `edit_file` reports **Call impact**, not full semantic blast radius. The warning uses call-graph callers only.
 
@@ -160,7 +148,7 @@ Use `replace_between` inside `edit_file` when you know stable start/end anchors
 
 ### Literal rename / refactor
 
-Use `bulk_replace` for text rename patterns across one or more files. Do not use it as a substitute for structured block rewrites.
+Use `bulk_replace` for text rename patterns across one or more files. Returns compact summary by default; pass `format: "full"` for capped diffs. Do not use it as a substitute for structured block rewrites.
 
 ### read_file
 

package/dist/hook.mjs

@@ -91,13 +91,13 @@ var BINARY_EXT = /* @__PURE__ */ new Set([
 ]);
 var REVERSE_TOOL_HINTS = {
   "mcp__hex-line__read_file": "Read (file_path, offset, limit)",
-  "mcp__hex-line__edit_file": "Edit (revision-aware hash edits, block rewrite, auto-rebase)",
+  "mcp__hex-line__edit_file": "Edit (old_string, new_string, replace_all)",
   "mcp__hex-line__write_file": "Write (file_path, content)",
   "mcp__hex-line__grep_search": "Grep (pattern, path)",
   "mcp__hex-line__directory_tree": "Glob (pattern) or Bash(ls)",
   "mcp__hex-line__get_file_info": "Bash(stat/wc)",
   "mcp__hex-line__outline": "Read with offset/limit",
-  "mcp__hex-line__verify": "Verify held checksums / revision without reread",
+  "mcp__hex-line__verify": "Read (re-read file to check freshness)",
   "mcp__hex-line__changes": "Bash(git diff)",
   "mcp__hex-line__bulk_replace": "Edit (text rename/refactor across files)",
   "mcp__hex-line__setup_hooks": "Not available (hex-line disabled)"
@@ -114,10 +114,10 @@ var TOOL_HINTS = {
   stat: "mcp__hex-line__get_file_info (not stat/wc/file)",
   grep: "mcp__hex-line__grep_search (not grep/rg). Params: output, literal, context_before, context_after, multiline",
   sed: "mcp__hex-line__edit_file for hash edits, or mcp__hex-line__bulk_replace for text rename (not sed -i)",
-  diff: "mcp__hex-line__changes (not diff). Git-based semantic diff",
+  diff: "mcp__hex-line__changes (not diff). Git diff with change symbols",
   outline: "mcp__hex-line__outline (before reading large code files)",
   verify: "mcp__hex-line__verify (staleness / revision check without re-read)",
-  changes: "mcp__hex-line__changes (semantic AST diff)",
+  changes: "mcp__hex-line__changes (git diff with change symbols)",
   bulk: "mcp__hex-line__bulk_replace (multi-file search-replace)",
   setup: "mcp__hex-line__setup_hooks (configure hooks for agents)"
 };

package/dist/server.mjs

@@ -6,7 +6,7 @@ import { dirname as dirname4 } from "node:path";
 import { z as z2 } from "zod";
 
 // ../hex-common/src/runtime/mcp-bootstrap.mjs
-async function createServerRuntime({ name, version: version2, installDir }) {
+async function createServerRuntime({ name, version: version2 }) {
   let McpServer, StdioServerTransport2;
   try {
     ({ McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js"));
@@ -14,11 +14,16 @@ async function createServerRuntime({ name, version: version2, installDir }) {
   } catch {
     process.stderr.write(
       `${name}: @modelcontextprotocol/sdk not found.
-Run: cd ${installDir} && npm install
+Run: npm install @modelcontextprotocol/sdk
 `
     );
     process.exit(1);
   }
+  const shutdown = () => {
+    process.exit(0);
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
   return {
     server: new McpServer({ name, version: version2 }),
     StdioServerTransport: StdioServerTransport2
@@ -249,6 +254,9 @@ function listDirectory(dirPath, opts = {}) {
   return { text: lines.join("\n"), total };
 }
 var MAX_OUTPUT_CHARS = 8e4;
+var MAX_DIFF_CHARS = 3e4;
+var MAX_BULK_OUTPUT_CHARS = 3e4;
+var MAX_PER_FILE_DIFF_LINES = 50;
 function readText(filePath) {
   return readFileSync(filePath, "utf-8").replace(/\r\n/g, "\n");
 }
@@ -339,7 +347,7 @@ function getGraphDB(filePath) {
   try {
     const projectRoot = findProjectRoot(filePath);
     if (!projectRoot) return null;
-    const dbPath = join3(projectRoot, ".codegraph", "index.db");
+    const dbPath = join3(projectRoot, ".hex-skills/codegraph", "index.db");
     if (!existsSync2(dbPath)) return null;
     if (_dbs.has(dbPath)) return _dbs.get(dbPath);
     const require2 = createRequire(import.meta.url);
@@ -453,7 +461,7 @@ function getRelativePath(filePath) {
 function findProjectRoot(filePath) {
   let dir = dirname2(filePath);
   for (let i = 0; i < 10; i++) {
-    if (existsSync2(join3(dir, ".codegraph", "index.db"))) return dir;
+    if (existsSync2(join3(dir, ".hex-skills/codegraph", "index.db"))) return dir;
     const parent = dirname2(dir);
     if (parent === dir) break;
     dir = parent;
@@ -1036,125 +1044,131 @@ function editFile(filePath, edits, opts = {}) {
     autoRebased = true;
     return null;
   };
-  for (const e of sorted) {
-    if (e.set_line) {
-      const { tag, line } = parseRef(e.set_line.anchor);
-      const idx = locateOrConflict({ tag, line });
-      if (typeof idx === "string") return idx;
-      const conflict = ensureRevisionContext(idx + 1, idx + 1, idx);
-      if (conflict) return conflict;
-      const txt = e.set_line.new_text;
-      if (!txt && txt !== 0) {
-        lines.splice(idx, 1);
-      } else {
-        const origLine = [lines[idx]];
-        const raw = String(txt).split("\n");
-        const newLines = opts.restoreIndent ? restoreIndent(origLine, raw) : raw;
-        lines.splice(idx, 1, ...newLines);
-      }
-      continue;
-    }
-    if (e.insert_after) {
-      const { tag, line } = parseRef(e.insert_after.anchor);
-      const idx = locateOrConflict({ tag, line });
-      if (typeof idx === "string") return idx;
-      const conflict = ensureRevisionContext(idx + 1, idx + 1, idx);
-      if (conflict) return conflict;
-      let insertLines = e.insert_after.text.split("\n");
-      if (opts.restoreIndent) insertLines = restoreIndent([lines[idx]], insertLines);
-      lines.splice(idx + 1, 0, ...insertLines);
-      continue;
-    }
-    if (e.replace_lines) {
-      const s = parseRef(e.replace_lines.start_anchor);
-      const en = parseRef(e.replace_lines.end_anchor);
-      const si = locateOrConflict(s);
-      if (typeof si === "string") return si;
-      const ei = locateOrConflict(en);
-      if (typeof ei === "string") return ei;
-      const actualStart = si + 1;
-      const actualEnd = ei + 1;
-      const rc = e.replace_lines.range_checksum;
-      if (!rc) throw new Error("range_checksum required for replace_lines. Read the range first via read_file, then pass its checksum.");
-      if (staleRevision && conflictPolicy === "conservative") {
-        const conflict = ensureRevisionContext(actualStart, actualEnd, si);
+  for (let _ei = 0; _ei < sorted.length; _ei++) {
+    const e = sorted[_ei];
+    try {
+      if (e.set_line) {
+        const { tag, line } = parseRef(e.set_line.anchor);
+        const idx = locateOrConflict({ tag, line });
+        if (typeof idx === "string") return idx;
+        const conflict = ensureRevisionContext(idx + 1, idx + 1, idx);
         if (conflict) return conflict;
-        const baseCheck = hasBaseSnapshot ? verifyChecksumAgainstSnapshot(baseSnapshot, rc) : null;
-        if (!baseCheck?.ok) {
-          return conflictIfNeeded(
-            "stale_checksum",
-            si,
-            baseCheck?.actual || null,
-            baseCheck?.actual ? `Provided checksum ${rc} does not match base revision ${opts.baseRevision}.` : `Checksum range from ${rc} is outside the available base revision.`
-          );
+        const txt = e.set_line.new_text;
+        if (!txt && txt !== 0) {
+          lines.splice(idx, 1);
+        } else {
+          const origLine = [lines[idx]];
+          const raw = String(txt).split("\n");
+          const newLines = opts.restoreIndent ? restoreIndent(origLine, raw) : raw;
+          lines.splice(idx, 1, ...newLines);
         }
-      } else {
-        const { start: csStart, end: csEnd, hex: csHex } = parseChecksum(rc);
-        if (csStart > actualStart || csEnd < actualEnd) {
-          const snip = buildErrorSnippet(origLines, actualStart - 1);
-          throw new Error(
-            `CHECKSUM_RANGE_GAP: range ${csStart}-${csEnd} does not cover edit range ${actualStart}-${actualEnd}.
+        continue;
+      }
+      if (e.insert_after) {
+        const { tag, line } = parseRef(e.insert_after.anchor);
+        const idx = locateOrConflict({ tag, line });
+        if (typeof idx === "string") return idx;
+        const conflict = ensureRevisionContext(idx + 1, idx + 1, idx);
+        if (conflict) return conflict;
+        let insertLines = e.insert_after.text.split("\n");
+        if (opts.restoreIndent) insertLines = restoreIndent([lines[idx]], insertLines);
+        lines.splice(idx + 1, 0, ...insertLines);
+        continue;
+      }
+      if (e.replace_lines) {
+        const s = parseRef(e.replace_lines.start_anchor);
+        const en = parseRef(e.replace_lines.end_anchor);
+        const si = locateOrConflict(s);
+        if (typeof si === "string") return si;
+        const ei = locateOrConflict(en);
+        if (typeof ei === "string") return ei;
+        const actualStart = si + 1;
+        const actualEnd = ei + 1;
+        const rc = e.replace_lines.range_checksum;
+        if (!rc) throw new Error("range_checksum required for replace_lines. Read the range first via read_file, then pass its checksum. The checksum range must cover start-to-end anchors (inclusive).");
+        if (staleRevision && conflictPolicy === "conservative") {
+          const conflict = ensureRevisionContext(actualStart, actualEnd, si);
+          if (conflict) return conflict;
+          const baseCheck = hasBaseSnapshot ? verifyChecksumAgainstSnapshot(baseSnapshot, rc) : null;
+          if (!baseCheck?.ok) {
+            return conflictIfNeeded(
+              "stale_checksum",
+              si,
+              baseCheck?.actual || null,
+              baseCheck?.actual ? `Provided checksum ${rc} does not match base revision ${opts.baseRevision}.` : `Checksum range from ${rc} is outside the available base revision.`
+            );
+          }
+        } else {
+          const { start: csStart, end: csEnd, hex: csHex } = parseChecksum(rc);
+          if (csStart > actualStart || csEnd < actualEnd) {
+            const snip = buildErrorSnippet(origLines, actualStart - 1);
+            throw new Error(
+              `CHECKSUM_RANGE_GAP: checksum covers lines ${csStart}-${csEnd} but edit spans ${actualStart}-${actualEnd} (inclusive). Checksum range must fully contain the anchor range.
 
 Current content (lines ${snip.start}-${snip.end}):
 ${snip.text}
 
 Tip: Use updated hashes above for retry.`
-          );
-        }
-        const actual = buildRangeChecksum(currentSnapshot, csStart, csEnd);
-        const actualHex = actual?.split(":")[1];
-        if (!actual || csHex !== actualHex) {
-          const details = `CHECKSUM_MISMATCH: expected ${rc}, got ${actual}. File changed \u2014 re-read lines ${csStart}-${csEnd}.`;
-          if (conflictPolicy === "conservative") {
-            return conflictIfNeeded("stale_checksum", csStart - 1, actual, details);
+            );
           }
-          const snip = buildErrorSnippet(origLines, csStart - 1);
-          throw new Error(
-            `${details}
+          const actual = buildRangeChecksum(currentSnapshot, csStart, csEnd);
+          const actualHex = actual?.split(":")[1];
+          if (!actual || csHex !== actualHex) {
+            const details = `CHECKSUM_MISMATCH: expected ${rc}, got ${actual}. Content at lines ${csStart}-${csEnd} differs from when you read it \u2014 re-read before editing.`;
+            if (conflictPolicy === "conservative") {
+              return conflictIfNeeded("stale_checksum", csStart - 1, actual, details);
+            }
+            const snip = buildErrorSnippet(origLines, csStart - 1);
+            throw new Error(
+              `${details}
 
 Current content (lines ${snip.start}-${snip.end}):
 ${snip.text}
 
 Retry with fresh checksum ${actual}, or use set_line with hashes above.`
-          );
+            );
+          }
         }
+        const txt = e.replace_lines.new_text;
+        if (!txt && txt !== 0) {
+          lines.splice(si, ei - si + 1);
+        } else {
+          const origRange = lines.slice(si, ei + 1);
+          let newLines = String(txt).split("\n");
+          if (opts.restoreIndent) newLines = restoreIndent(origRange, newLines);
+          lines.splice(si, ei - si + 1, ...newLines);
+        }
+        continue;
       }
-      const txt = e.replace_lines.new_text;
-      if (!txt && txt !== 0) {
-        lines.splice(si, ei - si + 1);
-      } else {
-        const origRange = lines.slice(si, ei + 1);
-        let newLines = String(txt).split("\n");
-        if (opts.restoreIndent) newLines = restoreIndent(origRange, newLines);
-        lines.splice(si, ei - si + 1, ...newLines);
-      }
-      continue;
-    }
-    if (e.replace_between) {
-      const boundaryMode = e.replace_between.boundary_mode || "inclusive";
-      if (boundaryMode !== "inclusive" && boundaryMode !== "exclusive") {
-        throw new Error(`BAD_INPUT: replace_between boundary_mode must be inclusive or exclusive, got ${boundaryMode}`);
-      }
-      const s = parseRef(e.replace_between.start_anchor);
-      const en = parseRef(e.replace_between.end_anchor);
-      const si = locateOrConflict(s);
-      if (typeof si === "string") return si;
-      const ei = locateOrConflict(en);
-      if (typeof ei === "string") return ei;
-      if (si > ei) {
-        throw new Error(`BAD_INPUT: replace_between start anchor resolves after end anchor (${si + 1} > ${ei + 1})`);
+      if (e.replace_between) {
+        const boundaryMode = e.replace_between.boundary_mode || "inclusive";
+        if (boundaryMode !== "inclusive" && boundaryMode !== "exclusive") {
+          throw new Error(`BAD_INPUT: replace_between boundary_mode must be inclusive or exclusive, got ${boundaryMode}`);
+        }
+        const s = parseRef(e.replace_between.start_anchor);
+        const en = parseRef(e.replace_between.end_anchor);
+        const si = locateOrConflict(s);
+        if (typeof si === "string") return si;
+        const ei = locateOrConflict(en);
+        if (typeof ei === "string") return ei;
+        if (si > ei) {
+          throw new Error(`BAD_INPUT: replace_between start anchor resolves after end anchor (${si + 1} > ${ei + 1})`);
+        }
+        const targetRange = targetRangeForReplaceBetween(si, ei, boundaryMode);
+        const conflict = ensureRevisionContext(targetRange.start, targetRange.end, si);
+        if (conflict) return conflict;
+        const txt = e.replace_between.new_text;
+        let newLines = String(txt ?? "").split("\n");
+        const sliceStart = boundaryMode === "exclusive" ? si + 1 : si;
+        const removeCount = boundaryMode === "exclusive" ? Math.max(0, ei - si - 1) : ei - si + 1;
+        const origRange = lines.slice(sliceStart, sliceStart + removeCount);
+        if (opts.restoreIndent && origRange.length > 0) newLines = restoreIndent(origRange, newLines);
+        if (txt === "" || txt === null) newLines = [];
+        lines.splice(sliceStart, removeCount, ...newLines);
       }
-      const targetRange = targetRangeForReplaceBetween(si, ei, boundaryMode);
-      const conflict = ensureRevisionContext(targetRange.start, targetRange.end, si);
-      if (conflict) return conflict;
-      const txt = e.replace_between.new_text;
-      let newLines = String(txt ?? "").split("\n");
-      const sliceStart = boundaryMode === "exclusive" ? si + 1 : si;
-      const removeCount = boundaryMode === "exclusive" ? Math.max(0, ei - si - 1) : ei - si + 1;
-      const origRange = lines.slice(sliceStart, sliceStart + removeCount);
-      if (opts.restoreIndent && origRange.length > 0) newLines = restoreIndent(origRange, newLines);
-      if (txt === "" || txt === null) newLines = [];
-      lines.splice(sliceStart, removeCount, ...newLines);
+    } catch (editErr) {
+      if (sorted.length > 1) editErr.message = `Edit ${_ei + 1}/${sorted.length}: ${editErr.message}`;
+      throw editErr;
     }
   }
   let content = lines.join("\n");
@@ -1163,10 +1177,23 @@ Retry with fresh checksum ${actual}, or use set_line with hashes above.`
   if (original === content) {
     throw new Error("NOOP_EDIT: File already contains the desired content. No changes needed.");
   }
-  let diff = simpleDiff(origLines, content.split("\n"));
-  if (diff && diff.length > 8e4) {
-    diff = diff.slice(0, 8e4) + `
-... (diff truncated, ${diff.length} chars total)`;
+  const fullDiff = simpleDiff(origLines, content.split("\n"));
+  let displayDiff = fullDiff;
+  if (displayDiff && displayDiff.length > MAX_DIFF_CHARS) {
+    displayDiff = displayDiff.slice(0, MAX_DIFF_CHARS) + `
+... (diff truncated, ${displayDiff.length} chars total)`;
+  }
+  const newLinesAll = content.split("\n");
+  let minLine = Infinity, maxLine = 0;
+  if (fullDiff) {
+    for (const dl of fullDiff.split("\n")) {
+      const m = dl.match(/^[+-](\d+)\|/);
+      if (m) {
+        const n = +m[1];
+        if (n < minLine) minLine = n;
+        if (n > maxLine) maxLine = n;
+      }
+    }
   }
   if (opts.dryRun) {
     let msg2 = `status: ${autoRebased ? "AUTO_REBASED" : "OK"}
@@ -1175,11 +1202,11 @@ file: ${currentSnapshot.fileChecksum}
 Dry run: ${filePath} would change (${content.split("\n").length} lines)`;
     if (staleRevision && hasBaseSnapshot) msg2 += `
 changed_ranges: ${describeChangedRanges(changedRanges)}`;
-    if (diff) msg2 += `
+    if (displayDiff) msg2 += `
 
 Diff:
 \`\`\`diff
-${diff}
+${displayDiff}
 \`\`\``;
     return msg2;
   }
@@ -1195,78 +1222,55 @@ changed_ranges: ${describeChangedRanges(changedRanges)}`;
   }
   msg += `
 Updated ${filePath} (${content.split("\n").length} lines)`;
-  if (diff) msg += `
+  if (fullDiff && minLine <= maxLine) {
+    const ctxStart = Math.max(0, minLine - 6);
+    const ctxEnd = Math.min(newLinesAll.length, maxLine + 5);
+    const ctxLines = [];
+    const ctxHashes = [];
+    for (let i = ctxStart; i < ctxEnd; i++) {
+      const h = fnv1a(newLinesAll[i]);
+      ctxHashes.push(h);
+      ctxLines.push(`${lineTag(h)}.${i + 1}	${newLinesAll[i]}`);
+    }
+    const ctxCs = rangeChecksum(ctxHashes, ctxStart + 1, ctxEnd);
+    msg += `
 
-Diff:
-\`\`\`diff
-${diff}
-\`\`\``;
+Post-edit (lines ${ctxStart + 1}-${ctxEnd}):
+${ctxLines.join("\n")}
+checksum: ${ctxCs}`;
+  }
   try {
     const db = getGraphDB(real);
     const relFile = db ? getRelativePath(real) : null;
-    if (db && relFile && diff) {
-      const diffLinesOut = diff.split("\n");
-      let minLine = Infinity, maxLine = 0;
-      for (const dl of diffLinesOut) {
-        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 affected = callImpact(db, relFile, minLine, maxLine);
-        if (affected.length > 0) {
-          const list = affected.map((a) => `${a.name} (${a.file}:${a.line})`).join(", ");
-          msg += `
+    if (db && relFile && fullDiff && minLine <= maxLine) {
+      const affected = callImpact(db, relFile, minLine, maxLine);
+      if (affected.length > 0) {
+        const list = affected.map((a) => `${a.name} (${a.file}:${a.line})`).join(", ");
+        msg += `
 
 \u26A0 Call impact: ${affected.length} callers in other files
   ${list}`;
-        }
       }
     }
   } catch {
   }
-  const newLinesAll = 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(newLinesAll.length, maxLine + 5);
-      const ctxLines = [];
-      const ctxHashes = [];
-      for (let i = ctxStart; i < ctxEnd; i++) {
-        const h = fnv1a(newLinesAll[i]);
-        ctxHashes.push(h);
-        ctxLines.push(`${lineTag(h)}.${i + 1}	${newLinesAll[i]}`);
-      }
-      const ctxCs = rangeChecksum(ctxHashes, ctxStart + 1, ctxEnd);
-      msg += `
+  if (displayDiff) msg += `
 
-Post-edit (lines ${ctxStart + 1}-${ctxEnd}):
-${ctxLines.join("\n")}
-checksum: ${ctxCs}`;
-    }
-  }
+Diff:
+\`\`\`diff
+${displayDiff}
+\`\`\``;
   return msg;
 }
 
 // lib/search.mjs
 import { spawn } from "node:child_process";
-import { resolve as resolve2 } from "node:path";
+import { resolve as resolve2, isAbsolute as isAbsolute2 } from "node:path";
+import { existsSync as existsSync3 } from "node:fs";
 var rgBin = "rg";
 try {
   rgBin = (await import("@vscode/ripgrep")).rgPath;
+  if (isAbsolute2(rgBin) && !existsSync3(rgBin)) rgBin = "rg";
 } catch {
 }
 var DEFAULT_LIMIT2 = 100;
@@ -1292,7 +1296,13 @@ function spawnRg(args) {
       stderrBuf += chunk.toString("utf-8");
     });
     child.on("error", (err) => {
-      reject(new Error(`rg spawn error: ${err.message}`));
+      if (err.code === "ENOENT") {
+        reject(new Error(
+          `ripgrep not available. Reinstall dependencies so @vscode/ripgrep can provide its binary, or install system rg and add it to PATH. Attempted binary: "${rgBin}".`
+        ));
+      } else {
+        reject(new Error(`rg spawn error: ${err.message}`));
+      }
     });
     child.on("close", (code) => {
       resolve_({ stdout, code, stderr: stderrBuf, killed });
@@ -1694,7 +1704,7 @@ file: ${current.fileChecksum}`;
 }
 
 // lib/tree.mjs
-import { readdirSync as readdirSync2, readFileSync as readFileSync3, statSync as statSync6, existsSync as existsSync3 } from "node:fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync3, statSync as statSync6, existsSync as existsSync4 } from "node:fs";
 import { resolve as resolve4, basename, join as join4, relative as relative2 } from "node:path";
 import ignore from "ignore";
 var SKIP_DIRS = /* @__PURE__ */ new Set([
@@ -1713,7 +1723,7 @@ function globToRegex(pat) {
 }
 function loadGitignore(rootDir) {
   const gi = join4(rootDir, ".gitignore");
-  if (!existsSync3(gi)) return null;
+  if (!existsSync4(gi)) return null;
   try {
     const content = readFileSync3(gi, "utf-8");
     return ignore().add(content);
@@ -1730,7 +1740,7 @@ function findByPattern(dirPath, opts) {
   const filterType = opts.type || "all";
   const maxDepth = opts.max_depth ?? 20;
   const abs = resolve4(normalizePath(dirPath));
-  if (!existsSync3(abs)) throw new Error(`DIRECTORY_NOT_FOUND: ${abs}`);
+  if (!existsSync4(abs)) throw new Error(`DIRECTORY_NOT_FOUND: ${abs}`);
   if (!statSync6(abs).isDirectory()) throw new Error(`Not a directory: ${abs}`);
   const ig = opts.gitignore ?? true ? loadGitignore(abs) : null;
   const matches = [];
@@ -1771,7 +1781,7 @@ function directoryTree(dirPath, opts = {}) {
   const compact = opts.format === "compact";
   const maxDepth = compact ? 1 : opts.max_depth ?? 3;
   const abs = resolve4(normalizePath(dirPath));
-  if (!existsSync3(abs)) throw new Error(`DIRECTORY_NOT_FOUND: ${abs}. Check path or use directory_tree on parent directory.`);
+  if (!existsSync4(abs)) throw new Error(`DIRECTORY_NOT_FOUND: ${abs}. Check path or use directory_tree on parent directory.`);
   const rootStat = statSync6(abs);
   if (!rootStat.isDirectory()) throw new Error(`Not a directory: ${abs}`);
   const ig = opts.gitignore ?? true ? loadGitignore(abs) : null;
@@ -1868,7 +1878,7 @@ ${lines.join("\n")}`;
 
 // lib/info.mjs
 import { statSync as statSync7, openSync as openSync2, readSync as readSync2, closeSync as closeSync2 } from "node:fs";
-import { resolve as resolve5, isAbsolute as isAbsolute2, extname as extname2, basename as basename2 } from "node:path";
+import { resolve as resolve5, isAbsolute as isAbsolute3, extname as extname2, basename as basename2 } from "node:path";
 var MAX_LINE_COUNT_SIZE = 10 * 1024 * 1024;
 var EXT_NAMES = {
   ".ts": "TypeScript source",
@@ -1937,7 +1947,7 @@ function detectBinary(filePath, size) {
 function fileInfo(filePath) {
   if (!filePath) throw new Error("Empty file path");
   const normalized = normalizePath(filePath);
-  const abs = isAbsolute2(normalized) ? normalized : resolve5(process.cwd(), normalized);
+  const abs = isAbsolute3(normalized) ? normalized : resolve5(process.cwd(), normalized);
   const stat = statSync7(abs);
   if (!stat.isFile()) throw new Error(`Not a regular file: ${abs}`);
   const size = stat.size;
@@ -1961,19 +1971,18 @@ function fileInfo(filePath) {
 }
 
 // lib/setup.mjs
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync4, mkdirSync } from "node:fs";
-import { resolve as resolve6, dirname as dirname3 } from "node:path";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync5, mkdirSync, copyFileSync } from "node:fs";
+import { resolve as resolve6, dirname as dirname3, join as join5 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
+var STABLE_HOOK_DIR = resolve6(homedir(), ".claude", "hex-line");
+var STABLE_HOOK_PATH = join5(STABLE_HOOK_DIR, "hook.mjs").replace(/\\/g, "/");
+var HOOK_COMMAND = `node ${STABLE_HOOK_PATH}`;
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname3(__filename);
-var HOOK_SCRIPT = resolve6(__dirname, "..", "hook.mjs").replace(/\\/g, "/");
-var HOOK_COMMAND = `node ${HOOK_SCRIPT}`;
-var HOOK_SIGNATURE = "hex-line-mcp/hook.mjs";
-var NPX_MARKERS = ["_npx", "npx-cache", ".npm/_npx"];
-function isEphemeralInstall(scriptPath) {
-  return NPX_MARKERS.some((m) => scriptPath.includes(m));
-}
+var SOURCE_HOOK = resolve6(__dirname, "..", "hook.mjs");
+var DIST_HOOK = resolve6(__dirname, "hook.mjs");
+var HOOK_SIGNATURE = "hex-line";
 var CLAUDE_HOOKS = {
   SessionStart: {
     matcher: "*",
@@ -1989,7 +1998,7 @@ var CLAUDE_HOOKS = {
   }
 };
 function readJson(filePath) {
-  if (!existsSync4(filePath)) return null;
+  if (!existsSync5(filePath)) return null;
   return JSON.parse(readFileSync4(filePath, "utf-8"));
 }
 function writeJson(filePath, data) {
@@ -2035,7 +2044,7 @@ function writeHooksToFile(settingsPath, label) {
     return `Claude (${label}): already configured`;
   }
   writeJson(settingsPath, config);
-  return `Claude (${label}): hooks -> ${HOOK_SCRIPT} OK`;
+  return `Claude (${label}): hooks -> ${STABLE_HOOK_PATH} OK`;
 }
 function cleanLocalHooks() {
   const localPath = resolve6(process.cwd(), ".claude/settings.local.json");
@@ -2081,10 +2090,14 @@ function installOutputStyle() {
   return msg;
 }
 function setupClaude() {
-  if (isEphemeralInstall(HOOK_SCRIPT)) {
-    return "Claude: SKIPPED \u2014 hook.mjs is in npx cache (ephemeral). Install permanently: npm i -g @levnikolaevich/hex-line-mcp, then re-run setup_hooks.";
-  }
   const results = [];
+  const hookSource = existsSync5(DIST_HOOK) ? DIST_HOOK : SOURCE_HOOK;
+  if (!existsSync5(hookSource)) {
+    return "Claude: FAILED \u2014 hook.mjs not found. Reinstall @levnikolaevich/hex-line-mcp.";
+  }
+  mkdirSync(STABLE_HOOK_DIR, { recursive: true });
+  copyFileSync(hookSource, STABLE_HOOK_PATH);
+  results.push(`hook.mjs -> ${STABLE_HOOK_PATH}`);
   const globalPath = resolve6(homedir(), ".claude/settings.json");
   results.push(writeHooksToFile(globalPath, "global"));
   results.push(cleanLocalHooks());
@@ -2263,7 +2276,7 @@ Summary: ${summary}`);
 
 // lib/bulk-replace.mjs
 import { writeFileSync as writeFileSync3, readdirSync as readdirSync3 } from "node:fs";
-import { resolve as resolve7, relative as relative3, join as join5 } from "node:path";
+import { resolve as resolve7, relative as relative3, join as join6 } from "node:path";
 var ignoreMod;
 try {
   ignoreMod = await import("ignore");
@@ -2279,7 +2292,7 @@ function walkFiles(dir, rootDir, ig) {
   }
   for (const e of entries) {
     if (e.name === ".git" || e.name === "node_modules") continue;
-    const full = join5(dir, e.name);
+    const full = join6(dir, e.name);
     const rel = relative3(rootDir, full).replace(/\\/g, "/");
     if (ig && ig.ignores(rel)) continue;
     if (e.isDirectory()) {
@@ -2291,21 +2304,21 @@ function walkFiles(dir, rootDir, ig) {
   return results;
 }
 function globMatch(filename, pattern) {
-  const re = pattern.replace(/\./g, "\\.").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(/\0/g, ".*").replace(/\?/g, ".");
+  const re = pattern.replace(/\./g, "\\.").replace(/\{([^}]+)\}/g, (_, alts) => "(" + alts.split(",").join("|") + ")").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(/\0/g, ".*").replace(/\?/g, ".");
   return new RegExp("^" + re + "$").test(filename);
 }
 function loadGitignore2(rootDir) {
   if (!ignoreMod) return null;
   const ig = (ignoreMod.default || ignoreMod)();
   try {
-    const content = readText(join5(rootDir, ".gitignore"));
+    const content = readText(join6(rootDir, ".gitignore"));
     ig.add(content);
   } catch {
   }
   return ig;
 }
 function bulkReplace(rootDir, globPattern, replacements, opts = {}) {
-  const { dryRun = false, maxFiles = 100 } = opts;
+  const { dryRun = false, maxFiles = 100, format = "compact" } = opts;
   const abs = resolve7(normalizePath(rootDir));
   const ig = loadGitignore2(abs);
   const allFiles = walkFiles(abs, abs, ig);
@@ -2318,52 +2331,85 @@ function bulkReplace(rootDir, globPattern, replacements, opts = {}) {
     return `TOO_MANY_FILES: Found ${files.length} files, max_files is ${maxFiles}. Use more specific glob or increase max_files.`;
   }
   const results = [];
-  let changed = 0, skipped = 0, errors = 0;
-  const MAX_OUTPUT2 = MAX_OUTPUT_CHARS;
-  let totalChars = 0;
+  let changed = 0, skipped = 0, errors = 0, totalReplacements = 0;
   for (const file of files) {
     try {
       const original = readText(file);
       let content = original;
+      let replacementCount = 0;
       for (const { old: oldText, new: newText } of replacements) {
-        content = content.split(oldText).join(newText);
+        if (oldText === newText) continue;
+        const parts = content.split(oldText);
+        replacementCount += parts.length - 1;
+        content = parts.join(newText);
       }
       if (content === original) {
         skipped++;
         continue;
       }
-      const diff = simpleDiff(original.split("\n"), content.split("\n"));
       if (!dryRun) {
         writeFileSync3(file, content, "utf-8");
       }
-      const relPath = file.replace(abs, "").replace(/^[/\\]/, "");
-      results.push(`--- ${relPath}
-${diff || "(no visible diff)"}`);
+      const relPath = relative3(abs, file).replace(/\\/g, "/");
+      totalReplacements += replacementCount;
       changed++;
-      totalChars += results[results.length - 1].length;
-      if (totalChars > MAX_OUTPUT2) {
-        const remaining = files.length - files.indexOf(file) - 1;
-        if (remaining > 0) results.push(`OUTPUT_CAPPED: ${remaining} more files not shown. Output exceeded ${MAX_OUTPUT2} chars.`);
-        break;
+      if (format === "full") {
+        const diff = simpleDiff(original.split("\n"), content.split("\n"));
+        let diffText = diff || "(no visible diff)";
+        const diffLines3 = diffText.split("\n");
+        if (diffLines3.length > MAX_PER_FILE_DIFF_LINES) {
+          const omitted = diffLines3.length - MAX_PER_FILE_DIFF_LINES;
+          diffText = diffLines3.slice(0, MAX_PER_FILE_DIFF_LINES).join("\n") + `
+--- ${omitted} lines omitted ---`;
+        }
+        results.push(`--- ${relPath}: ${replacementCount} replacements
+${diffText}`);
+      } else {
+        results.push(`--- ${relPath}: ${replacementCount} replacements`);
       }
     } catch (e) {
       results.push(`ERROR: ${file}: ${e.message}`);
       errors++;
     }
   }
-  const header = `Bulk replace: ${changed} files changed, ${skipped} skipped, ${errors} errors (dry_run: ${dryRun})`;
-  return results.length ? `${header}
+  const header = `Bulk replace: ${changed} files changed (${totalReplacements} replacements), ${skipped} skipped, ${errors} errors (dry_run: ${dryRun})`;
+  let output = results.length ? `${header}
 
 ${results.join("\n\n")}` : header;
+  if (output.length > MAX_BULK_OUTPUT_CHARS) {
+    output = output.slice(0, MAX_BULK_OUTPUT_CHARS) + `
+OUTPUT_CAPPED: Output exceeded ${MAX_BULK_OUTPUT_CHARS} chars.`;
+  }
+  return output;
 }
 
 // server.mjs
-var version = true ? "1.3.5" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.4.0" : (await null).createRequire(import.meta.url)("./package.json").version;
 var { server, StdioServerTransport } = await createServerRuntime({
   name: "hex-line-mcp",
-  version,
-  installDir: "mcp/hex-line-mcp"
+  version
 });
+var replacementPairsSchema = z2.array(
+  z2.object({ old: z2.string().min(1), new: z2.string() })
+).min(1);
+function coerceEdit(e) {
+  if (!e || typeof e !== "object" || Array.isArray(e)) return e;
+  if (e.set_line || e.replace_lines || e.insert_after || e.replace_between || e.replace) return e;
+  if (e.anchor && !e.start_anchor && !e.end_anchor && !e.boundary_mode && !e.range_checksum) {
+    const raw = e.new_text ?? e.updated_lines ?? e.content ?? e.line;
+    if (raw !== void 0) {
+      const text = Array.isArray(raw) ? raw.join("\n") : raw;
+      return { set_line: { anchor: e.anchor, new_text: text } };
+    }
+  }
+  if (e.start_anchor && e.end_anchor && e.boundary_mode && e.new_text !== void 0) {
+    return { replace_between: { start_anchor: e.start_anchor, end_anchor: e.end_anchor, new_text: e.new_text, boundary_mode: e.boundary_mode } };
+  }
+  if (e.start_anchor && e.end_anchor && e.new_text !== void 0) {
+    return { replace_lines: { start_anchor: e.start_anchor, end_anchor: e.end_anchor, new_text: e.new_text, ...e.range_checksum ? { range_checksum: e.range_checksum } : {} } };
+  }
+  return e;
+}
 server.registerTool("read_file", {
   title: "Read File",
   description: "Read a file with hash-annotated lines, range checksums, and current revision. Use offset/limit for targeted reads; use outline first for large code files.",
@@ -2402,8 +2448,8 @@ server.registerTool("edit_file", {
   description: "Apply revision-aware partial edits to one file. Prefer one batched call per file. Supports set_line, replace_lines, insert_after, and replace_between. For text rename/refactor use bulk_replace.",
   inputSchema: z2.object({
     path: z2.string().describe("File to edit"),
-    edits: z2.string().describe(
-      'JSON array. Examples:\n{"set_line":{"anchor":"ab.12","new_text":"new"}} \u2014 replace line\n{"replace_lines":{"start_anchor":"ab.10","end_anchor":"cd.15","new_text":"...","range_checksum":"10-15:a1b2c3d4"}} \u2014 range\n{"replace_between":{"start_anchor":"ab.10","end_anchor":"cd.40","new_text":"...","boundary_mode":"inclusive"}} \u2014 block rewrite\n{"insert_after":{"anchor":"ab.20","text":"inserted"}} \u2014 insert below. For text rename use bulk_replace tool.'
+    edits: z2.union([z2.string(), z2.array(z2.any())]).describe(
+      'JSON array. Types: set_line, replace_lines, insert_after, replace_between.\n[{"set_line":{"anchor":"ab.12","new_text":"x"}}]\n[{"replace_lines":{"start_anchor":"ab.10","end_anchor":"cd.15","new_text":"x","range_checksum":"10-15:a1b2"}}]\n[{"replace_between":{"start_anchor":"ab.10","end_anchor":"cd.40","new_text":"x","boundary_mode":"inclusive"}}]\n[{"insert_after":{"anchor":"ab.20","text":"x"}}]'
     ),
     dry_run: flexBool().describe("Preview changes without writing"),
     restore_indent: flexBool().describe("Auto-fix indentation to match anchor (default: false)"),
@@ -2414,12 +2460,18 @@ server.registerTool("edit_file", {
 }, async (rawParams) => {
   const { path: p, edits: json, dry_run, restore_indent, base_revision, conflict_policy } = coerceParams(rawParams);
   try {
-    const parsed = JSON.parse(json);
+    let parsed;
+    try {
+      parsed = typeof json === "string" ? JSON.parse(json) : json;
+    } catch {
+      throw new Error('edits: invalid JSON. Expected: [{"set_line":{"anchor":"xx.N","new_text":"..."}}]');
+    }
     if (!Array.isArray(parsed) || !parsed.length) throw new Error("Edits: non-empty JSON array required");
+    const normalized = parsed.map(coerceEdit);
     return {
       content: [{
         type: "text",
-        text: editFile(p, parsed, {
+        text: editFile(p, normalized, {
           dryRun: dry_run,
           restoreIndent: restore_indent,
           baseRevision: base_revision,
@@ -2452,7 +2504,7 @@ server.registerTool("write_file", {
 });
 server.registerTool("grep_search", {
   title: "Search Files",
-  description: "Search file contents with ripgrep. Returns hash-annotated matches with per-group checksums for direct editing. Output modes: content (default, edit-ready hashes+checksums), files (paths only), count (match counts). For single-line edits: grep -> set_line directly. For range edits: use checksum from grep output. ALWAYS prefer over shell grep/rg/findstr.",
+  description: "Search file contents with ripgrep. Returns hash-annotated matches with checksums. Modes: content (default), files, count. Use checksums with set_line/replace_lines. Prefer over shell grep/rg.",
   inputSchema: z2.object({
     pattern: z2.string().describe("Search pattern (regex by default, literal if literal:true)"),
     path: z2.string().optional().describe("Search dir/file (default: cwd)"),
@@ -2513,7 +2565,7 @@ server.registerTool("grep_search", {
 });
 server.registerTool("outline", {
   title: "File Outline",
-  description: "AST-based structural outline: functions, classes, interfaces with line ranges. 10-20 lines instead of 500 \u2014 95% token reduction. Use before reading large code files. NOT for .md/.json/.yaml \u2014 use read_file.",
+  description: "AST-based structural outline: functions, classes, interfaces with line ranges. Use before reading large code files. Not for .md/.json/.yaml.",
   inputSchema: z2.object({
     path: z2.string().describe("Source file path")
   }),
@@ -2548,7 +2600,7 @@ server.registerTool("verify", {
 });
 server.registerTool("directory_tree", {
   title: "Directory Tree",
-  description: "Compact directory tree with root .gitignore support (path-based rules, negation). Supports pattern glob to find files/dirs by name (like find -name). Use to understand repo structure or find specific files/dirs. Skips node_modules, .git, dist by default.",
+  description: "Directory tree with .gitignore support. Pattern glob to find files/dirs by name. Skips node_modules, .git, dist.",
   inputSchema: z2.object({
     path: z2.string().describe("Directory path"),
     pattern: z2.string().optional().describe('Glob filter on names (e.g. "*-mcp", "*.mjs"). Returns flat match list instead of tree'),
@@ -2583,7 +2635,7 @@ server.registerTool("get_file_info", {
 });
 server.registerTool("setup_hooks", {
   title: "Setup Hooks",
-  description: "Install or uninstall hex-line hooks in CLI agent settings. install: writes hooks to ~/.claude/settings.json, removes old per-project hooks. uninstall: removes hex-line hooks from global settings. Idempotent: re-running produces no changes if already in desired state.",
+  description: "Install or uninstall hex-line hooks in CLI agent settings. Idempotent.",
   inputSchema: z2.object({
     agent: z2.string().optional().describe('Target agent: "claude", "gemini", "codex", or "all" (default: "all")'),
     action: z2.string().optional().describe('"install" (default) or "uninstall"')
@@ -2599,7 +2651,7 @@ server.registerTool("setup_hooks", {
 });
 server.registerTool("changes", {
   title: "Semantic Diff",
-  description: "Compare file or directory against git ref (default: HEAD). For files: shows added/removed/modified symbols at AST level. For directories: lists changed files with insertions/deletions stats. Use to understand what changed before committing.",
+  description: "Compare file or directory against git ref (default: HEAD). Shows added/removed/modified symbols or file stats.",
   inputSchema: z2.object({
     path: z2.string().describe("File or directory path"),
     compare_against: z2.string().optional().describe('Git ref to compare against (default: "HEAD")')
@@ -2615,25 +2667,32 @@ server.registerTool("changes", {
 });
 server.registerTool("bulk_replace", {
   title: "Bulk Replace",
-  description: "Search-and-replace across multiple files. Finds files by glob, applies ordered text replacements, returns per-file diffs. Use dry_run:true to preview. For single-file rename, set glob to the filename.",
+  description: "Search-and-replace across multiple files. Finds files by glob, applies ordered text replacements. Default format is compact (summary only); use format:'full' for capped diffs. Use dry_run:true to preview. For single-file rename, set glob to the filename.",
   inputSchema: z2.object({
-    replacements: z2.string().describe('JSON array of {old, new} pairs: [{"old":"foo","new":"bar"}]'),
+    replacements: z2.union([z2.string(), replacementPairsSchema]).describe('JSON array of {old, new} pairs: [{"old":"foo","new":"bar"}]'),
     glob: z2.string().optional().describe('File glob (default: "**/*.{md,mjs,json,yml,ts,js}")'),
     path: z2.string().optional().describe("Root directory (default: cwd)"),
     dry_run: flexBool().describe("Preview without writing (default: false)"),
-    max_files: flexNum().describe("Max files to process (default: 100)")
+    max_files: flexNum().describe("Max files to process (default: 100)"),
+    format: z2.enum(["compact", "full"]).optional().describe('"compact" (default) = summary only, "full" = include capped diffs')
   }),
   annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false }
 }, async (rawParams) => {
   try {
     const params = coerceParams(rawParams);
-    const replacements = JSON.parse(params.replacements);
-    if (!Array.isArray(replacements) || !replacements.length) throw new Error("replacements: non-empty JSON array of {old, new} required");
+    const raw = params.replacements;
+    let replacementsInput;
+    try {
+      replacementsInput = typeof raw === "string" ? JSON.parse(raw) : raw;
+    } catch {
+      throw new Error('replacements: invalid JSON. Expected: [{"old":"text","new":"replacement"}]');
+    }
+    const replacements = replacementPairsSchema.parse(replacementsInput);
     const result = bulkReplace(
       params.path || process.cwd(),
       params.glob || "**/*.{md,mjs,json,yml,ts,js}",
       replacements,
-      { dryRun: params.dry_run || false, maxFiles: params.max_files || 100 }
+      { dryRun: params.dry_run || false, maxFiles: params.max_files || 100, format: params.format }
     );
     return { content: [{ type: "text", text: result }] };
   } catch (e) {

package/output-style.md

@@ -12,15 +12,17 @@ keep-coding-instructions: true
 |-----------|-----|-----|
 | Read | `mcp__hex-line__read_file` | Hash-annotated, revision-aware |
 | Edit | `mcp__hex-line__edit_file` | Hash-verified anchors + conservative auto-rebase |
-| Write | `mcp__hex-line__write_file` | Consistent workflow |
+| Write | `mcp__hex-line__write_file` | No prior Read needed |
 | Grep | `mcp__hex-line__grep_search` | Hash-annotated matches |
 | Edit (text rename) | `mcp__hex-line__bulk_replace` | Multi-file text rename/refactor |
+| Bash `find`/`tree` | `mcp__hex-line__directory_tree` | Pattern search, gitignore-aware |
 
 ## Efficient File Reading
 
 For UNFAMILIAR code files >100 lines, PREFER:
-1. `outline` first (10-20 lines of structure)
+1. `outline` first (code files only — not .md/.json/.yaml)
 2. `read_file` with offset/limit for the specific section you need
+3. Batch: `paths` array reads multiple files in one call
 
 Avoid reading a large file in full — outline+targeted read saves 75% tokens.
 
@@ -33,7 +35,7 @@ Prefer:
 1. collect all known hunks for one file
 2. send one `edit_file` call with batched edits
 3. carry `revision` from `read_file` into `base_revision` on follow-up edits
-4. use `replace_between` for large block rewrites
+4. edit types: `set_line` (1 line), `replace_lines` (range + checksum), `insert_after`, `replace_between` (large blocks)
 5. use `verify` before rereading a file after staleness
 
 Avoid:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "mcpName": "io.github.levnikolaevich/hex-line-mcp",
   "type": "module",
   "description": "Hash-verified file editing MCP + token efficiency hook for AI coding agents. 11 tools: read, edit, write, grep, outline, verify, directory_tree, file_info, setup_hooks, changes, bulk_replace.",
@@ -28,7 +28,7 @@
   "_dep_notes": {
     "web-tree-sitter": "Pinned ^0.25.0: v0.26 ABI incompatible with tree-sitter-wasms 0.1.x (built with tree-sitter-cli 0.20.8). Language.load() silently fails.",
     "zod": "Pinned ^3.25.0: zod 4 breaks zod-to-json-schema (used by MCP SDK internally). Tool parameter descriptions not sent to clients. Revisit when MCP SDK switches to z.toJSONSchema().",
-    "better-sqlite3": "Optional. Used only by lib/graph-enrich.mjs for readonly access to hex-graph .codegraph/index.db. Graceful fallback if absent."
+    "better-sqlite3": "Optional. Used only by lib/graph-enrich.mjs for readonly access to hex-graph .hex-skills/codegraph/index.db. Graceful fallback if absent."
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0",