@levnikolaevich/hex-line-mcp 1.25.1 → 1.26.0

package/README.md

@@ -46,7 +46,7 @@ Advanced / occasional:
 
 | Event | Trigger | Action |
 |-------|---------|--------|
-| **PreToolUse** | Read/Edit/Write/Grep/Glob on project text scope | Hard redirect to hex-line for project-scoped text files and file discovery; built-in tools stay available for binary/media and text paths outside the current project root |
+| **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 |
 | **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 |
@@ -54,7 +54,7 @@ Advanced / occasional:
 
 ### Bash Redirects
 
-PreToolUse also intercepts project-scoped file inspection Bash commands: `cat`, `type`, `Get-Content`, `head`, `tail`, `ls`, `dir`, `tree`, `find`, `Get-ChildItem`, `stat`, `wc`, `Get-Item`, `grep`, `rg`, `findstr`, `Select-String`, `sed -i`. Targeted inspection pipelines are redirected too; Git/build/test/docker/network and stdin-filter pipelines remain allowed.
+PreToolUse also intercepts project-scoped file inspection Bash commands: `cat`, `type`, `Get-Content`, `head`, `tail`, `ls`, `dir`, `tree`, `find`, `Get-ChildItem`, `stat`, `wc`, `Get-Item`, `grep`, `rg`, `findstr`, `Select-String`, `sed -i`. Targeted inspection pipelines receive advisory hints by default and are hard redirected only in explicit blocking mode; Git/build/test/docker/network and stdin-filter pipelines remain allowed.
 ## Install
 
 ### MCP Server
@@ -360,11 +360,11 @@ The unified hook (`hook.mjs`) handles five Claude hook events:
 
 ### PreToolUse: Tool Redirect
 
-Hard-routes built-in `Read`, `Edit`, `Write`, `Grep`, and `Glob` on project-scoped text workflows to hex-line. Binary/media files (images, PDFs, notebooks, archives, executables, fonts, media) and text paths outside the current project root stay on built-in tools.
+Advises built-in `Read`, `Edit`, `Write`, `Grep`, and `Glob` on project-scoped text workflows to use hex-line. Missing or malformed hook state defaults to advisory mode; set `.hex-skills/environment_state.json` to `hooks.mode: "blocking"` to hard-route covered calls. Binary/media files (images, PDFs, notebooks, archives, executables, fonts, media), plan markdown files in Plan Mode, and text paths outside the current project root stay on built-in tools.
 
 ### PreToolUse: Bash Redirect + Dangerous Blocker
 
-Intercepts project-scoped Bash file inspection commands (`cat`, `type`, `Get-Content`, `head`, `tail`, `ls`, `dir`, `tree`, `find`, `Get-ChildItem`, `stat`, `wc`, `Get-Item`, `grep`, `rg`, `findstr`, `Select-String`, `sed -i`, etc.) and redirects covered cases to hex-line tools. Targeted inspection pipelines are redirected. Dangerous commands (`rm -rf /`, `git push --force`, `git reset --hard`, `DROP TABLE`, `chmod 777`, `mkfs`, `dd`) are blocked.
+Intercepts project-scoped Bash file inspection commands (`cat`, `type`, `Get-Content`, `head`, `tail`, `ls`, `dir`, `tree`, `find`, `Get-ChildItem`, `stat`, `wc`, `Get-Item`, `grep`, `rg`, `findstr`, `Select-String`, `sed -i`, etc.) and advises hex-line tools by default. Explicit blocking mode hard redirects covered cases. Dangerous commands (`rm -rf /`, `git push --force`, `git reset --hard`, `DROP TABLE`, `chmod 777`, `mkfs`, `dd`) are always blocked.
 
 ### PostToolUse: RTK Output Filter
 

package/dist/hook.mjs

@@ -207,6 +207,15 @@ function extOf(filePath) {
 function getFilePath(toolInput) {
   return toolInput.file_path || toolInput.path || "";
 }
+function getMutatingTargetPath(toolInput) {
+  return toolInput.file_path || toolInput.path || "";
+}
+function isPlanMarkdownFile(filePath) {
+  if (!filePath) return false;
+  const normalized = filePath.replace(/\\/g, "/");
+  const name = normalized.slice(normalized.lastIndexOf("/") + 1);
+  return /^plan_.*\.md$/i.test(name);
+}
 function getGlobScopePath(toolInput) {
   if (toolInput.path) return toolInput.path;
   const pattern = typeof toolInput.pattern === "string" ? toolInput.pattern : "";
@@ -390,11 +399,11 @@ function _resetHexLineDisabledCache() {
 var _hookMode;
 function getHookMode() {
   if (_hookMode !== void 0) return _hookMode;
-  _hookMode = "blocking";
+  _hookMode = "advisory";
   try {
     const stateFile = resolve(process.cwd(), ".hex-skills/environment_state.json");
     const data = JSON.parse(readFileSync(stateFile, "utf-8"));
-    if (data.hooks?.mode === "advisory") _hookMode = "advisory";
+    if (data.hooks?.mode === "blocking") _hookMode = "blocking";
   } catch {
   }
   return _hookMode;
@@ -443,7 +452,7 @@ function handlePreToolUse(data) {
   const toolName = data.tool_name || "";
   const toolInput = data.tool_input || {};
   if (data.permission_mode === "plan" && HEX_LINE_MUTATING.has(toolName)) {
-    const targetPath = (toolInput.path || "").replace(/\\/g, "/");
+    const targetPath = getMutatingTargetPath(toolInput).replace(/\\/g, "/");
     const isPlanSafe = PLAN_SAFE_FOLDERS.some((folder) => targetPath.includes(folder));
     if (!isPlanSafe) {
       block(
@@ -467,14 +476,22 @@ function handlePreToolUse(data) {
     }
     if (toolName === "Read") {
       const ext = filePath ? extOf(filePath) : "";
+      if (data.permission_mode === "plan" && isPlanMarkdownFile(filePath)) {
+        process.exit(0);
+      }
       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(file_path="${filePath}").${rangeHint}${outlineTip}` : "Use mcp__hex-line__read_file or mcp__hex-line__inspect_path.";
+      const editReadyTip = ' If preparing an edit, call mcp__hex-line__read_file with edit_ready=true and verbosity="full" to get anchors and checksums.';
+      const target = filePath ? `Use mcp__hex-line__read_file(file_path="${filePath}").${rangeHint}${outlineTip}${editReadyTip}` : "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(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 (data.permission_mode === "plan" && isPlanMarkdownFile(filePath)) {
+        process.exit(0);
+      }
+      const editShape = 'edits=[{"set_line":{"anchor":"ab.12","new_text":"replacement"}}]';
+      const target = filePath ? `Use mcp__hex-line__edit_file(file_path="${filePath}", ${editShape}). If you need anchors first: mcp__hex-line__read_file(file_path="${filePath}", edit_ready=true, verbosity="full") or mcp__hex-line__grep_search(output_mode="content", edit_ready=true).` : `Use mcp__hex-line__edit_file(${editShape}). If you need anchors first: mcp__hex-line__grep_search(output_mode="content", edit_ready=true).`;
+      redirect(target, "Hash-verified edits for project text files. In default advisory mode, built-in Edit remains available as fallback.\n" + DEFERRED_HINT);
     }
     if (toolName === "Write") {
       const pathNote = filePath ? ` with file_path="${filePath}"` : "";

package/dist/server.mjs

@@ -4870,7 +4870,7 @@ function errorResult(code, message, recovery, { large = false, extra = null } =
 }
 
 // server.mjs
-var version = true ? "1.25.1" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.26.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([

package/output-style.md

@@ -58,8 +58,8 @@ Prefer `hex-line` for text files you may inspect or modify. Hash-annotated reads
 
 ## Exceptions
 
-- Built-in `Read`/`Edit`/`Write`/`Grep`/`Glob` are fallback only. With the hook active, project-scoped text calls and file discovery route to hex-line. Built-in OK for images, PDFs, notebooks, and text paths outside the current project root.
-- Bash is still fine for npm, node, git, docker, curl, non-inspection pipelines, and other runtime workflows. Project file inspection commands route to hex-line, including Windows-native readers/searchers/listing commands.
+- Built-in `Read`/`Edit`/`Write`/`Grep`/`Glob` are fallback only by preference. With the hook active, project-scoped text calls and file discovery receive hex-line guidance by default and hard-route only when `hooks.mode` is `blocking`. Built-in OK for images, PDFs, notebooks, plan files in Plan Mode, and text paths outside the current project root.
+- Bash is still fine for npm, node, git, docker, curl, non-inspection pipelines, and other runtime workflows. Project file inspection commands receive hex-line guidance, including Windows-native readers/searchers/listing commands.
 
 ## hex-graph
 

package/package.json

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