@tekyzinc/gsd-t 5.18.10 → 5.19.10

package/bin/gsd-t.js

@@ -514,6 +514,24 @@ const FALLBACK_HOOK_MARKER = "gsd-t-fallback-guard";
 const FALLBACK_HOOK_COMMAND =
   'node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-fallback-guard.js"';
 
+// ─── M117 Graph search guard (PreToolUse Bash|Grep) ─────────────────────────
+// Blocks a search that asks a structural question about code, and names the
+// graph command that answers it. NO `|| true`, for the same reason as the
+// fallback guard: a missing script must fail loudly, not silently re-open the
+// hole. The hole it closes is specific — the Grep-tool and Read-tool hooks
+// never fired, because bypass mode routes every search through Bash.
+const GRAPH_SEARCH_HOOK_MARKER = "gsd-t-graph-search-guard";
+const GRAPH_SEARCH_HOOK_COMMAND =
+  'node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-graph-search-guard.js"';
+
+// ─── M117 Graph use report (Stop) ───────────────────────────────────────────
+// Reports a turn that hit structural questions and never asked the graph. It
+// reports rather than blocks: a Stop hook fires after the work is done, so
+// blocking there punishes rather than redirects. Prevention is the guard above.
+const GRAPH_USE_REPORT_MARKER = "gsd-t-graph-use-report";
+const GRAPH_USE_REPORT_COMMAND =
+  'bash -c \'[ -f "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-graph-use-report.js" ] && node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-graph-use-report.js" || true\'';
+
 // ─── M108 Install self-heal (SessionStart) ──────────────────────────────────
 // Checks the project's tools before any work starts, restores what is missing,
 // and reports what it could not fix. Not a fallback — it repairs the failure
@@ -992,6 +1010,69 @@ function configureFallbackGuardHook(settingsPath) {
   return configureWriteEditHook(settingsPath, FALLBACK_HOOK_MARKER, FALLBACK_HOOK_COMMAND, "fallback guard");
 }
 
+// M117 — register the graph search guard on Bash|Grep. Both doors: bypass mode
+// routes searches through Bash, and leaving either open makes it the habit.
+function configureGraphSearchGuardHook(settingsPath) {
+  return configurePreToolUseHook(
+    settingsPath, GRAPH_SEARCH_HOOK_MARKER, GRAPH_SEARCH_HOOK_COMMAND,
+    "graph search guard", "Bash|Grep"
+  );
+}
+
+// M117 — register the Stop-time graph use report.
+function configureGraphUseReportHook(settingsPath) {
+  return configureStopHook(
+    settingsPath, GRAPH_USE_REPORT_MARKER, GRAPH_USE_REPORT_COMMAND, "graph use report"
+  );
+}
+
+// Register a Stop hook by marker. Same find-refresh-or-add shape as the
+// PreToolUse registrar; Stop entries carry no matcher.
+function configureStopHook(settingsPath, marker, command, label) {
+  const targetPath = settingsPath || SETTINGS_JSON;
+  let settings = {};
+  if (fs.existsSync(targetPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+      if (!settings || typeof settings !== "object") settings = {};
+    } catch {
+      warn(`settings.json has invalid JSON — cannot configure ${label} hook`);
+      return { installed: false, action: "noop" };
+    }
+  }
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.Stop)) settings.hooks.Stop = [];
+
+  let action = "noop";
+  let found = false;
+  for (const entry of settings.hooks.Stop) {
+    if (!entry || !Array.isArray(entry.hooks)) continue;
+    for (const h of entry.hooks) {
+      if (!h || typeof h.command !== "string") continue;
+      if (h.command === command || h.command.includes(marker)) {
+        found = true;
+        if (h.command !== command) { h.command = command; action = "updated"; }
+      }
+    }
+  }
+  if (!found) {
+    settings.hooks.Stop.push({ hooks: [{ type: "command", command }] });
+    action = "added";
+  }
+  if (action === "noop") return { installed: true, action: "noop" };
+  if (isSymlink(targetPath)) {
+    warn("Skipping settings.json write — target is a symlink");
+    return { installed: false, action: "noop" };
+  }
+  try {
+    fs.writeFileSync(targetPath, JSON.stringify(settings, null, 2));
+  } catch (e) {
+    warn(`Failed to write settings.json: ${e.message}`);
+    return { installed: false, action: "noop" };
+  }
+  return { installed: true, action };
+}
+
 // M107 RETIRED (v5.11.15). The rewriter shortened a reply after it was written,
 // and a Stop hook cannot unsay what is already on screen — so David read the
 // long version, then the short one. It also cost a whole extra turn, and its
@@ -1097,6 +1178,13 @@ function configureEventHook(settingsPath, event, marker, command, label) {
 }
 
 function configureWriteEditHook(settingsPath, marker, command, label) {
+  return configurePreToolUseHook(settingsPath, marker, command, label, "Write|Edit");
+}
+
+// M117 — the same registrar, with the matcher named rather than assumed. The
+// graph search guard watches Bash|Grep, not Write|Edit, and a second copy of
+// this function is where the two would drift apart.
+function configurePreToolUseHook(settingsPath, marker, command, label, matcher) {
   const targetPath = settingsPath || SETTINGS_JSON;
   let settings = {};
   if (fs.existsSync(targetPath)) {
@@ -1121,13 +1209,13 @@ function configureWriteEditHook(settingsPath, marker, command, label) {
       if (h.command === cmd || h.command.includes(marker)) {
         found = true;
         if (h.command !== cmd) { h.command = cmd; action = "updated"; }
-        if (entry.matcher !== "Write|Edit") { entry.matcher = "Write|Edit"; action = action === "noop" ? "updated" : action; }
+        if (entry.matcher !== matcher) { entry.matcher = matcher; action = action === "noop" ? "updated" : action; }
       }
     }
   }
   if (!found) {
     settings.hooks.PreToolUse.push({
-      matcher: "Write|Edit",
+      matcher,
       hooks: [{ type: "command", command: cmd }],
     });
     action = "added";
@@ -1806,6 +1894,9 @@ const GLOBAL_BIN_TOOLS = [
   // write rather than allowing it unchecked, so an omission here breaks every
   // Write/Edit rather than failing silently. Also in PROJECT_BIN_TOOLS below.
   "gsd-t-fallback-detect.cjs",
+  // M117 — Search classifier. The graph search guard resolves it from the
+  // package when a project has no copy, so it must ship globally too.
+  "gsd-t-code-search-classifier.cjs",
   // M108 — Install self-check, run by the SessionStart hook and by
   // `gsd-t install-check`.
   "gsd-t-install-check.cjs",
@@ -2346,6 +2437,25 @@ async function doInstall(opts = {}) {
   }
 
 
+  // M117 — the graph search guard and its Stop-time report. The graph rule had
+  // three enforcement points before this and all three missed the path actually
+  // taken: the Grep-tool and Read-tool hooks never fire in bypass mode (every
+  // search goes out through Bash), and the runtime use-gate only runs inside
+  // verify, never in a plain conversation.
+  const gsHook = configureGraphSearchGuardHook(SETTINGS_JSON);
+  if (gsHook.installed) {
+    if (gsHook.action === "added") success("Graph search guard added (blocks a structural code search, names the graph query — M117)");
+    else if (gsHook.action === "updated") success("Graph search guard refreshed");
+    else info("Graph search guard already configured");
+  }
+
+  const gurHook = configureGraphUseReportHook(SETTINGS_JSON);
+  if (gurHook.installed) {
+    if (gurHook.action === "added") success("Graph use report added (flags a turn that did structural work without asking the graph — M117)");
+    else if (gurHook.action === "updated") success("Graph use report refreshed");
+    else info("Graph use report already configured");
+  }
+
   const ccHook = removeConciseHook(SETTINGS_JSON);
   if (ccHook.removed) success("Concise-rewrite hook removed — retired in v5.11.15");
 
@@ -3507,6 +3617,11 @@ const PROJECT_BIN_TOOLS = [
   // and it reads the project's OWN .gsd-t/graphDB/logs ledger, so it must live
   // in the project — [[project_global_bin_propagation_gap]].
   "gsd-t-graph-use-gate.cjs",
+  // M117 — Search classifier for the graph search guard. The PreToolUse guard
+  // prefers the project-local copy and DENIES every search if it cannot load
+  // one, so an omission here blocks all work rather than failing quietly —
+  // [[project_global_bin_propagation_gap]].
+  "gsd-t-code-search-classifier.cjs",
   // M107 — Concise rewriter, invoked by the Stop hook.
   // M108 — Install self-check. Every project carries its own copy so it can
   // verify and repair itself even when the global install is what broke.

package/commands/cpua.md

@@ -133,8 +133,16 @@ if [ "$ON_DISK" != "{NEW_VERSION}" ]; then
   ON_DISK=$(node -p "require('$G/package.json').version")
   [ "$ON_DISK" = "{NEW_VERSION}" ] || { echo "HALT: global install still $ON_DISK"; exit 1; }
 fi
-# 3. Only now propagate.
+# 3. Refresh the HOME install (commands + ~/.claude/.gsd-t-version) BEFORE propagating.
+#    v5.18.10 (2026-09-03): with the version file still on the old number, `update-all`
+#    reported all 33 projects "already current", copied nothing, and the global package
+#    was found back on the old version afterwards. `gsd-t install` writes the version
+#    file and the command files; only then does update-all see the new release.
+gsd-t install 2>&1 | tail -5
+[ "$(cat ~/.claude/.gsd-t-version)" = "{NEW_VERSION}" ] || { echo "HALT: ~/.claude/.gsd-t-version did not advance"; exit 1; }
+# 4. Propagate, then prove the global is STILL the new version and a NEW file reached a project.
 gsd-t update-all 2>&1 | tail -30
+[ "$(node -p "require('$G/package.json').version")" = "{NEW_VERSION}" ] || { echo "HALT: global package reverted during update-all"; exit 1; }
 ```
 
 Never `npm update -g` (npm rejects it for legacy version strings like `3.19.00`). After `update-all`, prove propagation by `ls`/`grep` of one NEW or CHANGED file in a real registered project — the "copied N tool(s)" line is a report, not proof. Note: `update-all` also overwrites `~/.claude/commands/*.md` from the package, so THIS file's source of truth is `commands/cpua.md` in the GSD-T repo; an edit made only in `~/.claude/commands/` is lost on the next propagation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.18.10",
+  "version": "5.19.10",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/scripts/gsd-t-graph-search-guard.js

@@ -0,0 +1,490 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-graph-search-guard.js
+ *
+ * M117 - PreToolUse hook on Bash and Grep. Blocks a search that asks a
+ * structural question about code, and names the graph command that answers it.
+ *
+ * [RULE] search-guard-blocks-structural-code-search
+ * [RULE] search-guard-unclear-blocks-never-allows
+ * [RULE] search-guard-missing-graph-blocks-never-degrades
+ *
+ * WHY THIS EXISTS
+ *   The graph rule already said "query the graph, do not grep around it", and
+ *   two hooks already enforced it - on the Grep tool and the Read tool. Neither
+ *   ever fired in real work. In bypass-permissions mode the standing house rule
+ *   is to work through Bash, so every structural search went out as `grep` in a
+ *   Bash call and sailed past both hooks. The ledger records the result: two
+ *   grep events in three months, both from June test probes, against 34,418
+ *   graph queries all from the graph's own tooling. The rule had no trigger on
+ *   the path actually taken.
+ *
+ * THE THREE OUTCOMES (there is no fourth, and none of them continues past a
+ * failure):
+ *   structural  BLOCK. Print the graph command to run instead.
+ *   content     ALLOW. Markdown, JSON, SQL, config, prose - the graph does not
+ *               index them, so it has no answer to route to. Not a bypass.
+ *   unclear     BLOCK. The classifier could not read the intent, and guessing
+ *               "probably text" is the guess that keeps the rule toothless.
+ *
+ * A MISSING OR BROKEN GRAPH ALSO BLOCKS. Allowing the grep because the graph is
+ * unavailable is the exact fallback that hid the binvoice failure - a project
+ * grepping its way through 827 files while the graph sat unbuilt. The answer is
+ * `gsd-t graph index`, which the block message says.
+ *
+ * WHAT IT CANNOT SEE, STATED PLAINLY: it governs tool calls, not reasoning.
+ * Reading a file end to end to work out who calls something leaves no pattern
+ * for any guard to match. The Stop-time check (gsd-t-graph-use-report.js) is
+ * what covers that, by comparing structural work against graph queries issued.
+ *
+ * --- Stdin (Claude Code PreToolUse payload) --------------------------------
+ *   { "tool_name": "Bash"|"Grep", "cwd": "...",
+ *     "tool_input": { "command": "..." } | { "pattern": "...", "glob": "..." } }
+ *
+ * --- Decision contract -----------------------------------------------------
+ *   Deny:  {"hookSpecificOutput":{"hookEventName":"PreToolUse",
+ *           "permissionDecision":"deny","permissionDecisionReason":"..."}}
+ *   Allow: exit 0, no output.
+ *
+ * Zero dependencies.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+function deny(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  }) + "\n");
+  process.exit(0);
+}
+
+function allow() { process.exit(0); }
+
+/**
+ * Locate the classifier. A project without one has an incomplete install, and
+ * the repair is `gsd-t install-check` - not a hunt for a copy elsewhere, and
+ * not silently letting every search through.
+ */
+function findClassifier(projectDir) {
+  const inProject = path.join(projectDir, "bin", "gsd-t-code-search-classifier.cjs");
+  if (fs.existsSync(inProject)) return inProject;
+
+  const inPackage = path.join(__dirname, "..", "bin", "gsd-t-code-search-classifier.cjs");
+  if (fs.existsSync(inPackage)) return inPackage;
+
+  throw new Error(
+    "This project has no copy of the search classifier at " + inProject + ", which " +
+    "means its GSD-T install is incomplete. Run 'gsd-t install-check' to repair it."
+  );
+}
+
+/** Thrown when the settings file exists but cannot be understood. */
+class ConfigUnreadable extends Error {}
+
+/**
+ * Is the guard switched on for this project?
+ * An unreadable settings file throws - assuming "on" or "off" would be a guess
+ * about what the project wanted. Only an ABSENT file means on, because absence
+ * is unambiguous.
+ */
+function isEnabled(projectDir) {
+  const p = path.join(projectDir, ".gsd-t", "graph-search-gate.json");
+  if (!fs.existsSync(p)) return true;
+  let raw;
+  try {
+    raw = fs.readFileSync(p, "utf8");
+  } catch (e) {
+    throw new ConfigUnreadable(p + " could not be read: " + e.message);
+  }
+  const cfg = JSON.parse(raw);
+  return cfg.enabled !== false;
+}
+
+// --- Command parsing -------------------------------------------------------
+//
+// Split a shell command into its pipeline stages, then look at each stage that
+// runs a search program. A structural search buried in the middle of a pipe is
+// still a structural search.
+
+const SEARCH_PROGRAMS = new Set(["grep", "egrep", "fgrep", "rg", "ripgrep", "ag", "ack", "find", "ugrep"]);
+
+// Flags that take a value in the NEXT argument, so that value is not the pattern.
+const FLAGS_TAKING_VALUE = new Set([
+  "-e", "--regexp", "-f", "--file", "--include", "--exclude", "--glob", "-g",
+  "-m", "--max-count", "-A", "-B", "-C", "--after-context", "--before-context",
+  "--context", "-d", "--directories", "--color", "--colour", "-t", "--type",
+  "-name", "-iname", "-path", "-type", "-maxdepth", "-mindepth",
+]);
+
+/**
+ * Break a command line into tokens, keeping quoted runs together and dropping
+ * the quotes. Good enough for reading a search invocation; it is not a shell.
+ */
+function tokenize(command) {
+  const tokens = [];
+  let cur = "";
+  let quote = null;
+  let started = false;
+
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i];
+
+    if (quote) {
+      if (ch === quote) { quote = null; continue; }
+      cur += ch;
+      started = true;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; started = true; continue; }
+    if (ch === "\\" && i + 1 < command.length) { cur += command[i + 1]; started = true; i++; continue; }
+    if (/\s/.test(ch)) {
+      if (started) { tokens.push(cur); cur = ""; started = false; }
+      continue;
+    }
+    cur += ch;
+    started = true;
+  }
+  if (started) tokens.push(cur);
+  return tokens;
+}
+
+/** Split a token list on shell stage separators. */
+function pipelineStages(tokens) {
+  const SEPARATORS = new Set(["|", "||", "&&", ";", "&"]);
+  const stages = [];
+  let cur = [];
+  for (const t of tokens) {
+    if (SEPARATORS.has(t)) {
+      if (cur.length) stages.push(cur);
+      cur = [];
+      continue;
+    }
+    cur.push(t);
+  }
+  if (cur.length) stages.push(cur);
+  return stages;
+}
+
+
+// --- Where the pattern sits, one reader per spelling -----------------------
+
+function hasExplicitRegexpFlag(argv) {
+  for (const a of argv) {
+    if (a === "-e") return true;
+    if (a === "--regexp") return true;
+  }
+  return false;
+}
+
+function patternFromRegexpFlag(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "-e" || argv[i] === "--regexp") return argv[i + 1];
+  }
+  return null;
+}
+
+function patternFromNameFlag(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "-name" || argv[i] === "-iname") return argv[i + 1];
+  }
+  return null;
+}
+
+function firstPositional(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (FLAGS_TAKING_VALUE.has(a)) { i++; continue; }
+    if (a.startsWith("-")) continue;
+    return a;
+  }
+  return null;
+}
+
+/**
+ * From one pipeline stage, work out the search program and its pattern.
+ * Returns null when the stage runs no search program.
+ */
+function readSearchStage(stage) {
+  let idx = 0;
+
+  // Step past environment assignments and common prefixes.
+  while (idx < stage.length) {
+    const t = stage[idx];
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(t)) { idx++; continue; }
+    if (t === "sudo" || t === "command" || t === "time" || t === "xargs") { idx++; continue; }
+    break;
+  }
+  if (idx >= stage.length) return null;
+
+  const program = path.basename(stage[idx]);
+  if (!SEARCH_PROGRAMS.has(program)) return null;
+
+  const argv = stage.slice(idx + 1);
+
+  // Where the pattern sits depends only on how the command was spelled. These
+  // are three SPELLINGS of the same argument, not three attempts with earlier
+  // ones falling back to later ones: `find` always carries it after -name,
+  // grep-family tools carry it after -e when that flag is used and positionally
+  // otherwise. Which reader applies is decided up front, from the command
+  // itself, so nothing here substitutes for a value that went missing.
+  const pattern = program === "find"
+    ? patternFromNameFlag(argv)
+    : (hasExplicitRegexpFlag(argv) ? patternFromRegexpFlag(argv) : firstPositional(argv));
+
+  // A search program was invoked but no pattern could be read out of it. That
+  // is NOT "no search here" - it is a search this guard could not inspect, and
+  // reporting null would let it run unexamined. It is returned as unreadable so
+  // the caller blocks and says so.
+  if (typeof pattern !== "string") {
+    return { program, pattern: null, argv, unreadable: true };
+  }
+  return { program, pattern, argv, unreadable: false };
+}
+
+// --- Graph availability ----------------------------------------------------
+//
+// A structural question needs a graph to answer it. No graph is a BLOCK with
+// "build it", never a quiet permission to grep instead.
+
+function graphStorePath(projectDir) {
+  const candidates = [
+    path.join(projectDir, ".gsd-t", "graphDB", "graph.db"),
+    path.join(projectDir, ".gsd-t", "graph.db"),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+function buildNoGraphReason(found, cls) {
+  return [
+    "This is a structural question about code, and this project has no code graph built.",
+    "",
+    "  searching for: " + found.pattern,
+    "  which is:      " + cls.reason,
+    "",
+    "Build the graph, then ask it:",
+    "",
+    "  gsd-t graph index",
+    "",
+    "Grepping instead would answer a question about relationships by matching text,",
+    "which is a different and wrong answer. A missing graph is a repairable condition,",
+    "not a reason to fall back to grep.",
+  ].join("\n");
+}
+
+function buildStructuralReason(found, cls) {
+  const lines = [];
+
+  const symbol = cls.symbol === null ? found.pattern : cls.symbol;
+  const verb = cls.verb === null ? "who-calls" : cls.verb;
+
+  lines.push(
+    "This is a structural question about code. The graph answers it; grep only matches text.",
+    "",
+    "  searching for: " + found.pattern,
+    "  which is:      " + cls.reason,
+    "",
+    "Ask the graph instead:",
+    "",
+    "  gsd-t graph " + verb + " " + symbol,
+    "",
+    "Other verbs: who-imports, who-calls, defines, blast-radius, body.",
+    "",
+    "If this really is a text search - a phrase in prose, a key in config, a string in a",
+    "document - scope it to the files the graph does not index, and it will run:",
+    "",
+    "  grep --include='*.md' --include='*.json' ..."
+  );
+  return lines.join("\n");
+}
+
+function buildUnclearReason(found, cls) {
+  return [
+    "This search could be asking about code structure, and that has to be settled before",
+    "it runs - a guess in either direction is how the graph rule stopped having teeth.",
+    "",
+    "  searching for: " + found.pattern,
+    "  why unclear:   " + cls.reason,
+    "",
+    "Say which it is:",
+    "",
+    "  Structure (who calls, who imports, where defined):",
+    "    gsd-t graph who-calls <symbol>",
+    "",
+    "  Text in files the graph does not index (.md, .json, .sql, config, prose):",
+    "    add --include='*.md' (or the right extensions) and run it again",
+  ].join("\n");
+}
+
+
+// --- Recording the decision ------------------------------------------------
+//
+// One line per block, into the same ledger the graph's own tooling writes. The
+// Stop-time report reads these to spot a turn that hit structural questions and
+// never asked the graph. Writing it must never change the decision, so a sink
+// failure is swallowed here and nowhere else in this file.
+
+function recordBlock(projectDir, program, pattern, verdict) {
+  try {
+    const dir = path.join(projectDir, ".gsd-t", "graphDB", "logs");
+    if (!fs.existsSync(dir)) return;
+    let names = fs.readdirSync(dir)
+      .filter((n) => n.startsWith("graph-events-") && n.endsWith(".jsonl"));
+    if (names.length === 0) return;
+    names.sort();
+    const file = path.join(dir, names[names.length - 1]);
+    const line = JSON.stringify({
+      kind: "search-blocked",
+      ts: new Date().toISOString(),
+      program,
+      verdict,
+      patternShape: String(pattern).slice(0, 120),
+      consumer: "search-guard",
+    });
+    fs.appendFileSync(file, line + "\n");
+  } catch (e) {
+    // The block still happens - the decision is made above and does not depend
+    // on this record. But the failure is SAID, not swallowed: the Stop-time
+    // report reads these lines, so a ledger that silently stopped accepting
+    // them would make that report quietly under-count and look clean.
+    // stderr, because stdout carries the permission decision.
+    process.stderr.write(
+      "[GSD-T GRAPH] the search-block record could not be written (" + e.message + "). " +
+      "The search was still blocked; the Stop-time graph-use report will under-count.\n"
+    );
+  }
+}
+
+function main() {
+  let input = "";
+  let done = false;
+
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (c) => { input += c; });
+  process.stdin.on("end", () => {
+    if (done) return;
+    done = true;
+    decide(input);
+  });
+
+  // A payload that never arrives is not a search to judge. Exiting 0 here is
+  // "nothing was asked", not "a failure was ignored".
+  setTimeout(() => {
+    if (done) return;
+    done = true;
+    decide(input);
+  }, 4000);
+}
+
+function decide(raw) {
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    // No readable payload means no search to classify. Not applicable.
+    allow();
+    return;
+  }
+
+  const toolName = payload.tool_name;
+  if (toolName !== "Bash" && toolName !== "Grep") { allow(); return; }
+
+  const projectDir = typeof payload.cwd === "string" ? payload.cwd : process.cwd();
+
+  // Not a GSD-T project - this rule is GSD-T's, so it does not apply.
+  if (!fs.existsSync(path.join(projectDir, ".gsd-t"))) { allow(); return; }
+
+  let enabled;
+  try {
+    enabled = isEnabled(projectDir);
+  } catch (e) {
+    deny(
+      "The graph-search gate's settings could not be read, so it cannot be known whether " +
+      "this search is allowed: " + e.message + "\n\n" +
+      "Fix or delete .gsd-t/graph-search-gate.json."
+    );
+    return;
+  }
+  if (!enabled) { allow(); return; }
+
+  let classifySearch;
+  try {
+    const mod = require(findClassifier(projectDir));
+    classifySearch = mod.classifySearch;
+  } catch (e) {
+    deny("The graph-search gate could not load its classifier: " + e.message);
+    return;
+  }
+
+  // Gather the search stages this call would run.
+  const found = [];
+  if (toolName === "Grep") {
+    const gi = payload.tool_input;
+    if (!gi) { allow(); return; }
+    const argv = [];
+    if (typeof gi.glob === "string") { argv.push("--glob", gi.glob); }
+    if (typeof gi.path === "string") { argv.push(gi.path); }
+    if (typeof gi.type === "string") { argv.push("-t" + gi.type); }
+    if (typeof gi.pattern !== "string") { allow(); return; }
+    found.push({ program: "rg", pattern: gi.pattern, argv });
+  } else {
+    const command = payload.tool_input === undefined ? undefined : payload.tool_input.command;
+    if (typeof command !== "string") { allow(); return; }
+    for (const stage of pipelineStages(tokenize(command))) {
+      const s = readSearchStage(stage);
+      if (s !== null) found.push(s);
+    }
+  }
+
+  if (found.length === 0) { allow(); return; }
+
+  const hasGraph = graphStorePath(projectDir) !== null;
+
+  for (const f of found) {
+    // A search whose pattern could not be read is a search that cannot be
+    // judged. It blocks: letting it through would be deciding it is safe on
+    // the strength of evidence that could not be gathered.
+    if (f.unreadable === true) {
+      deny(
+        "A " + f.program + " search was invoked but this guard could not read what it " +
+        "searches for, so it cannot tell whether the code graph should answer it instead.\n\n" +
+        "Rewrite it so the pattern is a plain argument (or use -e <pattern>), or ask the " +
+        "graph directly:\n\n  gsd-t graph who-calls <symbol>"
+      );
+      return;
+    }
+
+    let cls;
+    try {
+      cls = classifySearch({ pattern: f.pattern, argv: f.argv, program: f.program });
+    } catch (e) {
+      deny("The graph-search gate could not classify this search: " + e.message);
+      return;
+    }
+
+    if (cls.verdict === "structural") {
+      recordBlock(projectDir, f.program, f.pattern, "structural");
+      if (hasGraph) deny(buildStructuralReason(f, cls));
+      else deny(buildNoGraphReason(f, cls));
+      return;
+    }
+    if (cls.verdict === "unclear") {
+      recordBlock(projectDir, f.program, f.pattern, "unclear");
+      deny(buildUnclearReason(f, cls));
+      return;
+    }
+  }
+
+  allow();
+}
+
+main();