@levnikolaevich/hex-line-mcp 1.24.0 → 1.25.0

package/README.md

@@ -164,8 +164,8 @@ Read a file with progressive disclosure. Default mode is discovery-first: plain
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `path` | string | yes | File path |
-| `paths` | string[] | no | Array of file paths to read (batch mode) |
+| `file_path` | string | yes | File path |
+| `file_paths` | string[] | no | Array of file paths to read (batch mode) |
 | `offset` | number | no | Start line, 1-indexed (default: 1) |
 | `limit` | number | no | Max lines to return (default: 200 for discovery, 2000 for edit-ready, 0 = all) |
 | `ranges` | array | no | Explicit line ranges, e.g. `[{ "start": 10, "end": 30 }]` |
@@ -211,7 +211,7 @@ Edit using revision-aware hash-verified anchors. Prefer one batched call per fil
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `path` | string | yes | File to edit |
+| `file_path` | string | yes | File to edit |
 | `edits` | string | yes | JSON array of edit operations (see below) |
 | `dry_run` | boolean | no | Preview changes without writing |
 | `restore_indent` | boolean | no | Auto-fix indentation to match anchor context (default: false) |
@@ -232,7 +232,7 @@ Edit operations (JSON array):
 
 Discipline:
 
-- Never invent `range_checksum`. Copy it from `read_file` or `grep_search(output:"content")`.
+- Never invent `range_checksum`. Copy it from `read_file` or `grep_search(output_mode:"content")`.
 - First mutation in a file: prefer `grep_search` for narrow targets, or `outline -> read_file(ranges)` for structural edits.
 - Prefer 1-2 hunks on the first pass. Once `edit_file` returns a fresh `revision`, continue from that state as `base_revision`.
 - `hex-line` preserves existing file line endings on write; repo-level line-ending cleanup should be a separate deliberate operation, not a side effect of `edit_file`.
@@ -242,12 +242,10 @@ Result footer includes:
 - `status: OK | AUTO_REBASED | CONFLICT`
 - `reason: ...` as the canonical machine-readable cause for the current status
 - `revision: ...`
-- `file: ...`
 - `summary: ...` with edited line span / diff counts on successful edits
 - `payload_sections: ...` so callers know which detailed sections follow
-- `graph_enrichment: available | unavailable`
-- `semantic_impact_count: ...`, `semantic_fact_count: ...`, and `clone_warning_count: ...` when graph-backed review data is available
-- `provenance_summary: ...` for the edit protocol + optional graph source
+- `graph_enrichment: unavailable` + `graph_fix: ...` when the project graph is missing or out of sync (silent when graph is healthy)
+- `⚠ Semantic impact:` and `⚠ N clone(s):` blocks emitted directly when graph-backed review data is available
 - `changed_ranges: ...` when relevant
 - `recovery_ranges: ...` with the narrowest recommended `read_file` ranges for retry
 - `next_action: ...` as the canonical immediate choice: `apply_retry_edit`, `apply_retry_batch`, or `reread_then_retry`
@@ -266,7 +264,7 @@ Create a new file or overwrite an existing one. Creates parent directories autom
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `path` | string | yes | File path |
+| `file_path` | string | yes | File path |
 | `content` | string | yes | File content |
 | `allow_external` | boolean | no | Allow writing a path outside the current project root |
 
@@ -280,7 +278,7 @@ Search file contents using ripgrep. Default mode is `summary` for discovery. Use
 | `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: `"summary"` (default), `"content"`, `"files"`, `"count"` |
+| `output_mode` | enum | no | Output format: `"summary"` (default), `"content"`, `"files_with_matches"`, `"count"` |
 | `case_insensitive` | boolean | no | Ignore case |
 | `smart_case` | boolean | no | CI when lowercase, CS when uppercase (`-S`) |
 | `literal` | boolean | no | Literal string search, no regex (`-F`) |
@@ -289,7 +287,7 @@ Search file contents using ripgrep. Default mode is `summary` for discovery. Use
 | `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: 20 for `summary`, 100 for `content`) |
-| `total_limit` | number | no | Total match events across all files; multiline matches count as 1 (default: 50 for `summary`, 200 for `content`, 1000 for `files`/`count`, 0 = unlimited) |
+| `head_limit` | number | no | Total match events across all files; multiline matches count as 1 (default: 50 for `summary`, 200 for `content`, 1000 for `files_with_matches`/`count`, 0 = unlimited) |
 | `plain` | boolean | no | Omit hash tags inside block entries, return `lineNum\|content` |
 | `edit_ready` | boolean | no | Preserve hash/checksum search hunks in `content` mode |
 | `allow_large_output` | boolean | no | Bypass the default `content`-mode block/char caps when you intentionally need a larger payload |
@@ -305,7 +303,7 @@ AST-based structural outline with hash anchors for direct `edit_file` usage. Sup
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `path` | string | yes | Source file path |
+| `file_path` | string | yes | Source file path |
 
 Supported languages: JavaScript (`.js`, `.mjs`, `.cjs`, `.jsx`), TypeScript (`.ts`, `.tsx`), Python (`.py`), C# (`.cs`), and PHP (`.php`) via tree-sitter WASM.
 
@@ -317,7 +315,7 @@ Check if range checksums from prior read/search blocks are still valid, optional
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `path` | string | yes | File path |
+| `file_path` | string | yes | File path |
 | `checksums` | string[] | yes | Array of checksum strings, e.g. `["1-50:f7e2a1b0"]` |
 | `base_revision` | string | no | Prior revision to compare against latest state |
 
@@ -327,12 +325,11 @@ Example output:
 status: STALE
 reason: checksums_stale
 revision: rev-17-deadbeef
-file: 1-120:abc123ef
 summary: valid=0 stale=1 invalid=0
 next_action: reread_ranges
 base_revision: rev-16-feedcafe
 changed_ranges: 10-12(replace)
-suggested_read_call: {"tool":"mcp__hex-line__read_file","arguments":{"path":"/repo/file.ts","ranges":["10-12"]}}
+suggested_read_call: {"tool":"mcp__hex-line__read_file","arguments":{"file_path":"/repo/file.ts","ranges":["10-12"]}}
 
 entry: 1/1 | status: STALE | span: 10-12 | checksum: 10-12:oldc0de0 | current_checksum: 10-12:newc0de0 | next_action: reread_range | summary: content changed since checksum capture
 ```

package/dist/hook.mjs

@@ -116,16 +116,16 @@ var REVERSE_TOOL_HINTS = {
 };
 var TOOL_HINTS = {
   Read: "mcp__hex-line__read_file (not Read). For structure-first: mcp__hex-line__outline then mcp__hex-line__read_file with ranges",
-  Edit: "mcp__hex-line__edit_file (not Edit). If you need hash anchors: mcp__hex-line__grep_search(output='content', edit_ready=true) first",
+  Edit: "mcp__hex-line__edit_file (not Edit). If you need hash anchors: mcp__hex-line__grep_search(output_mode='content', edit_ready=true) first",
   Write: "mcp__hex-line__write_file (not Write). No prior Read needed",
-  Grep: "mcp__hex-line__grep_search (not Grep). Params: output, literal, context_before, context_after, multiline",
+  Grep: "mcp__hex-line__grep_search (not Grep). Params: output_mode, literal, context_before, context_after, multiline",
   Glob: "mcp__hex-line__inspect_path (not Glob). Use pattern=... with an explicit path for project file discovery and name/path globbing",
   cat: "mcp__hex-line__read_file (not cat/head/tail/less/more/type/Get-Content)",
   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__inspect_path for tree or pattern search (not ls/dir/find/tree/Get-ChildItem). E.g. pattern='*-mcp' type='dir'",
   stat: "mcp__hex-line__inspect_path for compact file metadata (not stat/wc/Get-Item/file)",
-  grep: "mcp__hex-line__grep_search (not grep/rg/findstr/Select-String). Params: output, literal, context_before, context_after, multiline",
+  grep: "mcp__hex-line__grep_search (not grep/rg/findstr/Select-String). Params: output_mode, literal, context_before, context_after, multiline",
   sed: "mcp__hex-line__edit_file for hash edits, or mcp__hex-line__bulk_replace with path=<project root> for text rename (not sed -i)",
   diff: "mcp__hex-line__changes (not diff). Git diff with change symbols",
   outline: "mcp__hex-line__outline (before reading large code files)",
@@ -469,15 +469,15 @@ function handlePreToolUse(data) {
       const ext = filePath ? extOf(filePath) : "";
       const rangeHint = isPartialRead(toolInput) ? " Preserve the same offset/limit or ranges." : "";
       const outlineTip = filePath && OUTLINEABLE_EXT.has(ext) ? ` For structure-first discovery: mcp__hex-line__outline then mcp__hex-line__read_file with ranges.` : "";
-      const target = filePath ? `Use mcp__hex-line__read_file(path="${filePath}").${rangeHint}${outlineTip}` : "Use mcp__hex-line__read_file or mcp__hex-line__inspect_path.";
+      const target = filePath ? `Use mcp__hex-line__read_file(file_path="${filePath}").${rangeHint}${outlineTip}` : "Use mcp__hex-line__read_file or mcp__hex-line__inspect_path.";
       redirect(target, DEFERRED_HINT);
     }
     if (toolName === "Edit") {
-      const target = filePath ? `Use mcp__hex-line__edit_file(path="${filePath}"). If you need hash anchors first: mcp__hex-line__grep_search(output="content", edit_ready=true).` : 'Use mcp__hex-line__edit_file. If you need hash anchors first: mcp__hex-line__grep_search(output="content", edit_ready=true).';
+      const target = filePath ? `Use mcp__hex-line__edit_file(file_path="${filePath}"). If you need hash anchors first: mcp__hex-line__grep_search(output_mode="content", edit_ready=true).` : 'Use mcp__hex-line__edit_file. If you need hash anchors first: mcp__hex-line__grep_search(output_mode="content", edit_ready=true).';
       redirect(target, "Hash-verified edits for project text files.\n" + DEFERRED_HINT);
     }
     if (toolName === "Write") {
-      const pathNote = filePath ? ` with path="${filePath}"` : "";
+      const pathNote = filePath ? ` with file_path="${filePath}"` : "";
       redirect(`Use mcp__hex-line__write_file${pathNote}`, TOOL_HINTS.Write + "\n" + DEFERRED_HINT);
     }
     if (toolName === "Grep") {

package/dist/server.mjs

@@ -439,9 +439,11 @@ function diagnoseGraph(filePath) {
     return { reason: "driver_missing" };
   }
 }
-function diagnoseGraphForProject(projectRoot) {
+function diagnoseGraphForProject(directoryPath) {
   if (_driverUnavailable) return { reason: "driver_missing" };
   try {
+    if (!directoryPath) return { reason: "no_project_root" };
+    const projectRoot = findProjectRoot(join3(directoryPath, "__hex-line_probe__"));
     if (!projectRoot) return { reason: "no_project_root" };
     const dbPath = join3(projectRoot, ".hex-skills/codegraph", "index.db");
     if (!existsSync2(dbPath)) return { reason: "index_missing", projectRoot };
@@ -462,9 +464,9 @@ function diagnoseGraphForProject(projectRoot) {
     return { reason: "driver_missing" };
   }
 }
-function getGraphDBForProject(projectRoot) {
-  const { reason } = diagnoseGraphForProject(projectRoot);
-  if (reason !== "ok") return null;
+function getGraphDBForProject(directoryPath) {
+  const { reason, projectRoot } = diagnoseGraphForProject(directoryPath);
+  if (reason !== "ok" || !projectRoot) return null;
   const dbPath = join3(projectRoot, ".hex-skills/codegraph", "index.db");
   return _dbs.get(dbPath) || null;
 }
@@ -1381,7 +1383,12 @@ function serializeSearchBlock(block, opts = {}) {
   const requestedSpan = renderRequestedSpan(block);
   if (requestedSpan) lines.push(requestedSpan);
   if (Array.isArray(block.meta.matchLines) && block.meta.matchLines.length > 0) {
-    lines.push(`match_lines: ${block.meta.matchLines.join(",")}`);
+    const matchLinesStr = block.meta.matchLines.join(",");
+    const spanStr = `${block.startLine}-${block.endLine}`;
+    const singleSpan = block.startLine === block.endLine ? String(block.startLine) : null;
+    if (matchLinesStr !== spanStr && matchLinesStr !== singleSpan) {
+      lines.push(`match_lines: ${matchLinesStr}`);
+    }
   }
   if (block.meta.summary) lines.push(`summary: ${block.meta.summary}`);
   lines.push(...renderMetaLines(Object.fromEntries(
@@ -2005,7 +2012,7 @@ function buildConflictEntryModel({ lines, centerIdx, reason, details, recoveryRa
     snippet: buildSnippetModel(lines, centerIdx)
   };
 }
-function renderConflictEntry(entry) {
+function renderConflictEntry(entry, { skipRetryEdit = false } = {}) {
   let msg = "";
   if (entry.edit) msg += `edit: ${entry.edit}
 `;
@@ -2014,7 +2021,7 @@ function renderConflictEntry(entry) {
 recovery_ranges: ${entry.recovery_ranges.join(", ")}`;
   if (entry.retry_checksum) msg += `
 retry_checksum: ${entry.retry_checksum}`;
-  if (entry.retry_edit) msg += `
+  if (entry.retry_edit && !skipRetryEdit) msg += `
 retry_edit: ${entry.retry_edit}`;
   if (entry.remapped_refs) msg += `
 remapped_refs: ${entry.remapped_refs}`;
@@ -2270,12 +2277,12 @@ next_action: ${recovery.next_action}`;
 retry_edits: ${JSON.stringify(recovery.retry_edits)}`;
   if (recovery.suggested_read_call) msg += `
 suggested_read_call: ${recovery.suggested_read_call}`;
-  if (recovery.retry_plan) msg += `
+  if (recovery.retry_plan && conflicts.length > 1) msg += `
 retry_plan: ${recovery.retry_plan}`;
   for (const entry of entries) {
     msg += `
 
-${renderConflictEntry(entry)}`;
+${renderConflictEntry(entry, { skipRetryEdit: conflicts.length === 1 })}`;
   }
   return msg;
 }
@@ -2996,12 +3003,12 @@ ${serializeReadBlock(block)}`;
           if (impact.counts.sameNameSymbols > 0) totals.push(`${impact.counts.sameNameSymbols} same-name siblings`);
           const headline = totals.length > 0 ? totals.join(", ") : "no downstream graph facts";
           const factLines = impact.facts.slice(0, 6).map((fact) => {
-            if (fact.fact_kind === "public_api") return "public_api: exported symbol";
+            if (fact.fact_kind === "public_api") return null;
             const location = fact.target_file && fact.target_line ? ` (${fact.target_file}:${fact.target_line})` : "";
             const target = fact.target_display_name ? `${fact.target_display_name}${location}` : `${fact.target_file}:${fact.target_line}`;
             const via = fact.path_kind ? ` via ${fact.path_kind}` : "";
             return `${fact.fact_kind}: ${target}${via}`;
-          });
+          }).filter(Boolean);
           return [
             `${impact.symbol}: ${headline}`,
             ...factLines.map((line) => `  ${line}`)
@@ -3116,7 +3123,7 @@ function grepSearch(pattern, opts = {}) {
 function applyListModeTotalLimit(lines, totalLimit) {
   if (!totalLimit || totalLimit <= 0 || lines.length <= totalLimit) return lines.join("\n");
   const visible = lines.slice(0, totalLimit);
-  visible.push(`OUTPUT_CAPPED: ${lines.length - totalLimit} more result line(s) omitted. Narrow with path= or glob=, or raise total_limit.`);
+  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");
 }
 async function filesMode(pattern, target, opts, totalLimit) {
@@ -3181,15 +3188,17 @@ async function summaryMode(pattern, target, opts, totalLimit) {
   }
   const topFiles = [...fileHits.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 5);
   const lines = [
-    `summary: ${rawLines.length} match event(s) across ${fileHits.size} file(s)`,
-    topFiles.length ? `top_files: ${topFiles.map(([file, count]) => `${file} (${count})`).join(", ")}` : "top_files: none"
+    `summary: ${rawLines.length} match event(s) across ${fileHits.size} file(s)`
   ];
+  if (fileHits.size > 1 && topFiles.length) {
+    lines.push(`top_files: ${topFiles.map(([file, count]) => `${file} (${count})`).join(", ")}`);
+  }
   if (snippets.length > 0) {
     lines.push("snippets:");
     lines.push(...snippets.map((snippet) => `- ${snippet}`));
   }
   if (totalLimit > 0 && rawLines.length > totalLimit) {
-    lines.push(`continuation_hint: rerun grep_search with a higher total_limit or narrower path/glob to inspect ${rawLines.length - totalLimit} additional match event(s)`);
+    lines.push(`continuation_hint: rerun grep_search with a higher head_limit or narrower path/glob to inspect ${rawLines.length - totalLimit} additional match event(s)`);
   }
   return lines.join("\n");
 }
@@ -3198,10 +3207,10 @@ function buildSearchRefineCall(target, pattern, opts) {
   if (opts.glob) args.glob = opts.glob;
   if (opts.type) args.type = opts.type;
   return JSON.stringify({
-    tool: "mcp__hex_line__grep_search",
+    tool: "mcp__hex-line__grep_search",
     arguments: {
       ...args,
-      output: "summary"
+      output_mode: "summary"
     }
   });
 }
@@ -3326,7 +3335,7 @@ async function contentMode(pattern, target, opts, plain, editReady, totalLimit,
       if (totalLimit > 0 && matchCount >= totalLimit) {
         flushGroup();
         blocks.push(buildDiagnosticBlock({
-          kind: "total_limit",
+          kind: "head_limit",
           meta: {
             total_matches: matchCount,
             shown_matches: matchCount,
@@ -3336,7 +3345,7 @@ async function contentMode(pattern, target, opts, plain, editReady, totalLimit,
             next_action: "narrow_search_scope",
             suggested_refine_call: buildSearchRefineCall(target, pattern, opts)
           },
-          message: `Search stopped after ${totalLimit} match event(s). Narrow the query, raise total_limit, or pass total_limit=0 to disable the cap.`,
+          message: `Search stopped after ${totalLimit} match event(s). Narrow the query, raise head_limit, or pass head_limit=0 to disable the cap.`,
           path: String(target).replace(/\\/g, "/")
         }));
         return blocks.map((block) => block.type === "edit_ready_block" ? serializeSearchBlock(block, { plain: plainOutput }) : serializeDiagnosticBlock(block)).join("\n\n");
@@ -3611,7 +3620,7 @@ function markdownOutline(sourceLines) {
   }
   return entries;
 }
-function formatOutline(entries, skippedRanges, sourceLineCount, snapshot, db, relFile, note = "") {
+function formatOutline(entries, skippedRanges, _sourceLineCount, snapshot, db, relFile, note = "") {
   const lines = [];
   if (note) lines.push(note, "");
   if (skippedRanges.length > 0) {
@@ -3628,8 +3637,6 @@ function formatOutline(entries, skippedRanges, sourceLineCount, snapshot, db, re
     const prefix = tag ? `${tag}.` : "";
     lines.push(`${indent}${prefix}${e.start}-${e.end}: ${e.text}${suffix}`);
   }
-  lines.push("");
-  lines.push(`(${entries.length} symbols, ${sourceLineCount} source lines)`);
   return lines.join("\n");
 }
 async function fileOutline(filePath) {
@@ -3680,7 +3687,7 @@ function classifyChecksum(currentSnapshot, entry) {
       checksum: entry.raw,
       span: null,
       currentChecksum: null,
-      reason: `invalid checksum format: ${entry.error}`
+      reason: entry.error.replace(/^Bad checksum:\s*/, "format error: ")
     };
   }
   const { start, end } = entry.parsed;
@@ -3861,7 +3868,7 @@ function buildPatternRefineCall(absRoot, pattern, type, groups) {
   const args = { path: bestGroup ? join4(absRoot, bestGroup) : absRoot, pattern };
   if (type && type !== "all") args.type = type;
   return JSON.stringify({
-    tool: "mcp__hex_line__inspect_path",
+    tool: "mcp__hex-line__inspect_path",
     arguments: args
   });
 }
@@ -4109,13 +4116,14 @@ function fileInfo(filePath) {
   const lineCount = !isBinary && size > 0 ? countFileLines(abs, size, MAX_LINE_COUNT_SIZE) : null;
   const sizeStr = lineCount !== null ? `Size: ${formatSize(size)} (${lineCount} lines)` : `Size: ${formatSize(size)}`;
   const timeStr = `Modified: ${mtime.toISOString().replace("T", " ").slice(0, 19)} (${relativeTime(mtime)})`;
-  return [
+  const lines = [
     `File: ${normalized}`,
     sizeStr,
     timeStr,
-    `Type: ${typeName}`,
-    `Binary: ${isBinary ? "yes" : "no"}`
-  ].join("\n");
+    `Type: ${typeName}`
+  ];
+  if (isBinary) lines.push(`Binary: yes`);
+  return lines.join("\n");
 }
 
 // lib/inspect-path.mjs
@@ -4594,7 +4602,6 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
         `path: ${filePath}`,
         `compare_against: ${compareAgainst}`,
         "scope: directory",
-        "summary: changed_files=0",
         ...graphHint2
       ].join("\n");
     }
@@ -4647,7 +4654,6 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
       `path: ${filePath}`,
       `compare_against: ${compareAgainst}`,
       "scope: file",
-      "summary: added=0 removed=0 modified=0",
       ...graphHint
     ].join("\n");
   }
@@ -4864,7 +4870,7 @@ function errorResult(code, message, recovery, { large = false, extra = null } =
 }
 
 // server.mjs
-var version = true ? "1.24.0" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.25.0" : (await null).createRequire(import.meta.url)("./package.json").version;
 var STATUS_ENUM = z2.enum(["OK", "ERROR", "AUTO_REBASED", "CONFLICT", "STALE", "INVALID", "NO_CHANGES", "CHANGED", "UNSUPPORTED"]);
 var ERROR_SHAPE = z2.object({ code: z2.string(), message: z2.string(), recovery: z2.string() }).optional();
 var LINE_REPORT_KEYS = /* @__PURE__ */ new Set([
@@ -4933,8 +4939,8 @@ server.registerTool("read_file", {
   title: "Read File",
   description: "Read file with progressive disclosure. Default: minimal plain partial read for discovery; enable edit-ready metadata explicitly when preparing a verified edit.",
   inputSchema: z2.object({
-    path: z2.string().optional().describe("File path"),
-    paths: z2.array(z2.string()).optional().describe("Array of file paths to read (batch mode)"),
+    file_path: z2.string().optional().describe("File path"),
+    file_paths: z2.array(z2.string()).optional().describe("Array of file paths to read (batch mode)"),
     offset: flexNum().describe("Start line (1-indexed, default: 1)"),
     limit: flexNum().describe("Max lines (default: 200 for discovery, 2000 for edit-ready, 0 = all)"),
     ranges: z2.union([z2.string(), z2.array(readRangeSchema)]).optional().describe('Line ranges, e.g. ["10-25", {"start":40,"end":55}]'),
@@ -4944,8 +4950,8 @@ server.registerTool("read_file", {
   }),
   outputSchema: z2.object({
     status: STATUS_ENUM,
-    path: z2.string().optional(),
-    paths: z2.array(z2.string()).optional(),
+    file_path: z2.string().optional(),
+    file_paths: z2.array(z2.string()).optional(),
     content: z2.string().optional(),
     edit_ready: z2.boolean().optional(),
     next_action: z2.string().optional(),
@@ -4953,7 +4959,7 @@ server.registerTool("read_file", {
   }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
 }, async (rawParams) => {
-  const { path: p, paths: multi, offset, limit, ranges: rawRanges, plain, verbosity, edit_ready } = rawParams ?? {};
+  const { file_path: p, file_paths: multi, offset, limit, ranges: rawRanges, plain, verbosity, edit_ready } = rawParams ?? {};
   try {
     const ranges = parseReadRanges(rawRanges);
     const readVerbosity = verbosity ?? "minimal";
@@ -4965,7 +4971,7 @@ server.registerTool("read_file", {
         try {
           if (!edit_ready && readVerbosity !== "full") {
             results.push(`${fileInfo(fp)}
-next_hint: read_file path="${fp}" verbosity="compact"`);
+next_hint: read_file file_path="${fp}" verbosity="compact"`);
           } else {
             results.push(readFile2(fp, {
               offset,
@@ -4983,9 +4989,9 @@ ERROR: ${e.message}`);
         }
       }
       const content2 = results.join("\n\n---\n\n");
-      return result({ status: "OK", paths: multi, content: content2, edit_ready: !!edit_ready }, { large: !!edit_ready || readVerbosity === "full" || content2.length > 5e4 });
+      return result({ status: "OK", file_paths: multi, content: content2, edit_ready: !!edit_ready }, { large: !!edit_ready || readVerbosity === "full" || content2.length > 5e4 });
     }
-    if (!p) throw new Error("Either 'path' or 'paths' is required");
+    if (!p) throw new Error("Either 'file_path' or 'file_paths' is required");
     const content = readFile2(p, {
       offset,
       limit: readLimit,
@@ -4994,7 +5000,7 @@ ERROR: ${e.message}`);
       verbosity: readVerbosity,
       editReady: !!edit_ready
     });
-    return result({ status: "OK", path: p, content, edit_ready: !!edit_ready }, { large: !!edit_ready || readVerbosity === "full" || content.length > 5e4 });
+    return result({ status: "OK", file_path: p, content, edit_ready: !!edit_ready }, { large: !!edit_ready || readVerbosity === "full" || content.length > 5e4 });
   } catch (e) {
     return errorResult(e.code || "READ_ERROR", e.message, e.recovery || "Check path and permissions");
   }
@@ -5003,7 +5009,7 @@ 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.",
   inputSchema: z2.object({
-    path: z2.string().describe("File to edit"),
+    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"}}]'
     ),
@@ -5013,10 +5019,10 @@ server.registerTool("edit_file", {
     conflict_policy: z2.enum(["strict", "conservative"]).optional().describe('Conflict handling (default: "conservative"). "conservative" returns structured CONFLICT output with recovery_ranges, retry_edit/retry_edits, suggested_read_call, and retry_plan when available.'),
     allow_external: flexBool().describe("Allow editing a path outside the current project root. Use only when you intentionally target a temp or external file.")
   }),
-  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), summary: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
+  outputSchema: z2.object({ status: STATUS_ENUM, file_path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), summary: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
   annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
 }, async (rawParams) => {
-  const { path: p, edits: json, dry_run, restore_indent, base_revision, conflict_policy, allow_external } = rawParams ?? {};
+  const { file_path: p, edits: json, dry_run, restore_indent, base_revision, conflict_policy, allow_external } = rawParams ?? {};
   try {
     assertProjectScopedPath(p, { allowExternal: !!allow_external });
     let parsed;
@@ -5032,7 +5038,7 @@ server.registerTool("edit_file", {
       baseRevision: base_revision,
       conflictPolicy: conflict_policy
     });
-    return lineReportResult({ path: p }, content, { large: content.length > 5e4 });
+    return lineReportResult({ file_path: p }, content, { large: content.length > 5e4 });
   } catch (e) {
     return errorResult(e.code || "EDIT_ERROR", e.message, e.recovery || "Check anchors and checksums");
   }
@@ -5041,21 +5047,21 @@ server.registerTool("write_file", {
   title: "Write File",
   description: "Create a new file or overwrite existing. Creates parent dirs. For existing files prefer edit_file (shows diff, verifies hashes).",
   inputSchema: z2.object({
-    path: z2.string().describe("File path"),
+    file_path: z2.string().describe("File path"),
     content: z2.string().describe("File content"),
     allow_external: flexBool().describe("Allow writing a path outside the current project root. Use only when you intentionally target a temp or external file.")
   }),
-  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), lines: z2.number().optional(), error: ERROR_SHAPE }),
+  outputSchema: z2.object({ status: STATUS_ENUM, file_path: z2.string().optional(), lines: z2.number().optional(), error: ERROR_SHAPE }),
   annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
 }, async (rawParams) => {
-  const { path: p, content, allow_external } = rawParams ?? {};
+  const { file_path: p, content, allow_external } = rawParams ?? {};
   try {
     assertProjectScopedPath(p, { allowExternal: !!allow_external });
     const abs = validateWritePath(p);
     mkdirSync2(dirname6(abs), { recursive: true });
     writeFileSync4(abs, content, "utf-8");
     const lines = content.split("\n").length;
-    return result({ status: "OK", path: p, lines });
+    return result({ status: "OK", file_path: p, lines });
   } catch (e) {
     return errorResult(e.code || "WRITE_ERROR", e.message, e.recovery || "Check path and permissions");
   }
@@ -5068,7 +5074,7 @@ server.registerTool("grep_search", {
     path: z2.string().optional().describe("Search dir/file (default: cwd)"),
     glob: z2.string().optional().describe('Glob filter (e.g. "*.ts")'),
     type: z2.string().optional().describe('File type (e.g. "js", "py")'),
-    output: z2.enum(["summary", "content", "files", "count"]).optional().describe("Output format (default: summary)"),
+    output_mode: z2.enum(["summary", "content", "files_with_matches", "count"]).optional().describe("Output format (default: summary)"),
     case_insensitive: flexBool().describe("Ignore case (-i)"),
     smart_case: flexBool().describe("CI when pattern is all lowercase, CS if uppercase (-S)"),
     literal: flexBool().describe("Literal string search, no regex (-F)"),
@@ -5077,7 +5083,7 @@ server.registerTool("grep_search", {
     context_before: flexNum().describe("Context lines BEFORE match (-B)"),
     context_after: flexNum().describe("Context lines AFTER match (-A)"),
     limit: flexNum().describe("Max matches per file (default: 20 for summary discovery, 100 for content)"),
-    total_limit: flexNum().describe("Total match events across all files; multiline matches count as 1 (default: 50 for summary discovery, 200 for content, 1000 for files/count, 0 = unlimited)"),
+    head_limit: flexNum().describe("Total match events across all files; multiline matches count as 1 (default: 50 for summary discovery, 200 for content, 1000 for files_with_matches/count, 0 = unlimited)"),
     plain: flexBool().describe("Omit hash tags, return file:line:content"),
     edit_ready: flexBool().describe("Preserve hash/checksum search hunks in `content` mode. Default: false."),
     allow_large_output: flexBool().describe("Bypass the default content-mode block/char caps when you intentionally need a larger payload.")
@@ -5090,7 +5096,7 @@ server.registerTool("grep_search", {
     path: p,
     glob,
     type,
-    output,
+    output_mode,
     case_insensitive,
     smart_case,
     literal,
@@ -5099,15 +5105,15 @@ server.registerTool("grep_search", {
     context_before,
     context_after,
     limit,
-    total_limit,
+    head_limit,
     plain,
     edit_ready,
     allow_large_output
   } = rawParams ?? {};
   try {
-    const resolvedOutput = output ?? "summary";
+    const resolvedOutput = output_mode === "files_with_matches" ? "files" : output_mode ?? "summary";
     const resolvedLimit = limit ?? (resolvedOutput === "summary" ? 20 : 100);
-    const resolvedTotalLimit = total_limit ?? (resolvedOutput === "summary" ? 50 : void 0);
+    const resolvedTotalLimit = head_limit ?? (resolvedOutput === "summary" ? 50 : void 0);
     const searchResult = await grepSearch(pattern, {
       path: p,
       glob,
@@ -5135,15 +5141,15 @@ server.registerTool("outline", {
   title: "File Outline",
   description: "AST-based structural outline with hash anchors for direct edit_file usage. Supports JavaScript/TypeScript, Python, C#, and PHP code files plus markdown headings (.md/.mdx, fence-aware).",
   inputSchema: z2.object({
-    path: z2.string().describe("Source file path")
+    file_path: z2.string().describe("Source file path")
   }),
-  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), summary: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
+  outputSchema: z2.object({ status: STATUS_ENUM, file_path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), summary: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
 }, async (rawParams) => {
-  const { path: p } = rawParams ?? {};
+  const { file_path: p } = rawParams ?? {};
   try {
     const content = await fileOutline(p);
-    return lineReportResult({ path: p }, content);
+    return lineReportResult({ file_path: p }, content);
   } catch (e) {
     return errorResult(e.code || "OUTLINE_ERROR", e.message, e.recovery || "Check file path and language support");
   }
@@ -5152,20 +5158,20 @@ server.registerTool("verify", {
   title: "Verify Checksums",
   description: "Check if held checksums are still valid without rereading. Use before delayed or mixed-tool follow-up edits; returns canonical status, next_action, and reread guidance.",
   inputSchema: z2.object({
-    path: z2.string().describe("File path"),
+    file_path: z2.string().describe("File path"),
     checksums: z2.array(z2.string()).describe('Checksum strings, e.g. ["1-50:f7e2a1b0", "51-100:abcd1234"]'),
     base_revision: z2.string().optional().describe("Optional prior revision to compare against latest state.")
   }),
-  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), summary: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
+  outputSchema: z2.object({ status: STATUS_ENUM, file_path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), summary: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
 }, async (rawParams) => {
-  const { path: p, checksums, base_revision } = rawParams ?? {};
+  const { file_path: p, checksums, base_revision } = rawParams ?? {};
   try {
     if (!Array.isArray(checksums) || checksums.length === 0) {
       throw new Error("checksums must be a non-empty array of strings");
     }
     const content = verifyChecksums(p, checksums, { baseRevision: base_revision });
-    return lineReportResult({ path: p }, content);
+    return lineReportResult({ file_path: p }, content);
   } catch (e) {
     return errorResult(e.code || "VERIFY_ERROR", e.message, e.recovery || "Check checksums format");
   }

package/output-style.md

@@ -27,7 +27,7 @@ Prefer `hex-line` for text files you may inspect or modify. Hash-annotated reads
 
 | Path | Flow |
 |------|------|
-| Surgical | `grep_search(output="summary") -> grep_search(output="content", edit_ready=true) if needed -> edit_file` |
+| Surgical | `grep_search(output_mode="summary") -> grep_search(output_mode="content", edit_ready=true) if needed -> edit_file` |
 | Exploratory | `outline -> read_file (ranges) -> edit_file(base_revision)` |
 | Multi-file | `bulk_replace(path=<project root>)` |
 | Follow-up after delay | `verify(base_revision) -> reread only if STALE -> retry with returned helpers` |
@@ -43,8 +43,8 @@ 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:"content", edit_ready=true)` block.
-- First mutation in a file: use `grep_search(output="summary")` for narrow targets, or `outline -> read_file(ranges)` for structural edits. Escalate to `grep_search(output="content", edit_ready=true)` only when the next edit needs canonical hunks.
+- Never invent `range_checksum`. Copy it from a fresh `read_file` or `grep_search(output_mode:"content", edit_ready=true)` block.
+- 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.
 - Use `replace_lines` only when you already hold the exact inclusive range checksum for that block.
@@ -54,7 +54,7 @@ Prefer `hex-line` for text files you may inspect or modify. Hash-annotated reads
 - Reuse `retry_checksum` when it is returned for the exact same target range.
 - Once `hex-line` owns a file edit session, avoid mixing built-in `Edit`/`Write` on that file unless you intentionally want a new baseline.
 - Follow `next_action` first. Treat `summary` and `snippet` as the compact local context, not as prose to reinterpret.
-- If broad `grep_search(output="content")` or pattern `inspect_path` truncates, narrow `path`, `glob`, or query shape before retrying. Use `allow_large_output=true` only when you intentionally accept a larger payload.
+- If broad `grep_search(output_mode="content")` or pattern `inspect_path` truncates, narrow `path`, `glob`, or query shape before retrying. Use `allow_large_output=true` only when you intentionally accept a larger payload.
 
 ## Exceptions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.24.0",
+  "version": "1.25.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.",