@levnikolaevich/hex-line-mcp 1.3.1 → 1.3.3

package/benchmark/index.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Hex-line workflow benchmark with optional diagnostics.
+ *
+ * Public benchmark mode reports only comparative multi-step workflows.
+ * Synthetic tool-level scenarios are available behind --diagnostics and
+ * should not be treated as headline benchmark results.
+ *
+ * Usage:
+ *   node mcp/hex-line-mcp/benchmark/index.mjs [--repo /path/to/repo]
+ *   node mcp/hex-line-mcp/benchmark/index.mjs --diagnostics [--with-graph]
+ */
+
+import { writeFileSync, unlinkSync } from "node:fs";
+import { resolve, basename } from "node:path";
+import { tmpdir } from "node:os";
+import {
+    walkDir, getFileLines, categorize, generateTempCode,
+    fmt, pctSavings, RUNS,
+} from "../lib/benchmark-helpers.mjs";
+import { runAtomic } from "./atomic.mjs";
+import { runGraph } from "./graph.mjs";
+import { runWorkflows } from "./workflows.mjs";
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+let repoRoot = process.cwd();
+const repoIdx = args.indexOf("--repo");
+if (repoIdx !== -1 && args[repoIdx + 1]) {
+    repoRoot = resolve(args[repoIdx + 1]);
+}
+
+const diagnostics = args.includes("--diagnostics");
+const withGraph = args.includes("--with-graph");
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+    const allFiles = walkDir(repoRoot);
+    if (allFiles.length === 0) {
+        console.log(`No code files found in ${repoRoot}`);
+        process.exit(1);
+    }
+
+    const totalLines = allFiles.reduce((sum, f) => {
+        const lines = getFileLines(f);
+        return lines ? sum + lines.length : sum;
+    }, 0);
+
+    const cats = categorize(allFiles);
+    const repoName = basename(repoRoot);
+
+    // Top 3 largest code files for realistic tests
+    const sorted = allFiles.map(f => ({ f, lines: getFileLines(f)?.length || 0 }))
+        .sort((a, b) => b.lines - a.lines);
+    const largeFiles = sorted.slice(0, 3).map(s => s.f);
+
+    // Temp file setup
+    const ts = Date.now();
+    const tmpPath = resolve(tmpdir(), `hex-line-bench-${ts}.js`);
+    const tmpLines = generateTempCode();
+    const tmpContent = tmpLines.join("\n");
+    writeFileSync(tmpPath, tmpContent, "utf-8");
+
+    // Build config shared across all benchmark modules
+    const config = { allFiles, cats, largeFiles, tmpPath, tmpContent, tmpLines, repoRoot, ts };
+
+    // Run benchmark suites
+    const workflowResults = await runWorkflows(config);
+    const results = diagnostics ? await runAtomic(config) : [];
+    const graphOut = diagnostics && withGraph ? await runGraph(config) : [];
+
+    // Cleanup
+    try { unlinkSync(tmpPath); } catch { /* ok */ }
+
+    // ===================================================================
+    // Report
+    // ===================================================================
+    const out = [];
+    out.push("# Hex-line Workflow Benchmark");
+    out.push("");
+    out.push(`Repository: ${repoName} (${fmt(allFiles.length)} code files, ${fmt(totalLines)} lines)  `);
+    out.push(`Temp file: ${tmpPath} (200 lines)  `);
+    out.push(`Date: ${new Date().toISOString().slice(0, 10)}  `);
+    out.push(`Runs per scenario: ${RUNS} (median)  `);
+    out.push("");
+    out.push("Mode: comparative workflow benchmark");
+    out.push("");
+    out.push("## Workflow Scenarios");
+    out.push("");
+    out.push("| # | Scenario | Built-in | Hex-line | Savings | Ops |");
+    out.push("|---|----------|----------|----------|---------|-----|");
+    for (const w of workflowResults) {
+        out.push(`| ${w.id} | ${w.scenario} | ${fmt(w.without)} chars | ${fmt(w.withSL)} chars | ${pctSavings(w.without, w.withSL)} | ${w.opsWithout}\u2192${w.opsWith} |`);
+    }
+    out.push("");
+
+    if (workflowResults.length > 0) {
+        const avgWorkflowSavings = workflowResults.reduce((sum, w) => {
+            if (w.without === 0) return sum;
+            return sum + (((w.without - w.withSL) / w.without) * 100);
+        }, 0) / workflowResults.length;
+        const totalWorkflowOpsWithout = workflowResults.reduce((sum, w) => sum + w.opsWithout, 0);
+        const totalWorkflowOpsWith = workflowResults.reduce((sum, w) => sum + w.opsWith, 0);
+        const workflowOpsPct = totalWorkflowOpsWithout > 0
+            ? (((totalWorkflowOpsWithout - totalWorkflowOpsWith) / totalWorkflowOpsWithout) * 100).toFixed(0)
+            : "0";
+        out.push(`Workflow summary: ${avgWorkflowSavings.toFixed(0)}% average token savings | ${totalWorkflowOpsWithout}\u2192${totalWorkflowOpsWith} ops (${workflowOpsPct}% fewer)`);
+        out.push("");
+    }
+
+    out.push("Note: benchmark mode reports only multi-step comparative workflows. Synthetic tool-level scenarios live under diagnostics and are not headline results.");
+    out.push("");
+
+    if (diagnostics) {
+        out.push("## Diagnostics");
+        out.push("");
+        out.push("These rows are modeled tool-level comparisons for engineering inspection only. They are not part of the public workflow benchmark score.");
+        out.push("");
+        out.push("| # | Scenario | Baseline | Hex-line | Savings |");
+        out.push("|---|----------|----------|----------|---------|");
+        for (const r of results) {
+            out.push(`| ${r.num} | ${r.scenario} | ${fmt(r.without)} chars | ${fmt(r.withSL)} chars | ${r.savings} |`);
+        }
+        out.push("");
+        if (graphOut.length > 0) {
+            out.push("### Graph Enrichment Diagnostics");
+            out.push("");
+            out.push("Graph-enrichment rows remain diagnostics only. Run with `--with-graph` to inspect them alongside the atomic rows.");
+            out.push("");
+            out.push(...graphOut);
+            out.push("");
+        }
+    }
+
+    console.log(out.join("\n"));
+}
+
+main();

package/benchmark/workflows.mjs

@@ -0,0 +1,350 @@
+/**
+ * Session-derived workflow scenarios built from recent real Claude usage.
+ *
+ * These are still local, reproducible benchmarks, but the tasks are framed
+ * after actual day-to-day workflows observed in recent sessions:
+ * - debugging hex-line hook behavior
+ * - adjusting setup/output guidance
+ * - repo-wide benchmark wording refactor
+ * - targeted edit inside a large smoke test
+ */
+
+import { copyFileSync, mkdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fnv1a, lineTag, rangeChecksum } from "../lib/hash.mjs";
+import { readFile } from "../lib/read.mjs";
+import { verifyChecksums } from "../lib/verify.mjs";
+import { editFile } from "../lib/edit.mjs";
+import { bulkReplace } from "../lib/bulk-replace.mjs";
+import { fileOutline } from "../lib/outline.mjs";
+import {
+    getFileLines,
+    simBuiltInReadFull,
+    simBuiltInGrep,
+    simBuiltInEdit,
+    simHexLineEditDiff,
+    runN,
+} from "../lib/benchmark-helpers.mjs";
+
+function ensureLine(lines, matcher, label) {
+    const idx = lines.findIndex((line) => matcher(line));
+    if (idx === -1) throw new Error(`Benchmark fixture missing line for ${label}`);
+    return idx;
+}
+
+function copyIntoTemp(tempRoot, sourceRoot, relPath) {
+    const src = resolve(sourceRoot, relPath);
+    const dst = resolve(tempRoot, relPath);
+    mkdirSync(dirname(dst), { recursive: true });
+    copyFileSync(src, dst);
+    return dst;
+}
+
+export async function runWorkflows(config) {
+    const { repoRoot, allFiles, largeFiles } = config;
+    const workflowResults = [];
+
+    // W1: derived from "Debug hex line formatting in file listings"
+    {
+        const sourcePath = resolve(repoRoot, "hook.mjs");
+        const sourceLines = getFileLines(sourcePath);
+        if (!sourceLines) throw new Error("Unable to load hook.mjs for benchmark workflow W1");
+
+        const targetIdx = ensureLine(
+            sourceLines,
+            (line) => line.includes("ls -R, ls -laR (recursive only)"),
+            "hook redirect comment",
+        );
+        const tempPath = resolve(tmpdir(), `hex-line-wf1-${Date.now()}.mjs`);
+        copyFileSync(sourcePath, tempPath);
+
+        const updatedLine = sourceLines[targetIdx].replace("recursive only", "recursive listing only");
+        const updatedLines = [...sourceLines];
+        updatedLines[targetIdx] = updatedLine;
+
+        const { value: without } = runN(() => {
+            let total = 0;
+            total += simBuiltInGrep("ls -R", tempPath).length;
+            total += simBuiltInReadFull(tempPath, sourceLines).length;
+            total += simBuiltInEdit(tempPath, sourceLines, updatedLines).length;
+            return total;
+        });
+
+        const { value: withSL } = runN(() => {
+            let total = 0;
+            const tag = lineTag(fnv1a(sourceLines[targetIdx]));
+            total += `${tempPath}:>>${tag}.${targetIdx + 1}\t${sourceLines[targetIdx]}`.length;
+            try {
+                total += editFile(tempPath, [{ set_line: { anchor: `${tag}.${targetIdx + 1}`, new_text: updatedLine } }]).length;
+            } catch (e) {
+                total += e.message.length;
+            }
+            return total;
+        });
+
+        workflowResults.push({
+            id: "W1",
+            scenario: "Debug hook file-listing redirect",
+            without,
+            withSL,
+            opsWithout: 3,
+            opsWith: 2,
+        });
+        try { unlinkSync(tempPath); } catch {}
+    }
+
+    // W2: derived from setup / guidance updates in repo tooling sessions
+    {
+        const sourcePath = resolve(repoRoot, "lib", "setup.mjs");
+        const sourceLines = getFileLines(sourcePath);
+        if (!sourceLines) throw new Error("Unable to load lib/setup.mjs for benchmark workflow W2");
+
+        const targetIdx = ensureLine(
+            sourceLines,
+            (line) => line.includes("Codex: Not supported"),
+            "setup guidance line",
+        );
+        const tempPath = resolve(tmpdir(), `hex-line-wf2-${Date.now()}.mjs`);
+        copyFileSync(sourcePath, tempPath);
+
+        const updatedLine = sourceLines[targetIdx].replace(
+            "Add MCP Tool Preferences to AGENTS.md instead",
+            "Document MCP Tool Preferences in AGENTS.md instead",
+        );
+        const updatedLines = [...sourceLines];
+        updatedLines[targetIdx] = updatedLine;
+        const windowStart = Math.max(1, targetIdx - 3);
+        const windowLimit = Math.min(sourceLines.length - windowStart + 1, 10);
+        const hashes = sourceLines.map((line) => fnv1a(line));
+        const checksum = rangeChecksum(hashes, windowStart, windowStart + windowLimit - 1);
+
+        const { value: without } = runN(() => {
+            let total = 0;
+            total += simBuiltInReadFull(tempPath, sourceLines).length;
+            total += simBuiltInEdit(tempPath, sourceLines, updatedLines).length;
+            total += simBuiltInReadFull(tempPath, sourceLines).length;
+            return total;
+        });
+
+        const { value: withSL } = runN(() => {
+            let total = 0;
+            total += readFile(tempPath, { offset: windowStart, limit: windowLimit }).length;
+            copyFileSync(sourcePath, tempPath);
+            try {
+                const tag = lineTag(fnv1a(sourceLines[targetIdx]));
+                total += editFile(tempPath, [{ set_line: { anchor: `${tag}.${targetIdx + 1}`, new_text: updatedLine } }]).length;
+            } catch (e) {
+                total += e.message.length;
+            }
+            try {
+                total += verifyChecksums(tempPath, [checksum]).length;
+            } catch (e) {
+                total += e.message.length;
+            }
+            return total;
+        });
+
+        workflowResults.push({
+            id: "W2",
+            scenario: "Adjust setup_hooks guidance and verify",
+            without,
+            withSL,
+            opsWithout: 3,
+            opsWith: 3,
+        });
+        try { unlinkSync(tempPath); } catch {}
+    }
+
+    // W3: derived from repo-wide benchmark wording refactors
+    {
+        const tempRoot = resolve(tmpdir(), `hex-line-wf3-${Date.now()}`);
+        mkdirSync(tempRoot, { recursive: true });
+        const fixtureFiles = [
+            "README.md",
+            "package.json",
+            "benchmark/index.mjs",
+            "benchmark/atomic.mjs",
+            "benchmark/workflows.mjs",
+        ];
+        const copiedFiles = fixtureFiles.map((relPath) => copyIntoTemp(tempRoot, repoRoot, relPath));
+        const fileLines = copiedFiles.map((filePath) => getFileLines(filePath));
+        const replacements = [{ old: "benchmark", new: "workflow benchmark" }];
+
+        const { value: without } = runN(() => {
+            let total = 0;
+            for (let i = 0; i < copiedFiles.length; i++) {
+                const filePath = copiedFiles[i];
+                const lines = fileLines[i];
+                if (!lines) continue;
+                total += simBuiltInGrep("benchmark", filePath).length;
+                total += simBuiltInReadFull(filePath, lines).length;
+                const updated = lines.map((line) => line.split("benchmark").join("workflow benchmark"));
+                total += simBuiltInEdit(filePath, lines, updated).length;
+            }
+            return total;
+        });
+
+        const { value: withSL } = runN(() => {
+            return bulkReplace(
+                tempRoot,
+                "**/*.{md,json,mjs}",
+                replacements,
+                { dryRun: true, maxFiles: 10 },
+            ).length;
+        });
+
+        workflowResults.push({
+            id: "W3",
+            scenario: "Repo-wide benchmark wording refresh",
+            without,
+            withSL,
+            opsWithout: copiedFiles.length * 3,
+            opsWith: 1,
+        });
+        try { rmSync(tempRoot, { recursive: true }); } catch {}
+    }
+
+    // W4: derived from reviewing large smoke tests before a focused change
+    {
+        const preferredLarge = allFiles.find((filePath) => filePath.endsWith("test\\smoke.mjs"))
+            || largeFiles[0]
+            || allFiles[0];
+        const largeLines = getFileLines(preferredLarge);
+        if (largeLines && largeLines.length > 100) {
+            const targetIdx = ensureLine(
+                largeLines,
+                (line) => line.includes("describe(\"hook — ls redirect\""),
+                "large smoke test anchor",
+            );
+            const sliceStart = Math.max(0, targetIdx - 5);
+            const sliceEnd = Math.min(largeLines.length, targetIdx + 15);
+            const editedSlice = largeLines.slice(sliceStart, sliceEnd).map((line, idx) =>
+                idx === (targetIdx - sliceStart) ? `${line} // benchmark-note` : line,
+            );
+
+            const { value: without } = runN(() => {
+                let total = 0;
+                total += simBuiltInReadFull(preferredLarge, largeLines).length;
+                total += simBuiltInGrep("hook — ls redirect", preferredLarge).length;
+                const updatedLines = [...largeLines];
+                updatedLines[targetIdx] = `${updatedLines[targetIdx]} // benchmark-note`;
+                total += simBuiltInEdit(preferredLarge, largeLines, updatedLines).length;
+                return total;
+            });
+
+            let outlineLen = 500;
+            try { outlineLen = (await fileOutline(preferredLarge)).length; } catch {}
+
+            const { value: withSL } = runN(() => {
+                let total = 0;
+                total += outlineLen;
+                total += readFile(preferredLarge, { offset: sliceStart + 1, limit: sliceEnd - sliceStart }).length;
+                total += simHexLineEditDiff(largeLines.slice(sliceStart, sliceEnd), editedSlice).length;
+                return total;
+            });
+
+            workflowResults.push({
+                id: "W4",
+                scenario: `Inspect large smoke test before edit (${largeLines.length}L)`,
+                without,
+                withSL,
+                opsWithout: 3,
+                opsWith: 3,
+            });
+        }
+    }
+
+    // W5: revision-aware follow-up edit after unrelated line shift
+    {
+        const tempPath = resolve(tmpdir(), `hex-line-wf5-${Date.now()}.mjs`);
+        const prefix = Array.from({ length: 80 }, (_, i) => `pre-${i}`);
+        const suffix = Array.from({ length: 80 }, (_, i) => `post-${i}`);
+        const sourceLines = [
+            ...prefix,
+            "head1",
+            "head2",
+            "targetA",
+            "targetB",
+            "tail",
+            ...suffix,
+            "",
+        ];
+        const sourceText = sourceLines.join("\n");
+        mkdirSync(dirname(tempPath), { recursive: true });
+        writeFileSync(tempPath, sourceText, "utf-8");
+
+        const head1Idx = prefix.length;
+        const targetAIdx = prefix.length + 2;
+        const targetBIdx = prefix.length + 3;
+        const withInsert = [
+            ...prefix,
+            "head1",
+            "inserted",
+            "head2",
+            "targetA",
+            "targetB",
+            "tail",
+            ...suffix,
+            "",
+        ];
+        const updatedLines = [
+            ...prefix,
+            "head1",
+            "inserted",
+            "head2",
+            "targetA",
+            "updatedB",
+            "tail",
+            ...suffix,
+            "",
+        ];
+
+        const { value: without } = runN(() => {
+            let total = 0;
+            total += simBuiltInReadFull(tempPath, sourceLines).length;
+            total += simBuiltInEdit(tempPath, sourceLines, withInsert).length;
+            total += simBuiltInReadFull(tempPath, withInsert).length;
+            total += simBuiltInEdit(tempPath, withInsert, updatedLines).length;
+            return total;
+        });
+
+        const { value: withSL } = runN(() => {
+            let total = 0;
+            writeFileSync(tempPath, sourceText, "utf-8");
+            const baseRead = readFile(tempPath, { offset: head1Idx + 1, limit: 8 });
+            total += baseRead.length;
+            const baseRevision = baseRead.match(/revision: (\S+)/)?.[1];
+            const headTag = lineTag(fnv1a(sourceLines[head1Idx]));
+            total += editFile(tempPath, [{ insert_after: { anchor: `${headTag}.${head1Idx + 1}`, text: "inserted" } }]).length;
+            const startTag = lineTag(fnv1a(sourceLines[targetAIdx]));
+            const endTag = lineTag(fnv1a(sourceLines[targetBIdx]));
+            const rc = rangeChecksum(
+                [fnv1a(sourceLines[targetAIdx]), fnv1a(sourceLines[targetBIdx])],
+                targetAIdx + 1,
+                targetBIdx + 1,
+            );
+            total += editFile(tempPath, [{
+                replace_lines: {
+                    start_anchor: `${startTag}.${targetAIdx + 1}`,
+                    end_anchor: `${endTag}.${targetBIdx + 1}`,
+                    new_text: "targetA\nupdatedB",
+                    range_checksum: rc,
+                }
+            }], { baseRevision, conflictPolicy: "conservative" }).length;
+            return total;
+        });
+
+        workflowResults.push({
+            id: "W5",
+            scenario: "Follow-up edit after unrelated line shift",
+            without,
+            withSL,
+            opsWithout: 4,
+            opsWith: 3,
+        });
+        try { unlinkSync(tempPath); } catch {}
+    }
+
+    return workflowResults;
+}

package/hook.mjs

@@ -14,16 +14,17 @@
  *
  * PostToolUse:
  *   - RTK output filter: compresses verbose Bash output
- *     (npm install, test, build, pip, git) to save context tokens.
+ *     (npm install, test, build, pip, git). Stderr shown to
+ *     Claude as feedback.
  *
  * SessionStart:
  *   - Injects tool preference list into agent context.
  *
  * Exit 0 = approve / no feedback / systemMessage
- * Exit 2 = block (PreToolUse) or feedback via stderr (PostToolUse)
+ * Exit 2 = block (PreToolUse) or stderr feedback (PostToolUse)
  */
 
-import { normalizeOutput } from "./lib/normalize.mjs";
+import { normalizeOutput } from "@levnikolaevich/hex-common/output/normalize";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { homedir } from "node:os";
@@ -41,21 +42,21 @@ const BINARY_EXT = new Set([
 
 const REVERSE_TOOL_HINTS = {
     "mcp__hex-line__read_file":      "Read (file_path, offset, limit)",
-    "mcp__hex-line__edit_file":      "Edit (file_path, old_string, new_string)",
+    "mcp__hex-line__edit_file":      "Edit (revision-aware hash edits, block rewrite, auto-rebase)",
     "mcp__hex-line__write_file":     "Write (file_path, content)",
     "mcp__hex-line__grep_search":    "Grep (pattern, path)",
     "mcp__hex-line__directory_tree": "Glob (pattern) or Bash(ls)",
     "mcp__hex-line__get_file_info":  "Bash(stat/wc)",
     "mcp__hex-line__outline":        "Read with offset/limit",
-    "mcp__hex-line__verify":         "Read the file again with Read",
+    "mcp__hex-line__verify":         "Verify held checksums / revision without reread",
     "mcp__hex-line__changes":        "Bash(git diff)",
-    "mcp__hex-line__bulk_replace":   "Edit for each file",
+    "mcp__hex-line__bulk_replace":   "Edit (text rename/refactor across files)",
     "mcp__hex-line__setup_hooks":    "Not available (hex-line disabled)",
 };
 
 const TOOL_HINTS = {
     Read:  "mcp__hex-line__read_file (not Read). For writing: write_file (no prior Read needed)",
-    Edit:  "mcp__hex-line__edit_file (not Edit, not sed -i). read_file first for hashes",
+    Edit:  "mcp__hex-line__edit_file for revision-aware hash edits. Batch same-file hunks, carry base_revision, use replace_between for block rewrites",
     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",
     cat:   "mcp__hex-line__read_file (not cat/head/tail/less/more)",
@@ -64,10 +65,10 @@ const TOOL_HINTS = {
     ls:    "mcp__hex-line__directory_tree with pattern param (not ls/find/tree). E.g. pattern='*-mcp' type='dir'",
     stat:  "mcp__hex-line__get_file_info (not stat/wc/file)",
     grep:  "mcp__hex-line__grep_search (not grep/rg). Params: output, literal, context_before, context_after, multiline",
-    sed:   "mcp__hex-line__edit_file (not sed -i). read_file first for hashes",
+    sed:   "mcp__hex-line__edit_file for hash edits, or mcp__hex-line__bulk_replace for text rename (not sed -i)",
     diff:  "mcp__hex-line__changes (not diff). Git-based semantic diff",
     outline: "mcp__hex-line__outline (before reading large code files)",
-    verify:  "mcp__hex-line__verify (staleness check without re-read)",
+    verify:  "mcp__hex-line__verify (staleness / revision check without re-read)",
     changes: "mcp__hex-line__changes (semantic AST diff)",
     bulk:    "mcp__hex-line__bulk_replace (multi-file search-replace)",
     setup:   "mcp__hex-line__setup_hooks (configure hooks for agents)",
@@ -78,7 +79,8 @@ const BASH_REDIRECTS = [
     { regex: /^head\s+/, key: "head" },
     { regex: /^tail\s+(?!-[fF])/, key: "tail" },
     { regex: /^(less|more)\s+/, key: "cat" },
-    { regex: /^(ls|dir)(\s+-\S+)*\s+/, key: "ls" },
+    { regex: /^ls\s+-\S*R(\s|$)/, key: "ls" },   // ls -R, ls -laR (recursive only)
+    { regex: /^dir\s+\/[sS](\s|$)/, key: "ls" }, // dir /s, dir /S (recursive only)
     { regex: /^tree\s+/, key: "ls" },
     { regex: /^find\s+/, key: "ls" },
     { regex: /^(stat|wc)\s+/, key: "stat" },
@@ -152,6 +154,18 @@ function detectCommandType(cmd) {
     return "generic";
 }
 
+function extractBashText(response) {
+    if (typeof response === "string") return response;
+    if (response && typeof response === "object") {
+        // Combine stdout + stderr in stable order
+        const parts = [];
+        if (response.stdout) parts.push(response.stdout);
+        if (response.stderr) parts.push(response.stderr);
+        return parts.join("\n") || "";
+    }
+    return ""; // unknown shape \u2192 fail open
+}
+
 /** Cache: null = not computed yet */
 let _hexLineDisabled = null;
 
@@ -225,6 +239,25 @@ function handlePreToolUse(data) {
             process.exit(0);
         }
 
+        // Skip Claude config files (settings.json, settings.local.json)
+        const ALLOWED_CONFIGS = new Set(["settings.json", "settings.local.json"]);
+        const fileName = normalPath.split("/").pop();
+        if (ALLOWED_CONFIGS.has(fileName)) {
+            let candidate = filePath;
+            if (candidate.startsWith("~/")) {
+                candidate = homedir().replace(/\\/g, "/") + candidate.slice(1);
+            }
+            const absPath = resolve(process.cwd(), candidate).replace(/\\/g, "/");
+            const projectClaude = resolve(process.cwd(), ".claude").replace(/\\/g, "/") + "/";
+            const globalClaude = resolve(homedir(), ".claude").replace(/\\/g, "/") + "/";
+            const cmp = process.platform === "win32"
+                ? (a, b) => a.toLowerCase().startsWith(b.toLowerCase())
+                : (a, b) => a.startsWith(b);
+            if (cmp(absPath, projectClaude) || cmp(absPath, globalClaude)) {
+                process.exit(0);
+            }
+        }
+
         // Block with redirect — include extracted path for instant retry
         const hint = TOOL_HINTS[hintKey];
         const toolName2 = hint.split(" (")[0];
@@ -317,15 +350,15 @@ function handlePostToolUse(data) {
     }
 
     const toolInput = data.tool_input || {};
-    const toolResult = data.tool_result;
+    const rawText = extractBashText(data.tool_response);
     const command = toolInput.command || "";
 
     // Nothing to filter
-    if (!toolResult || typeof toolResult !== "string") {
+    if (!rawText) {
         process.exit(0);
     }
 
-    const lines = toolResult.split("\n");
+    const lines = rawText.split("\n");
     const originalCount = lines.length;
 
     // Short output - no filtering
@@ -390,9 +423,9 @@ function handleSessionStart() {
             lines.push(`- ${hint}`);
         }
     }
-    lines.push("Exceptions: images, PDFs, notebooks \u2192 built-in Read");
+    lines.push("Exceptions: images, PDFs, notebooks, .claude/settings.json, .claude/settings.local.json \u2192 built-in Read; Glob always OK");
     lines.push("Bash OK for: npm/node/git/docker/curl, pipes, scripts");
-    const msg = "Hex-line MCP available. ALWAYS prefer:\n" + lines.join("\n");
+    const msg = "Hex-line MCP available. Workflow:\n- Discovery: read_file, grep_search, outline, directory_tree\n- Same-file edits: prefer ONE edit_file call per file, carry revision/base_revision\n- Hash edits: edit_file (set_line, replace_lines, insert_after, replace_between)\n- Large rewrites: replace_between instead of reciting old blocks\n- Text rename: bulk_replace (multi-file search-replace)\n- Verify staleness: verify before considering reread\n- Write new: write_file\n" + lines.join("\n");
     process.stdout.write(JSON.stringify({ systemMessage: msg }));
     process.exit(0);
 }

package/lib/benchmark-helpers.mjs

@@ -2,7 +2,7 @@ import { readFileSync, statSync, readdirSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { performance } from "node:perf_hooks";
 import { resolve, extname, join } from "node:path";
-import { fnv1a, lineTag } from "./hash.mjs";
+import { fnv1a, lineTag } from "@levnikolaevich/hex-common/text-protocol/hash";
 import { readFile } from "./read.mjs";
 
 // ---------------------------------------------------------------------------

package/lib/changes.mjs

@@ -9,7 +9,7 @@
 import { execFileSync } from "node:child_process";
 import { statSync } from "node:fs";
 import { extname } from "node:path";
-import { validatePath } from "./security.mjs";
+import { validatePath, normalizePath } from "./security.mjs";
 import { readText } from "./format.mjs";
 import { outlineFromContent } from "./outline.mjs";
 
@@ -75,6 +75,7 @@ function gitRelativePath(absPath) {
  * @returns {Promise<string>}      Formatted diff
  */
 export async function fileChanges(filePath, compareAgainst = "HEAD") {
+    filePath = normalizePath(filePath);
     const real = validatePath(filePath);
 
     // Directory: return git diff --stat (compact file list, no content reads)