@cstart/coldstart 2.0.0

package/hooks/codex-nudge-handler.mjs

@@ -0,0 +1,370 @@
+/**
+ * codex-nudge-handler.mjs — Codex PostToolUse nudge for `find`/`gs`, CLI and MCP.
+ *
+ * The agent may reach coldstart via the CLI (Bash `coldstart find/gs`) or the MCP
+ * tools (`mcp__coldstart__find/gs`). normalizeColdstartCall rewrites an MCP call
+ * into the equivalent CLI command string so every detector below runs unchanged on
+ * either surface — same logic, only the entry tool name differs.
+ *
+ * Fires advisory nudges (additionalContext) at the moments the agent's search
+ * behaviour goes wrong. Detectors, each fires sparingly:
+ *
+ *   1. READ-AFTER-2-FINDS  — ran `coldstart find` twice with no Read/gs in between
+ *                            => stop searching, open a candidate.
+ *   2. EMPTY-SEARCH        — a grep/glob/shell-find returned nothing
+ *                            => empty != absent; refine find or read what you have.
+ *   3. NONFIND-SHELL-3     — 3 non-find search/shell calls since last find/Read/gs
+ *                            => the spiral; go back to find or read.
+ *   3b. NO-NEW-EVIDENCE    — a grep/find CONFINED to files already in context
+ *                            => re-checks surfaced data, can't reveal a new file.
+ *                            Recall-safe: any call surfacing a new file is silent.
+ *   4. CHECKPOINT          — every CHECKPOINT_EVERY tool calls
+ *                            => can you answer from what you've read? name the gap.
+ *   5. GS-OVER-SLICE       — sliced the SAME file with `gs` >= GS_SLICE_CAP times
+ *                            => you have its bodies + pointers; answer or move on.
+ *   6. GS-REGUESS          — re-called `gs --symbol` on a file that just returned
+ *                            the method-menu fallback => pick from the menu.
+ *
+ * Also REGISTERS the canonical key of every SUCCESSFUL (non-empty) find into
+ * `seen_find_queries` — the Codex PreToolUse guard denies a re-run of
+ * a registered key. The key fn is shared (canonical-find-key.mjs); it MUST match
+ * the guard exactly or the deny-key and registration-key drift.
+ *
+ * State per (session,agent) in /tmp. Fail-open: any error → null (runHook swallows).
+ *
+ * Ported 1:1 from find-nudge.py. Thresholds below are the same defaults.
+ */
+
+import { readFileSync, writeFileSync, renameSync, existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { canonicalFindKey } from "./canonical-find-key.mjs";
+import { normalizeColdstartCall } from "./coldstart-call.mjs";
+
+// hooks/ sits beside dist/ in both the repo and the published package.
+const KB_CLI = fileURLToPath(new URL("../dist/index.js", import.meta.url));
+
+// ---- detector thresholds (tune freely) ----
+const FINDS_BEFORE_READ = 2; // (1) nudge to read after this many finds w/o a Read/gs
+const NONFIND_SHELL_STREAK = 3; // (3) nudge after this many non-find search/shell calls
+const CHECKPOINT_EVERY = 12; // (4) checkpoint nudge cadence, in tool calls
+const GS_SLICE_CAP = 3; // (5) nudge once gs has sliced the SAME file this many times
+const EMPTY_NUDGE_CAP = 2; // (2) max empty-search nudges per session
+const REDUNDANT_CAP = 6; // (3b) max no-new-evidence nudges per session
+
+// coldstart find (the GOOD locator)
+const FIND_RE = /coldstart\s+find\b|index\.js\s+find\b/;
+// coldstart gs (the GOOD reader — slices symbol bodies): read-equivalent for the
+// spiral, but with its own abuse modes (over-slice, re-guess after a menu fallback).
+const GS_RE = /coldstart\s+gs\b|index\.js\s+gs\b/;
+// coldstart kb (notebook search/write) — proves the session is coldstart-aware.
+const KB_RE = /coldstart\s+kb\b|index\.js\s+kb\b/;
+// the gs menu-fallback marker (printed when --symbol isn't a declared symbol)
+const GS_FALLBACK_RE = /NOT a declared symbol here|no declared symbol matches/;
+// search/shell that ISN'T coldstart find/gs — the spiral surface
+const SEARCH_RE =
+  /(^|[;&|]|\s)(grep|egrep|fgrep|rg)\b|git\s+grep|git\s+log|(^|[;&|]|\s)find\s|(^|[;&|]|\s)ls\b|(^|[;&|]|\s)cat\b/;
+const GS_FILE_RE = /(?:coldstart|index\.js)\s+gs\s+(\S+)/;
+
+// Evidence store regexes — paths printed in ANY output, and files named as ARGS.
+const PATH_RE = /[\w./-]+\.(?:py|js|jsx|ts|tsx|htm|html|vue|json|scss|css|rb|java)/g;
+const FILE_ARG_RE =
+  /(?<![\w/])([\w][\w./-]*\.(?:py|js|jsx|ts|tsx|htm|html|vue|json|scss|css|rb|java))\b/g;
+
+/** Mirror of find-nudge.py result_text: extract the raw text payload of a tool
+ * response, collapsing a present-but-empty stdout to "" (NOT to the JSON of the
+ * whole envelope, which would hide emptiness). */
+function resultText(input) {
+  let r = input.tool_response;
+  if (r === undefined) r = input.tool_output;
+  if (r === undefined || r === null) return null;
+  if (typeof r === "string") return r;
+  if (Array.isArray(r)) {
+    return r
+      .map((x) => (x && typeof x === "object" ? x.text || "" : String(x)))
+      .join(" ");
+  }
+  if (typeof r === "object") {
+    const KEYS = ["stdout", "stderr", "content", "output", "result"];
+    if (KEYS.some((k) => k in r)) {
+      return KEYS.map((k) => String(r[k] ?? "")).join("");
+    }
+    return JSON.stringify(r);
+  }
+  return String(r);
+}
+
+function matchAllGroup(re, s, group) {
+  const found = new Set();
+  if (!s) return found;
+  for (const m of s.matchAll(re)) found.add(group ? m[group] : m[0]);
+  return found;
+}
+
+/** The pattern the agent is grepping for — first quoted string or bare arg
+ *  after the grep/rg invocation. Empty when nothing sensible is extractable. */
+function grepPattern(cmd) {
+  const m = String(cmd || "").match(
+    /(?:^|[;&|]\s*|\s)(?:grep|egrep|fgrep|rg|git\s+grep)\s+(?:-{1,2}[\w=-]+\s+)*(?:"([^"]+)"|'([^']+)'|([^\s'"|;&-]\S*))/,
+  );
+  return m ? (m[1] || m[2] || m[3] || "").replace(/[\\^$.*+?()[\]{}]/g, " ").trim() : "";
+}
+
+/** Hit-gated notebook probe for the spiral nudge: ONE hook-mode kb search on
+ *  what the agent is grepping for. Returns the top note's title, or null —
+ *  and the nudge only mentions the notebook when a note actually exists
+ *  (a generic "try the notebook" would be boilerplate steering; a hit is a
+ *  report of fact). Fail-open and skipped entirely when there's no notebook. */
+function kbSpiralHit(root, pattern) {
+  try {
+    if (!pattern || !root || !existsSync(join(root, ".coldstart", "notebook", ".raw"))) return null;
+    const page = execFileSync(
+      "node", [KB_CLI, "kb", "search", "--hook", "--max", "1", "--root", root, pattern],
+      { encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] },
+    );
+    const m = page.match(/^- \*\*(.+?)\*\*/m);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {any} input parsed PostToolUse stdin payload
+ * @returns {object|null} an additionalContext envelope, or null for no nudge
+ */
+export default function handle(input) {
+  const sid = input.session_id || "default";
+  const aid = input.agent_id || ""; // set when inside a subagent
+  const tin = input.tool_input && typeof input.tool_input === "object" ? input.tool_input : {};
+  // Collapse CLI and MCP coldstart calls to one shape: an MCP find/gs becomes a
+  // synthetic `coldstart find/gs ...` Bash command so the detectors run unchanged.
+  const { tool, cmd } = normalizeColdstartCall(input.tool_name || "", tin);
+  const out = resultText(input);
+
+  const key = aid ? `${sid}_${aid}` : sid;
+  const stateFile = `/tmp/find_nudge_${key}.json`;
+  const st = {
+    seen_find: false,
+    total: 0,
+    finds_since_read: 0,
+    nonfind_streak: 0,
+    empty_fired: 0,
+    last_checkpoint: 0,
+    read_fired: false,
+    shell_fired: false,
+    gs_counts: {},
+    gs_slice_fired: [],
+    last_gs_fallback: "",
+    gs_reguess_fired: false,
+    held_files: [],
+    redundant_fired: 0,
+    seen_find_queries: [],
+  };
+  try {
+    Object.assign(st, JSON.parse(readFileSync(stateFile, "utf8")));
+  } catch {
+    /* defaults */
+  }
+
+  // classify this call
+  const isFind = tool === "Bash" && FIND_RE.test(cmd);
+  const isGs = tool === "Bash" && GS_RE.test(cmd);
+  const isKb = tool === "Bash" && KB_RE.test(cmd);
+  let gsFile = "";
+  if (isGs) {
+    const gm = GS_FILE_RE.exec(cmd);
+    gsFile = gm ? gm[1] : "";
+  }
+  const prevFallback = st.last_gs_fallback || ""; // set by the PREVIOUS gs call's output
+  const isRead = tool === "Read";
+  // gs/find/kb are tools, not the grep-spiral, even when piped to head/grep
+  const isSearch =
+    tool === "Grep" ||
+    tool === "Glob" ||
+    (tool === "Bash" && !isFind && !isGs && !isKb && SEARCH_RE.test(cmd));
+  const isNonfindShell = isSearch;
+
+  const _ob = out !== null && out !== undefined ? out.trim().toLowerCase() : null;
+  const outEmpty =
+    _ob !== null &&
+    (_ob === "" ||
+      _ob.includes("completed with no output") ||
+      _ob === "no matches found" ||
+      _ob === "no files found");
+
+  st.total += 1;
+  // seen_find gates the spiral detectors (3/3b): they stay silent for sessions that
+  // never touch coldstart at all (deliberate — this hook must not nag non-users).
+  // Any coldstart surface proves awareness: find (set below on the find branch),
+  // gs, a kb call, or a kb-recall injection (kb-recall.mjs pre-seeds this flag) —
+  // a note-implanted session may legitimately skip `find` because the note handed
+  // it the files, and it still needs the anti-grep-spiral coverage (the q23 case).
+  if (isGs || isKb) st.seen_find = true;
+  const msgs = []; // [priority, text]; lower priority number = more urgent, wins
+
+  // --- evidence: what files THIS call touched, and which are genuinely NEW ---
+  const held = new Set(st.held_files || []);
+  const outFiles = matchAllGroup(PATH_RE, out, 0);
+  const cmdFiles = matchAllGroup(FILE_ARG_RE, cmd, 1);
+  if (isRead) {
+    const rp = typeof tin.file_path === "string" ? tin.file_path : "";
+    if (rp) cmdFiles.add(rp);
+  }
+  const scope = new Set([...outFiles, ...cmdFiles]);
+  const novel = [...scope].filter((f) => !held.has(f)); // files newly in context
+
+  if (isFind) {
+    st.seen_find = true;
+    st.finds_since_read += 1;
+    st.nonfind_streak = 0;
+    st.shell_fired = false;
+    // register the canonical key ONLY on a successful (non-empty) result, so the
+    // PreToolUse guard never blocks a retry of a find that errored/returned nothing.
+    if (out && !outEmpty) {
+      const ck = canonicalFindKey(cmd);
+      if (ck && !st.seen_find_queries.includes(ck)) {
+        st.seen_find_queries = st.seen_find_queries.concat([ck]);
+      }
+    }
+    if (st.finds_since_read >= FINDS_BEFORE_READ && !st.read_fired) {
+      st.read_fired = true;
+      msgs.push([
+        2,
+        `You've run \`coldstart find\` ${st.finds_since_read}× without opening a file. ` +
+          "The page already ranks candidates and shows symbol + body lines WITH line numbers — " +
+          "stop searching and READ the 1–2 most promising now. Refine the query only if a file's " +
+          "actual contents send you elsewhere.",
+      ]);
+    }
+  } else if (isRead) {
+    st.finds_since_read = 0;
+    st.nonfind_streak = 0;
+    st.read_fired = false;
+    st.shell_fired = false;
+  } else if (isGs) {
+    // gs opens file content — credit it like a Read for the spiral/find counters.
+    st.finds_since_read = 0;
+    st.nonfind_streak = 0;
+    st.read_fired = false;
+    st.shell_fired = false;
+    const counts = st.gs_counts || {};
+    counts[gsFile] = (counts[gsFile] || 0) + 1;
+    st.gs_counts = counts;
+    const fired = st.gs_slice_fired || [];
+    // (6) GS-REGUESS — the previous gs on THIS file returned the method menu, and
+    // the agent is slicing it again instead of picking a name from that menu.
+    if (gsFile && prevFallback === gsFile && !st.gs_reguess_fired) {
+      st.gs_reguess_fired = true;
+      msgs.push([
+        2,
+        `\`${gsFile}\` just returned its method MENU — the \`--symbol\` name you passed isn't declared ` +
+          "there. Pick a name from that menu, or `Read` the file. Re-calling `gs --symbol` with another " +
+          "guessed name on the same file is the single most common wasted call — you already have the menu.",
+      ]);
+    } else if (gsFile && counts[gsFile] >= GS_SLICE_CAP && !fired.includes(gsFile)) {
+      // (5) GS-OVER-SLICE — sliced one file enough times; you have it.
+      fired.push(gsFile);
+      st.gs_slice_fired = fired;
+      msgs.push([
+        2,
+        `You've sliced \`${gsFile}\` ${counts[gsFile]}× with \`gs\` — you have its bodies plus the ` +
+          "`calls:`/`callers:` pointers, so you almost certainly have enough of THIS file. Answer from " +
+          "what you have, `Read` it whole if you need lines BETWEEN symbols, or follow a pointer to a " +
+          "DIFFERENT file. Stop re-slicing this one.",
+      ]);
+    }
+  } else if (isNonfindShell && st.seen_find) {
+    st.nonfind_streak += 1;
+    // (3b) NO-NEW-EVIDENCE — per-call: this grep/find is confined to files the
+    // agent ALREADY has in context, so it surfaced nothing new.
+    const confined = scope.size > 0 && novel.length === 0 && !outEmpty;
+    if (confined && (st.redundant_fired || 0) < REDUNDANT_CAP) {
+      st.redundant_fired = (st.redundant_fired || 0) + 1;
+      const heldHits = [...scope].sort().slice(0, 3);
+      const names = heldHits.map((f) => "`" + f + "`").join(", ");
+      msgs.push([
+        1,
+        `This search only touched files you ALREADY have in context — ${names}. You surfaced or read ` +
+          "them earlier, so re-grepping them returns lines you already hold; it cannot reveal a new file. " +
+          "The answer is in the results already in your context — RE-READ those (the find/gs page, the " +
+          "files you opened) and answer the task now. Only search if you can name a genuinely NEW file, " +
+          "identifier, or directory you have not yet covered.",
+      ]);
+    } else if (st.nonfind_streak >= NONFIND_SHELL_STREAK && !st.shell_fired) {
+      // (3) generic spiral fallback — non-find streak, but nothing was re-checked
+      st.shell_fired = true;
+      // Hit-gated notebook pointer: if the notebook already has a note on what
+      // the agent is hunting, say so — that note may END the hunt.
+      const noteTitle = kbSpiralHit(input.cwd, grepPattern(cmd));
+      msgs.push([
+        3,
+        `${st.nonfind_streak} non-find search/shell calls since your last \`coldstart find\`/Read — ` +
+          "this is the spiral. `coldstart find` already body-scans the top files and ranks on filenames " +
+          "and symbols, not just body text. Add the missing term and re-run it, or Read a candidate you " +
+          "already have. Reserve grep for a literal body string you KNOW exists." +
+          (noteTitle
+            ? ` Also: the repo notebook has a note matching what you're grepping for — "${noteTitle}". ` +
+              `Fetch it first: \`coldstart kb search ${noteTitle.split(/\s+/).slice(0, 5).join(" ")}\`.`
+            : ""),
+      ]);
+    }
+  }
+
+  // (2) empty search result — independent, capped
+  if (isSearch && outEmpty && st.empty_fired < EMPTY_NUDGE_CAP) {
+    st.empty_fired += 1;
+    msgs.push([
+      4,
+      "That search returned nothing. An empty result only tells you the term doesn't appear here — it is " +
+        "not evidence the thing is absent. If you're grepping a specific FILE for an identifier, run " +
+        "`coldstart gs <file> --symbol <token>` instead: it returns the body lines where the token appears " +
+        "(it greps in-tool), so you don't have to guess at spelling.",
+    ]);
+  }
+
+  // record whether THIS gs call hit the menu fallback, so the NEXT call can detect a re-guess
+  if (isGs) {
+    st.last_gs_fallback = out && GS_FALLBACK_RE.test(out) ? gsFile : "";
+  }
+
+  // (4) checkpoint — periodic, lowest urgency
+  if (st.total - st.last_checkpoint >= CHECKPOINT_EVERY) {
+    st.last_checkpoint = st.total;
+    msgs.push([
+      5,
+      `Checkpoint (${st.total} tool calls). Stop and think before the next call — answer these in order:\n` +
+        "1. Restate the task in one sentence — what is the ONE thing it asks for?\n" +
+        "2. List the files you have already surfaced or read that bear on it.\n" +
+        "3. Can you answer (1) from (2)? If YES — write the answer now and stop searching; you almost " +
+        "certainly have enough.\n" +
+        "4. Only if NO — name the single specific fact still missing, and make the next call target ONLY " +
+        "that. Do not re-run a search whose results are already in your context.",
+    ]);
+  }
+
+  // merge THIS call's evidence into the store (after novelty was computed above)
+  if (scope.size > 0) {
+    st.held_files = [...new Set([...held, ...scope])];
+  }
+
+  try {
+    const tmp = stateFile + ".tmp";
+    writeFileSync(tmp, JSON.stringify(st));
+    renameSync(tmp, stateFile);
+  } catch {
+    /* never fail on state write */
+  }
+
+  if (msgs.length) {
+    msgs.sort((a, b) => a[0] - b[0]);
+    return {
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: msgs[0][1],
+      },
+    };
+  }
+  return null;
+}

package/hooks/codex-preguard-handler.mjs

@@ -0,0 +1,75 @@
+/**
+ * codex-preguard-handler.mjs — Codex PreToolUse guard for `coldstart find`.
+ *
+ * `coldstart find` is a PURE function of its term-SET: reordering terms, changing
+ * case, or repeating a term yields byte-identical output (every ranking stage is
+ * set/sum based, sort is deterministic by score then unique path). So an exact
+ * re-query is PROVABLY redundant on a static index: its result is already in the
+ * agent's context. This handler canonicalizes a PROPOSED find (lowercase → dedup
+ * → SORT terms, + significant flags) and, if that canonical key was already run
+ * SUCCESSFULLY this session, DENIES the call before it costs a generation.
+ *
+ * Safety:
+ *   - Only EXACT term-set+flag matches are blocked. Add/drop a term, or change
+ *     --path/--tests, and it's a different query that legitimately differs → allowed.
+ *   - Registration happens in the PostToolUse hook (find-nudge) and ONLY on a
+ *     successful, non-empty result — so retrying a FAILED/empty find is never blocked.
+ *   - Flags are folded into the key, so a scoped re-query (`--path ...`) never
+ *     collides with the unscoped one. Bias is toward specificity: a missed dup just
+ *     falls back to the PostToolUse late-catch; a false block is the error we avoid.
+ *   - Fail-open: any error → return null and the call proceeds (runHook swallows).
+ *
+ * State is shared with find-nudge: /tmp/find_nudge_{session}_{agent}.json,
+ * list key `seen_find_queries`.
+ *
+ * Ported 1:1 from find-preguard.py.
+ */
+
+import { readFileSync } from "node:fs";
+import { canonicalFindKey } from "./canonical-find-key.mjs";
+import { normalizeColdstartCall } from "./coldstart-call.mjs";
+
+const REASON =
+  "You have ALREADY run this exact `coldstart find` earlier in this session — same " +
+  "terms (order/case/repeats don't change the result), same scope. `find` is deterministic " +
+  "on a static index, so re-running it returns the IDENTICAL ranked page you already have in " +
+  "context. Re-read that earlier find result and answer, or search a GENUINELY different " +
+  "term-set (add/drop a salient identifier, or add `--path` to scope it). Do not re-run the " +
+  "same query.";
+
+/**
+ * @param {any} input parsed PreToolUse stdin payload
+ * @returns {object|null} a permissionDecision:"deny" envelope, or null to allow
+ */
+export default function handle(input) {
+  const tin = input.tool_input && typeof input.tool_input === "object" ? input.tool_input : {};
+  // Normalize so a `mcp__coldstart__find` call is deduped against a CLI `coldstart
+  // find` (and vice-versa) using the same canonical key. Non-coldstart Bash falls
+  // through to canonicalFindKey, which returns null for anything that isn't a find.
+  const { tool, cmd } = normalizeColdstartCall(input.tool_name || "", tin);
+  if (tool !== "Bash") return null;
+  const key = canonicalFindKey(cmd);
+  if (!key) return null;
+
+  const sid = input.session_id || "default";
+  const aid = input.agent_id || "";
+  const skey = aid ? `${sid}_${aid}` : sid;
+  const stateFile = `/tmp/find_nudge_${skey}.json`;
+
+  let st = {};
+  try {
+    st = JSON.parse(readFileSync(stateFile, "utf8"));
+  } catch {
+    st = {};
+  }
+  const seen = Array.isArray(st.seen_find_queries) ? st.seen_find_queries : [];
+  if (!seen.includes(key)) return null; // never run before → allow
+
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: REASON,
+    },
+  };
+}

package/hooks/codex-run-hook.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * codex-run-hook.mjs — crash-resilient wrapper for coldstart Codex hook entries.
+ *
+ * Adapted from context-mode's run-hook.mjs (MIT). The whole point: a coldstart
+ * hook must NEVER block a tool call or spam the user, no matter what breaks —
+ * a parse error, a missing dep, a malformed stdin payload, a thrown handler.
+ * Codex surfaces a non-zero hook exit as a hook error. A single bad deploy can
+ * therefore nag the user on every matching tool call.
+ * This wrapper guarantees exit 0 and fail-open (no output = no decision = the
+ * tool proceeds normally) on any failure.
+ *
+ * Three layers of protection:
+ *   1. This file imports ONLY node: built-ins, so it cannot fail at parse time.
+ *   2. process-level uncaughtException / unhandledRejection nets, installed
+ *      before any handler runs, catch async throws the try/catch would miss.
+ *   3. The handler is invoked inside a try; any throw is logged and we exit 0.
+ *      Load your real handler via dynamic import INSIDE the handler thunk so its
+ *      own parse-time import errors are caught here too (see usage below).
+ *
+ * Failures log to <configDir>/coldstart/hook-errors.log, where configDir honors
+ * $CODEX_HOME (incl. a leading ~) and falls back to ~/.codex.
+ *
+ * Usage — keep the entry file's top-level imports to node: built-ins only:
+ *     #!/usr/bin/env node
+ *     import { runHook } from "./codex-run-hook.mjs";
+ *     await runHook(async (input) => {
+ *       const { default: handle } = await import("./codex-preguard-handler.mjs");
+ *       return handle(input); // return an object → printed as JSON to stdout
+ *     });
+ *
+ * The handler receives the parsed stdin payload (or {} if stdin was empty/bad)
+ * and may return:
+ *   - undefined / null  → no stdout (fail-open: tool proceeds)
+ *   - a string          → written to stdout verbatim
+ *   - an object         → JSON.stringify'd to stdout (e.g. a PreToolUse
+ *                         permissionDecision, or PostToolUse additionalContext)
+ */
+
+import { homedir } from "node:os";
+import { resolve, join } from "node:path";
+import { existsSync, mkdirSync, appendFileSync } from "node:fs";
+
+// Inlined so this wrapper stays dependency-free (parse-time-proof).
+function resolveCodexConfigDir() {
+  const envVal = process.env.CODEX_HOME;
+  if (envVal) {
+    if (envVal.startsWith("~")) return join(homedir(), envVal.replace(/^~[/\\]?/, ""));
+    return envVal;
+  }
+  return resolve(homedir(), ".codex");
+}
+
+function logError(err) {
+  try {
+    const dir = resolve(resolveCodexConfigDir(), "coldstart");
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const line = `[${new Date().toISOString()}] pid=${process.pid} ${err?.stack || err?.message || String(err)}\n`;
+    appendFileSync(resolve(dir, "hook-errors.log"), line);
+  } catch {
+    /* never fail logging */
+  }
+}
+
+// Safety nets BEFORE any handler code runs. Static top-level imports in the
+// ENTRY file would bypass these, which is why the entry must dynamic-import its
+// real handler from inside the thunk.
+process.on("uncaughtException", (err) => {
+  logError(err);
+  process.exit(0);
+});
+process.on("unhandledRejection", (err) => {
+  logError(err);
+  process.exit(0);
+});
+
+/** Read all of stdin. Resolves to "" if stdin is closed/empty. */
+function readStdin() {
+  return new Promise((res) => {
+    let data = "";
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      res(data);
+    };
+    try {
+      if (process.stdin.isTTY) return done();
+      process.stdin.setEncoding("utf8");
+      process.stdin.on("data", (c) => (data += c));
+      process.stdin.on("end", done);
+      process.stdin.on("error", done);
+      // Hard ceiling so a wedged pipe can never hang the tool call.
+      setTimeout(done, 2000).unref?.();
+    } catch {
+      done();
+    }
+  });
+}
+
+/**
+ * Run a hook handler with full crash-resilience. Reads + parses stdin, invokes
+ * the handler, prints its return value, and ALWAYS exits 0.
+ *
+ * @param {(input: any) => Promise<unknown> | unknown} handler
+ */
+export async function runHook(handler) {
+  let input = {};
+  try {
+    const raw = await readStdin();
+    if (raw && raw.trim()) input = JSON.parse(raw);
+  } catch (e) {
+    // Malformed/absent payload is non-fatal — hand the handler {} and let it
+    // decide. Most handlers no-op without the fields they need.
+    logError(e);
+  }
+
+  try {
+    const out = await handler(input);
+    if (out == null) {
+      // fail-open / no-op: emit nothing, tool proceeds normally.
+    } else if (typeof out === "string") {
+      process.stdout.write(out);
+    } else {
+      process.stdout.write(JSON.stringify(out));
+    }
+  } catch (e) {
+    logError(e);
+    // Swallow: no stdout means no hook decision → the tool is not blocked.
+  }
+  process.exit(0);
+}

package/hooks/coldstart-call.mjs

@@ -0,0 +1,58 @@
+/**
+ * coldstart-call.mjs — normalize a tool call into the shape the detectors expect.
+ *
+ * coldstart is reachable two ways with IDENTICAL semantics:
+ *   - CLI  : Bash `coldstart find <terms>` / `coldstart gs <file> --symbol <s>`
+ *   - MCP  : tools `mcp__coldstart__find {query}` / `mcp__coldstart__gs {file_path,...}`
+ *
+ * The nudge/preguard detectors were written against the CLI surface: they key on
+ * `tool === "Bash"` and run regexes over the command STRING. Rather than fork the
+ * detector logic per surface, this normalizer rewrites an MCP coldstart call into
+ * the equivalent CLI command string and reports it as a Bash call. Every downstream
+ * regex (FIND_RE/GS_RE/GS_FILE_RE/SEARCH_RE) and the canonical-find-key then run
+ * UNCHANGED — same logic, regardless of which surface the agent used.
+ *
+ * Non-coldstart calls pass through untouched (tool name + `tool_input.command`).
+ *
+ * The MCP tool name is `mcp__<serverKey>__<tool>`; the benchmark wires coldstart
+ * under the server key `coldstart` (see the arm's `.mcp.json`). If you key it
+ * differently, change MCP_SERVER_KEY below — that is the only surface-specific knob.
+ */
+
+const MCP_SERVER_KEY = "coldstart";
+const MCP_FIND = `mcp__${MCP_SERVER_KEY}__find`;
+const MCP_GS = `mcp__${MCP_SERVER_KEY}__gs`;
+
+function str(v) {
+  return typeof v === "string" ? v : "";
+}
+
+/**
+ * @param {string} toolName  input.tool_name
+ * @param {any}    toolInput input.tool_input (already coerced to {} if missing)
+ * @returns {{ tool: string, cmd: string }}
+ *   For an MCP coldstart find/gs call: { tool: "Bash", cmd: "<synthesized CLI command>" }.
+ *   For anything else: { tool: <toolName>, cmd: <tool_input.command or ""> }.
+ */
+export function normalizeColdstartCall(toolName, toolInput) {
+  const tin = toolInput && typeof toolInput === "object" ? toolInput : {};
+
+  if (toolName === MCP_FIND) {
+    // find accepts `query` (alias `domain_filter`); `path` scopes it (folded into the dedup key).
+    const query = str(tin.query) || str(tin.domain_filter);
+    const path = str(tin.path) ? ` --path ${str(tin.path)}` : "";
+    return { tool: "Bash", cmd: `coldstart find ${query}${path}`.trim() };
+  }
+
+  if (toolName === MCP_GS) {
+    // gs needs the file as the first token after `gs` (GS_FILE_RE), plus the flags
+    // that the detectors look at (--symbol drives the slice/re-guess detectors).
+    const file = str(tin.file_path) || str(tin.file) || str(tin.file_name);
+    const symbol = str(tin.symbol) ? ` --symbol ${str(tin.symbol)}` : "";
+    const match = str(tin.match) ? ` --match ${str(tin.match)}` : "";
+    const view = str(tin.view) ? ` --view ${str(tin.view)}` : "";
+    return { tool: "Bash", cmd: `coldstart gs ${file}${symbol}${match}${view}`.trim() };
+  }
+
+  return { tool: toolName || "", cmd: str(tin.command) };
+}

package/hooks/cursor-find-nudge.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * cursor-find-nudge.mjs — Cursor postToolUse entry. Emits search nudges + registers
+ * successful find keys for the preToolUse guard.
+ * Wire as: node <abs>/cursor-find-nudge.mjs   (hook: postToolUse)
+ *
+ * Top-level imports stay node:-builtin-only (via run-hook); the real handler is
+ * dynamic-imported inside the thunk so its parse-time errors are caught + fail-open.
+ */
+import { runHook } from "./cursor-run-hook.mjs";
+
+await runHook(async (input) => {
+  const { default: handle } = await import("./cursor-nudge-handler.mjs");
+  return handle(input);
+});

package/hooks/cursor-find-preguard.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * cursor-find-preguard.mjs — Cursor preToolUse entry for exact find re-runs.
+ * Wire as: node <abs>/cursor-find-preguard.mjs   (hook: preToolUse)
+ *
+ * Top-level imports stay node:-builtin-only (via run-hook); the real handler is
+ * dynamic-imported inside the thunk so its parse-time errors are caught + fail-open.
+ */
+import { runHook } from "./cursor-run-hook.mjs";
+
+await runHook(async (input) => {
+  const { default: handle } = await import("./cursor-preguard-handler.mjs");
+  return handle(input);
+});