@sdsrs/code-graph 0.143.0 → 0.145.0

package/README.md

@@ -528,6 +528,7 @@ defaults are what you get by doing nothing.
 | `CODE_GRAPH_NO_AUTO_UPDATE=1` | Never check GitHub for a new release. |
 | `CODE_GRAPH_NO_AUTO_ADOPT=1` | Do not write the steering block into a project's `CLAUDE.md` on SessionStart. |
 | `CODE_GRAPH_NO_TEMPLATE_REFRESH=1` | Keep hand edits to the generated steering block — it is otherwise refreshed to the current template. |
+| `CODE_GRAPH_NO_GITIGNORE=1` | Never touch `.gitignore` — not even to add the `.code-graph/` entry. |
 | `CODE_GRAPH_QUIET_HOOKS=1` | Hooks inject a one-line pointer instead of the full decision table. |
 | `CODE_GRAPH_VERBOSE_HOOKS=1` | The opposite: opt into the noisy form. |
 | `CODE_GRAPH_NO_BLOCK_GREP=1` | Never turn a `grep` hint into a block — prefix a single command with it to get past one. |

package/bin/cli.js

@@ -1,159 +1,20 @@
 #!/usr/bin/env node
-
-const { spawn } = require("child_process");
-const path = require("path");
-
-// Tell find-binary.js our package root so it can locate bundled binaries
-// and detect dev mode from bin/ → repo root (one level up)
-process.env._FIND_BINARY_ROOT = path.resolve(__dirname, "..");
-
-// Intercept adopt / unadopt before forwarding — they're node-only concerns
-// (write <cwd>/CLAUDE.md + <cwd>/.claude/) and have no Rust counterpart.
-// Lets `code-graph-mcp adopt` / `unadopt` work uniformly across plugin / npm / npx.
-const sub = process.argv[2];
-
-// Reject unknown flags on the intercepted subcommands BEFORE doing their work.
-// `--help` was already guarded, but every OTHER token was ignored, so
-// `code-graph-mcp adopt --helpp` ran adopt and wrote the user's CLAUDE.md — a
-// typo away from the very side effect the --help guard exists to prevent. This
-// is the fourth entry point onto the same "ignore what you don't recognise"
-// idiom (doctor.js, lifecycle.js doctor, src/main.rs were the first three); it
-// is the npm/npx surface, so it is the one most users reach.
-function rejectUnknownFlags(name, known) {
-  const unknown = process.argv.slice(3).filter((a) => !known.has(a));
-  if (unknown.length) {
-    process.stderr.write(
-      `code-graph-mcp ${name}: unknown argument(s): ${unknown.join(" ")}\n` +
-      `Run \`code-graph-mcp ${name} --help\` for usage.\n`);
-    process.exit(2);
-  }
-}
-if (sub === "adopt" || sub === "unadopt") {
-  // `--help`/`-h` must be side-effect-free: adopt() writes the memory file +
-  // MEMORY.md sentinel, unadopt() removes them. The Rust binary guards this for
-  // direct invocation, but npm/npx routes through this wrapper, which intercepts
-  // adopt/unadopt *before* the binary — so the guard must be repeated here, or
-  // `code-graph-mcp adopt --help` rewrites MEMORY.md (the common new-user path).
-  if (process.argv.slice(3).some((a) => a === "--help" || a === "-h")) {
-    process.stdout.write(sub === "adopt"
-      // Kept in sync with src/main.rs's adopt/unadopt help. This text described
-      // the pre-v0.74 scheme (a sentinel in the ~/.claude memory dir) for three
-      // releases after the target moved to the project's own CLAUDE.md, so npm
-      // users were told this command edits a file it has not touched since.
-      ? "code-graph-mcp adopt — install the code-graph steering block into the project CLAUDE.md\n\n" +
-        "USAGE:\n    code-graph-mcp adopt\n\n" +
-        "Writes a sentinel-wrapped managed block into <cwd>/CLAUDE.md plus a\n" +
-        "<cwd>/.claude/plugin_code_graph_mcp.md detail doc, so Claude Code loads the\n" +
-        "decision table each session. Run `code-graph-mcp unadopt` to remove it.\n"
-      : "code-graph-mcp unadopt — remove the code-graph steering block\n\n" +
-        "USAGE:\n    code-graph-mcp unadopt\n\n" +
-        "Reverses `code-graph-mcp adopt`: strips the managed block from\n" +
-        "<cwd>/CLAUDE.md and deletes <cwd>/.claude/plugin_code_graph_mcp.md.\n" +
-        "User content outside the sentinel is kept.\n");
-    process.exit(0);
-  }
-  rejectUnknownFlags(sub, new Set(["--help", "-h"]));
-  const { adopt, unadopt, formatResult } = require("../claude-plugin/scripts/adopt");
-  const result = sub === "unadopt" ? unadopt() : adopt();
-  process.stdout.write(formatResult(sub, result) + "\n");
-  process.exit(result.ok === false ? 1 : 0);
-}
-
-// Intercept `uninstall` — full local teardown (restore prior statusline, strip
-// code-graph hooks from settings.json, delete ~/.cache/code-graph, and unadopt the
-// CURRENT project). Node-only; no Rust counterpart. CC's `/plugin uninstall` fires
-// no uninstall hook, so this is the user's one-shot CLI teardown. Guard `--help`
-// before the destructive work (same discipline as adopt/unadopt above).
-if (sub === "uninstall") {
-  if (process.argv.slice(3).some((a) => a === "--help" || a === "-h")) {
-    process.stdout.write(
-      "code-graph-mcp uninstall — remove code-graph config + cache from this machine\n\n" +
-      "USAGE:\n    code-graph-mcp uninstall [--unadopt-all] [--purge-global]\n\n" +
-      "Restores your prior statusline, strips code-graph hooks from settings.json,\n" +
-      "deletes ~/.cache/code-graph, and removes this project's CLAUDE.md adoption\n" +
-      "block. --unadopt-all also removes the managed block + detail file from every\n" +
-      "registered adopted project; --purge-global removes the globally-installed\n" +
-      "@sdsrs npm packages even without the plugin-install marker. Also run\n" +
-      "`/plugin uninstall code-graph-mcp` in Claude Code to sync its UI.\n");
-    process.exit(0);
-  }
-  rejectUnknownFlags("uninstall", new Set(["--help", "-h", "--unadopt-all", "--purge-global"]));
-  const lifecycle = require("../claude-plugin/scripts/lifecycle");
-  const { unadopt } = require("../claude-plugin/scripts/adopt");
-  const r = lifecycle.uninstall({
-    purgeGlobal: process.argv.slice(3).includes("--purge-global"),
-    unadoptAll: process.argv.slice(3).includes("--unadopt-all"),
-  });
-  let ua = { ok: false };
-  try { ua = unadopt(); } catch { /* best-effort — settings/cache already cleaned */ }
-  const projectUnadopted = !!(ua && (ua.blockPruned || ua.fileRemoved || ua.claudeMdRemoved));
-  let out =
-    `Uninstalled code-graph-mcp | settings cleaned=${r.settingsChanged}` +
-    ` | this project unadopted=${projectUnadopted}\n`;
-  if (r.globalPkgsRemoved.length) {
-    out += `  Removed global npm package(s): ${r.globalPkgsRemoved.join(", ")}\n`;
-  }
-  if (r.globalPkgsRemaining.length) {
-    out += `  Global npm package(s) still installed: ${r.globalPkgsRemaining.join(", ")}\n` +
-      `    Remove with: npm uninstall -g ${r.globalPkgsRemaining.join(" ")}` +
-      (r.pluginInstalledGlobals ? "\n" : "   (or re-run with --purge-global)\n");
-  }
-  if (r.unadopted.length) {
-    const cleaned = r.unadopted.filter((u) => u.cleaned).length;
-    out += `  Unadopted ${cleaned}/${r.unadopted.length} registered project(s) (--unadopt-all).\n`;
-  }
-  const otherAdopted = r.adoptedProjects.filter((p) => p !== process.cwd());
-  if (otherAdopted.length) {
-    out += "  Other adopted project(s) — re-run with --unadopt-all, or in each:" +
-      " `code-graph-mcp unadopt` + `rm -rf .code-graph`\n" +
-      otherAdopted.map((p) => `    ${p}\n`).join("");
-  }
-  out += "  Also run `/plugin uninstall code-graph-mcp` in Claude Code to sync its UI state.\n";
-  process.stdout.write(out);
-  process.exit(0);
-}
-
-const { findBinary, unsupportedPlatformHint } = require("../claude-plugin/scripts/find-binary");
-
-const binary = findBinary();
-
-if (!binary) {
-  const hint = unsupportedPlatformHint();
-  console.error(
-    "Error: code-graph-mcp binary not found.\n\n" +
-    (hint ? hint + "\n\n" : "") +
-    "To install:\n" +
-    "  npm install -g @sdsrs/code-graph\n\n" +
-    "To build from source:\n" +
-    "  cargo install code-graph-mcp --features embed-model\n"
-  );
-  process.exit(1);
-}
-
-// Spawn the binary, forwarding stdio for MCP JSON-RPC communication
-// windowsHide as a literal rather than via claude-plugin/scripts/proc-opts:
-// this file is the npm package's bin entry and ships in tarballs that may not
-// carry claude-plugin/. Same meaning — CREATE_NO_WINDOW, so a console-less
-// parent (the MCP client) does not flash a window; inherited stdio still works.
-const child = spawn(binary, process.argv.slice(2), {
-  stdio: "inherit",
-  env: process.env,
-  windowsHide: true,
-});
-
-child.on("error", (err) => {
-  console.error(`Failed to start code-graph-mcp: ${err.message}`);
-  // A glibc binary installed on musl (older npm ignores the `libc` field) is present
-  // but fails to exec — surface the actionable platform hint instead of a bare error.
-  const hint = unsupportedPlatformHint();
-  if (hint) console.error("\n" + hint);
-  process.exit(1);
-});
-
-child.on("exit", (code, signal) => {
-  if (signal) {
-    process.kill(process.pid, signal);
-  } else {
-    process.exit(code ?? 1);
-  }
+'use strict';
+/**
+ * The npm package's `code-graph-mcp` / `code-graph` bin entry.
+ *
+ * The dispatcher it used to hold now lives in claude-plugin/scripts/cli-entry.js,
+ * shared with the plugin's own launcher (claude-plugin/bin/code-graph-mcp) so
+ * the two PATH names cannot drift. `claude-plugin/` is in this package's `files`
+ * list and this entry already required from it, so nothing new is depended on
+ * here — a comment in the old body claimed some tarballs omit that directory,
+ * which was already false of the top-level `find-binary` require above it.
+ *
+ * `_FIND_BINARY_ROOT` is this package's root, one level up from bin/: it is what
+ * lets find-binary.js find a bundled `bin/<binary>` and detect a dev checkout.
+ */
+const path = require('path');
+
+require('../claude-plugin/scripts/cli-entry').main({
+  findBinaryRoot: path.resolve(__dirname, '..'),
 });

package/claude-plugin/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.143.0",
+  "version": "0.145.0",
   "keywords": [
     "code-graph",
     "ast",

package/claude-plugin/bin/code-graph-mcp

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * The plugin's `code-graph-mcp` on PATH.
+ *
+ * Claude Code adds `<plugin-root>/bin` to the Bash tool's PATH for every
+ * enabled plugin. This plugin shipped no such directory, so the PATH entry
+ * pointed at nothing and every steering surface that printed the bare name —
+ * the CLAUDE.md block's six rows, the MCP `instructions` field, the `unadopt`
+ * escape hatch — printed a command the user's shell answered with "command not
+ * found" (issue #41). A `/plugin install` downloads the native binary to
+ * `~/.cache/code-graph/bin/` and resolves it internally; nothing ever put a
+ * name in front of it.
+ *
+ * Deliberately a Node script and not a symlink to that cached binary: the
+ * binary is fetched at runtime, after this file is already on PATH, so a
+ * symlink would be dangling exactly when a new user first types the command.
+ * This can explain itself instead — and it reaches `adopt` / `unadopt` /
+ * `uninstall`, which are JS-dispatched and have no counterpart in the binary.
+ *
+ * No logic lives here. See scripts/cli-entry.js for why there is one dispatcher
+ * behind both PATH names, and for why this entry point passes no
+ * `findBinaryRoot`.
+ */
+require('../scripts/cli-entry').main();

package/claude-plugin/bin/code-graph-mcp.cmd

@@ -0,0 +1,11 @@
+@echo off
+REM Windows PATHEXT sibling of the extensionless launcher beside it: cmd.exe
+REM will not execute a file with no extension, so the same PATH entry that works
+REM on POSIX resolves nothing here without this shim. Runs the very same file
+REM through node rather than duplicating its three lines.
+node "%~dp0code-graph-mcp" %*
+REM Propagate the exit code explicitly. cmd.exe leaves %ERRORLEVEL% set after the
+REM last command, but a caller that runs this through `cmd /c` gets the SCRIPT's
+REM status, and relying on the implicit path is what makes a non-zero `doctor` or
+REM a failed search look like success to a wrapper.
+exit /b %ERRORLEVEL%

package/claude-plugin/scripts/cg-answer.js

@@ -97,6 +97,91 @@ function sanitizeSearchPath(searchPath) {
   return kept || undefined;
 }
 
+/**
+ * The same split, but keeping the half `sanitizeSearchPath` throws away.
+ *
+ * Widening `tests/*.mjs` to `tests` keeps rg from exiting 1, and for years that
+ * was the whole story — but the deny then PRINTS the widened command above an
+ * answer covering files the user excluded (field report 2026-09-08: a
+ * `tests/*.mjs` grep answered with 25+ hits from all of `tests/`). The glob has
+ * a faithful destination: `code-graph-mcp grep -g <glob>`, which matches
+ * basename-style across nested directories.
+ *
+ * `{scope, glob}`, either of which may be undefined: `tests/*.mjs` →
+ * `{scope:'tests', glob:'*.mjs'}`, `src/**` + `/*.rs` → `{scope:'src',
+ * glob:'**\/*.rs'}`, a leading glob (`*.py`) → `{scope:undefined,
+ * glob:'*.py'}` (repo-wide, filtered), no glob → `{scope:<path>}`.
+ */
+function splitSearchPathGlob(searchPath) {
+  if (!searchPath || typeof searchPath !== 'string') return {};
+  const segs = searchPath.split('/');
+  const i = segs.findIndex((s) => /[*?[\]{}]/.test(s));
+  if (i === -1) return { scope: searchPath };
+  const scope = segs.slice(0, i).join('/') || undefined;
+  const glob = segs.slice(i).join('/') || undefined;
+  return { scope, glob };
+}
+
+/**
+ * The argv for the grep answer — the ONE place the answer's shape is decided.
+ *
+ * Both the child process and the command string the deny prints are built from
+ * this array, because two renderings of one command are two things that drift:
+ * v0.142.0 shipped a fix for two printers of a single `unadopt` string that had
+ * done exactly that. Here the drift was live and user-visible in a different
+ * form — the printed command never carried the grep's flags at all, so a
+ * `grep -l` deny announced a file-list command and delivered hit lines.
+ *
+ * `flags` are already translated to cg spellings by the caller
+ * (pre-grep-guide.extractCgFlags). A `-g` among them came from `--include` and
+ * wins over one derived from the path: the user spelled that filter explicitly.
+ */
+function buildGrepArgs({ pattern, searchPath, flags = [] } = {}) {
+  const { scope, glob } = splitSearchPathGlob(searchPath);
+  const args = ['grep', ...flags, pattern];
+  if (scope) args.push(scope);
+  // `hasGlobFlag`, not `flags.includes('-g')`: `flags` is a flat argv fragment,
+  // so a VALUE can equal a flag name. `rg -t -g "sym" src/*.rs` yields
+  // `['-t','-g']` — `-g` there is the VALUE of `-t` — and the bare membership
+  // test dropped the path-derived glob, widening `src/*.rs` to `src`. That is
+  // the defect this function exists to fix, reintroduced one layer up (round 2
+  // of pre-ship review).
+  if (glob && !hasGlobFlag(flags)) args.push('-g', glob);
+  return args;
+}
+
+// True when `flags` carries a real `-g` (an explicit `--include`/`--glob`), as
+// opposed to the string `-g` sitting in a value position.
+function hasGlobFlag(flags) {
+  for (let i = 0; i < (flags || []).length; i++) {
+    if (flags[i] === '-g') return true;
+    if (flags[i] === '-t') i++;  // skip its value
+  }
+  return false;
+}
+
+// Render an argv as the command a human can paste. Single-quote anything that
+// would not survive a shell verbatim — the glob especially, which is the whole
+// point of passing it (`-g *.mjs` unquoted is expanded by the user's shell).
+// Characters that survive a shell verbatim. A glob does not, which is the whole
+// reason the argument is worth quoting: `-g *.mjs` unquoted is expanded by the
+// reader's own shell before cg ever sees it.
+const SHELL_SAFE_ARG = /^[A-Za-z0-9_.,:@%+=/-]+$/;
+// POSIX single-quote escape: close, emit an escaped quote, reopen.
+const SQ_ESCAPED = "'\\''";
+
+function formatCgCommand(args) {
+  // Deliberately no nested template literal, and no regex holding a quote.
+  // windows-hide.test.js masks literals with a character scanner that pairs
+  // backticks like any other quote, so a `${…`…`…}` inside a template closes the
+  // outer one early and swallows the rest of the file — which took all three of
+  // THIS file's spawn call sites out of that guard's view until it was written
+  // this way. Code a guard cannot parse is code the guard is not checking.
+  const shown = args.map((a) =>
+    (SHELL_SAFE_ARG.test(a) ? a : "'" + a.split("'").join(SQ_ESCAPED) + "'"));
+  return 'code-graph-mcp ' + shown.join(' ');
+}
+
 /**
  * The four runners below each spawned the binary and mapped the result by hand
  * — the same fifteen lines, four times (audit 2026-08-29 ARC-07). Hoisted into
@@ -206,6 +291,7 @@ function runGrepAnswer(opts = {}) {
     cwd,
     pattern,
     searchPath,
+    flags = [],
     timeoutMs = DEFAULT_TIMEOUT_MS,
     maxBytes = DEFAULT_MAX_BYTES,
   } = opts;
@@ -216,11 +302,10 @@ function runGrepAnswer(opts = {}) {
     const binary = resolveAnswerBinary(opts);
     if (!binary) return { status: 'no-binary' };
 
-    // Defensive re-sanitize: callers should pass a clean path, but a glob
-    // reaching argv is a guaranteed nonzero exit (see sanitizeSearchPath).
-    const scope = sanitizeSearchPath(searchPath);
-    const args = ['grep', pattern];
-    if (scope) args.push(scope);
+    // buildGrepArgs does the glob split itself, so a caller that passes a raw
+    // `dir/*.py` still cannot put a literal glob into argv (the guaranteed
+    // nonzero exit sanitizeSearchPath exists for) — it becomes scope + `-g`.
+    const args = buildGrepArgs({ pattern, searchPath, flags });
     const res = runCg(binary, args, { cwd, timeoutMs });
     // Older binaries exit 0 on no-match with NO_MATCH_PREFIX on stdout — that
     // shape resolves to 'no-hits' through isEmptyAnswer below.
@@ -411,6 +496,9 @@ function runCallgraphAnswer(opts = {}) {
 module.exports = {
   runGrepAnswer, runShowAnswer, runOverviewAnswer, runCallgraphAnswer,
   truncateAtLine, sanitizeSearchPath,
+  // The one argv builder + its renderer, so the deny copy and the child process
+  // cannot describe different commands.
+  splitSearchPathGlob, buildGrepArgs, formatCgCommand,
   // Exported so the integer property can be asserted where it is ESTABLISHED.
   // Asserting it end-to-end instead passes either way: `remainingMs` floors
   // again downstream, so such a test cannot fail and proves nothing (NEW-02).

package/claude-plugin/scripts/cli-entry.js

@@ -0,0 +1,205 @@
+'use strict';
+/**
+ * The dispatcher behind every `code-graph-mcp <subcommand>` a user can type.
+ *
+ * Two files put that name on a PATH: the npm package's bin entry
+ * (`bin/cli.js`, from `npm i -g @sdsrs/code-graph`) and this plugin's launcher
+ * (`claude-plugin/bin/code-graph-mcp`, which Claude Code puts on PATH for every
+ * enabled plugin). Both are three lines that call `main()` here.
+ *
+ * Why one module and not two entry points: v0.142.0 shipped a fix for two
+ * printers of the same `unadopt` string that had drifted apart, and the release
+ * before it shipped a fix for the first of them. Two dispatchers for the same
+ * six subcommands would be that defect with a much larger surface — `adopt`
+ * writes the user's CLAUDE.md and `uninstall` deletes their cache, so a drift
+ * between them is a drift between two destructive paths.
+ *
+ * `adopt` / `unadopt` / `uninstall` are intercepted here rather than forwarded:
+ * they write `<cwd>/CLAUDE.md`, `<cwd>/.claude/` and `~/.cache/code-graph`, and
+ * have no counterpart in the Rust binary. Everything else is forwarded verbatim.
+ */
+const { spawn } = require('child_process');
+const path = require('path');
+const { hidden } = require('./proc-opts');
+
+/**
+ * Reject unknown flags on an intercepted subcommand BEFORE doing its work.
+ *
+ * `--help` was already guarded, but every OTHER token was ignored, so
+ * `code-graph-mcp adopt --helpp` ran adopt and wrote the user's CLAUDE.md — a
+ * typo away from the very side effect the --help guard exists to prevent. This
+ * is the fourth entry point onto the same "ignore what you don't recognise"
+ * idiom (doctor.js, lifecycle.js doctor, src/main.rs were the first three); it
+ * is the surface both PATH names reach, so it is the one most users hit.
+ */
+function rejectUnknownFlags(argv, name, known) {
+  const unknown = argv.slice(3).filter((a) => !known.has(a));
+  if (unknown.length) {
+    process.stderr.write(
+      `code-graph-mcp ${name}: unknown argument(s): ${unknown.join(" ")}\n` +
+      `Run \`code-graph-mcp ${name} --help\` for usage.\n`);
+    process.exit(2);
+  }
+}
+
+/**
+ * @param {object}   [opts]
+ * @param {string[]} [opts.argv]           process.argv-shaped: [node, entry, sub, ...]
+ * @param {string}   [opts.findBinaryRoot] package root for find-binary's dev-mode and
+ *   bundled-`bin/` tiers. The npm entry passes its package root. The plugin
+ *   launcher passes NOTHING on purpose: find-binary derives the right root from
+ *   its own `__dirname` in every install shape, and pointing this at the plugin
+ *   root would add the launcher's own directory to the bundled-binary tier.
+ */
+function main({ argv = process.argv, findBinaryRoot = null } = {}) {
+  if (findBinaryRoot) process.env._FIND_BINARY_ROOT = path.resolve(findBinaryRoot);
+
+  const sub = argv[2];
+
+  if (sub === "adopt" || sub === "unadopt") {
+    // `--help`/`-h` must be side-effect-free: adopt() writes the managed block
+    // into CLAUDE.md, unadopt() removes it. The Rust binary guards this for
+    // direct invocation, but both PATH names route through this wrapper, which
+    // intercepts adopt/unadopt *before* the binary — so the guard must be
+    // repeated here, or `code-graph-mcp adopt --help` adopts the project (the
+    // common new-user path).
+    if (argv.slice(3).some((a) => a === "--help" || a === "-h")) {
+      process.stdout.write(sub === "adopt"
+        // Kept in sync with src/main.rs's adopt/unadopt help. This text described
+        // the pre-v0.74 scheme (a sentinel in the ~/.claude memory dir) for three
+        // releases after the target moved to the project's own CLAUDE.md, so npm
+        // users were told this command edits a file it has not touched since.
+        ? "code-graph-mcp adopt — install the code-graph steering block into the project CLAUDE.md\n\n" +
+          "USAGE:\n    code-graph-mcp adopt\n\n" +
+          "Writes a sentinel-wrapped managed block into <cwd>/CLAUDE.md plus a\n" +
+          "<cwd>/.claude/plugin_code_graph_mcp.md detail doc, so Claude Code loads the\n" +
+          "decision table each session. Run `code-graph-mcp unadopt` to remove it.\n"
+        : "code-graph-mcp unadopt — remove the code-graph steering block\n\n" +
+          "USAGE:\n    code-graph-mcp unadopt\n\n" +
+          "Reverses `code-graph-mcp adopt`: strips the managed block from\n" +
+          "<cwd>/CLAUDE.md and deletes <cwd>/.claude/plugin_code_graph_mcp.md.\n" +
+          "User content outside the sentinel is kept.\n");
+      process.exit(0);
+    }
+    rejectUnknownFlags(argv, sub, new Set(["--help", "-h"]));
+    const { adopt, unadopt, formatResult } = require("./adopt");
+    const result = sub === "unadopt" ? unadopt() : adopt();
+    process.stdout.write(formatResult(sub, result) + "\n");
+    process.exit(result.ok === false ? 1 : 0);
+  }
+
+  // Full local teardown (restore prior statusline, strip code-graph hooks from
+  // settings.json, delete ~/.cache/code-graph, and unadopt the CURRENT project).
+  // Node-only; no Rust counterpart. Claude Code's `/plugin uninstall` fires no
+  // uninstall hook, so this is the user's one-shot CLI teardown. Guard `--help`
+  // before the destructive work (same discipline as adopt/unadopt above).
+  if (sub === "uninstall") {
+    if (argv.slice(3).some((a) => a === "--help" || a === "-h")) {
+      process.stdout.write(
+        "code-graph-mcp uninstall — remove code-graph config + cache from this machine\n\n" +
+        "USAGE:\n    code-graph-mcp uninstall [--unadopt-all] [--purge-global]\n\n" +
+        "Restores your prior statusline, strips code-graph hooks from settings.json,\n" +
+        "deletes ~/.cache/code-graph, and removes this project's CLAUDE.md adoption\n" +
+        "block. --unadopt-all also removes the managed block + detail file from every\n" +
+        "registered adopted project; --purge-global removes the globally-installed\n" +
+        "@sdsrs npm packages even without the plugin-install marker. Also run\n" +
+        "`/plugin uninstall code-graph-mcp` in Claude Code to sync its UI.\n");
+      process.exit(0);
+    }
+    rejectUnknownFlags(argv, "uninstall", new Set(["--help", "-h", "--unadopt-all", "--purge-global"]));
+    const lifecycle = require("./lifecycle");
+    const { unadopt } = require("./adopt");
+    const r = lifecycle.uninstall({
+      purgeGlobal: argv.slice(3).includes("--purge-global"),
+      unadoptAll: argv.slice(3).includes("--unadopt-all"),
+    });
+    let ua = { ok: false };
+    try { ua = unadopt(); } catch { /* best-effort — settings/cache already cleaned */ }
+    const projectUnadopted = !!(ua && (ua.blockPruned || ua.fileRemoved || ua.claudeMdRemoved));
+    let out =
+      `Uninstalled code-graph-mcp | settings cleaned=${r.settingsChanged}` +
+      ` | this project unadopted=${projectUnadopted}\n`;
+    if (r.globalPkgsRemoved.length) {
+      out += `  Removed global npm package(s): ${r.globalPkgsRemoved.join(", ")}\n`;
+    }
+    if (r.globalPkgsRemaining.length) {
+      out += `  Global npm package(s) still installed: ${r.globalPkgsRemaining.join(", ")}\n` +
+        `    Remove with: npm uninstall -g ${r.globalPkgsRemaining.join(" ")}` +
+        (r.pluginInstalledGlobals ? "\n" : "   (or re-run with --purge-global)\n");
+    }
+    if (r.unadopted.length) {
+      const cleaned = r.unadopted.filter((u) => u.cleaned).length;
+      out += `  Unadopted ${cleaned}/${r.unadopted.length} registered project(s) (--unadopt-all).\n`;
+    }
+    const otherAdopted = r.adoptedProjects.filter((p) => p !== process.cwd());
+    if (otherAdopted.length) {
+      out += "  Other adopted project(s) — re-run with --unadopt-all, or in each:" +
+        " `code-graph-mcp unadopt` + `rm -rf .code-graph`\n" +
+        otherAdopted.map((p) => `    ${p}\n`).join("");
+    }
+    out += "  Also run `/plugin uninstall code-graph-mcp` in Claude Code to sync its UI state.\n";
+    process.stdout.write(out);
+    process.exit(0);
+  }
+
+  // `doctor` is the third JS-dispatched subcommand, and the one that used to be
+  // reached the long way round: forwarded to the binary, which re-execs a
+  // `doctor.js` it looks for beside itself. That works for a source build and
+  // for the npm package; it does NOT work for the install this launcher exists
+  // for, where the binary is the downloaded one in `~/.cache/code-graph/bin/`
+  // and answers `doctor.js not found. Looked in: …`. The script is right here,
+  // so ask it directly.
+  //
+  // `runDoctorCli` rather than a private re-parse: it is the function
+  // `node doctor.js …` and `node lifecycle.js doctor …` already share, and it
+  // exists as one function because the first version of doctor's unknown-flag
+  // guard lived in only one of them and a typo'd flag kept running the repair
+  // pass on the other. A third entry point re-implementing the parse would
+  // restore exactly that.
+  if (sub === "doctor") {
+    const { runDoctorCli } = require("./doctor");
+    process.exit(runDoctorCli(argv.slice(3)));
+  }
+
+  const { findBinary, unsupportedPlatformHint } = require("./find-binary");
+
+  const binary = findBinary();
+
+  if (!binary) {
+    const hint = unsupportedPlatformHint();
+    console.error(
+      "Error: code-graph-mcp binary not found.\n\n" +
+      (hint ? hint + "\n\n" : "") +
+      "To install:\n" +
+      "  npm install -g @sdsrs/code-graph\n\n" +
+      "To build from source:\n" +
+      "  cargo install code-graph-mcp --features embed-model\n"
+    );
+    process.exit(1);
+  }
+
+  // Forward stdio so MCP JSON-RPC (`serve`) and interactive output both work.
+  const child = spawn(binary, argv.slice(2), hidden({
+    stdio: "inherit",
+    env: process.env,
+  }));
+
+  child.on("error", (err) => {
+    console.error(`Failed to start code-graph-mcp: ${err.message}`);
+    // A glibc binary installed on musl (older npm ignores the `libc` field) is present
+    // but fails to exec — surface the actionable platform hint instead of a bare error.
+    const hint = unsupportedPlatformHint();
+    if (hint) console.error("\n" + hint);
+    process.exit(1);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code ?? 1);
+    }
+  });
+}
+
+module.exports = { main, rejectUnknownFlags };

package/claude-plugin/scripts/find-binary.js

@@ -190,11 +190,58 @@ function nvmNodeModulesDirs(base = path.join(os.homedir(), '.nvm', 'versions', '
     .filter((d) => { try { return fs.statSync(d).isDirectory(); } catch { return false; } });
 }
 
+/**
+ * The plugin's own `bin/`, resolved once through realpath (plugin caches can sit
+ * behind a symlinked home) and remembered.
+ *
+ * Claude Code puts this directory on the Bash tool's PATH, and the file in it is
+ * NAMED `code-graph-mcp` — that is the whole point of it (issue #41). See
+ * `isNativeBinary` for why that name has to be excluded here.
+ */
+let launcherDirMemo;
+function launcherDir() {
+  if (launcherDirMemo === undefined) {
+    const dir = path.resolve(__dirname, '..', 'bin');
+    try { launcherDirMemo = fs.realpathSync(dir); } catch { launcherDirMemo = dir; }
+  }
+  return launcherDirMemo;
+}
+
+/**
+ * Is this candidate the native binary, as opposed to a wrapper that resolves it?
+ *
+ * The basename test is what rejects the npm shim: `npm i -g` installs
+ * `code-graph-mcp` as a symlink whose realpath is `.../bin/cli.js`, and running
+ * that instead of the binary would make the wrapper spawn itself.
+ *
+ * The plugin launcher is the same hazard under a name the basename test cannot
+ * catch, because PATH resolution requires it to BE `code-graph-mcp`. Two tiers
+ * of the discovery chain offer it: the PATH probe (`which code-graph-mcp`) and
+ * the bundled-`bin/` tier, which `mcp-launcher.js` points at the plugin root.
+ * It resolves the binary by calling `findBinary()` — so accepting it here is a
+ * launcher that execs the launcher, and a `binary-path` cache entry that
+ * remembers to keep doing it. Excluded by directory rather than by content
+ * (a magic-byte test would be the more general guard and would reject the
+ * planted fixtures this module's own suite is built on).
+ */
 function isNativeBinary(candidate) {
   if (!candidate) return false;
   try {
     if (!fs.existsSync(candidate)) return false;
     const realPath = fs.realpathSync(candidate);
+    const dir = path.dirname(realPath);
+    // Our OWN launcher directory, and — pre-ship review — any OTHER copy's.
+    // Matching only `launcherDir()` covers the copy this module was loaded from,
+    // so a machine with BOTH `npm i -g` and the plugin had the npm entry's PATH
+    // tier resolve the PLUGIN's launcher as the binary: accepted by the gate,
+    // written into the shared `~/.cache/code-graph/binary-path`, and thereafter
+    // one extra node process per call plus cache thrash between the two copies.
+    // The `.cmd` sibling is the marker because it is what makes a directory a
+    // launcher directory: `claude-plugin/bin/` always ships both spellings, and
+    // nothing that ships an actual native binary ships a `.cmd` beside it.
+    // Not a magic-byte test on purpose — see the note in tasks/specs.
+    if (dir === launcherDir()) return false;
+    if (fs.existsSync(path.join(dir, 'code-graph-mcp.cmd'))) return false;
     return path.basename(realPath) === BINARY_NAME;
   } catch {
     return false;

package/claude-plugin/scripts/post-grep-inject.js

@@ -23,22 +23,28 @@ if (require.main === module) require('./hook-fail-open').installHookFailOpen('Po
 //
 // Reuses the PreToolUse pure predicates wholesale (feedback_hook_class_bug_sweep —
 // no inline copies of the grep gate): splitTopLevelSegments + classifyBlock pick
-// the foldable segment; pickBlockPattern / translateBreToRg / extractSearchPath +
-// sanitizeSearchPath + runGrepAnswer / runShowAnswer run the exact same answer the
-// deny path would have. Best-effort: any miss (no hits / unavailable / no binary)
+// the foldable segment; pickBlockPattern / translateBreToRg / extractCgFlags +
+// extractSearchPath + runGrepAnswer / runShowAnswer run the exact same answer the
+// deny path would have — including its flags and glob scope, which this hook did
+// NOT carry until v0.144 even as the deny path stopped taking these commands. Best-effort: any miss (no hits / unavailable / no binary)
 // exits silently with NO injection — an enhancement, never a new failure mode.
 
 const fs = require('fs');
 const path = require('path');
 const { cgTmpDir, cwdHash, makeCooldown } = require('./tmp-dir');
 const { recordRecommendation } = require('./recommendation-log');
-const { runGrepAnswer, runShowAnswer, runCallgraphAnswer, sanitizeSearchPath } = require('./cg-answer');
+// `sanitizeSearchPath` is deliberately NOT imported any more: this hook passes
+// the RAW path so buildGrepArgs can split a glob into scope + `-g` instead of
+// widening it away. Leaving the require behind would read as "still used".
+const { runGrepAnswer, runShowAnswer, runCallgraphAnswer } = require('./cg-answer');
 const { emitPostToolContext } = require('./hook-emit');
 const {
   splitTopLevelSegments,
   classifyBlock,
   pickBlockPattern,
   translateBreToRg,
+  extractCgFlags,
+  cgFlagSet,
   extractSearchPath,
   normalizeCommandPaths,
   rebaseRelativePaths,
@@ -265,9 +271,70 @@ function runMain() {
   // ~1KB context tax. Only a grep that found NOTHING (or an unreadable output —
   // no regression on older CC) proceeds: then cg's structural answer (the real
   // location / cross-file callers a failed grep never showed) is genuinely additive.
-  if (grepFoundPattern(extractGrepOutput(input), rawPattern)) return;
-  const pattern = translateBreToRg(segment, rawPattern);
-  const searchPath = sanitizeSearchPath(extractSearchPath(segment));
+  // v0.144 — RECORD the suppression instead of returning silently. PreToolUse
+  // stopped denying compound commands in this release, which moves a measured
+  // 27% of former denies (23 of 85 in this repo's own log carried `tail:true`,
+  // every one of them `answered:true`) onto this path — and this `return` is
+  // where they end when the model's own grep hit. That was the right trade only
+  // if it stays visible: an unrecorded skip makes the whole class disappear from
+  // the funnel, so "the compound case is covered by the inject" becomes a claim
+  // nobody can check after ship. Pre-ship review found this before release.
+  // `hook:'grep'` and `action:'observe'`, NOT a new hook name — round 2 of
+  // pre-ship review caught round 1 inventing `hook:'grep-inject'/action:'skip'`
+  // and thereby breaking the metric this record was added to protect.
+  // `aggregate_recommendations_jsonl` (src/cli/usage.rs) clears `armed` on EVERY
+  // line it reads, but only scores lines whose hook is `grep`/`read`, so an
+  // unrecognized hook consumed the arm set by the preceding answered deny
+  // without scoring it — measured on a crafted log: one such line between an
+  // answered deny and its follow-up took `fallthrough_rate` from 1.0 to 0.0.
+  // `skip` was also absent from the `observe`/`use`/`live_impact` exclusions, so
+  // it inflated `s.total` and shifted `tool_calls_per_rec` across releases.
+  //
+  // `observe` is the honest bucket as well as the safe one: the grep ran and
+  // produced its own hits, so nothing was recommended. The aggregator already
+  // reads it as "acting on the answer — neither sustained nor fall-through" and
+  // excludes it from the recommendation total. `reason` distinguishes this skip
+  // from the cooldown observes when grepping the JSONL; no counter reads it.
+  //
+  // KNOWN CONSEQUENCE, measured rather than reasoned — and round 3 corrected
+  // round 2's version of this paragraph, which described the wrong branch. The
+  // funnel scores only the IMMEDIATELY-next event after an answered deny, and
+  // `usage.rs` tests SAME-PATTERN first. So on the shape this record actually
+  // measures — a re-grep of the denied pattern — the outcome is unchanged
+  // (`fallthrough_after_answer` 1, rate 1.0, because a verbatim re-grep is
+  // fall-through whether it is spelled as this observe or as the deny that used
+  // to follow it). Only when the compound grep searches a DIFFERENT pattern does
+  // the window move onto it: there the rate goes 1.0 → 0.0, since a different
+  // query is not evidence the answer failed. `total` is unaffected either way
+  // (`observe` is excluded). Measured on the built binary, both branches.
+  const flags = extractCgFlags(segment);
+  // `-F` means the user asked for a LITERAL pattern, so the BRE→rust-regex
+  // unescape must not also run: `grep -F 'x\|y'` searches for `x\|y`, and
+  // unescaping it to `x|y` searches for something else (verified against GNU
+  // grep: `grep -Fc 'x\|y'` is 1 and `grep -Fc 'x|y'` is 0 on the same file).
+  const pattern = cgFlagSet(flags).has('-F') ? rawPattern : translateBreToRg(segment, rawPattern);
+  // The redundancy gate matches against the model's OWN grep output, which
+  // carries the pattern as the user wrote it → `rawPattern`. The RECORD carries
+  // the translated `pattern`, because that is the vocabulary every sibling
+  // record uses (pre-grep-guide's deny and observe, this file's two injects) and
+  // the funnel compares those strings for equality. Round 2 recorded the raw
+  // form: a deny of `"fn foo\|fn bar"` files `fn foo|fn bar` while the follow-up
+  // filed `fn foo\|fn bar`, so a verbatim re-grep scored neutral instead of
+  // fall-through. Round 1's record never reached that comparison at all (wrong
+  // hook name), so promoting it in is what exposed the mismatch.
+  if (grepFoundPattern(extractGrepOutput(input), rawPattern)) {
+    recordRecommendation(root, {
+      hook: 'grep', action: 'observe', reason: 'grep-hit-redundant',
+      ...(pattern ? { pattern } : {}),
+    });
+    return;
+  }
+  // RAW path, not `sanitizeSearchPath`: buildGrepArgs splits `tests/*.mjs` into
+  // scope + `-g`. The deny path got that in this release and this one did not,
+  // while the same release routed MORE traffic here — so `grep -rln "X"
+  // tests/*.mjs && echo done` ran without `-l` and against all of `tests/`,
+  // exactly the infidelity the deny path had just stopped committing.
+  const searchPath = extractSearchPath(segment);
   let answer = { status: 'unavailable' };
   let answeredMode = block.mode;
 
@@ -293,11 +360,11 @@ function runMain() {
       answer = runShowAnswer({ cwd: root, symbols: block.symbols });
       if (answer.status !== 'hits' && pattern) {
         answeredMode = 'grep';
-        answer = runGrepAnswer({ cwd: root, pattern, searchPath });
+        answer = runGrepAnswer({ cwd: root, pattern, searchPath, flags });
       }
     } else if (pattern) {
       answeredMode = 'grep';
-      answer = runGrepAnswer({ cwd: root, pattern, searchPath });
+      answer = runGrepAnswer({ cwd: root, pattern, searchPath, flags });
     }
   }
 

package/claude-plugin/scripts/pre-grep-guide.js

@@ -48,7 +48,7 @@ const fs = require('fs');
 const path = require('path');
 const { cgTmpDir, cwdHash, makeCooldown } = require('./tmp-dir');
 const { recordRecommendation } = require('./recommendation-log');
-const { runGrepAnswer, runShowAnswer, sanitizeSearchPath } = require('./cg-answer');
+const { runGrepAnswer, runShowAnswer, sanitizeSearchPath, buildGrepArgs, formatCgCommand } = require('./cg-answer');
 
 // --- Pure logic (testable) ---
 
@@ -248,6 +248,7 @@ function classifyBlock(cmd) {
   // must not disqualify the answerable head grep).
   const clause = firstShellClause(cmd);
   if (UNANSWERABLE_FLAGS.test(clause)) return null;  // intent the answer can't honor
+  if (isAgFilenameSearch(clause)) return null;       // a filename search, not a content one
   if (MARKER_ONLY.test(clause)) return null;         // bare TODO/FIXME — no cg equivalent
   const patterns = extractPatterns(clause);
   if (patterns.length === 0) return null;         // unquoted pattern — conservative, hint
@@ -266,6 +267,215 @@ function classifyBlock(cmd) {
   return { mode: 'grep' };
 }
 
+// Flags of the user's grep that `code-graph-mcp grep` can honor, in its own
+// spelling. Verified against the built binary rather than against help text:
+// `-l` prints bare paths, `-c` prints `path:count` exactly as `grep -c` does.
+//
+// Everything absent from this map is absent on purpose. `-r`/`-R`, `-n` and
+// `-H` ARE accepted by cg as grep-parity no-ops (it is always recursive and
+// always prints path and line number), so forwarding them would be harmless
+// rather than an error — they are simply nothing to say. `-h` is NOT the same
+// flag in the two tools: cg reads it as `--help`, so forwarding it would print
+// usage instead of searching. `-L`/`-v`/`--exclude*` never arrive here —
+// UNANSWERABLE_FLAGS sends them to the hint tier — and `-A/-B/-C` are routed to
+// show-mode or hint before this runs.
+const CG_SHORT_FLAGS = { i: '-i', w: '-w', F: '-F', l: '-l', c: '-c' };
+const CG_LONG_FLAGS = {
+  '--ignore-case': '-i',
+  '--word-regexp': '-w',
+  '--fixed-strings': '-F',
+  '--files-with-matches': '-l',
+  '--count': '-c',
+};
+// Flags that carry a VALUE and select which files are searched. All three spell
+// the same filter cg spells `-g` / `-t`, and dropping one silently widens the
+// answer to files the user excluded — the defect this whole flag map exists to
+// stop. `rg`'s spellings matter because rg is a folded verb: `rg -g '*.rs' Sym
+// src/` reached the answer as a bare `grep Sym src/`. cg takes `-g` repeatably,
+// so every occurrence is forwarded rather than only the first.
+const CG_VALUE_FLAGS = {
+  '--include': '-g',   // grep
+  '--glob': '-g',      // rg
+  '--type': '-t',      // rg
+};
+// Short forms of the value-carrying flags. RIPGREP ONLY, and the verb is
+// checked: `ag -t Sym src/` means "all text files" and takes no value, and ag's
+// `-g` prints matching FILENAMES rather than filtering — mapping either would
+// hand cg an argument the user never wrote. (Round 2 of pre-ship review; the
+// symptom was mild — cg exits 2 on an unknown file type, the answer degrades to
+// `unavailable` and the deny becomes an allow — but it is a fabricated
+// argument.) grep has no short spelling for `--include`.
+const CG_VALUE_SHORT = { g: '-g', t: '-t' };
+const RG_VERB = /(?:^|\s)rg$/;
+const AG_VERB = /(?:^|\s)ag$/;
+
+/**
+ * `ag -g PATTERN` searches FILENAMES, not file contents.
+ *
+ * Round 2 gated the short `-g`/`-t` map on ripgrep so ag's spellings would stop
+ * being folded into cg arguments the user never wrote. Round 3 found what that
+ * left behind: with the fabricated argument gone, `ag -g some_symbol src/` is a
+ * plain answerable content grep as far as `classifyBlock` is concerned, so the
+ * hook now DENIES it and answers with matching LINES — a different question
+ * from the one asked. Before round 2 the fabricated `-g some_symbol` matched no
+ * file, the answer came back empty and the deny degraded to an allow; the bug
+ * was accidentally its own safety valve.
+ *
+ * cg has no filename-search mode, so this belongs in the hint tier with the
+ * other intents the answer cannot honor: the user's `ag` runs untouched.
+ */
+function isAgFilenameSearch(clause) {
+  if (typeof clause !== 'string') return false;
+  if (!AG_VERB.test((clause.match(GREP_HEAD) || [])[1] || '')) return false;
+  // A TOKEN scan, not a regex over the whole clause (round 4 of pre-ship
+  // review). The first spelling of this guard matched `-g` only when it was
+  // whitespace-delimited, so `ag -g"some_symbol" src/` — the attached form
+  // `extractCgFlags` twelve lines below explicitly handles — still reached the
+  // deny and was answered with content lines. Scanning the raw clause instead
+  // had the mirror-image fault: a `-g` inside a quoted pattern
+  // (`ag "some_symbol -g x" src/`) demoted a real content search. Same
+  // flag-name-in-a-value-position class the sibling repairs fixed with
+  // cgFlagSet/hasGlobFlag, so this uses the same convention: a token that
+  // STARTS quoted is an argument, never a flag.
+  // Quoted spans are blanked BEFORE tokenizing, not skipped after: a quoted
+  // argument can contain whitespace, so `ag "some_symbol -g x" src/` splits into
+  // three tokens and the middle one looks exactly like a flag. Blanking leaves
+  // an attached value's flag behind (`-g"x"` → `-g`), which is what we want.
+  const scan = clause.replace(VERB_STRIP, '').replace(/"[^"]*"|'[^']*'/g, ' ');
+  for (const tok of scan.trim().split(/\s+/)) {
+    if (!tok || tok[0] !== '-') continue;
+    if (tok.startsWith('--')) {
+      if (/^--(?:filename-pattern|file-search-regex)(?:=|$)/.test(tok)) return true;
+      continue;
+    }
+    // Short cluster: ag's `-g` takes a value, so it ends the cluster — an
+    // attached value (`-g'x'`, `-g=x`) or the next token. Capital `-G` is a
+    // different ag flag (limit by filename) and must NOT match.
+    if (/^-[a-zA-Z]*g/.test(tok)) return true;
+  }
+  return false;
+}
+
+/**
+ * The boolean flags in an `extractCgFlags` result, without the VALUES.
+ *
+ * The result is a flat argv fragment (`['-i','-g','*.rs']`), which is what
+ * `buildGrepArgs` needs — but it means a membership test sees value tokens too.
+ * Round 2 of pre-ship review found both live consequences: `rg -t -g "sym"
+ * src/*.rs` yields `['-t','-g']`, whose bare `includes('-g')` made buildGrepArgs
+ * drop the path-derived glob and widen the scope — the exact defect this change
+ * exists to fix — and `grep --include -F "sym" src/` yields `['-g','-F']`, where
+ * `-F` is a filename glob and firing the literal-pattern guard on it is wrong.
+ */
+function cgFlagSet(flags) {
+  const out = new Set();
+  for (let i = 0; i < (flags || []).length; i++) {
+    const f = flags[i];
+    if (f === '-g' || f === '-t') { i++; continue; }  // skip its value
+    out.add(f);
+  }
+  return out;
+}
+// Canonical emission order, so the argv (and therefore the printed command) is a
+// function of WHICH flags were given, never of the order the user typed them.
+const CG_FLAG_ORDER = ['-i', '-w', '-F', '-l', '-c'];
+
+/**
+ * The grep's flags, translated to cg's.
+ *
+ * Until v0.144 the answer ran `['grep', pattern, scope]` and the deny printed
+ * the same three tokens, so every flag was dropped in both places at once — a
+ * `grep -rln` deny announced "the AST-aware equivalent already ran for you"
+ * above a command that was not the equivalent and returned hit lines where a
+ * file list was asked for (field report 2026-09-08).
+ *
+ * Scanning rules that matter: only the grep's OWN clause (a tail command's
+ * `-l` is not this grep's), and a token that STARTS quoted is an argument, not
+ * a flag — `grep "-l" src/` searches for the string `-l`.
+ */
+function extractCgFlags(cmd) {
+  if (!cmd || typeof cmd !== 'string') return [];
+  const clause = firstShellClause(cmd);
+  const isRg = RG_VERB.test((clause.match(GREP_HEAD) || [])[1] || '');
+  const toks = clause.replace(VERB_STRIP, '').trim().split(/\s+/);
+  const found = new Set();
+  const filters = [];  // [cgFlag, value] pairs, in the order the user wrote them
+  const unquote = (s) => (s || '').replace(/^["']|["']$/g, '');
+  const addFilter = (flag, value) => {
+    if (!value) return;
+    // `-g '*.rs' -g '*.rs'` is one filter written twice; cg would honour both
+    // identically, but the printed command should not look like a mistake.
+    if (!filters.some(([f, v]) => f === flag && v === value)) filters.push([flag, value]);
+  };
+  for (let i = 0; i < toks.length; i++) {
+    const tok = toks[i];
+    if (!tok || tok[0] === '"' || tok[0] === "'" || tok[0] !== '-') continue;
+    if (tok.startsWith('--')) {
+      const eq = tok.indexOf('=');
+      const name = eq === -1 ? tok : tok.slice(0, eq);
+      if (CG_VALUE_FLAGS[name]) {
+        addFilter(CG_VALUE_FLAGS[name], unquote(eq === -1 ? toks[i + 1] : tok.slice(eq + 1)));
+        if (eq === -1) i++;  // the value was a separate token — do not rescan it
+        continue;
+      }
+      if (CG_LONG_FLAGS[name]) found.add(CG_LONG_FLAGS[name]);
+      continue;
+    }
+    // A short cluster: `-rln` is r + l + n, and only `l` has a cg spelling. A
+    // value-carrying short flag ends the cluster and takes what follows —
+    // attached (`-g*.rs`) or as the next token (`-g '*.rs'`).
+    const letters = tok.slice(1);
+    let consumed = false;
+    for (let k = 0; k < letters.length; k++) {
+      const ch = letters[k];
+      if (isRg && CG_VALUE_SHORT[ch]) {
+        const attached = letters.slice(k + 1);
+        addFilter(CG_VALUE_SHORT[ch], attached ? unquote(attached) : unquote(toks[i + 1]));
+        // Consume the value token so the next pass cannot read it as a flag
+        // cluster: `rg -g -i 'sym' src/` must be `-g` with value `-i`, not `-g`
+        // plus a phantom `-i` (round 2 of pre-ship review — the test that named
+        // this property used a quoted value, which the quote guard already
+        // skipped, so it passed with the increment removed).
+        if (!attached) { i++; }
+        consumed = true;
+        break;
+      }
+      if (CG_SHORT_FLAGS[ch]) found.add(CG_SHORT_FLAGS[ch]);
+    }
+    if (consumed) continue;
+  }
+  const out = CG_FLAG_ORDER.filter((f) => found.has(f));
+  for (const [flag, value] of filters) out.push(flag, value);
+  return out;
+}
+
+/**
+ * The deny gate, as runMain applies it — strictly narrower than classifyBlock.
+ *
+ * classifyBlock answers "can the inline answer cover this grep". Denying asks
+ * something else: "may we cancel the WHOLE command". A top-level `;`/`&&` tail
+ * makes those different questions, because the deny cancels a `sed`/`wc`/`echo`
+ * the answer says nothing about. Until v0.144 the tail was detected and spent on
+ * a NOTE apologising for the loss; the deny fired anyway.
+ *
+ * It is the same incompleteness the ≥2-named-paths rule above already refuses to
+ * deny on ("only DENY when the inline grep answer can cover the SAME scope"),
+ * and the fallback was already built: post-grep-inject.js is a PostToolUse hook
+ * for compound greps whose segment walk has no head-is-grep exclusion, carries
+ * its own redundancy gate, and uses a distinct cooldown prefix. These commands
+ * reach it as soon as they are allowed to run.
+ *
+ * `|` and `||` are NOT tails: a pipe is one pipeline that the answer replaces
+ * whole, and the `||` branch would not have run given the answer carried hits.
+ *
+ * classifyBlock itself is deliberately left alone — post-grep-inject calls it
+ * per SEGMENT, where a top-level tail cannot exist by construction.
+ */
+function classifyDeny(cmd) {
+  if (extractUnansweredTail(cmd)) return null;
+  return classifyBlock(cmd);
+}
+
 function shouldBlock(cmd) {
   return classifyBlock(cmd) !== null;
 }
@@ -393,27 +603,12 @@ function extractUnansweredTail(cmd) {
   return null;
 }
 
-// Shared deny-copy footer for the unanswered compound tail. Budget-conscious:
-// two lines, verbatim command so the model can re-issue without thinking.
-// Wording is path-neutral — it must stay true for BOTH the answered deny
-// ("grep half answered, tail wasn't") and the static fallback (nothing was).
-// Head-line marker paired with the NOTE below: the NOTE sits at the END of a
-// long deny message and Claude Code's transcript view folds long tool errors,
-// so a human reading the truncated view saw a clean "answered" deny with no
-// clue the compound's tail was dropped (2026-07-18: two such denies were
-// misdiagnosed as product bugs). The model gets the full reason either way.
-function tailFlagSuffix(tail) {
-  return tail ? ' (compound tail NOT run — see NOTE at end)' : '';
-}
-
-function appendUnansweredTailNote(lines, tail) {
-  if (!tail) return;
-  const shown = tail.length > 300 ? tail.slice(0, 300) + '…' : tail;
-  lines.push(
-    'NOTE: the rest of this compound command (after the grep) did NOT run — re-issue it separately:',
-    `$ ${shown}`,
-  );
-}
+// v0.144 — the compound-tail apparatus that lived here is GONE, together with
+// the deny it apologised for. It was a head-line marker plus a closing NOTE
+// telling the model to re-issue the `; sed …` the deny had just cancelled, and
+// the honest version of that message is not to cancel it: `classifyDeny` now
+// refuses to deny a command with a top-level tail at all, so no deny reaching
+// these builders can carry one. `extractUnansweredTail` survives as that gate.
 
 // v0.47.0 — pull the first source-tree path token out of the denied command so
 // the inline answer can scope its search the same way the raw grep would have.
@@ -547,22 +742,20 @@ function buildHint() {
   ].join('\n');
 }
 
-function buildBlockReason(unansweredTail) {
+function buildBlockReason() {
   // Shown to Claude via PreToolUse `decision: block` reason. Must give a
   // concrete alternate command Claude can re-issue without further thinking.
   // v0.49 — NO escape-hatch line anywhere in deny copy: the daagu 2026-06-12
   // night proved even the "THIS command only" scoping reads as a teachable
   // permanent prefix (adopted in 8s, reused 11×, incl. on the exact identifier
   // searches this hook targets). The env opt-out stays documented in README.
-  const lines = [
-    `[code-graph] Raw \`grep -rn\` on indexed source — denied by code-graph hook.${tailFlagSuffix(unansweredTail)}`,
+  return [
+    '[code-graph] Raw `grep -rn` on indexed source — denied by code-graph hook.',
     'Use the AST-aware equivalent (returns containing fn/module per hit, repo-wide):',
     '  code-graph-mcp grep "<pattern>" [paths...]      # AST context per hit; -F literal, -i, -w, -l, -C N, --max-count 0',
     '  code-graph-mcp ast-search "<pattern>" --type fn # filter by node type',
     '  code-graph-mcp callgraph SYMBOL                 # callers + callees',
-  ];
-  appendUnansweredTailNote(lines, unansweredTail);
-  return lines.join('\n');
+  ].join('\n');
 }
 
 // v0.47.0 — deny WITH the answer inline. Hint-only had ~0% transfer and a bare
@@ -572,10 +765,15 @@ function buildBlockReason(unansweredTail) {
 // advertising the bypass taught it a permanent prefix within 5 seconds (daagu
 // 2026-06-11: one deny → 14 bypassed greps). The static deny keeps a scoped
 // escape because there we give no answer.
-function buildBlockReasonWithAnswer(pattern, searchPath, answer, unansweredTail) {
-  const cmdShown = `code-graph-mcp grep "${pattern}"${searchPath ? ` ${searchPath}` : ''}`;
+// `cmdShown` is rendered by the caller from the SAME argv array it handed the
+// child process (cg-answer.buildGrepArgs → formatCgCommand). It used to be
+// re-assembled here from `(pattern, searchPath)` alone, which is how a deny came
+// to print `code-graph-mcp grep "X" tests` above an answer that had actually run
+// with different arguments — the flags nobody forwarded, and a glob silently
+// widened to its parent directory.
+function buildBlockReasonWithAnswer(cmdShown, answer) {
   const lines = [
-    `[code-graph] Raw \`grep\` on indexed source — denied; the AST-aware equivalent already ran for you:${tailFlagSuffix(unansweredTail)}`,
+    '[code-graph] Raw `grep` on indexed source — denied; the AST-aware equivalent already ran for you:',
     `$ ${cmdShown}`,
     answer.text,
   ];
@@ -591,7 +789,6 @@ function buildBlockReasonWithAnswer(pattern, searchPath, answer, unansweredTail)
   // (deny-with-answer already satisfies in-place, 5/5 in the daagu replay). The
   // engagement nudge is kept only where it pays — the pre-edit impact summary,
   // a true before-you-edit reconciliation moment. Re-add here only behind an A/B.
-  appendUnansweredTailNote(lines, unansweredTail);
   return lines.join('\n');
 }
 
@@ -599,9 +796,9 @@ function buildBlockReasonWithAnswer(pattern, searchPath, answer, unansweredTail)
 // context flags (-A/-B/-C = "show me the body"); the answer IS the bodies,
 // fetched via `code-graph-mcp show`. answer.text already carries per-symbol
 // `$ code-graph-mcp show <sym>` headers.
-function buildShowDenyReason(answer, unansweredTail) {
+function buildShowDenyReason(answer) {
   const lines = [
-    `[code-graph] Raw grep for symbol definitions — denied; here are the definitions from the AST index:${tailFlagSuffix(unansweredTail)}`,
+    '[code-graph] Raw grep for symbol definitions — denied; here are the definitions from the AST index:',
     answer.text,
   ];
   if (answer.truncated) {
@@ -610,7 +807,6 @@ function buildShowDenyReason(answer, unansweredTail) {
   lines.push('Use these directly instead of re-running the search.');
   // NOTE (v0.63): forced-ack salience trialed + removed here too — see
   // buildBlockReasonWithAnswer. The definitions are already delivered.
-  appendUnansweredTailNote(lines, unansweredTail);
   return lines.join('\n');
 }
 
@@ -624,7 +820,16 @@ function translateBreToRg(cmd, pattern) {
   const verb = (cmd.match(GREP_HEAD) || [])[1];
   // git grep speaks BRE like plain grep; rg/ag are already extended-regex.
   if (!verb || !/grep$/.test(verb)) return pattern;
-  if (/(?:^|\s)-[a-zA-Z]*[EP][a-zA-Z]*(?:\s|=|\d|$)|--(?:extended-regexp|perl-regexp)\b/.test(cmd)) {
+  // The grep's OWN clause, not the whole command. This was the one flag check
+  // in this module that v0.96 did not clause-scope, and round 4 of pre-ship
+  // review found what it costs: `grep -rln "a\|b" src/ | xargs -P4 wc -l` read
+  // the tail's `-P4` as "this grep speaks Perl regex", so the pattern was left
+  // escaped. On its own that is a wrong dialect decision; it also desynchronised
+  // the two hooks, because post-grep-inject passes a SEGMENT here while the deny
+  // path passes the whole command — the same pattern then filed under two
+  // spellings and the funnel scored a verbatim re-grep as neutral.
+  const clause = firstShellClause(cmd);
+  if (/(?:^|\s)-[a-zA-Z]*[EP][a-zA-Z]*(?:\s|=|\d|$)|--(?:extended-regexp|perl-regexp)\b/.test(clause)) {
     return pattern;
   }
   return pattern.replace(/\\([|(){}+?])/g, '$1');
@@ -725,7 +930,17 @@ function runMain() {
   // of an answered deny (inline answer ignored → fall-through) from a deeper
   // drill-down. undefined when there's no identifier-like pattern (unquoted / prose
   // grep) → omitted from the event, so the funnel stays back-compatible.
-  const grepPattern = translateBreToRg(cmd, pickBlockPattern(cmd));
+  // `-F` asks for a LITERAL pattern, and the BRE→rust-regex unescape must not
+  // also run on it: `grep -F 'x\|y'` searches for the five characters `x\|y`,
+  // while the unescaped `x|y` is a different string (GNU grep on a file holding
+  // the literal: `grep -Fc 'x\|y'` is 1, `grep -Fc 'x|y'` is 0). Before this
+  // release the flag was dropped entirely, so the answer was merely broader;
+  // forwarding `-F` without this guard would make it search the wrong text.
+  const cgFlags = extractCgFlags(cmd);
+  const rawGrepPattern = pickBlockPattern(cmd);
+  const grepPattern = cgFlagSet(cgFlags).has('-F')
+    ? rawGrepPattern
+    : translateBreToRg(cmd, rawGrepPattern);
 
   // v0.48 — deliberate escape: record it (funnel visibility) and stay silent.
   // Before GREP_HEAD accepted bare KEY=VALUE prefixes these were invisible.
@@ -744,7 +959,26 @@ function runMain() {
 
   markCooldown(rawCmd, root);
 
-  const block = isBlockDisabled() ? null : classifyBlock(cmd);
+  // classifyDeny, not classifyBlock: a command with a top-level `;`/`&&` tail is
+  // never denied, because cancelling it would cancel the tail too. Those run and
+  // are answered by post-grep-inject instead — which is also where they are
+  // RECORDED.
+  //
+  // Round 1 added an `observe compound:true` row here. Round 2 showed no counter
+  // reads the field, and round 3 showed the row double-counts: a head-grep
+  // compound whose grep hits writes this row AND post-grep-inject's redundancy
+  // observe, so one Bash call became two entries in a counter `usage.rs`
+  // documents as the model's raw search fan-out. The post-side rows carry more
+  // (they say what happened to the answer), so this side stays silent — exactly
+  // as it did before the compound change.
+  //
+  // One configuration where that leaves NO trace, named because round 4 caught
+  // the claim overstated: under `CODE_GRAPH_NO_INJECT=1` the post side does not
+  // run either, so a first-run compound is invisible to the funnel. A repeat
+  // within 60 s still lands in the cooldown `observe` branch above. A kill
+  // switch silencing the hook that carries the telemetry is coherent; silently
+  // claiming coverage it does not have is not.
+  const block = isBlockDisabled() ? null : classifyDeny(cmd);
   if (block) {
     // v0.47.0 — run the AST-aware equivalent inside the hook and embed the
     // results in the deny reason ("answer in the deny"). Degrades to the
@@ -754,19 +988,24 @@ function runMain() {
     // falling back to the grep answer, then the static deny.
     let answer = { status: 'unavailable' };
     const pattern = grepPattern; // computed once above; reused for the answer + deny fingerprint
-    // v0.48 — glob-truncated once, shared by the run and the deny message
-    // (a literal `dir/*.py` argv made rg exit 1 → answered:false static deny).
-    const searchPath = sanitizeSearchPath(extractSearchPath(cmd));
+    // The path is passed RAW (globs and all). buildGrepArgs splits `tests/*.mjs`
+    // into scope `tests` + `-g '*.mjs'`, which is both what keeps a literal glob
+    // out of argv (the exit-1 shape sanitizeSearchPath was added for) and what
+    // stops the answer from quietly searching files the user excluded.
+    const searchPath = extractSearchPath(cmd);
+    const flags = cgFlags;  // computed once above, beside the -F pattern guard
+    // ONE argv, used to run the child AND to render the command the deny prints.
+    const args = buildGrepArgs({ pattern, searchPath, flags });
     let answeredMode = block.mode;
     if (!isAnswerDisabled()) {
       if (block.mode === 'show') {
         answer = runShowAnswer({ cwd: root, symbols: block.symbols });
         if (answer.status !== 'hits' && pattern) {
           answeredMode = 'grep';
-          answer = runGrepAnswer({ cwd: root, pattern, searchPath });
+          answer = runGrepAnswer({ cwd: root, pattern, searchPath, flags });
         }
       } else if (pattern) {
-        answer = runGrepAnswer({ cwd: root, pattern, searchPath });
+        answer = runGrepAnswer({ cwd: root, pattern, searchPath, flags });
       }
     }
 
@@ -802,9 +1041,6 @@ function runMain() {
     // is the documented modern path. Exit 0 — this is a routing decision, not
     // a hook failure (exit 2 would mark the tool call as "hook errored").
     const answered = answer.status === 'hits';
-    // v0.50 — flag the unanswered `;`/`&&` tail. Extracted from rawCmd: its
-    // paths are valid in the model's shell cwd, where the re-issue will run.
-    const unansweredTail = extractUnansweredTail(rawCmd);
     recordRecommendation(root, {
       hook: 'grep', action: 'deny', answered,
       // pattern fingerprints the denied search so the funnel can score a verbatim
@@ -817,19 +1053,16 @@ function runMain() {
       // 'unavailable' (binary ran but failed/timed out). Without this the two
       // are indistinguishable in the funnel ("broken" looks like "no hits").
       ...(answered ? {} : { reason: answer.status }),
-      // tail segments compound-command denies — lets the funnel compare
-      // re-issue behavior for denies that carried a tail note.
-      ...(unansweredTail ? { tail: true } : {}),
     });
     process.stdout.write(JSON.stringify({
       hookSpecificOutput: {
         hookEventName: 'PreToolUse',
         permissionDecision: 'deny',
         permissionDecisionReason: !answered
-          ? buildBlockReason(unansweredTail)
+          ? buildBlockReason()
           : answeredMode === 'show'
-            ? buildShowDenyReason(answer, unansweredTail)
-            : buildBlockReasonWithAnswer(pattern, searchPath, answer, unansweredTail),
+            ? buildShowDenyReason(answer)
+            : buildBlockReasonWithAnswer(formatCgCommand(args), answer),
       },
     }) + '\n');
     return;
@@ -853,6 +1086,9 @@ module.exports = {
   shouldHint,
   shouldBlock,
   classifyBlock,         // v0.49 — intent-aware block tiers
+  classifyDeny,          // v0.144 — the deny gate: block-tier AND nothing discarded
+  extractCgFlags,        // v0.144 — the grep's flags in cg's spelling
+  cgFlagSet,             // v0.144 — the boolean flags of that result, without values
   splitTopLevelSegments, // compound-grep — quote-aware top-level segment splitter (PostToolUse reuse)
   firstShellClause,      // v0.96 — grep's own clause (up to first top-level separator)
   extractDeclSymbols,    // v0.49 — show-mode symbol extraction

package/claude-plugin/templates/code-graph-snapshot.yml

@@ -35,7 +35,7 @@ jobs:
           node-version: '20'
       - name: Build snapshot
         run: |
-          npx -y -p @sdsrs/code-graph@0.143.0 code-graph-mcp snapshot create --out snapshot.db
+          npx -y -p @sdsrs/code-graph@0.145.0 code-graph-mcp snapshot create --out snapshot.db
           zstd -9 snapshot.db -o snapshot.db.zst
           mv snapshot.db.zst "code-graph-snapshot-${GITHUB_SHA:0:7}.db.zst"
       - name: Upload to release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.143.0",
+  "version": "0.145.0",
   "description": "MCP server that indexes codebases into an AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing",
   "license": "MIT",
   "repository": {
@@ -35,10 +35,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.143.0",
-    "@sdsrs/code-graph-linux-arm64": "0.143.0",
-    "@sdsrs/code-graph-darwin-x64": "0.143.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.143.0",
-    "@sdsrs/code-graph-win32-x64": "0.143.0"
+    "@sdsrs/code-graph-linux-x64": "0.145.0",
+    "@sdsrs/code-graph-linux-arm64": "0.145.0",
+    "@sdsrs/code-graph-darwin-x64": "0.145.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.145.0",
+    "@sdsrs/code-graph-win32-x64": "0.145.0"
   }
 }