@levnikolaevich/hex-line-mcp 1.16.0 → 1.17.1

package/README.md

@@ -35,10 +35,10 @@ Advanced / occasional:
 | `read_file` | Read file with progressive disclosure, optional edit-ready metadata, and automatic graph hints when available | Minimal plain discovery by default, explicit `edit_ready` for verified edits |
 | `edit_file` | Revision-aware anchor edits (`set_line`, `replace_lines`, `insert_after`, `replace_between`) | Batched same-file edits + conservative auto-rebase |
 | `write_file` | Create new file or overwrite, auto-creates parent dirs | Path validation, no hash overhead |
-| `grep_search` | Search with ripgrep, summary-first discovery, and optional edit-ready hunks | `summary` by default, explicit `content` + `edit_ready` for verified edits |
+| `grep_search` | Search with ripgrep, summary-first discovery, and optional edit-ready hunks | `summary` by default, capped `content` mode with explicit `allow_large_output` escape hatch |
 | `outline` | AST-based structural overview with hash anchors via tree-sitter WASM. Supports JavaScript/TypeScript, Python, C#, PHP, and fence-aware markdown headings | 95% token reduction, direct edit anchors |
 | `verify` | Check if held checksums / revision are still current | Staleness check without full re-read |
-| `inspect_path` | Unified file-or-directory inspection | Minimal tree discovery by default, deeper traversal on demand |
+| `inspect_path` | Unified file-or-directory inspection | Minimal tree discovery by default, capped pattern-mode lists with refine hints |
 | `changes` | Compare file against git ref, shows added/removed/modified symbols | AST-level semantic diff with risk/provenance preview |
 | `bulk_replace` | Search-and-replace across multiple files inside an explicit root path | Compact summary (default) or capped diffs via `format`, dry_run, max_files |
 
@@ -46,7 +46,7 @@ Advanced / occasional:
 
 | Event | Trigger | Action |
 |-------|---------|--------|
-| **PreToolUse** | Read/Edit/Write/Grep on text files | Redirect-first policy for text files; built-in tools stay reserved for binary/media and `.claude/settings*.json` exceptions |
+| **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** | 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 simple Bash commands: cat, head, tail, tree, find, stat, wc -l, grep, rg, sed -i — redirects to hex-line equivalents. `ls`/`dir` only redirected for recursive listing (`ls -R`, `dir /s`); simple `ls path` is allowed. Compound commands with pipes are 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 are redirected too; Git/build/test/docker/network and stdin-filter pipelines remain allowed.
 ## Install
 
 ### MCP Server
@@ -292,9 +292,13 @@ Search file contents using ripgrep. Default mode is `summary` for discovery. Use
 | `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) |
 | `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 |
 
 `summary` mode returns counts, top files, and a few plain snippets. `content` mode returns canonical `search_hunk` blocks with per-hunk checksums enabling direct `replace_lines` from grep results without intermediate `read_file`.
 
+- Default `content` mode is intentionally capped to keep discovery cheap. When truncation happens, the diagnostic block includes `shown_matches`, `file_count`, `truncated`, `next_action`, and `suggested_refine_call`.
+- Treat `allow_large_output: true` as an explicit override for review/debug workflows, not as the normal discovery path.
+
 ### outline
 
 AST-based structural outline with hash anchors for direct `edit_file` usage. Supports JavaScript/TypeScript, Python, C#, PHP, and fence-aware markdown heading navigation (`.md`/`.mdx`). Each entry includes a hash tag for immediate anchor use without intermediate `read_file`.
@@ -343,6 +347,7 @@ Inspect a file or directory path without guessing which low-level tool to call f
 | `pattern` | string | no | Glob filter on names (e.g. `"*-mcp"`, `"*.mjs"`). Returns flat match list instead of tree |
 | `type` | string | no | `"file"`, `"dir"`, or `"all"` (default). Like `find -type f/d` |
 | `max_depth` | number | no | Max recursion depth (default: 2 for discovery, or 20 in pattern mode) |
+| `max_entries` | number | no | Max entries to show in pattern mode before truncation metadata is returned (default: 60, `0` = unlimited) |
 | `gitignore` | boolean | no | Respect root .gitignore patterns (default: true). Nested .gitignore not supported |
 | `format` | string | no | `"compact"` = shorter path view. `"full"` = include sizes / metadata where available |
 | `verbosity` | enum | no | `minimal`, `compact`, or `full` |
@@ -350,6 +355,7 @@ Inspect a file or directory path without guessing which low-level tool to call f
 - For regular files it returns compact metadata: size, line count when cheap, modification time, type, and binary flag.
 - For directories it returns a gitignore-aware tree.
 - With `pattern`, it switches to flat match mode and works as the preferred replacement for `find` / recursive `ls`.
+- Broad pattern mode is capped by default and returns `match_count`, `shown_count`, `truncated`, `next_action`, and `suggested_refine_call` so the caller can narrow `path` before asking for more.
 
 ## Hook
 
@@ -357,11 +363,11 @@ The unified hook (`hook.mjs`) handles three Claude hook events:
 
 ### PreToolUse: Tool Redirect
 
-Applies redirect-first steering to built-in `Read`, `Edit`, `Write`, and `Grep` on text files. Binary/media files (images, PDFs, notebooks, archives, executables, fonts, media) stay on built-in tools. `.claude/settings.json` and `.claude/settings.local.json` at project root or home are also allowed on built-in tools.
+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.
 
 ### PreToolUse: Bash Redirect + Dangerous Blocker
 
-Intercepts simple Bash commands (`cat`, `head`, `tail`, `tree`, `find`, `stat`, `wc -l`, `grep`, `rg`, `sed -i`, etc.) and redirects covered cases to hex-line tools. `ls`/`dir` are redirected only for recursive listing. 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 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.
 
 ### PostToolUse: RTK Output Filter
 
@@ -477,7 +483,7 @@ The PostToolUse hook normalizes Bash output (replaces UUIDs, timestamps, IPs wit
 <details>
 <summary><b>Can I disable the built-in tool blocking?</b></summary>
 
-Yes. To downgrade redirects to advice, set `.hex-skills/environment_state.json` to `{ "hooks": { "mode": "advisory" } }`. To remove the hook entirely, delete the `hex-line` hook entries from `~/.claude/settings.json`. To disable the MCP server for one project, add `hex-line` to `~/.claude.json -> projects.{cwd}.disabledMcpServers`.
+Yes. The supported runtime bypass is `.hex-skills/environment_state.json` -> `{ "hooks": { "mode": "advisory" } }`, which downgrades project text redirects to advice. To remove the hook entirely, delete the `hex-line` hook entries from `~/.claude/settings.json`. To disable the MCP server for one project, add `hex-line` to `~/.claude.json -> projects.{cwd}.disabledMcpServers`.
 
 </details>
 

package/dist/hook.mjs

@@ -55,11 +55,10 @@ function normalizeOutput(text, opts = {}) {
 
 // hook.mjs
 import { readFileSync, writeSync } from "node:fs";
-import { resolve as resolve2 } from "node:path";
+import { resolve } from "node:path";
 import { homedir } from "node:os";
 
 // lib/hook-policy.mjs
-import { resolve } from "node:path";
 var BINARY_EXT = /* @__PURE__ */ new Set([
   ".png",
   ".jpg",
@@ -109,7 +108,7 @@ var REVERSE_TOOL_HINTS = {
   "mcp__hex-line__edit_file": "Edit (old_string, new_string, replace_all)",
   "mcp__hex-line__write_file": "Write (file_path, content)",
   "mcp__hex-line__grep_search": "Grep (pattern, path)",
-  "mcp__hex-line__inspect_path": "Path info / tree / Bash(ls,stat)",
+  "mcp__hex-line__inspect_path": "Glob (pattern, path) / Path info / tree / Bash(ls,stat)",
   "mcp__hex-line__outline": "Read with offset/limit",
   "mcp__hex-line__verify": "Read (check checksum/revision freshness before follow-up edits)",
   "mcp__hex-line__changes": "Bash(git diff)",
@@ -120,12 +119,13 @@ var TOOL_HINTS = {
   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)",
+  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/find/tree). E.g. pattern='*-mcp' type='dir'",
-  stat: "mcp__hex-line__inspect_path for compact file metadata (not stat/wc/file)",
-  grep: "mcp__hex-line__grep_search (not grep/rg). Params: output, literal, context_before, context_after, multiline",
+  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",
   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)",
@@ -135,23 +135,25 @@ var TOOL_HINTS = {
 };
 var DEFERRED_HINT = "If schemas not loaded: ToolSearch('+hex-line read edit')";
 var BASH_REDIRECTS = [
-  { regex: /^cat\s+\S+/, key: "cat" },
-  { regex: /^head\s+/, key: "head" },
-  { regex: /^tail\s+(?!-[fF])/, key: "tail" },
-  { regex: /^(less|more)\s+/, key: "cat" },
-  { regex: /^ls\s+-\S*R(\s|$)/, key: "ls" },
-  { regex: /^dir\s+\/[sS](\s|$)/, key: "ls" },
-  { regex: /^tree\s+/, key: "ls" },
-  { regex: /^find\s+/, key: "ls" },
-  { regex: /^(stat|wc)\s+/, key: "stat" },
-  { regex: /^(grep|rg)\s+/, key: "grep" },
-  { regex: /^sed\s+-i/, key: "sed" }
+  { regex: /^(cat|type)\b/i, key: "cat", kind: "reader" },
+  { regex: /^head\b/i, key: "head", kind: "reader" },
+  { regex: /^tail\b(?!.*\s-[fF](\s|$))(?!.*\s--follow(\s|$))/i, key: "tail", kind: "reader" },
+  { regex: /^(less|more)\b/i, key: "cat", kind: "reader" },
+  { regex: /^(Get-Content|gc)\b/i, key: "cat", kind: "reader" },
+  { regex: /^(ls|dir|tree|find)\b/i, key: "ls", kind: "list" },
+  { regex: /^(Get-ChildItem|gci)\b/i, key: "ls", kind: "list" },
+  { regex: /^(stat|wc)\b/i, key: "stat", kind: "meta" },
+  { regex: /^(Get-Item|gi)\b/i, key: "stat", kind: "meta" },
+  { regex: /^(grep|rg|findstr)\b/i, key: "grep", kind: "search" },
+  { regex: /^Select-String\b/i, key: "grep", kind: "search" },
+  { regex: /^sed\b.*\s-i(\s|$)/i, key: "sed", kind: "edit" }
 ];
 var TOOL_REDIRECT_MAP = {
   Read: "Read",
   Edit: "Edit",
   Write: "Write",
-  Grep: "Grep"
+  Grep: "Grep",
+  Glob: "Glob"
 };
 var DANGEROUS_PATTERNS = [
   { regex: /rm\s+(-[rf]+\s+)*[/~]/, reason: "rm -rf on root/home directory" },
@@ -175,15 +177,16 @@ var HOOK_OUTPUT_POLICY = {
   headLines: 15,
   tailLines: 15
 };
-function buildAllowedClaudeSettingsPaths(cwd, home) {
-  const cwdNorm = cwd.replace(/\\/g, "/");
-  const homeNorm = home.replace(/\\/g, "/");
-  return [
-    resolve(cwdNorm, ".claude/settings.json"),
-    resolve(cwdNorm, ".claude/settings.local.json"),
-    resolve(homeNorm, ".claude/settings.json"),
-    resolve(homeNorm, ".claude/settings.local.json")
-  ].map((entry) => entry.replace(/\\/g, "/").toLowerCase());
+function normalizePolicyPath(filePath) {
+  if (!filePath) return "";
+  let normalized = filePath.replace(/\\/g, "/");
+  if (normalized.length > 1 && normalized.endsWith("/")) normalized = normalized.slice(0, -1);
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function isWithinDir(candidatePath, dirPath) {
+  const candidate = normalizePolicyPath(candidatePath);
+  const dir = normalizePolicyPath(dirPath);
+  return !!candidate && !!dir && (candidate === dir || candidate.startsWith(`${dir}/`));
 }
 
 // hook.mjs
@@ -195,10 +198,140 @@ function extOf(filePath) {
 function getFilePath(toolInput) {
   return toolInput.file_path || toolInput.path || "";
 }
+function getGlobScopePath(toolInput) {
+  if (toolInput.path) return toolInput.path;
+  const pattern = typeof toolInput.pattern === "string" ? toolInput.pattern : "";
+  if (!pattern) return "";
+  const prefix = pattern.split(/[*?[{\]]/, 1)[0];
+  return prefix.replace(/[\\/]+$/, "");
+}
 function resolveToolPath(filePath) {
   if (!filePath) return "";
-  if (filePath.startsWith("~/")) return resolve2(homedir(), filePath.slice(2));
-  return resolve2(process.cwd(), filePath);
+  if (filePath.startsWith("~/")) return resolve(homedir(), filePath.slice(2));
+  return resolve(process.cwd(), filePath);
+}
+function stripMatchingQuotes(token) {
+  if (!token || token.length < 2) return token;
+  const first = token[0];
+  const last = token[token.length - 1];
+  return first === last && (first === '"' || first === "'" || first === "`") ? token.slice(1, -1) : token;
+}
+function tokenizeCommand(segment) {
+  return (segment.match(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`|\S+/g) || []).map(stripMatchingQuotes);
+}
+function splitCompoundCommand(command) {
+  return command.split(/\s*(?:\|\||&&|[|;]|>>?)\s*/).map((part) => part.trim()).filter(Boolean);
+}
+function readNamedOptionValues(tokens, optionNames) {
+  const values = [];
+  const names = new Set(optionNames.map((name) => name.toLowerCase()));
+  for (let i = 1; i < tokens.length; i++) {
+    const token = tokens[i];
+    const lower = token.toLowerCase();
+    let matched = false;
+    for (const name of names) {
+      if (lower === name) {
+        if (tokens[i + 1]) {
+          values.push(tokens[i + 1]);
+        }
+        matched = true;
+        break;
+      }
+      if (lower.startsWith(`${name}=`) || lower.startsWith(`${name}:`)) {
+        values.push(token.slice(name.length + 1));
+        matched = true;
+        break;
+      }
+    }
+    if (matched) continue;
+  }
+  return { values };
+}
+function collectPositionals(tokens, { optionValueFlags = [], slashOptions = false } = {}) {
+  const values = [];
+  const expectsValue = new Set(optionValueFlags.map((flag) => flag.toLowerCase()));
+  for (let i = 1; i < tokens.length; i++) {
+    const token = tokens[i];
+    const lower = token.toLowerCase();
+    if (expectsValue.has(lower)) {
+      i += 1;
+      continue;
+    }
+    if (lower.startsWith("-")) continue;
+    if (slashOptions && lower.startsWith("/")) continue;
+    values.push(token);
+  }
+  return values;
+}
+function resolveCandidatePaths(pathTokens) {
+  return pathTokens.map(resolveToolPath).filter(Boolean).map(normalizePolicyPath);
+}
+function isProjectScopedPath(filePath) {
+  return !!filePath && isWithinDir(resolveToolPath(filePath), process.cwd());
+}
+function getBashPathCandidates(spec, tokens, isFirstSegment) {
+  const command = (tokens[0] || "").toLowerCase();
+  const powershellPaths = readNamedOptionValues(tokens, ["-path", "-literalpath"]);
+  const positional = (flags = [], slashOptions = false) => collectPositionals(tokens, { optionValueFlags: flags, slashOptions });
+  if (spec.kind === "reader") {
+    if (powershellPaths.values.length > 0) return powershellPaths.values;
+    if (command === "head" || command === "tail") {
+      return positional(["-n", "-c", "--lines", "--bytes"]).slice(-1);
+    }
+    return positional();
+  }
+  if (spec.kind === "list") {
+    if (powershellPaths.values.length > 0) return powershellPaths.values;
+    if (command === "find") return positional().slice(0, 1);
+    if (command === "dir") return positional([], true);
+    return positional();
+  }
+  if (spec.kind === "meta") {
+    if (powershellPaths.values.length > 0) return powershellPaths.values;
+    if (command === "wc") return positional(["-l", "-w", "-c", "-m", "-L"]).slice(0);
+    return positional();
+  }
+  if (spec.kind === "edit") {
+    const args = positional(["-e", "-f"]);
+    const hasScriptOption = tokens.some((token) => {
+      const lower = token.toLowerCase();
+      return lower === "-e" || lower === "-f";
+    });
+    return hasScriptOption ? args : args.slice(1);
+  }
+  if (spec.kind === "search") {
+    if (powershellPaths.values.length > 0) return powershellPaths.values;
+    const args = command === "findstr" ? positional(["/c"], true) : positional(["-e", "-f", "-g", "--glob", "-t", "--type", "--type-not", "-A", "-B", "-C", "-m"]);
+    const hasExplicitPatternOption = command === "findstr" ? tokens.some((token) => {
+      const lower = token.toLowerCase();
+      return lower === "/c" || lower.startsWith("/c:");
+    }) : tokens.some((token) => {
+      const lower = token.toLowerCase();
+      return lower === "-e" || lower === "-f";
+    });
+    const pathArgs = hasExplicitPatternOption ? args : args.slice(1);
+    if (pathArgs.length > 0) return pathArgs;
+    return isFirstSegment ? [process.cwd()] : [];
+  }
+  return [];
+}
+function getBashRedirect(segment, isFirstSegment) {
+  const tokens = tokenizeCommand(segment);
+  if (tokens.length === 0) return null;
+  const spec = BASH_REDIRECTS.find((entry) => entry.regex.test(segment));
+  if (!spec) return null;
+  const targets = resolveCandidatePaths(getBashPathCandidates(spec, tokens, isFirstSegment));
+  if (targets.length > 0 && !targets.some((target) => isWithinDir(target, process.cwd()))) {
+    return null;
+  }
+  if (targets.length === 0 && spec.kind !== "list" && !(spec.kind === "search" && isFirstSegment)) {
+    return null;
+  }
+  const hint = TOOL_HINTS[spec.key];
+  return {
+    hint,
+    toolName: hint.split(" (")[0]
+  };
 }
 function isPartialRead(toolInput) {
   return [toolInput.offset, toolInput.limit, toolInput.start_line, toolInput.end_line, toolInput.ranges].some((value) => value !== void 0 && value !== null && value !== "");
@@ -224,7 +357,7 @@ function isHexLineDisabled(configPath) {
   if (_hexLineDisabled !== null) return _hexLineDisabled;
   _hexLineDisabled = false;
   try {
-    const p = configPath || resolve2(homedir(), ".claude.json");
+    const p = configPath || resolve(homedir(), ".claude.json");
     const claudeJson = JSON.parse(readFileSync(p, "utf-8"));
     const projects = claudeJson.projects;
     if (!projects || typeof projects !== "object") return _hexLineDisabled;
@@ -250,7 +383,7 @@ function getHookMode() {
   if (_hookMode !== void 0) return _hookMode;
   _hookMode = "blocking";
   try {
-    const stateFile = resolve2(process.cwd(), ".hex-skills/environment_state.json");
+    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";
   } catch {
@@ -270,7 +403,9 @@ function block(reason, context) {
 ${context}` : reason;
   const output = {
     hookSpecificOutput: {
-      permissionDecision: "deny"
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason
     },
     systemMessage: msg
   };
@@ -280,7 +415,9 @@ ${context}` : reason;
 function advise(reason, context) {
   const output = {
     hookSpecificOutput: {
-      permissionDecision: "allow"
+      hookEventName: "PreToolUse",
+      permissionDecision: "allow",
+      permissionDecisionReason: reason
     },
     systemMessage: context ? `${reason}
 ${context}` : reason
@@ -302,27 +439,23 @@ function handlePreToolUse(data) {
   }
   const hintKey = TOOL_REDIRECT_MAP[toolName];
   if (hintKey) {
-    const filePath = getFilePath(toolInput);
+    const filePath = toolName === "Glob" ? getGlobScopePath(toolInput) : getFilePath(toolInput);
     if (BINARY_EXT.has(extOf(filePath))) {
       process.exit(0);
     }
-    const resolvedNorm = resolveToolPath(filePath).replace(/\\/g, "/");
-    const claudeAllow = buildAllowedClaudeSettingsPaths(process.cwd(), homedir());
-    if (claudeAllow.includes(resolvedNorm.toLowerCase())) {
+    const projectScoped = filePath ? isProjectScopedPath(filePath) : toolName === "Grep" || toolName === "Glob";
+    if (!projectScoped) {
       process.exit(0);
     }
-    if (resolvedNorm.includes("/.claude/")) {
-      redirect("Protected .claude/ path. Use built-in tools for .claude/ config files.");
-    }
     if (toolName === "Read") {
       const ext = filePath ? extOf(filePath) : "";
       const rangeHint = isPartialRead(toolInput) ? " Preserve the same offset/limit or ranges in read_file." : "";
       const outlineHint = filePath && OUTLINEABLE_EXT.has(ext) ? `Use mcp__hex-line__outline(path="${filePath}") for structure, then mcp__hex-line__read_file(path="${filePath}") with ranges to read only what you need.${rangeHint}` : filePath ? `Use mcp__hex-line__read_file(path="${filePath}") with ranges or offset/limit.${rangeHint}` : "Use mcp__hex-line__inspect_path or mcp__hex-line__read_file";
-      redirect(outlineHint, "Use hex-line for text-file reads to keep hashes, revision metadata, and graph hints in one flow.\n" + DEFERRED_HINT);
+      redirect(outlineHint, "Use hex-line for project text-file reads to keep hashes, revision metadata, and graph hints in one flow.\n" + DEFERRED_HINT);
     }
     if (toolName === "Edit") {
       const target = filePath ? `Use mcp__hex-line__grep_search or mcp__hex-line__read_file, then mcp__hex-line__edit_file with path="${filePath}"` : "Use mcp__hex-line__grep_search or mcp__hex-line__read_file, then mcp__hex-line__edit_file";
-      redirect(target, "Use hash-verified edits for text files. Locate anchors/checksums first, then call edit_file once with batched edits.\n" + DEFERRED_HINT);
+      redirect(target, "Use hash-verified edits for project text files. Locate anchors/checksums first, then call edit_file once with batched edits.\n" + DEFERRED_HINT);
     }
     if (toolName === "Write") {
       const pathNote = filePath ? ` with path="${filePath}"` : "";
@@ -332,6 +465,15 @@ function handlePreToolUse(data) {
       const pathNote = filePath ? ` with path="${filePath}"` : "";
       redirect(`Use mcp__hex-line__grep_search${pathNote}`, TOOL_HINTS.Grep + "\n" + DEFERRED_HINT);
     }
+    if (toolName === "Glob") {
+      const pattern = typeof toolInput.pattern === "string" ? toolInput.pattern : "";
+      const inspectPath = JSON.stringify(filePath || process.cwd());
+      const inspectPattern = pattern ? JSON.stringify(pattern) : '"..."';
+      redirect(
+        `Use mcp__hex-line__inspect_path(path=${inspectPath}, pattern=${inspectPattern})`,
+        "Use inspect_path(pattern=...) for project file discovery and name/path globbing. grep_search(glob=...) remains available when you also need content search.\n" + DEFERRED_HINT
+      );
+    }
   }
   if (toolName === "Bash") {
     const command = (toolInput.command || "").trim();
@@ -348,24 +490,20 @@ function handlePreToolUse(data) {
       }
     }
     if (COMPOUND_OPERATORS.test(command)) {
-      const firstCmd = command.split(/\s*[|;&>]\s*/)[0].trim();
-      for (const { regex, key } of BASH_REDIRECTS) {
-        if (regex.test(firstCmd)) {
-          const hint = TOOL_HINTS[key];
-          const toolName2 = hint.split(" (")[0];
-          redirect(`Use ${toolName2} instead of piped command`, hint);
+      const segments = splitCompoundCommand(command);
+      for (const [index, segment] of segments.entries()) {
+        const redirectInfo2 = getBashRedirect(segment, index === 0);
+        if (redirectInfo2) {
+          redirect(`Use ${redirectInfo2.toolName} instead of project file inspection pipeline`, redirectInfo2.hint);
         }
       }
       process.exit(0);
     }
-    for (const { regex, key } of BASH_REDIRECTS) {
-      if (regex.test(command)) {
-        const hint = TOOL_HINTS[key];
-        const toolName2 = hint.split(" (")[0];
-        const args = command.split(/\s+/).slice(1).join(" ");
-        const argsNote = args ? ` \u2014 args: "${args}"` : "";
-        redirect(`Use ${toolName2}${argsNote}`, hint);
-      }
+    const redirectInfo = getBashRedirect(command, true);
+    if (redirectInfo) {
+      const args = command.split(/\s+/).slice(1).join(" ");
+      const argsNote = args ? ` \u2014 args: "${args}"` : "";
+      redirect(`Use ${redirectInfo.toolName}${argsNote}`, redirectInfo.hint);
     }
   }
   process.exit(0);
@@ -423,9 +561,9 @@ function handlePostToolUse(data) {
 }
 function handleSessionStart() {
   const settingsFiles = [
-    resolve2(process.cwd(), ".claude/settings.local.json"),
-    resolve2(process.cwd(), ".claude/settings.json"),
-    resolve2(homedir(), ".claude/settings.json")
+    resolve(process.cwd(), ".claude/settings.local.json"),
+    resolve(process.cwd(), ".claude/settings.json"),
+    resolve(homedir(), ".claude/settings.json")
   ];
   let styleActive = false;
   for (const f of settingsFiles) {
@@ -439,7 +577,7 @@ function handleSessionStart() {
     } catch {
     }
   }
-  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, Glob, .claude/settings.json, and .claude/settings.local.json.</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  </tips>\n  <exceptions>Built-in tools stay OK for images, PDFs, notebooks, Glob, .claude/settings.json, and .claude/settings.local.json.</exceptions>\n</hex-line_instructions>";
+  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);
 }
 var _norm = (p) => p.replace(/\\/g, "/");

package/dist/server.mjs

@@ -1272,6 +1272,7 @@ function serializeDiagnosticBlock(block) {
   if (block.requestedStartLine !== null && block.requestedEndLine !== null) {
     lines.push(`requested_span: ${block.requestedStartLine}-${block.requestedEndLine}`);
   }
+  lines.push(...renderMetaLines(block.meta));
   lines.push(`message: ${block.message}`);
   return lines.join("\n");
 }
@@ -2161,7 +2162,6 @@ function collectBatchConflicts({
   changedRanges,
   conflictPolicy,
   currentSnapshot,
-  filePath,
   hasBaseSnapshot,
   opts,
   staleRevision
@@ -2717,7 +2717,6 @@ ${snip.text}`;
     changedRanges,
     conflictPolicy,
     currentSnapshot,
-    filePath,
     hasBaseSnapshot,
     opts,
     staleRevision
@@ -2924,6 +2923,8 @@ try {
 var DEFAULT_LIMIT2 = 100;
 var DEFAULT_TOTAL_LIMIT_CONTENT = 200;
 var DEFAULT_TOTAL_LIMIT_LIST = 1e3;
+var DEFAULT_CONTENT_BLOCK_LIMIT = 12;
+var DEFAULT_CONTENT_OUTPUT_CHARS = 12e3;
 var MAX_OUTPUT = 10 * 1024 * 1024;
 var TIMEOUT2 = 3e4;
 var MAX_SEARCH_OUTPUT_CHARS = 8e4;
@@ -2964,15 +2965,16 @@ function spawnRg(args) {
 function grepSearch(pattern, opts = {}) {
   const normPath = normalizePath(opts.path || "");
   const target = normPath ? resolve2(normPath) : process.cwd();
-  const output = opts.output || "content";
+  const output = opts.output || "summary";
   const plain = !!opts.plain;
   const editReady = !!opts.editReady;
+  const allowLargeOutput = !!opts.allowLargeOutput;
   const defaultTotalLimit = output === "content" ? DEFAULT_TOTAL_LIMIT_CONTENT : DEFAULT_TOTAL_LIMIT_LIST;
   const totalLimit = opts.totalLimit === 0 ? 0 : opts.totalLimit && opts.totalLimit > 0 ? opts.totalLimit : defaultTotalLimit;
   if (output === "summary") return summaryMode(pattern, target, opts, totalLimit);
   if (output === "files") return filesMode(pattern, target, opts, totalLimit);
   if (output === "count") return countMode(pattern, target, opts, totalLimit);
-  return contentMode(pattern, target, opts, plain, editReady, totalLimit);
+  return contentMode(pattern, target, opts, plain, editReady, totalLimit, allowLargeOutput);
 }
 function applyListModeTotalLimit(lines, totalLimit) {
   if (!totalLimit || totalLimit <= 0 || lines.length <= totalLimit) return lines.join("\n");
@@ -3054,10 +3056,24 @@ async function summaryMode(pattern, target, opts, totalLimit) {
   }
   return lines.join("\n");
 }
-async function contentMode(pattern, target, opts, plain, editReady, totalLimit) {
+function buildSearchRefineCall(target, pattern, opts) {
+  const args = { path: String(target).replace(/\\/g, "/"), pattern };
+  if (opts.glob) args.glob = opts.glob;
+  if (opts.type) args.type = opts.type;
+  return JSON.stringify({
+    tool: "mcp__hex_line__grep_search",
+    arguments: {
+      ...args,
+      output: "summary"
+    }
+  });
+}
+async function contentMode(pattern, target, opts, plain, editReady, totalLimit, allowLargeOutput) {
   const realArgs = ["--json"];
   const plainOutput = plain || !editReady;
   const shouldUseGraph = editReady && !plain;
+  const contentBlockLimit = allowLargeOutput ? Number.POSITIVE_INFINITY : DEFAULT_CONTENT_BLOCK_LIMIT;
+  const outputCharBudget = allowLargeOutput ? MAX_SEARCH_OUTPUT_CHARS : DEFAULT_CONTENT_OUTPUT_CHARS;
   if (opts.caseInsensitive) realArgs.push("-i");
   else if (opts.smartCase) realArgs.push("-S");
   if (opts.literal) realArgs.push("-F");
@@ -3079,6 +3095,7 @@ async function contentMode(pattern, target, opts, plain, editReady, totalLimit)
   const db = shouldUseGraph ? getGraphDB(target) : null;
   const relCache = /* @__PURE__ */ new Map();
   let annotationBudget = GRAPH_MATCH_ANNOTATION_BUDGET;
+  const matchedFiles = /* @__PURE__ */ new Set();
   let groupFile = null;
   let groupEntries = [];
   let matchCount = 0;
@@ -3123,6 +3140,7 @@ async function contentMode(pattern, target, opts, plain, editReady, totalLimit)
     const filePath = (data.path?.text || "").replace(/\\/g, "/");
     const lineNum = data.line_number;
     if (!lineNum) continue;
+    if (msg.type === "match") matchedFiles.add(filePath);
     let content = data.lines?.text;
     if (content === void 0 && data.lines?.bytes) {
       content = Buffer.from(data.lines.bytes, "base64").toString("utf-8");
@@ -3172,6 +3190,15 @@ async function contentMode(pattern, target, opts, plain, editReady, totalLimit)
         flushGroup();
         blocks.push(buildDiagnosticBlock({
           kind: "total_limit",
+          meta: {
+            total_matches: matchCount,
+            shown_matches: matchCount,
+            file_count: matchedFiles.size,
+            shown_count: blocks.filter((block) => block.type === "edit_ready_block").length,
+            truncated: true,
+            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.`,
           path: String(target).replace(/\\/g, "/")
         }));
@@ -3181,10 +3208,18 @@ async function contentMode(pattern, target, opts, plain, editReady, totalLimit)
   }
   flushGroup();
   if (db) blocks.sort((a, b) => (b.meta.graphScore || 0) - (a.meta.graphScore || 0));
+  const searchBlocks = blocks.filter((block) => block.type === "edit_ready_block");
+  const totalSearchBlocks = searchBlocks.length;
   const parts = [];
-  let budget = MAX_SEARCH_OUTPUT_CHARS;
+  let budget = outputCharBudget;
   let capped = false;
+  let shownBlocks = 0;
+  let shownMatches = 0;
   for (const block of blocks) {
+    if (block.type === "edit_ready_block" && shownBlocks >= contentBlockLimit) {
+      capped = true;
+      break;
+    }
     const serialized = block.type === "edit_ready_block" ? serializeSearchBlock(block, { plain: plainOutput }) : serializeDiagnosticBlock(block);
     if (parts.length > 0 && budget - serialized.length < 0) {
       capped = true;
@@ -3192,12 +3227,26 @@ async function contentMode(pattern, target, opts, plain, editReady, totalLimit)
     }
     parts.push(serialized);
     budget -= serialized.length;
+    if (block.type === "edit_ready_block") {
+      shownBlocks++;
+      shownMatches += Array.isArray(block.meta.matchLines) ? block.meta.matchLines.length : 0;
+    }
   }
   if (capped) {
-    const remaining = blocks.length - parts.length;
+    const remaining = Math.max(0, totalSearchBlocks - shownBlocks);
     parts.push(serializeDiagnosticBlock(buildDiagnosticBlock({
       kind: "output_capped",
-      message: `OUTPUT_CAPPED: ${remaining} more search block(s) omitted (${MAX_SEARCH_OUTPUT_CHARS} char limit). Narrow with path= or glob= filters.`
+      path: String(target).replace(/\\/g, "/"),
+      meta: {
+        total_matches: matchCount,
+        shown_matches: shownMatches,
+        file_count: matchedFiles.size,
+        shown_count: shownBlocks,
+        truncated: true,
+        next_action: "narrow_search_scope",
+        suggested_refine_call: buildSearchRefineCall(target, pattern, opts)
+      },
+      message: `OUTPUT_CAPPED: ${remaining} more search block(s) omitted (${outputCharBudget} char limit${allowLargeOutput ? "" : `, ${DEFAULT_CONTENT_BLOCK_LIMIT} block default`}). Narrow with path= or glob= filters or pass allow_large_output=true when you intentionally need a larger payload.`
     })));
   }
   return parts.join("\n\n");
@@ -3657,10 +3706,30 @@ function isIgnored(ig, relPath, isDir) {
   if (!ig) return false;
   return ig.ignores(isDir ? relPath + "/" : relPath);
 }
+function topPatternGroups(matches) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const entry of matches) {
+    const trimmed = entry.endsWith("/") ? entry.slice(0, -1) : entry;
+    const [head] = trimmed.split("/");
+    const key = trimmed.includes("/") ? head : ".";
+    groups.set(key, (groups.get(key) || 0) + 1);
+  }
+  return [...groups.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 4);
+}
+function buildPatternRefineCall(absRoot, pattern, type, groups) {
+  const bestGroup = groups.find(([key]) => key !== ".")?.[0];
+  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",
+    arguments: args
+  });
+}
 function findByPattern(dirPath, opts) {
   const re = globToRegex(opts.pattern);
   const filterType = opts.type || "all";
   const maxDepth = opts.max_depth ?? 20;
+  const maxEntries = opts.max_entries === 0 ? 0 : Math.max(1, Number(opts.max_entries ?? 60));
   const abs = resolve4(normalizePath(dirPath));
   if (!existsSync5(abs)) throw new Error(`DIRECTORY_NOT_FOUND: ${abs}`);
   if (!statSync7(abs).isDirectory()) throw new Error(`Not a directory: ${abs}`);
@@ -3694,9 +3763,25 @@ function findByPattern(dirPath, opts) {
   if (matches.length === 0) {
     return `No matches for "${opts.pattern}" in ${rootName}/`;
   }
-  return `Found ${matches.length} match${matches.length === 1 ? "" : "es"} for "${opts.pattern}" in ${rootName}/
-
-${matches.join("\n")}`;
+  const shown = maxEntries === 0 ? matches : matches.slice(0, maxEntries);
+  const truncated = shown.length < matches.length;
+  const groups = topPatternGroups(matches);
+  const lines = [
+    `Found ${matches.length} match${matches.length === 1 ? "" : "es"} for "${opts.pattern}" in ${rootName}/`,
+    `match_count: ${matches.length}`,
+    `shown_count: ${shown.length}`,
+    `truncated: ${truncated}`
+  ];
+  if (groups.length > 0) {
+    lines.push(`top_groups: ${groups.map(([group, count]) => `${group} (${count})`).join(", ")}`);
+  }
+  if (truncated) {
+    lines.push("next_action: narrow_path");
+    lines.push(`suggested_refine_call: ${buildPatternRefineCall(abs, opts.pattern, filterType, groups)}`);
+  }
+  lines.push("");
+  lines.push(...shown);
+  return lines.join("\n");
 }
 function directoryTree(dirPath, opts = {}) {
   if (opts.pattern) return findByPattern(dirPath, opts);
@@ -4638,7 +4723,7 @@ OUTPUT_CAPPED: Output exceeded ${MAX_BULK_OUTPUT_CHARS} chars.`;
 }
 
 // server.mjs
-var version = true ? "1.16.0" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.17.1" : (await null).createRequire(import.meta.url)("./package.json").version;
 var { server, StdioServerTransport } = await createServerRuntime({
   name: "hex-line-mcp",
   version
@@ -4801,7 +4886,8 @@ server.registerTool("grep_search", {
     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)"),
     plain: flexBool().describe("Omit hash tags, return file:line:content"),
-    edit_ready: flexBool().describe("Preserve hash/checksum search hunks in `content` mode. Default: false.")
+    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 }
 }, async (rawParams) => {
@@ -4821,7 +4907,8 @@ server.registerTool("grep_search", {
     limit,
     total_limit,
     plain,
-    edit_ready
+    edit_ready,
+    allow_large_output
   } = rawParams ?? {};
   try {
     const resolvedOutput = output ?? "summary";
@@ -4842,7 +4929,8 @@ server.registerTool("grep_search", {
       limit: resolvedLimit,
       totalLimit: resolvedTotalLimit,
       plain,
-      editReady: !!edit_ready
+      editReady: !!edit_ready,
+      allowLargeOutput: !!allow_large_output
     });
     return { content: [{ type: "text", text: result }] };
   } catch (e) {
@@ -4893,13 +4981,14 @@ server.registerTool("inspect_path", {
     pattern: z2.string().optional().describe('Glob filter on names (e.g. "*-mcp", "*.mjs"). Returns flat match list instead of tree'),
     type: z2.enum(["file", "dir", "all"]).optional().describe('"file", "dir", or "all" (default). Like find -type f/d'),
     max_depth: flexNum().describe("Max recursion depth (default: 2 for discovery, or 20 in pattern mode)"),
+    max_entries: flexNum().describe("Max entries to show in pattern mode before truncation metadata is returned (default: 60, 0 = unlimited)"),
     gitignore: flexBool().describe("Respect root .gitignore patterns (default: true). Nested .gitignore not supported"),
     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 }
 }, async (rawParams) => {
-  const { path: p, max_depth, gitignore, format, pattern, type: entryType, verbosity } = 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, {
@@ -4907,7 +4996,8 @@ server.registerTool("inspect_path", {
       gitignore,
       format: format ?? (resolvedVerbosity === "full" ? "full" : "compact"),
       pattern,
-      type: entryType
+      type: entryType,
+      max_entries
     }) }] };
   } catch (e) {
     return { content: [{ type: "text", text: e.message }], isError: true };

package/output-style.md

@@ -13,7 +13,8 @@ Prefer `hex-line` for text files you may inspect or modify. Hash-annotated reads
 | Read | `mcp__hex-line__read_file` | Hash-annotated, revision-aware |
 | Edit | `mcp__hex-line__edit_file` | Hash-verified anchors + conservative auto-rebase |
 | Write | `mcp__hex-line__write_file` | No prior Read needed |
-| Grep | `mcp__hex-line__grep_search` | Edit-ready matches |
+| Grep | `mcp__hex-line__grep_search` | Summary-first discovery with edit-ready escalation |
+| Glob | `mcp__hex-line__inspect_path` | Project file discovery and name/path globbing |
 | Text rename across files | `mcp__hex-line__bulk_replace` | Multi-file text rename/refactor inside an explicit root path |
 | Path/tree/stat Bash | `mcp__hex-line__inspect_path` | Compact path info and pattern search |
 | Large code read | `mcp__hex-line__outline` then `read_file` with ranges | Structure first, targeted reads |
@@ -26,7 +27,7 @@ Prefer `hex-line` for text files you may inspect or modify. Hash-annotated reads
 
 | Path | Flow |
 |------|------|
-| Surgical | `grep_search -> edit_file` |
+| Surgical | `grep_search(output="summary") -> grep_search(output="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` |
@@ -36,14 +37,14 @@ Prefer `hex-line` for text files you may inspect or modify. Hash-annotated reads
 - Auto-fill `path` instead of leaving scope implicit.
 - For file tools (`read_file`, `edit_file`, `outline`, `changes` on one file), use the target file path.
 - Read-only file tools may target explicit temp-file paths outside the repo when you intentionally inspect a scratch file.
-- For repo-wide tools (`bulk_replace`, directory `inspect_path`, broad `grep_search`), use the resolved project root or intended directory scope.
+- For repo-wide tools (`bulk_replace`, directory `inspect_path`, broad `grep_search`), use the resolved project root or intended directory scope, then narrow further before requesting rich output.
 - Mutating tools stay inside the current project root by default. Add `allow_external=true` only when you intentionally edit a temp or external path.
 - Treat missing or ambiguous scope as an error to fix, not as a reason to guess across repositories.
 
 ## Edit Discipline
 
-- Never invent `range_checksum`. Copy it from a fresh `read_file` or `grep_search(output:"content")` block.
-- First mutation in a file: use `grep_search` for narrow targets, or `outline -> read_file(ranges)` for structural edits.
+- 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.
 - 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.
@@ -53,11 +54,12 @@ 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.
 
 ## Exceptions
 
-- Built-in `Read`/`Edit`/`Write`/`Grep` are fallback only. Built-in OK for images, PDFs, notebooks, Glob, `.claude/settings.json`, and `.claude/settings.local.json`.
-- Bash is still fine for npm, node, git, docker, curl, pipes, and compound commands.
+- 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.
 
 ## hex-graph
 

package/package.json

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