@sdsrs/code-graph 0.161.0 → 0.162.0

package/claude-plugin/scripts/session-edits.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+'use strict';
+// Per-session edit log shared by the PreToolUse(Edit) hook (writer) and the
+// Stop hook (reader) — P1 #3.
+//
+// Two files per (project, session), both in the shared cgTmpDir() so the
+// SessionStart prune (24 h, mtime) and `uninstall`'s wholesale removal of that
+// dir cover them without a new cleanup path:
+//
+//   .cg-edits-<cwdHash>-<sid>.jsonl  one line per Edit call: {ts, file, symbol[, sigs]}
+//   .cg-stop-<cwdHash>-<sid>.json    written by the Stop hook only:
+//                                    {lastStopAt, reported: ["file#symbol", …]}
+//
+// The edit log is APPEND-only: parallel Edit calls each run their own hook
+// process, and a read-modify-write JSON file would drop one of two concurrent
+// records. A single small `appendFileSync` is one O_APPEND write. The Stop
+// file has exactly one writer (Claude Code runs one Stop per turn), so plain
+// write-then-rename is enough there.
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { cgTmpDir, cwdHash } = require('./tmp-dir');
+
+// Claude Code's session_id is a UUID. Anything else is hashed rather than
+// trusted as a path segment: it is stdin from the harness, and a `../` in it
+// must not be able to name a file outside cgTmpDir().
+function sessionKey(sessionId) {
+  const s = String(sessionId || '');
+  if (!s) return null;
+  if (/^[A-Za-z0-9-]{1,64}$/.test(s)) return s;
+  return crypto.createHash('sha1').update(s).digest('hex').slice(0, 16);
+}
+
+function editsPath(root, sessionId) {
+  const key = sessionKey(sessionId);
+  return key ? path.join(cgTmpDir(), `.cg-edits-${cwdHash(root)}-${key}.jsonl`) : null;
+}
+
+function stopStatePath(root, sessionId) {
+  const key = sessionKey(sessionId);
+  return key ? path.join(cgTmpDir(), `.cg-stop-${cwdHash(root)}-${key}.json`) : null;
+}
+
+// Baseline capture limits: a larger file, or more same-named definitions than
+// this, records no baseline — and the Stop hook then says nothing about it.
+const MAX_BASELINE_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_BASELINE_SIGS = 32;
+
+/**
+ * The symbol's definition headers in the file as it is NOW — called from
+ * PreToolUse, i.e. before the Edit lands. The Stop hook compares the working
+ * tree with the turn's first such record, so "changed this turn" means what it
+ * says (review H1). null = no exact reading (stop-impact.js LANGS, size, IO).
+ */
+function baselineSignatures(root, file, symbol) {
+  try {
+    const abs = path.join(root, file);
+    if (fs.statSync(abs).size > MAX_BASELINE_FILE_BYTES) return null;
+    const { extractSignatures } = require('./stop-impact');
+    const sigs = extractSignatures(fs.readFileSync(abs, 'utf8'), symbol, path.extname(file).toLowerCase());
+    return sigs && sigs.length <= MAX_BASELINE_SIGS ? sigs : null;
+  } catch { return null; }
+}
+
+/**
+ * Append one Edit to the session log. Best-effort: a failed write costs the
+ * Stop check one record, never the Edit it rides on. A record with a symbol
+ * also carries `sigs`, that symbol's signatures before this Edit.
+ * @param {string} root project root
+ * @param {string} sessionId
+ * @param {{file: string, symbol?: string|null}} rec file is root-relative
+ * @returns {boolean} written
+ */
+function recordEdit(root, sessionId, { file, symbol = null }, now = Date.now()) {
+  const p = editsPath(root, sessionId);
+  if (!p || !file) return false;
+  const rec = { ts: now, file, symbol: symbol || null };
+  if (symbol) rec.sigs = baselineSignatures(root, file, symbol);
+  try {
+    fs.appendFileSync(p, JSON.stringify(rec) + '\n');
+    return true;
+  } catch { return false; }
+}
+
+/** Every well-formed record in the session log; a torn or foreign line is skipped. */
+function readEdits(root, sessionId) {
+  const p = editsPath(root, sessionId);
+  if (!p) return [];
+  let raw;
+  try { raw = fs.readFileSync(p, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line) continue;
+    try {
+      const r = JSON.parse(line);
+      if (r && typeof r.ts === 'number' && typeof r.file === 'string') {
+        const sigs = Array.isArray(r.sigs) && r.sigs.every((x) => typeof x === 'string') ? r.sigs : null;
+        out.push({ ts: r.ts, file: r.file, symbol: typeof r.symbol === 'string' ? r.symbol : null, sigs });
+      }
+    } catch { /* torn line from a killed writer */ }
+  }
+  return out;
+}
+
+function readStopState(root, sessionId) {
+  const p = stopStatePath(root, sessionId);
+  const empty = { lastStopAt: null, reported: [] };
+  if (!p) return empty;
+  try {
+    const s = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return {
+      lastStopAt: typeof s.lastStopAt === 'number' ? s.lastStopAt : null,
+      reported: Array.isArray(s.reported) ? s.reported.filter((x) => typeof x === 'string') : [],
+    };
+  } catch { return empty; }
+}
+
+function writeStopState(root, sessionId, state) {
+  const p = stopStatePath(root, sessionId);
+  if (!p) return false;
+  const tmp = `${p}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(state));
+    fs.renameSync(tmp, p);
+    return true;
+  } catch {
+    try { fs.unlinkSync(tmp); } catch { /* never created */ }
+    return false;
+  }
+}
+
+module.exports = {
+  sessionKey, editsPath, stopStatePath, recordEdit, readEdits, readStopState, writeStopState,
+};

package/claude-plugin/scripts/stop-impact.js

@@ -0,0 +1,431 @@
+#!/usr/bin/env node
+'use strict';
+// FIRST statement, before the other requires — same reason as pre-edit-guide.js.
+if (require.main === module) require('./hook-fail-open').installHookFailOpen('Stop');
+
+// Stop hook (P1 #3b): the end-of-turn half of the edit-impact check.
+//
+// pre-edit-guide.js pushes "this function has N callers" BEFORE an edit, when
+// nobody yet knows whether the edit will change the signature. This runs when
+// the turn ends and asks the question that can be answered then: of the
+// symbols edited this turn, which ones' signatures did THIS TURN change, and
+// which of their callers sit in files this turn did not touch? Those are
+// listed as `file:line`, once per symbol per session, through the Stop
+// event's `additionalContext` — documented as non-error feedback that lets
+// the turn continue, as opposed to `decision: "block"`
+// (https://code.claude.com/docs/en/hooks, "Stop decision control").
+//
+// "Changed this turn" compares the working tree with the signatures
+// pre-edit-guide recorded just before the turn's FIRST Edit of the symbol
+// (session-edits.js `sigs`) — not with HEAD. Both sides of the comparison are
+// then scoped to the same turn: a signature changed in turn 1, with its
+// callers fixed in turn 1, is not re-raised by a body-only edit in turn 2
+// (review H1), and uncommitted work from before the session is not reported
+// as this turn's.
+//
+// Silent when: `stop_hook_active` (a continuation this or another Stop hook
+// caused — never loop), no session edit log, no index, not a git work tree,
+// no signature changed, the language has no exact header reading (LANGS),
+// every caller's file was touched this turn, or the symbol was already
+// reported this session. CODE_GRAPH_QUIET_HOOKS=1 silences it like the other
+// injecting hooks.
+//
+// "Touched this turn" = an Edit to the file was logged since the previous Stop,
+// OR the file's mtime is at or after the turn's start (covers Write, Bash
+// `sed -i`, formatters). The turn starts at the previous Stop; the first turn
+// of a session starts at its first logged Edit. Both only ever SUPPRESS a
+// line, so an over-wide "touched" set costs a missed report, never a wrong one.
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { hidden } = require('./proc-opts');
+const { shellQuoteArg, formatCgCommand } = require('./cg-answer');
+
+// Per-Stop work caps. The hook blocks the end of the turn, so its worst case
+// is bounded by count as well as by the registered budget. The symbol cap
+// bounds the `refs` queries, so it applies AFTER the text-only "did the
+// signature change" filter (review M1): body-only edits do not use it up.
+const MAX_SYMBOLS_CHECKED = 8;
+const MAX_CALLERS_LISTED = 8;
+// A header that has not ended within this many characters is not read at all
+// (no verdict), rather than cut: a cut header can run into the body, and a
+// body edit would then read as a signature change.
+const MAX_SIGNATURE_CHARS = 600;
+// A match on a line longer than this gives no reading (null): minified and
+// generated one-line files. Re-finding the line per match made such a file
+// quadratic (pre-tag review H2: a 1.5 MB one-line bundle took 9 s, past
+// pre-edit-guide's 4 s budget); with the cap a 2 MB file of 1,999-character
+// lines of definitions takes about 0.2 s.
+const MAX_DEFINITION_LINE_CHARS = 2000;
+
+const COMMENT_LINE = /^\s*(?:\/\/|#|\*|\/\*|--|;)/;
+// First words that make a C-family `Type name(` line a statement, not a
+// definition.
+const NOT_A_TYPE = new Set([
+  'return', 'new', 'throw', 'else', 'await', 'yield', 'case', 'delete', 'typeof',
+  'echo', 'print', 'puts', 'if', 'while', 'for', 'switch', 'catch', 'when', 'not',
+  'and', 'or', 'in', 'is', 'of', 'do', 'assert', 'raise', 'import', 'from', 'use',
+  'let', 'const', 'var', 'mut', 'match', 'go', 'defer', 'sizeof', 'co_return',
+  'co_await', 'co_yield', 'default', 'goto',
+]);
+
+// How each language's definition headers are found and where they end. Only
+// languages whose headers these rules read exactly are listed; every other
+// extension gets no verdict, and the Stop hook says nothing about its symbols
+// (review M2: silent beats wrong).
+//
+//   keyword  a definition is `<keyword> name` (`receiver`: Go's `func (r T) name`;
+//            `typeParams`: Kotlin's `fun <T> name`)
+//   jsForms  also `const name = (…) =>` bindings and one-line class methods
+//   typed    C-family `Type name(` lines — no keyword exists
+//   ends     characters that end the header at bracket depth 0; `\n` included
+//            only where a newline outside brackets cannot continue a header
+//   arrowEnds  `=>` at depth 0 ends it (JS arrow bodies, C# expression bodies);
+//            elsewhere `=>` is part of a type (Scala) and never an end
+//   angles   `<…>` nests like a bracket (TS generics may hold `{`)
+//   afterParams  a lone `:` after the parameter list ends it (C++ member
+//            initializers, C# `: base(…)` — body, not signature)
+//   closeParen  the parameter list's `)` ends it (Ruby, Lua: no return types,
+//            and a one-line body may follow on the same line)
+const LANGS = new Map();
+function defineLang(exts, profile) {
+  for (const e of exts) LANGS.set(e, profile);
+}
+defineLang(['.rs'], { keyword: 'fn', ends: '{;' });
+defineLang(['.py', '.pyi'], { keyword: 'def', ends: ':' });
+defineLang(['.go'], { keyword: 'func', receiver: true, ends: '{;\n' });
+defineLang(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts'],
+  { keyword: 'function\\*?', jsForms: true, ends: '{;', arrowEnds: true, angles: true });
+defineLang(['.php'], { keyword: 'function', ends: '{;' });
+defineLang(['.c', '.h', '.cc', '.cpp', '.cxx', '.hpp', '.hh', '.hxx', '.java', '.cs'],
+  { typed: true, ends: '{;', arrowEnds: true, afterParams: true });
+defineLang(['.kt', '.kts'], { keyword: 'fun', typeParams: true, ends: '{=\n' });
+defineLang(['.scala', '.sc'], { keyword: 'def', ends: '{=\n' });
+defineLang(['.rb'], { keyword: 'def', ends: ';=\n', closeParen: true });
+defineLang(['.lua'], { keyword: 'function', ends: '\n', closeParen: true });
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function definitionPatterns(S, lang) {
+  const out = [];
+  if (lang.keyword) {
+    const receiver = lang.receiver ? '(?:\\([^)\\n]*\\)\\s*)?' : '';
+    const typeParams = lang.typeParams ? '(?:<[^>\\n]*>\\s*)?' : '';
+    out.push({ re: new RegExp(`\\b(?:${lang.keyword})\\s+${receiver}${typeParams}${S}\\b`, 'g') });
+  }
+  if (lang.jsForms) {
+    out.push({ re: new RegExp(`\\b(?:const|let|var)\\s+${S}\\s*=\\s*(?:async\\s+)?(?:function\\b|\\([^)\\n]*\\)\\s*=>|[A-Za-z_$][\\w$]*\\s*=>)`, 'g') });
+    out.push({ re: new RegExp(`^[ \\t]*(?:(?:async|static|get|set|public|private|protected|readonly|override)\\s+)*\\*?${S}\\s*\\([^()\\n]*\\)\\s*(?::\\s*[^{;=\\n]+)?\\{[ \\t]*$`, 'gm') });
+  }
+  if (lang.typed) {
+    out.push({ re: new RegExp(`^[ \\t]*((?:[A-Za-z_][\\w<>\\[\\],.*&:?]*[ \\t]+)+)${S}[ \\t]*\\(`, 'gm'), typed: true });
+  }
+  return out;
+}
+
+/**
+ * Normalized signatures of every definition of `symbol` in `text`, sorted —
+ * or null when there is no exact reading: the language is not in LANGS, a
+ * header did not end within MAX_SIGNATURE_CHARS, or a match of a definition
+ * pattern sits on a line longer than MAX_DEFINITION_LINE_CHARS.
+ *
+ * A definition is located by the line it starts on (LANGS) and runs from that
+ * line's start to the first end character at bracket depth 0. The key drops
+ * all whitespace and a trailing comma, so a formatter re-wrapping the
+ * parameter list is not a change.
+ * @returns {string[]|null}
+ */
+function extractSignatures(text, symbol, ext = '') {
+  const lang = LANGS.get(String(ext).toLowerCase());
+  if (!lang) return null;
+  if (typeof text !== 'string' || !symbol) return [];
+  const lineStarts = new Set();
+  for (const { re, typed } of definitionPatterns(escapeRe(symbol), lang)) {
+    for (const m of text.matchAll(re)) {
+      const at = text.lastIndexOf('\n', m.index) + 1;
+      const lineEnd = text.indexOf('\n', at);
+      const line = text.slice(at, lineEnd === -1 ? text.length : lineEnd);
+      // Checked first: finding the line is the per-match cost, so a match on
+      // a long line must end the scan, or a one-line bundle is quadratic.
+      if (line.length > MAX_DEFINITION_LINE_CHARS) return null;
+      if (COMMENT_LINE.test(line)) continue;
+      if (typed) {
+        const first = (line.trim().match(/^[A-Za-z_]\w*/) || [''])[0];
+        if (NOT_A_TYPE.has(first)) continue;
+        // `label: f(`, `case X: f(`, `public: f(` — a token ending in a lone
+        // `:` is a label or access specifier, never part of a return type.
+        if (m[1].split(/[ \t]+/).some((tok) => /(?:^|[^:]):$/.test(tok))) continue;
+      }
+      lineStarts.add(at);
+    }
+  }
+  const out = [];
+  for (const at of lineStarts) {
+    const header = readHeader(text, at, lang);
+    if (header === null) return null;
+    out.push(signatureKey(header));
+  }
+  return out.sort();
+}
+
+function readHeader(text, at, lang) {
+  let depth = 0;
+  let angle = 0;
+  let sawParams = false;
+  const limit = Math.min(text.length, at + MAX_SIGNATURE_CHARS);
+  for (let i = at; i < limit; i++) {
+    const c = text[i];
+    if (c === '=' && text[i + 1] === '>') {
+      if (lang.arrowEnds && depth === 0 && angle === 0) return text.slice(at, i);
+      i++; // part of a type or a default value: step over both characters
+      continue;
+    }
+    if (c === '(' || c === '[') { depth++; continue; }
+    if (c === ')' || c === ']') {
+      depth = Math.max(0, depth - 1);
+      if (c === ')' && depth === 0) {
+        sawParams = true;
+        if (lang.closeParen) return text.slice(at, i + 1);
+      }
+      continue;
+    }
+    if (depth !== 0) continue;
+    if (lang.angles && c === '<') { angle++; continue; }
+    if (lang.angles && c === '>') { angle = Math.max(0, angle - 1); continue; }
+    if (angle !== 0) continue;
+    if (lang.ends.includes(c) && !(c === '\n' && i === at)) return text.slice(at, i);
+    if (lang.afterParams && sawParams && c === ':' && text[i - 1] !== ':' && text[i + 1] !== ':') {
+      return text.slice(at, i);
+    }
+  }
+  // End of text ends a header; running out of the character budget does not.
+  return limit === text.length ? text.slice(at, limit) : null;
+}
+
+function signatureKey(header) {
+  return header.replace(/\s+/g, '').replace(/,\)/g, ')');
+}
+
+/**
+ * True when a definition that existed before is gone: its header changed, or
+ * it was removed while others of the same name remain. A definition ADDED
+ * beside unchanged ones (a new overload, a new `impl From<B>`) changes no
+ * existing caller's target, so it is not a change (review M2).
+ */
+function signatureChanged(oldSigs, newSigs) {
+  const remaining = new Map();
+  for (const s of newSigs) remaining.set(s, (remaining.get(s) || 0) + 1);
+  for (const s of oldSigs) {
+    const n = remaining.get(s) || 0;
+    if (n === 0) return true;
+    remaining.set(s, n - 1);
+  }
+  return false;
+}
+
+/**
+ * The line of the first mention of `symbol` at or after the caller's own
+ * start line — the call site, which is what a reader needs to open. Falls
+ * back to the caller's start line.
+ */
+function findCallSiteLine(text, symbol, startLine) {
+  const start = Math.max(1, Number(startLine) || 1);
+  if (typeof text !== 'string') return start;
+  const lines = text.split('\n');
+  const re = new RegExp(`(?:^|[^\\w$])${escapeRe(symbol)}(?![\\w$])`);
+  for (let i = start - 1; i < lines.length && i < start - 1 + 400; i++) {
+    if (!COMMENT_LINE.test(lines[i]) && re.test(lines[i])) return i + 1;
+  }
+  return start;
+}
+
+/**
+ * The decision, with every side effect injected (unit-testable without git or
+ * a binary). Returns the lines to report and the next Stop state.
+ *
+ * @param {object} a
+ * @param {{ts:number,file:string,symbol:string|null,sigs:string[]|null}[]} a.edits
+ *   whole session log; `sigs` = the symbol's signatures just before that Edit
+ * @param {{lastStopAt:number|null, reported:string[]}} a.state
+ * @param {number} a.now
+ * @param {(file:string)=>string|null} a.workText  file in the working tree
+ * @param {(symbol:string,file:string)=>({file:string,line:number,name:string}[]|null)} a.callers
+ * @param {(file:string)=>number|null} a.mtimeMs
+ */
+function computeStopReport({ edits, state, now, workText, callers, mtimeMs }) {
+  const lastStopAt = state.lastStopAt;
+  const turn = edits.filter((e) => lastStopAt === null || e.ts > lastStopAt);
+  const next = { lastStopAt: now, reported: [...state.reported] };
+  if (turn.length === 0) return { lines: [], state: next };
+
+  const turnStart = lastStopAt !== null ? lastStopAt : Math.min(...edits.map((e) => e.ts));
+  const editedThisTurn = new Set(turn.map((e) => e.file));
+  const touched = (file) => {
+    if (editedThisTurn.has(file)) return true;
+    const m = mtimeMs(file);
+    return m !== null && m >= turnStart;
+  };
+
+  // One candidate per (file, symbol). Its baseline is what pre-edit-guide
+  // recorded before the turn's FIRST Edit of it — the signature as the turn
+  // found it. Later records of the same symbol this turn were taken after
+  // earlier edits had landed, so they are not the baseline.
+  const seen = new Set();
+  const changed = [];
+  for (const e of turn) {
+    if (!e.symbol) continue;
+    const key = `${e.file}#${e.symbol}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    if (next.reported.includes(key)) continue;
+    // null: no exact reading (language, unreadable file, a pre-repair log
+    // line). [] (the definition was added this turn) needs no test of its
+    // own: signatureChanged counts only definitions that went missing.
+    if (!Array.isArray(e.sigs)) continue;
+    const after = extractSignatures(workText(e.file), e.symbol, path.extname(e.file).toLowerCase());
+    if (!after || after.length === 0) continue;     // removed, or no reading now
+    if (!signatureChanged(e.sigs, after)) continue; // body-only this turn
+    changed.push({ key, file: e.file, symbol: e.symbol });
+  }
+
+  const lines = [];
+  for (const c of changed.slice(0, MAX_SYMBOLS_CHECKED)) {
+    const refs = callers(c.symbol, c.file);
+    if (!refs || refs.length === 0) continue;
+    const untouched = [];
+    const dedup = new Set();
+    for (const r of refs) {
+      if (r.file === c.file || touched(r.file)) continue;
+      const id = `${r.file}:${r.line}`;
+      if (dedup.has(id)) continue;
+      dedup.add(id);
+      untouched.push(r);
+    }
+    if (untouched.length === 0) continue;
+    untouched.sort((x, y) => (x.file < y.file ? -1 : x.file > y.file ? 1 : x.line - y.line));
+    // Every repo-derived token is shell-quoted (review M3): a file name is
+    // text from the repository, and the model may paste it into a command.
+    const shown = untouched.slice(0, MAX_CALLERS_LISTED).map((r) => {
+      const name = r.name && r.name !== '<module>' ? ' (' + shellQuoteArg(r.name) + ')' : '';
+      return shellQuoteArg(r.file) + ':' + r.line + name;
+    });
+    let line = '  ' + shellQuoteArg(c.symbol) + '() in ' + shellQuoteArg(c.file) + ': ' + shown.join(', ');
+    if (untouched.length > MAX_CALLERS_LISTED) {
+      line += ', and ' + (untouched.length - MAX_CALLERS_LISTED) + ' more (' +
+        formatCgCommand(['refs', c.symbol, '--file', c.file]) + ')';
+    }
+    lines.push(line);
+    next.reported.push(c.key);
+  }
+  // Changed beyond the query cap: named, not dropped in silence (review M1).
+  // Not marked reported, and a later turn does not see them as changed again
+  // (their baseline moves on), so this line is the only mention they get.
+  const unchecked = changed.slice(MAX_SYMBOLS_CHECKED);
+  if (unchecked.length > 0) {
+    lines.push('  ' + unchecked.length + ' more changed, callers not checked: ' +
+      unchecked.map((c) => shellQuoteArg(c.symbol) + '() in ' + shellQuoteArg(c.file)).join(', '));
+  }
+  return { lines, state: next };
+}
+
+function formatStopContext(lines) {
+  if (!lines.length) return null;
+  // No apostrophe in the fixed text: file names are single-quoted in it.
+  return '[code-graph] Signatures changed this turn (each compared with its file before ' +
+    'the first edit of it this turn); their callers in files not edited this turn, from the code-graph index:\n' +
+    lines.join('\n') + '\n';
+}
+
+// --- Side-effecting shell ---------------------------------------------------
+
+function readStdinJson() {
+  try {
+    // fd 0, not '/dev/stdin' (ENXIO on socketpair stdin) — as the other hooks.
+    return JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch { return null; }
+}
+
+function runMain() {
+  if (process.env.CODE_GRAPH_QUIET_HOOKS === '1') return;
+  const input = readStdinJson();
+  if (!input || input.stop_hook_active === true) return;
+  if (!input.session_id) return;
+
+  const { resolveProjectRoot } = require('./project-root');
+  const root = resolveProjectRoot(typeof input.cwd === 'string' && input.cwd ? input.cwd : process.cwd());
+  if (root === null) return;
+
+  const sessionEdits = require('./session-edits');
+  const edits = sessionEdits.readEdits(root, input.session_id);
+  if (edits.length === 0) return; // no log → nothing to check, and nothing written
+  const state = sessionEdits.readStopState(root, input.session_id);
+
+  const { remainingMs } = require('./hook-fail-open');
+  const run = (cmd, args, defaultMs) => {
+    const budget = remainingMs(defaultMs);
+    if (budget === null) return null;
+    try {
+      return execFileSync(cmd, args, hidden({
+        cwd: root,
+        timeout: budget,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
+        maxBuffer: 16 * 1024 * 1024,
+      }));
+    } catch { return null; }
+  };
+
+  // The comparison no longer reads HEAD (baselines come from the edit log),
+  // but "silent outside a git work tree" is the spec's contract for this
+  // hook, so the gate stays.
+  const inGit = run('git', ['rev-parse', '--is-inside-work-tree'], 1000);
+  let binary = null;
+  let report = { lines: [], state: { lastStopAt: Date.now(), reported: state.reported } };
+  if (inGit !== null && inGit.trim() === 'true') {
+    binary = require('./find-binary').findBinary();
+  }
+  if (binary) {
+    report = computeStopReport({
+      edits,
+      state,
+      now: Date.now(),
+      workText: (file) => {
+        try { return fs.readFileSync(path.join(root, file), 'utf8'); } catch { return null; }
+      },
+      callers: (symbol, file) => {
+        const raw = run(binary, ['refs', symbol, '--file', file, '--relation', 'calls',
+          '--min-confidence', 'inferred', '--json'], 1500);
+        if (raw === null) return null;
+        let parsed;
+        try { parsed = JSON.parse(raw); } catch { return null; }
+        if (!parsed || !Array.isArray(parsed.references)) return null;
+        return parsed.references
+          .filter((r) => r && typeof r.file_path === 'string')
+          .map((r) => {
+            let text = null;
+            try { text = fs.readFileSync(path.join(root, r.file_path), 'utf8'); } catch { /* gone */ }
+            return { file: r.file_path, name: r.name, line: findCallSiteLine(text, symbol, r.start_line) };
+          });
+      },
+      mtimeMs: (file) => {
+        try { return fs.statSync(path.join(root, file)).mtimeMs; } catch { return null; }
+      },
+    });
+  }
+  sessionEdits.writeStopState(root, input.session_id, report.state);
+
+  const text = formatStopContext(report.lines);
+  if (!text) return;
+  const { emitEventContext } = require('./hook-emit');
+  process.stdout.write(emitEventContext('Stop', text) + '\n');
+}
+
+if (require.main === module) runMain();
+
+module.exports = {
+  extractSignatures, signatureChanged, findCallSiteLine, computeStopReport, formatStopContext,
+  MAX_SYMBOLS_CHECKED, MAX_CALLERS_LISTED,
+};

package/claude-plugin/scripts/subagent-start.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+'use strict';
+// FIRST statement, before the other requires — same reason as pre-edit-guide.js.
+if (require.main === module) require('./hook-fail-open').installHookFailOpen('SubagentStart');
+
+// SubagentStart hook (P1 #3a), registered by lifecycle.js with the matcher
+// `Explore|Plan|general-purpose`.
+//
+// Explore and Plan subagents do not load CLAUDE.md, so the adopt block that
+// tells the main session about the index never reaches them, and they fall
+// back to multi-round grep/Read for structural questions. This hands them the
+// same facts at spawn: the repo has an index, how big and how fresh, and the
+// three CLI commands that answer structural questions from it.
+//
+// Facts only — no "you must". The hooks reference says imperative text framed
+// as out-of-band instructions can trip Claude's prompt-injection defenses
+// (https://code.claude.com/docs/en/hooks, "Add context for Claude").
+//
+// Silent when: no index up the tree, no binary (the commands would not run),
+// the health check fails or reports 0 files, or CODE_GRAPH_QUIET_HOOKS=1 (the
+// same switch that skips the SessionStart project-map injection).
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const { hidden } = require('./proc-opts');
+
+// Hard ceiling on the injected text, in characters (spec: ≤400). Every
+// subagent spawn pays it in context, and a subagent's context is small.
+const MAX_CONTEXT_CHARS = 400;
+
+/**
+ * The text a subagent receives, or null when there is nothing true to say.
+ * @param {{files?: number, index_age?: string, index_version_stale?: boolean}} report
+ *   `health-check --format json` output
+ * @param {number} [maxChars] ceiling; a parameter only so tests can reach the
+ *   check — the builder's longest output (389) is below the real one
+ * @returns {string|null}
+ */
+function buildSubagentContext(report, maxChars = MAX_CONTEXT_CHARS) {
+  if (!report || typeof report !== 'object') return null;
+  const files = Number(report.files);
+  if (!Number.isFinite(files) || files <= 0) return null;
+  const age = typeof report.index_age === 'string' && /^[\w .-]{1,24}$/.test(report.index_age)
+    ? report.index_age : null;
+  let text = `This repository has a code-graph AST index of ${files} files`;
+  text += age ? `, last updated ${age}.` : '.';
+  if (report.index_version_stale === true) text += ' A rebuild for a newer extractor is pending.';
+  text += ' Structural questions are answered from it through Bash:' +
+    ' `code-graph-mcp callgraph <fn>` (callers and callees),' +
+    ' `code-graph-mcp show <fn>` (a symbol\'s source and signature),' +
+    ' `code-graph-mcp overview <dir>` (symbols of a module grouped by file).';
+  return text.length <= maxChars ? text : null;
+}
+
+function readStdinJson() {
+  try {
+    // fd 0, not '/dev/stdin' (ENXIO on socketpair stdin) — as the other hooks.
+    return JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch { return null; }
+}
+
+function runMain() {
+  if (process.env.CODE_GRAPH_QUIET_HOOKS === '1') return;
+  const input = readStdinJson();
+  if (!input) return;
+
+  const { resolveProjectRoot } = require('./project-root');
+  const root = resolveProjectRoot(typeof input.cwd === 'string' && input.cwd ? input.cwd : process.cwd());
+  if (root === null) return;
+
+  const binary = require('./find-binary').findBinary();
+  if (!binary) return;
+
+  // Spend the registered budget, not a literal (hooks.test.js "armed must spend").
+  const budget = require('./hook-fail-open').remainingMs(1500);
+  if (budget === null) return;
+  let report;
+  try {
+    report = JSON.parse(execFileSync(binary, ['health-check', '--format', 'json'], hidden({
+      cwd: root,
+      timeout: budget,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
+    })));
+  } catch { return; }
+
+  const text = buildSubagentContext(report);
+  if (!text) return;
+  const { emitEventContext } = require('./hook-emit');
+  process.stdout.write(emitEventContext('SubagentStart', text) + '\n');
+}
+
+if (require.main === module) runMain();
+
+module.exports = { buildSubagentContext, MAX_CONTEXT_CHARS };

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.161.0 code-graph-mcp snapshot create --out snapshot.db
+          npx -y -p @sdsrs/code-graph@0.162.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