@levnikolaevich/hex-line-mcp 1.30.1 → 1.31.0

package/README.md

@@ -32,8 +32,8 @@ Advanced / occasional:
 
 | Tool | Description | Key Feature |
 |------|-------------|-------------|
-| `read_file` | Read file with progressive disclosure, optional edit-ready metadata, and automatic graph hints when available | Minimal plain discovery by default, explicit `edit_ready` for verified edits |
-| `edit_file` | Revision-aware anchor edits (`set_line`, `replace_lines`, `insert_after`, `replace_between`) | Batched same-file edits + conservative auto-rebase |
+| `read_file` | Read file with progressive disclosure, optional edit-ready metadata, and automatic graph hints when available | Minimal plain discovery by default (no hash overhead); per-line hashes are added only under `edit_ready`/`verbosity=full` for verified edits |
+| `edit_file` | Revision-aware anchor edits (`set_line`, `replace_lines`, `insert_after`, `replace_between`) | Batch all hunks for one file in a single call (avoids stale-conflict churn); forgiving anchors (`tag.N`, a bare line number, or unique line content) and `range_checksum: "auto"` |
 | `write_file` | Create new file or overwrite, auto-creates parent dirs | Path validation, no hash overhead |
 | `grep_search` | Search with ripgrep, summary-first discovery, and optional edit-ready hunks | `summary` by default, capped `content` mode with explicit `allow_large_output` escape hatch |
 | `outline` | AST-based structural overview with hash anchors via tree-sitter WASM. Supports JavaScript/TypeScript, Python, C#, PHP, and fence-aware markdown headings | 95% token reduction, direct edit anchors |
@@ -47,7 +47,7 @@ Advanced / occasional:
 | Event | Trigger | Action |
 |-------|---------|--------|
 | **PreToolUse** | Read/Edit/Write/Grep/Glob on project text scope | Advises hex-line by default for project-scoped text files and file discovery; explicit `hooks.mode: "blocking"` hard redirects. Built-in tools stay available for binary/media, plan files in Plan Mode, and text paths outside the current project root |
-| **PreToolUse** | Bash with dangerous commands | Blocks `rm -rf /`, `git push --force`, etc. Agent must confirm with user |
+| **PreToolUse** | Bash with dangerous commands | Blocks `rm -rf /`, `git push --force`, `git clean -f`, `git branch -D`, `git rebase -i`, `truncate -s`, `docker prune`, `docker rmi -f`, `chmod 777`, `DROP TABLE`, `mkfs`, `dd if=/dev/zero`, etc. Agent must confirm with user |
 | **PostToolUse** | Bash with 50+ lines output | RTK: deduplicates, truncates, shows filtered summary to Claude as feedback |
 | **SessionStart** | Session begins | Injects a short bootstrap hint; defers to the active output style when `hex-line` style is enabled |
 
@@ -70,12 +70,14 @@ Requires Node.js >= 20.19.0.
 
 ### Hooks
 
-Hooks and output style are auto-synced on every MCP server startup. The server compares installed files with bundled versions and updates only when content differs. First run after `npm i -g` triggers full install automatically.
+Hooks and output style are auto-synced on every MCP server startup (unless disabled — see below). The server compares installed files with bundled versions and updates only when content differs. First run after `npm i -g` triggers full install automatically.
 
 Hooks are written to global `~/.claude/settings.json` with absolute path to `hook.mjs`. Output style is installed to `~/.claude/output-styles/hex-line.md` and activated if no other style is set. To activate manually: `/config` > Output style > hex-line.
 
 No extra manual setup is required after install. The startup sync uses the current Node runtime and a stable hook path under `~/.claude/hex-line`, so the hook command survives spaces in the home directory on Windows, macOS, and Linux.
 
+To opt out of startup syncing entirely (hook copy, output-style install/activation, and `~/.claude/settings.json` writes), set `hooks.auto_sync: false` in the project's `.hex-skills/environment_state.json`. The output style is only auto-activated when no other style is set; it never overrides a style you chose.
+
 ## Validation
 
 Use the normal package checks:

package/dist/hook.mjs

@@ -54,8 +54,8 @@ function normalizeOutput(text, opts = {}) {
 }
 
 // hook.mjs
-import { readFileSync, writeSync } from "node:fs";
-import { resolve } from "node:path";
+import { readFileSync, writeSync, realpathSync, existsSync } from "node:fs";
+import { resolve, dirname, basename, join } from "node:path";
 import { homedir } from "node:os";
 
 // lib/hook-policy.mjs
@@ -160,9 +160,15 @@ var DANGEROUS_PATTERNS = [
   { regex: /git\s+push\s+(-f|--force)/, reason: "force push can overwrite remote history" },
   { regex: /git\s+reset\s+--hard/, reason: "hard reset discards uncommitted changes" },
   { regex: /DROP\s+(TABLE|DATABASE)/i, reason: "DROP destroys data permanently" },
-  { regex: /chmod\s+777/, reason: "chmod 777 removes all access restrictions" },
+  { regex: /chmod\s+(-[a-zA-Z]+\s+)*(777|a\+rwx)\b/i, reason: "chmod 777 / a+rwx removes all access restrictions" },
   { regex: /mkfs/, reason: "filesystem format destroys all data" },
-  { regex: /dd\s+if=\/dev\/zero/, reason: "direct disk write destroys data" }
+  { regex: /dd\s+if=\/dev\/zero/, reason: "direct disk write destroys data" },
+  { regex: /git\s+branch\s+-D\b/, reason: "git branch -D force-deletes branches" },
+  { regex: /git\s+clean\s+(-[a-z]*f|--force)/i, reason: "git clean -f deletes untracked files permanently" },
+  { regex: /git\s+rebase\s+(-i|--interactive)\b/, reason: "interactive rebase rewrites history and blocks on an editor" },
+  { regex: /\btruncate\s+-s/i, reason: "truncate -s can zero out file contents" },
+  { regex: /docker\s+(system|volume|image|container|network)\s+prune\b/i, reason: "docker prune destroys unused data permanently" },
+  { regex: /docker\s+rmi\s+(-f|--force)/i, reason: "docker rmi -f force-removes images" }
 ];
 var COMPOUND_OPERATORS = /[|]|>>?|&&|\|\||;/;
 var CMD_PATTERNS = [
@@ -197,8 +203,8 @@ var HEX_LINE_MUTATING = /* @__PURE__ */ new Set([
   "mcp__hex-line__bulk_replace"
 ]);
 var PLAN_SAFE_FOLDERS = [
-  ".hex-skills/",
-  ".claude/"
+  ".hex-skills",
+  ".claude"
 ];
 function extOf(filePath) {
   const dot = filePath.lastIndexOf(".");
@@ -284,8 +290,27 @@ function collectPositionals(tokens, { optionValueFlags = [], slashOptions = fals
 function resolveCandidatePaths(pathTokens) {
   return pathTokens.map(resolveToolPath).filter(Boolean).map(normalizePolicyPath);
 }
+function canonicalizeForScope(absPath) {
+  try {
+    return realpathSync(absPath);
+  } catch {
+    try {
+      let dir = absPath;
+      const tail = [];
+      while (dir && dir !== dirname(dir) && !existsSync(dir)) {
+        tail.unshift(basename(dir));
+        dir = dirname(dir);
+      }
+      if (existsSync(dir)) return tail.length ? join(realpathSync(dir), ...tail) : realpathSync(dir);
+    } catch {
+    }
+    return absPath;
+  }
+}
 function isProjectScopedPath(filePath) {
-  return !!filePath && isWithinDir(resolveToolPath(filePath), process.cwd());
+  if (!filePath) return false;
+  const resolved = canonicalizeForScope(resolveToolPath(filePath));
+  return isWithinDir(resolved, canonicalizeForScope(process.cwd()));
 }
 function getBashPathCandidates(spec, tokens, isFirstSegment) {
   const command = (tokens[0] || "").toLowerCase();
@@ -453,7 +478,8 @@ function handlePreToolUse(data) {
   const toolInput = data.tool_input || {};
   if (data.permission_mode === "plan" && HEX_LINE_MUTATING.has(toolName)) {
     const targetPath = getMutatingTargetPath(toolInput).replace(/\\/g, "/");
-    const isPlanSafe = PLAN_SAFE_FOLDERS.some((folder) => targetPath.includes(folder));
+    const planParts = targetPath.split("/").filter(Boolean);
+    const isPlanSafe = PLAN_SAFE_FOLDERS.some((folder) => planParts.includes(folder));
     if (!isPlanSafe) {
       block(
         "PLAN_MODE: You are in planning mode. Write your plan to the plan file, then call ExitPlanMode to get approval before making changes.",

package/dist/server.mjs

@@ -1680,6 +1680,11 @@ function requireOptionalString(value, path) {
     throw badInput(`${path} must be a string when provided`);
   }
 }
+function requireChecksumField(value, path) {
+  if (typeof value !== "string") {
+    throw badInput(`${path} must be a string: either "<start>-<end>:<hex>" copied from a fresh read, or "auto" to compute it for the current anchor range`);
+  }
+}
 function validateEditShape(edit) {
   requirePlainObject(edit, "edit");
   const kinds = ["set_line", "replace_lines", "insert_after", "replace_between"].filter((kind2) => edit[kind2] !== void 0);
@@ -1707,7 +1712,7 @@ function validateEditShape(edit) {
     requirePlainObject(edit.replace_lines, "replace_lines");
     requireString(edit.replace_lines.start_anchor, "replace_lines.start_anchor");
     requireString(edit.replace_lines.end_anchor, "replace_lines.end_anchor");
-    requireString(edit.replace_lines.range_checksum, "replace_lines.range_checksum");
+    requireChecksumField(edit.replace_lines.range_checksum, "replace_lines.range_checksum");
     requireString(edit.replace_lines.new_text, "replace_lines.new_text");
     return;
   }
@@ -2937,6 +2942,92 @@ Recovery: read_file path ranges=["${csStart}-${csEnd}"], then retry edit with fr
   }
   return null;
 }
+var CANONICAL_REF_RE = /^[a-z2-7]{2}\.\d+$/;
+var CANONICAL_CHECKSUM_RE = /^\d+-\d+:[0-9a-f]{8}$/;
+function uniqueLineIndex(lines, pred) {
+  let found = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (!pred(lines[i])) continue;
+    if (found >= 0) return -1;
+    found = i;
+  }
+  return found;
+}
+function refLineOrNull(anchor) {
+  const m = typeof anchor === "string" ? anchor.trim().match(/^[a-z2-7]{2}\.(\d+)$/) : null;
+  return m ? parseInt(m[1], 10) : null;
+}
+function lineContentMatches(line, candidate) {
+  if (line === candidate) return true;
+  const c = candidate.trim();
+  return c.length > 0 && line.replace(/\s+/g, "") === candidate.replace(/\s+/g, "");
+}
+function reconcileAnchorRef(rawAnchor, lines) {
+  if (typeof rawAnchor !== "string") return rawAnchor;
+  const s = rawAnchor.trim();
+  if (!s || CANONICAL_REF_RE.test(s)) return rawAnchor;
+  const tagAt = (n) => `${lineTag(fnv1a(lines[n - 1]))}.${n}`;
+  if (/^\d+$/.test(s)) {
+    const n = parseInt(s, 10);
+    return n >= 1 && n <= lines.length ? tagAt(n) : rawAnchor;
+  }
+  const dotN = s.match(/^([\s\S]*)\.(\d+)$/);
+  if (dotN) {
+    const n = parseInt(dotN[2], 10);
+    if (n >= 1 && n <= lines.length && lineContentMatches(lines[n - 1], dotN[1])) return tagAt(n);
+  }
+  const exact = uniqueLineIndex(lines, (l) => l === s);
+  if (exact >= 0) return tagAt(exact + 1);
+  const compact = s.replace(/\s+/g, "");
+  if (compact) {
+    const stripped = uniqueLineIndex(lines, (l) => l.replace(/\s+/g, "") === compact);
+    if (stripped >= 0) return tagAt(stripped + 1);
+  }
+  return rawAnchor;
+}
+function reconcileRangeChecksum(rawChecksum, startLine, endLine, snapshot) {
+  if (rawChecksum === void 0) return rawChecksum;
+  const s = String(rawChecksum).trim();
+  if (CANONICAL_CHECKSUM_RE.test(s)) return rawChecksum;
+  if (s === "" || /^(?:\d+-\d+:)?auto$/i.test(s)) {
+    return buildRangeChecksum(snapshot, startLine, endLine) || rawChecksum;
+  }
+  return rawChecksum;
+}
+function reconcileEdits(edits, snapshot, corrections) {
+  if (!Array.isArray(edits)) return edits;
+  const lines = snapshot.lines;
+  const note = (from, to) => {
+    if (to !== from && typeof from === "string" && from.trim() !== to) corrections.push({ from: from.trim(), to });
+  };
+  return edits.map((edit) => {
+    if (!edit || typeof edit !== "object" || Array.isArray(edit)) return edit;
+    const out = { ...edit };
+    for (const kind of ["set_line", "insert_after"]) {
+      const blk = out[kind];
+      if (!blk || typeof blk !== "object" || Array.isArray(blk)) continue;
+      const anchor = reconcileAnchorRef(blk.anchor, lines);
+      note(blk.anchor, anchor);
+      out[kind] = { ...blk, anchor };
+    }
+    for (const kind of ["replace_lines", "replace_between"]) {
+      const blk = out[kind];
+      if (!blk || typeof blk !== "object" || Array.isArray(blk)) continue;
+      const start_anchor = reconcileAnchorRef(blk.start_anchor, lines);
+      const end_anchor = reconcileAnchorRef(blk.end_anchor, lines);
+      note(blk.start_anchor, start_anchor);
+      note(blk.end_anchor, end_anchor);
+      const next = { ...blk, start_anchor, end_anchor };
+      const sLine = refLineOrNull(start_anchor);
+      const eLine = refLineOrNull(end_anchor);
+      if (sLine && eLine && (kind === "replace_lines" || blk.range_checksum !== void 0)) {
+        next.range_checksum = reconcileRangeChecksum(blk.range_checksum, sLine, eLine, snapshot);
+      }
+      out[kind] = next;
+    }
+    return out;
+  });
+}
 function editFile(filePath, edits, opts = {}) {
   filePath = normalizePath(filePath);
   const real = validatePath(filePath);
@@ -2955,7 +3046,15 @@ function editFile(filePath, edits, opts = {}) {
   let autoRebased = false;
   const remaps = [];
   const remapKeys = /* @__PURE__ */ new Set();
-  const anchored = normalizeAnchoredEdits(edits);
+  const reconcileCorrections = [];
+  const reconciledEdits = reconcileEdits(edits, currentSnapshot, reconcileCorrections);
+  for (const c of reconcileCorrections) {
+    const key = `${c.from}->${c.to}`;
+    if (remapKeys.has(key)) continue;
+    remapKeys.add(key);
+    remaps.push(c);
+  }
+  const anchored = normalizeAnchoredEdits(reconciledEdits);
   assertNonOverlappingTargets(collectEditTargets(anchored));
   const sorted = sortEditsForApply(anchored);
   const buildStrictConflictError = (reason, centerIdx, details, recoveryRanges = null, retryChecksum = null, retryEdit = null) => {
@@ -3325,14 +3424,18 @@ function applyListModeTotalLimit(lines, totalLimit) {
   visible.push(`OUTPUT_CAPPED: ${lines.length - totalLimit} more result line(s) omitted. Narrow with path= or glob=, or raise head_limit.`);
   return visible.join("\n");
 }
+function appendCommonRgFlags(args, opts) {
+  if (opts.caseInsensitive) args.push("-i");
+  else if (opts.smartCase) args.push("-S");
+  if (opts.literal) args.push("-F");
+  if (opts.multiline) args.push("-U", "--multiline-dotall");
+  if (opts.glob) args.push("--glob", opts.glob);
+  if (opts.type) args.push("--type", opts.type);
+  return args;
+}
 async function filesMode(pattern, target, opts, totalLimit) {
   const realArgs = ["-l"];
-  if (opts.caseInsensitive) realArgs.push("-i");
-  else if (opts.smartCase) realArgs.push("-S");
-  if (opts.literal) realArgs.push("-F");
-  if (opts.multiline) realArgs.push("-U", "--multiline-dotall");
-  if (opts.glob) realArgs.push("--glob", opts.glob);
-  if (opts.type) realArgs.push("--type", opts.type);
+  appendCommonRgFlags(realArgs, opts);
   realArgs.push("--", pattern, target);
   const { stdout, code, stderr, killed } = await spawnRg(realArgs);
   if (killed) return "GREP_OUTPUT_TRUNCATED: exceeded 10MB. Use specific glob/path.";
@@ -3344,12 +3447,7 @@ async function filesMode(pattern, target, opts, totalLimit) {
 }
 async function countMode(pattern, target, opts, totalLimit) {
   const realArgs = ["-c"];
-  if (opts.caseInsensitive) realArgs.push("-i");
-  else if (opts.smartCase) realArgs.push("-S");
-  if (opts.literal) realArgs.push("-F");
-  if (opts.multiline) realArgs.push("-U", "--multiline-dotall");
-  if (opts.glob) realArgs.push("--glob", opts.glob);
-  if (opts.type) realArgs.push("--type", opts.type);
+  appendCommonRgFlags(realArgs, opts);
   realArgs.push("--", pattern, target);
   const { stdout, code, stderr, killed } = await spawnRg(realArgs);
   if (killed) return "GREP_OUTPUT_TRUNCATED: exceeded 10MB. Use specific glob/path.";
@@ -3361,12 +3459,7 @@ async function countMode(pattern, target, opts, totalLimit) {
 }
 async function summaryMode(pattern, target, opts, totalLimit) {
   const realArgs = ["-n", "-H", "--no-heading", "--color", "never"];
-  if (opts.caseInsensitive) realArgs.push("-i");
-  else if (opts.smartCase) realArgs.push("-S");
-  if (opts.literal) realArgs.push("-F");
-  if (opts.multiline) realArgs.push("-U", "--multiline-dotall");
-  if (opts.glob) realArgs.push("--glob", opts.glob);
-  if (opts.type) realArgs.push("--type", opts.type);
+  appendCommonRgFlags(realArgs, opts);
   const limit = opts.limit && opts.limit > 0 ? opts.limit : 20;
   realArgs.push("-m", String(limit));
   realArgs.push("--", pattern, target);
@@ -3415,12 +3508,7 @@ async function contentMode(pattern, target, opts, plain, editReady, totalLimit,
   const shouldUseGraph = editReady && !plain;
   const contentBlockLimit = allowLargeOutput ? Number.POSITIVE_INFINITY : DEFAULT_CONTENT_BLOCK_LIMIT;
   const outputCharBudget = allowLargeOutput ? MAX_SEARCH_OUTPUT_CHARS : DEFAULT_CONTENT_OUTPUT_CHARS;
-  if (opts.caseInsensitive) realArgs.push("-i");
-  else if (opts.smartCase) realArgs.push("-S");
-  if (opts.literal) realArgs.push("-F");
-  if (opts.multiline) realArgs.push("-U", "--multiline-dotall");
-  if (opts.glob) realArgs.push("--glob", opts.glob);
-  if (opts.type) realArgs.push("--type", opts.type);
+  appendCommonRgFlags(realArgs, opts);
   if (opts.context && opts.context > 0) realArgs.push("-C", String(opts.context));
   if (opts.contextBefore && opts.contextBefore > 0) realArgs.push("-B", String(opts.contextBefore));
   if (opts.contextAfter && opts.contextAfter > 0) realArgs.push("-A", String(opts.contextAfter));
@@ -4389,6 +4477,11 @@ function safeRead(filePath) {
     return null;
   }
 }
+function isAutoSyncDisabled() {
+  const stateFile = resolve7(process.cwd(), ".hex-skills/environment_state.json");
+  const config = readJson(stateFile);
+  return config?.hooks?.auto_sync === false;
+}
 function writeHooksToFile(settingsPath) {
   const config = readJson(settingsPath) || {};
   if (!config.hooks || typeof config.hooks !== "object") config.hooks = {};
@@ -4456,6 +4549,7 @@ function syncOutputStyle() {
 function autoSync() {
   const hookSource = existsSync6(DIST_HOOK) ? DIST_HOOK : existsSync6(BUILT_HOOK) ? BUILT_HOOK : null;
   if (!hookSource) return;
+  if (isAutoSyncDisabled()) return;
   const changes = [];
   const srcHook = safeRead(hookSource);
   const dstHook = safeRead(STABLE_HOOK_PATH);
@@ -5130,7 +5224,7 @@ function errorResult(code, message, recovery, { large = false, extra = null } =
 }
 
 // server.mjs
-var version = true ? "1.30.1" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.31.0" : (await null).createRequire(import.meta.url)("./package.json").version;
 var STATUS_ENUM = z2.enum(STATUS_VALUES);
 var ERROR_SHAPE = z2.object({ code: z2.string(), message: z2.string(), recovery: z2.string() }).optional();
 var ERROR_RESULT_FIELDS = {
@@ -5324,11 +5418,11 @@ ERROR: ${e.message}`);
 });
 server.registerTool("edit_file", {
   title: "Edit File",
-  description: "Apply hash-verified partial edits to one file. Carry base_revision on same-file follow-ups. Preserves existing line endings and trailing-newline shape; conservative conflicts return retry helpers. boundary_mode=inclusive deletes the anchor lines themselves; new_text must close any delimiter whose opening falls inside the replaced range.",
+  description: 'Apply hash-verified partial edits to one file. Batch ALL hunks for the same file into ONE call via the `edits` array -- separate sequential edit_file calls on one file go stale and conflict (the most common edit failure). Carry base_revision only for a genuinely later follow-up after the file changed. Anchors accept tag.N, a bare line number, or unique line content (auto-resolved); range_checksum accepts "auto" to compute it for the current range. Preserves existing line endings and trailing-newline shape; conservative conflicts return retry helpers. boundary_mode=inclusive deletes the anchor lines themselves; new_text must close any delimiter whose opening falls inside the replaced range.',
   inputSchema: z2.object({
     file_path: z2.string().describe("File to edit"),
     edits: z2.union([z2.string(), z2.array(z2.any())]).describe(
-      'JSON array of canonical edits.\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[{"insert_after":{"anchor":"ab.20","text":"x"}}]\n[{"replace_between":{"start_anchor":"ab.10","end_anchor":"cd.40","new_text":"x","boundary_mode":"inclusive","range_checksum":"10-40:a1b2"}}]\nPrefer replace_lines with range_checksum when either anchor is a lone delimiter (}, ), ]) \u2014 replace_between anchors use short line-content hashes and may fuzzy-match a sibling delimiter.'
+      'JSON array of canonical edits.\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[{"insert_after":{"anchor":"ab.20","text":"x"}}]\n[{"replace_between":{"start_anchor":"ab.10","end_anchor":"cd.40","new_text":"x","boundary_mode":"inclusive","range_checksum":"10-40:a1b2"}}]\nPrefer replace_lines with range_checksum when either anchor is a lone delimiter (}, ), ]) \u2014 replace_between anchors use short line-content hashes and may fuzzy-match a sibling delimiter. Anchors also accept a bare line number or exact line content (auto-resolved to tag.N); range_checksum accepts "auto" to compute it for the current anchor range.'
     ),
     dry_run: flexBool().describe("Preview changes without writing"),
     restore_indent: flexBool().describe("Auto-fix indentation to match anchor (default: false)"),

package/output-style.md

@@ -43,15 +43,15 @@ Prefer `hex-line` for text files you may inspect or modify. Hash-annotated reads
 
 ## Edit Discipline
 
-- Never invent `range_checksum`. Copy it from a fresh `read_file` or `grep_search(output_mode:"content", edit_ready=true)` block.
+- Prefer a real `range_checksum` copied from a fresh `read_file` or `grep_search(output_mode:"content", edit_ready=true)` block. If you don't have one for the exact range, pass `"auto"` and the server computes it for the current anchor range.
 - First mutation in a file: use `grep_search(output_mode="summary")` for narrow targets, or `outline -> read_file(ranges)` for structural edits. Escalate to `grep_search(output_mode="content", edit_ready=true)` only when the next edit needs canonical hunks.
 - Preserve file conventions mentally: `hex-line` hashes normalized logical text, but `edit_file` preserves the file's existing line endings and trailing-newline shape on write.
 - Prefer `set_line` or `insert_after` for small local changes. Prefer `replace_between` for larger bounded block rewrites.
 - When either anchor of `replace_between` is a lone delimiter (`}`, `)`, `]`, `});`), switch to `replace_lines` with `range_checksum`, or pass `range_checksum` to `replace_between` directly. `replace_between` anchors use short line-content hashes and may fuzzy-match a sibling closing delimiter.
 - For inclusive `replace_between`: enumerate every `{`, `(`, `[` opened inside the replaced range and ensure `new_text` closes them all. If the range crosses a method/class/namespace boundary, prefer `set_line` + `insert_after` for each hunk.
 - After `replace_between` on C#/Java/Go/C++/Rust files, run the language build or type-check once before proceeding. Brace drift is invisible at edit time.
-- Use `replace_lines` only when you already hold the exact inclusive range checksum for that block.
-- Avoid large first-pass edit batches. Start with 1-2 hunks, then continue from the returned `revision` as `base_revision`.
+- Use `replace_lines` for bounded block replacement; supply its inclusive `range_checksum`, or pass `"auto"` to have the server compute it.
+- Batch ALL hunks for the same file into ONE `edit_file` call (the `edits` array). Separate sequential edits on one file go stale and conflict — this is the single most common edit failure. Use `base_revision` only for a genuinely later follow-up after the file already changed.
 - Before a delayed follow-up edit, a formatter pass, or any mixed-tool workflow on the same file, run `verify` with the last checksums and `base_revision`.
 - If `edit_file` returns `retry_edit`, `retry_edits`, or `retry_plan`, reuse those directly instead of rebuilding anchors/checksums by hand.
 - Reuse `retry_checksum` when it is returned for the exact same target range.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.30.1",
+  "version": "1.31.0",
   "mcpName": "io.github.levnikolaevich/hex-line-mcp",
   "type": "module",
   "description": "Hash-verified file editing MCP + token efficiency hook for AI coding agents. 9 tools: inspect_path, read, edit, write, grep, outline, verify, changes, bulk_replace.",