@levnikolaevich/hex-line-mcp 1.17.0 → 1.18.0

package/dist/hook.mjs

@@ -191,6 +191,11 @@ function isWithinDir(candidatePath, dirPath) {
 
 // hook.mjs
 import { fileURLToPath } from "node:url";
+var HEX_LINE_MUTATING = /* @__PURE__ */ new Set([
+  "mcp__hex-line__edit_file",
+  "mcp__hex-line__write_file",
+  "mcp__hex-line__bulk_replace"
+]);
 function extOf(filePath) {
   const dot = filePath.lastIndexOf(".");
   return dot !== -1 ? filePath.slice(dot).toLowerCase() : "";
@@ -403,7 +408,9 @@ function block(reason, context) {
 ${context}` : reason;
   const output = {
     hookSpecificOutput: {
-      permissionDecision: "deny"
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason
     },
     systemMessage: msg
   };
@@ -413,7 +420,8 @@ ${context}` : reason;
 function advise(reason, context) {
   const output = {
     hookSpecificOutput: {
-      permissionDecision: "allow"
+      hookEventName: "PreToolUse",
+      additionalContext: reason
     },
     systemMessage: context ? `${reason}
 ${context}` : reason
@@ -430,6 +438,12 @@ function redirect(reason, context) {
 function handlePreToolUse(data) {
   const toolName = data.tool_name || "";
   const toolInput = data.tool_input || {};
+  if (data.permission_mode === "plan" && HEX_LINE_MUTATING.has(toolName)) {
+    block(
+      "PLAN_MODE: hex-line write tools are blocked during planning.",
+      "Use read-only tools: read_file, grep_search, outline, verify, inspect_path, changes."
+    );
+  }
   if (toolName.startsWith("mcp__hex-line__")) {
     process.exit(0);
   }
@@ -576,6 +590,22 @@ function handleSessionStart() {
   const msg = styleActive ? "Hex-line MCP available. Output style active.\n<hex-line_instructions>\n  <deferred_loading>If hex-line schemas not loaded, run: ToolSearch('+hex-line read edit')</deferred_loading>\n  <note>Follow the active hex-line output style for primary tool choices.</note>\n  <exceptions>Built-in tools stay OK for images, PDFs, notebooks, and text paths outside the current project root.</exceptions>\n</hex-line_instructions>" : "Hex-line MCP available.\n<hex-line_instructions>\n  <deferred_loading>If hex-line schemas not loaded, run: ToolSearch('+hex-line read edit')</deferred_loading>\n  <exploration>\n    <rule>Use outline for structure (code + markdown), not Read. ~10-20 lines vs hundreds.</rule>\n    <rule>Use read_file with offset/limit or ranges for targeted reads.</rule>\n    <rule>Use grep_search before editing to get hash anchors.</rule>\n  </exploration>\n  <editing>\n    <path name='surgical'>grep_search \u2192 edit_file (fastest: hash-verified, no full read needed)</path>\n    <path name='exploratory'>outline \u2192 read_file (ranges) \u2192 edit_file with base_revision</path>\n    <path name='multi-file'>bulk_replace(path=&quot;&lt;project root&gt;&quot;) for text rename/refactor across files</path>\n  </editing>\n  <tips>\n    <tip>Auto-fill path from the active file or project root. Read-only tools may inspect explicit temp-file paths outside the repo. Mutating tools stay project-scoped unless you intentionally pass allow_external=true.</tip>\n    <tip>Never invent range_checksum. Copy it from fresh read_file or grep_search blocks.</tip>\n    <tip>Prefer set_line or insert_after for small local changes and replace_between for larger bounded rewrites.</tip>\n    <tip>Carry revision from read_file into base_revision on edit_file.</tip>\n    <tip>If edit returns CONFLICT, call verify \u2014 only reread when STALE.</tip>\n    <tip>Avoid large first-pass edit batches. Start with 1-2 hunks, then continue from the returned revision.</tip>\n    <tip>Use write_file for new files (no prior Read needed).</tip>\n    <tip>Use inspect_path(pattern=...) for project file discovery and name/path globbing.</tip>\n  </tips>\n  <exceptions>Built-in tools stay OK for images, PDFs, notebooks, and text paths outside the current project root.</exceptions>\n</hex-line_instructions>";
   safeExit(1, JSON.stringify({ systemMessage: msg }), 0);
 }
+function handleConfigChange(data) {
+  const source = data.source || "";
+  if (["project_settings", "local_settings", "user_settings", "policy_settings"].includes(source)) {
+    _hookMode = void 0;
+    _hexLineDisabled = null;
+  }
+  process.exit(0);
+}
+function handlePermissionDenied(data) {
+  const reason = data.reason || "";
+  const toolName = data.tool_name || "";
+  if (reason.includes("mcp__hex-line__") || toolName === "Bash") {
+    debugLog("PERMISSION_DENIED_AFTER_HEX_HINT", `${toolName}: ${reason.slice(0, 120)}`);
+  }
+  process.exit(0);
+}
 var _norm = (p) => p.replace(/\\/g, "/");
 if (_norm(process.argv[1]) === _norm(fileURLToPath(import.meta.url))) {
   let input = "";
@@ -586,6 +616,9 @@ if (_norm(process.argv[1]) === _norm(fileURLToPath(import.meta.url))) {
     try {
       const data = JSON.parse(input);
       const event = data.hook_event_name || "";
+      if (event === "ConfigChange") {
+        handleConfigChange(data);
+      }
       if (isHexLineDisabled()) {
         if (event === "PreToolUse") handlePreToolUseReverse(data);
         process.exit(0);
@@ -593,6 +626,7 @@ if (_norm(process.argv[1]) === _norm(fileURLToPath(import.meta.url))) {
       if (event === "SessionStart") handleSessionStart();
       else if (event === "PreToolUse") handlePreToolUse(data);
       else if (event === "PostToolUse") handlePostToolUse(data);
+      else if (event === "PermissionDenied") handlePermissionDenied(data);
       else process.exit(0);
     } catch {
       process.exit(0);

package/dist/server.mjs

@@ -3504,13 +3504,13 @@ async function fileOutline(filePath) {
   }
   const snapshot = readSnapshot(real);
   const isMarkdown = MARKDOWN_EXTS.has(ext);
-  const result = isMarkdown ? null : await outlineFromContent(snapshot.content, ext);
+  const result2 = isMarkdown ? null : await outlineFromContent(snapshot.content, ext);
   let entries;
   let skippedRanges = [];
   let note = "";
-  if (result && result.entries.length > 0) {
-    entries = result.entries;
-    skippedRanges = result.skippedRanges;
+  if (result2 && result2.entries.length > 0) {
+    entries = result2.entries;
+    skippedRanges = result2.skippedRanges;
   } else if (isMarkdown) {
     entries = markdownOutline(snapshot.lines);
   } else {
@@ -4722,8 +4722,34 @@ OUTPUT_CAPPED: Output exceeded ${MAX_BULK_OUTPUT_CHARS} chars.`;
   return output;
 }
 
+// ../hex-common/src/runtime/results.mjs
+var LARGE_RESULT_META = { "anthropic/maxResultSizeChars": 5e5 };
+function result(structured, { large = false } = {}) {
+  const text = JSON.stringify(structured);
+  const response = {
+    content: [{ type: "text", text }],
+    structuredContent: structured
+  };
+  if (large) response._meta = LARGE_RESULT_META;
+  if (structured.status === "ERROR") response.isError = true;
+  return response;
+}
+function errorResult(code, message, recovery, { large = false, extra = null } = {}) {
+  const payload = {
+    status: "ERROR",
+    error: { code, message, recovery },
+    summary: message
+  };
+  if (extra && typeof extra === "object") {
+    Object.assign(payload, extra);
+  }
+  return result(payload, { large });
+}
+
 // server.mjs
-var version = true ? "1.17.0" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.18.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 { server, StdioServerTransport } = await createServerRuntime({
   name: "hex-line-mcp",
   version
@@ -4759,7 +4785,16 @@ server.registerTool("read_file", {
     verbosity: z2.enum(["minimal", "compact", "full"]).optional().describe("Response budget. `minimal` is discovery-first, `compact` adds revision context, `full` preserves the richest payload."),
     edit_ready: flexBool().describe("Include hash/checksum edit protocol blocks explicitly. Default: false for discovery reads.")
   }),
-  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+  outputSchema: z2.object({
+    status: STATUS_ENUM,
+    path: z2.string().optional(),
+    paths: z2.array(z2.string()).optional(),
+    content: z2.string().optional(),
+    edit_ready: z2.boolean().optional(),
+    next_action: z2.string().optional(),
+    error: ERROR_SHAPE
+  }),
+  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 ?? {};
   try {
@@ -4790,19 +4825,21 @@ next_hint: read_file path="${fp}" verbosity="compact"`);
 ERROR: ${e.message}`);
         }
       }
-      return { content: [{ type: "text", text: results.join("\n\n---\n\n") }] };
+      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 });
     }
     if (!p) throw new Error("Either 'path' or 'paths' is required");
-    return { content: [{ type: "text", text: readFile2(p, {
+    const content = readFile2(p, {
       offset,
       limit: readLimit,
       ranges,
       plain: readPlain,
       verbosity: readVerbosity,
       editReady: !!edit_ready
-    }) }] };
+    });
+    return result({ status: "OK", path: p, content, edit_ready: !!edit_ready }, { large: !!edit_ready || readVerbosity === "full" || content.length > 5e4 });
   } catch (e) {
-    return { content: [{ type: "text", text: e.message }], isError: true };
+    return errorResult(e.code || "READ_ERROR", e.message, e.recovery || "Check path and permissions");
   }
 });
 server.registerTool("edit_file", {
@@ -4819,7 +4856,8 @@ 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.")
   }),
-  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false }
+  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: 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 ?? {};
   try {
@@ -4831,19 +4869,15 @@ server.registerTool("edit_file", {
       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");
-    return {
-      content: [{
-        type: "text",
-        text: editFile(p, parsed, {
-          dryRun: dry_run,
-          restoreIndent: restore_indent,
-          baseRevision: base_revision,
-          conflictPolicy: conflict_policy
-        })
-      }]
-    };
+    const content = editFile(p, parsed, {
+      dryRun: dry_run,
+      restoreIndent: restore_indent,
+      baseRevision: base_revision,
+      conflictPolicy: conflict_policy
+    });
+    return result({ status: "OK", path: p, content }, { large: content.length > 5e4 });
   } catch (e) {
-    return { content: [{ type: "text", text: e.message }], isError: true };
+    return errorResult(e.code || "EDIT_ERROR", e.message, e.recovery || "Check anchors and checksums");
   }
 });
 server.registerTool("write_file", {
@@ -4854,7 +4888,8 @@ server.registerTool("write_file", {
     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.")
   }),
-  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true }
+  outputSchema: z2.object({ status: STATUS_ENUM, 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 ?? {};
   try {
@@ -4862,9 +4897,10 @@ server.registerTool("write_file", {
     const abs = validateWritePath(p);
     mkdirSync2(dirname6(abs), { recursive: true });
     writeFileSync4(abs, content, "utf-8");
-    return { content: [{ type: "text", text: `Created ${p} (${content.split("\n").length} lines)` }] };
+    const lines = content.split("\n").length;
+    return result({ status: "OK", path: p, lines });
   } catch (e) {
-    return { content: [{ type: "text", text: e.message }], isError: true };
+    return errorResult(e.code || "WRITE_ERROR", e.message, e.recovery || "Check path and permissions");
   }
 });
 server.registerTool("grep_search", {
@@ -4889,7 +4925,8 @@ server.registerTool("grep_search", {
     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.")
   }),
-  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+  outputSchema: z2.object({ status: STATUS_ENUM, pattern: z2.string().optional(), content: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
 }, async (rawParams) => {
   const {
     pattern,
@@ -4914,7 +4951,7 @@ server.registerTool("grep_search", {
     const resolvedOutput = output ?? "summary";
     const resolvedLimit = limit ?? (resolvedOutput === "summary" ? 20 : 100);
     const resolvedTotalLimit = total_limit ?? (resolvedOutput === "summary" ? 50 : void 0);
-    const result = await grepSearch(pattern, {
+    const searchResult = await grepSearch(pattern, {
       path: p,
       glob,
       type,
@@ -4932,9 +4969,9 @@ server.registerTool("grep_search", {
       editReady: !!edit_ready,
       allowLargeOutput: !!allow_large_output
     });
-    return { content: [{ type: "text", text: result }] };
+    return result({ status: "OK", pattern, content: searchResult }, { large: !!allow_large_output || resolvedOutput === "content" });
   } catch (e) {
-    return { content: [{ type: "text", text: e.message }], isError: true };
+    return errorResult(e.code || "GREP_ERROR", e.message, e.recovery || "Check pattern syntax");
   }
 });
 server.registerTool("outline", {
@@ -4943,14 +4980,15 @@ server.registerTool("outline", {
   inputSchema: z2.object({
     path: z2.string().describe("Source file path")
   }),
-  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), error: ERROR_SHAPE }),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
 }, async (rawParams) => {
   const { path: p } = rawParams ?? {};
   try {
-    const result = await fileOutline(p);
-    return { content: [{ type: "text", text: result }] };
+    const content = await fileOutline(p);
+    return result({ status: "OK", path: p, content });
   } catch (e) {
-    return { content: [{ type: "text", text: e.message }], isError: true };
+    return errorResult(e.code || "OUTLINE_ERROR", e.message, e.recovery || "Check file path and language support");
   }
 });
 server.registerTool("verify", {
@@ -4961,16 +4999,18 @@ server.registerTool("verify", {
     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.")
   }),
-  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), error: ERROR_SHAPE }),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
 }, async (rawParams) => {
   const { 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");
     }
-    return { content: [{ type: "text", text: verifyChecksums(p, checksums, { baseRevision: base_revision }) }] };
+    const content = verifyChecksums(p, checksums, { baseRevision: base_revision });
+    return result({ status: "OK", path: p, content });
   } catch (e) {
-    return { content: [{ type: "text", text: e.message }], isError: true };
+    return errorResult(e.code || "VERIFY_ERROR", e.message, e.recovery || "Check checksums format");
   }
 });
 server.registerTool("inspect_path", {
@@ -4986,21 +5026,23 @@ server.registerTool("inspect_path", {
     format: z2.enum(["compact", "full"]).optional().describe('"compact" = shorter path view, "full" = include sizes/metadata where available'),
     verbosity: z2.enum(["minimal", "compact", "full"]).optional().describe("Response budget. `minimal` returns the shortest tree summary.")
   }),
-  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
 }, async (rawParams) => {
   const { path: p, max_depth, max_entries, gitignore, format, pattern, type: entryType, verbosity } = rawParams ?? {};
   try {
     const resolvedVerbosity = verbosity ?? "minimal";
-    return { content: [{ type: "text", text: inspectPath(p, {
+    const content = inspectPath(p, {
       max_depth: max_depth ?? (pattern ? 20 : resolvedVerbosity === "full" ? 3 : 2),
       gitignore,
       format: format ?? (resolvedVerbosity === "full" ? "full" : "compact"),
       pattern,
       type: entryType,
       max_entries
-    }) }] };
+    });
+    return result({ status: "OK", path: p, content });
   } catch (e) {
-    return { content: [{ type: "text", text: e.message }], isError: true };
+    return errorResult(e.code || "INSPECT_ERROR", e.message, e.recovery || "Check path exists");
   }
 });
 server.registerTool("changes", {
@@ -5010,13 +5052,15 @@ server.registerTool("changes", {
     path: z2.string().describe("File or directory path"),
     compare_against: z2.string().optional().describe('Git ref to compare against (default: "HEAD")')
   }),
-  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
 }, async (rawParams) => {
   const { path: p, compare_against } = rawParams ?? {};
   try {
-    return { content: [{ type: "text", text: await fileChanges(p, compare_against) }] };
+    const content = await fileChanges(p, compare_against);
+    return result({ status: "OK", path: p, content }, { large: content.length > 5e4 });
   } catch (e) {
-    return { content: [{ type: "text", text: e.message }], isError: true };
+    return errorResult(e.code || "CHANGES_ERROR", e.message, e.recovery || "Check git ref and path");
   }
 });
 server.registerTool("bulk_replace", {
@@ -5031,7 +5075,8 @@ server.registerTool("bulk_replace", {
     format: z2.enum(["compact", "full"]).optional().describe('"compact" (default) = summary only, "full" = include capped diffs'),
     allow_external: flexBool().describe("Allow a replacement root outside the current project root. Use only when you intentionally target a temp or external directory.")
   }),
-  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false }
+  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
 }, async (rawParams) => {
   try {
     const params = rawParams ?? {};
@@ -5044,15 +5089,15 @@ server.registerTool("bulk_replace", {
       throw new Error('replacements: invalid JSON. Expected: [{"old":"text","new":"replacement"}]');
     }
     const replacements = replacementPairsSchema.parse(replacementsInput);
-    const result = bulkReplace(
+    const content = bulkReplace(
       params.path,
       params.glob || "**/*.{md,mjs,json,yml,ts,js}",
       replacements,
       { dryRun: params.dry_run || false, maxFiles: params.max_files || 100, format: params.format }
     );
-    return { content: [{ type: "text", text: result }] };
+    return result({ status: "OK", path: params.path, content }, { large: params.format === "full" });
   } catch (e) {
-    return { content: [{ type: "text", text: e.message }], isError: true };
+    return errorResult(e.code || "REPLACE_ERROR", e.message, e.recovery || "Check replacement pairs and scope");
   }
 });
 var transport = new StdioServerTransport();

package/package.json

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