@sdsrs/code-graph 0.162.0 → 0.164.0

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

@@ -25,7 +25,9 @@ if (require.main === module) require('./hook-fail-open').installHookFailOpen('St
 //
 // 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),
+// no signature changed (optional parameters appended at the end of a list do
+// not count: every existing call stays valid), 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.
@@ -141,8 +143,54 @@ 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)) {
+  const starts = definitionStarts(text, lang, escapeRe(symbol), symbol);
+  if (starts === null) return null;
+  return headersAt(text, starts.get(symbol) || [], lang);
+}
+
+// The name slot of definitionPatterns when every definition is wanted.
+const ANY_NAME = '([A-Za-z_$][\\w$]*)';
+// Words the name slot must not take: the control words that open a
+// `word (…) {` line, which the JS one-line-method pattern reads as a method.
+// Not NOT_A_TYPE: `from`, `use`, `match` are ordinary method names (`fn from`).
+const NOT_A_NAME = new Set([
+  'if', 'for', 'while', 'switch', 'catch', 'with', 'function', 'foreach', 'elseif',
+  'synchronized', 'using', 'lock', 'fixed', 'until', 'unless', 'return', 'await',
+  'yield', 'typeof', 'sizeof', 'new', 'super', 'this',
+]);
+
+/**
+ * Every definition in `text` with its signatures (Q1): Map name → sorted keys,
+ * in order of first appearance in the file — for an edit that names no
+ * definition (Write, `sed -i`). One pass per pattern; each name reads exactly
+ * as extractSignatures(text, name) reads it, and a name whose header has no
+ * reading is left out. null: the language is not in LANGS, or a definition
+ * sits on a line over MAX_DEFINITION_LINE_CHARS (for every name at once: the
+ * scan stops there, as extractSignatures does).
+ * @returns {Map<string,string[]>|null}
+ */
+function allSignatures(text, ext = '') {
+  const lang = LANGS.get(String(ext).toLowerCase());
+  if (!lang || typeof text !== 'string') return null;
+  const starts = definitionStarts(text, lang, ANY_NAME, null);
+  if (starts === null) return null;
+  const byFirst = [...starts].sort((a, b) => Math.min(...a[1]) - Math.min(...b[1]));
+  const out = new Map();
+  for (const [name, lineStarts] of byFirst) {
+    const sigs = headersAt(text, lineStarts, lang);
+    if (sigs && sigs.length > 0) out.set(name, sigs);
+  }
+  return out;
+}
+
+/**
+ * Where definitions start: Map name → Set of line-start offsets. With `symbol`
+ * the patterns carry it escaped in `S`; without, `S` is ANY_NAME and the name
+ * is the pattern's last group. null when a match sits on an over-long line.
+ */
+function definitionStarts(text, lang, S, symbol) {
+  const out = new Map();
+  for (const { re, typed } of definitionPatterns(S, lang)) {
     for (const m of text.matchAll(re)) {
       const at = text.lastIndexOf('\n', m.index) + 1;
       const lineEnd = text.indexOf('\n', at);
@@ -158,9 +206,16 @@ function extractSignatures(text, symbol, ext = '') {
         // `:` 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 name = symbol || m[m.length - 1];
+      if (!symbol && NOT_A_NAME.has(name)) continue;
+      if (!out.has(name)) out.set(name, new Set());
+      out.get(name).add(at);
     }
   }
+  return out;
+}
+
+function headersAt(text, lineStarts, lang) {
   const out = [];
   for (const at of lineStarts) {
     const header = readHeader(text, at, lang);
@@ -212,15 +267,120 @@ function signatureKey(header) {
  * 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).
+ * existing caller's target, so it is not a change (review M2). Nor is a header
+ * whose only difference is optional parameters appended to its parameter list
+ * (Q2, see appendsOptionalParams) — every existing call stays valid. That
+ * reading needs `symbol` to find the parameter list; without it every
+ * difference counts.
  */
-function signatureChanged(oldSigs, newSigs) {
+function signatureChanged(oldSigs, newSigs, symbol = null) {
   const remaining = new Map();
   for (const s of newSigs) remaining.set(s, (remaining.get(s) || 0) + 1);
+  const unmatched = [];
   for (const s of oldSigs) {
     const n = remaining.get(s) || 0;
-    if (n === 0) return true;
-    remaining.set(s, n - 1);
+    if (n === 0) unmatched.push(s);
+    else remaining.set(s, n - 1);
+  }
+  if (unmatched.length === 0) return false;
+  if (!symbol) return true;
+  // Each old header may pair with one new header that only extends it.
+  const pool = [];
+  for (const [s, n] of remaining) for (let k = 0; k < n; k++) pool.push(s);
+  for (const s of unmatched) {
+    const at = pool.findIndex((t) => appendsOptionalParams(s, t, symbol));
+    if (at === -1) return true;
+    pool.splice(at, 1);
+  }
+  return false;
+}
+
+/**
+ * True when signature key `newKey` is `oldKey` with parameters inserted just
+ * before the `)` that closes `symbol`'s parameter list, and every inserted
+ * parameter is optional at a call site (isOptionalParam). Anything else that
+ * moved — a return type, a parameter before the end, a parameter list inside
+ * a type — makes it false. Keys are whitespace-free (signatureKey).
+ */
+function appendsOptionalParams(oldKey, newKey, symbol) {
+  if (newKey.length <= oldKey.length) return false;
+  let i = 0;
+  while (i < oldKey.length && oldKey[i] === newKey[i]) i++;
+  if (oldKey[i] !== ')') return false;
+  const tail = oldKey.slice(i);
+  if (!newKey.endsWith(tail)) return false;
+  // The `(` this `)` closes.
+  let open = -1;
+  for (let j = i - 1, depth = 0; j >= 0; j--) {
+    if (oldKey[j] === ')') depth++;
+    else if (oldKey[j] === '(') {
+      if (depth === 0) { open = j; break; }
+      depth--;
+    }
+  }
+  if (open === -1) return false;
+  // A parameter list opens right after the name, its generics, or — for a JS
+  // binding — `name = [async] [function]`. A `(` after `->`, `:` or `)` opens
+  // a return type or a Go receiver/result list, never the parameters.
+  const S = escapeRe(symbol);
+  const opener = new RegExp(`${S}(?:<.*>|\\[.*\\])?(?:=(?:async)?(?:function\\*?)?)?$`);
+  if (!opener.test(oldKey.slice(0, open))) return false;
+  let inserted = newKey.slice(i, newKey.length - tail.length);
+  if (open < i - 1) {
+    if (inserted[0] !== ',') return false;
+    inserted = inserted.slice(1);
+  }
+  const params = splitTopLevel(inserted);
+  return params.length > 0 && params.every(isOptionalParam);
+}
+
+// +1 for an opening bracket at s[i], -1 for a closing one, else 0. The `>` of
+// `=>` / `->` closes nothing.
+function bracketStep(s, i) {
+  const c = s[i];
+  if ('([{<'.includes(c)) return 1;
+  if (')]}'.includes(c) || (c === '>' && s[i - 1] !== '=' && s[i - 1] !== '-')) return -1;
+  return 0;
+}
+
+// Splits at commas outside brackets.
+function splitTopLevel(s) {
+  const out = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < s.length; i++) {
+    const step = bracketStep(s, i);
+    if (step !== 0) depth = Math.max(0, depth + step);
+    else if (s[i] === ',' && depth === 0) {
+      out.push(s.slice(start, i));
+      start = i + 1;
+    }
+  }
+  out.push(s.slice(start));
+  return out;
+}
+
+/**
+ * A parameter a caller may leave out: a default value (`x = 1`, `int y = 0`,
+ * `strict: bool = False`), TS `x?: T`, a variadic (`*args`, `**kwargs`, a bare
+ * `*` marker, `...rest`, Go `opts ...T`, Java `T... xs`). Whitespace is
+ * already gone from the key.
+ */
+function isOptionalParam(p) {
+  if (!p) return false;
+  if (p[0] === '*') return true;
+  let depth = 0;
+  for (let i = 0; i < p.length; i++) {
+    const c = p[i];
+    const step = bracketStep(p, i);
+    if (step !== 0) { depth = Math.max(0, depth + step); continue; }
+    if (depth !== 0) continue;
+    if (c === '.' && p.startsWith('...', i)) return true;
+    if (c === '?' && (p[i + 1] === ':' || i === p.length - 1)) return true;
+    // The first depth-0 `=` is the default, unless it starts `=>` (an arrow
+    // type). No `==`/`>=` can come earlier; `number>=new Map()` is a generic's
+    // `>` then a default.
+    if (c === '=' && p[i + 1] !== '>') return true;
   }
   return false;
 }
@@ -286,11 +446,13 @@ function computeStopReport({ edits, state, now, workText, callers, mtimeMs }) {
     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
+    // Body-only this turn, or only optional parameters appended (Q2).
+    if (!signatureChanged(e.sigs, after, e.symbol)) continue;
     changed.push({ key, file: e.file, symbol: e.symbol });
   }
 
   const lines = [];
+  const listed = new Set();
   for (const c of changed.slice(0, MAX_SYMBOLS_CHECKED)) {
     const refs = callers(c.symbol, c.file);
     if (!refs || refs.length === 0) continue;
@@ -318,6 +480,7 @@ function computeStopReport({ edits, state, now, workText, callers, mtimeMs }) {
     }
     lines.push(line);
     next.reported.push(c.key);
+    for (const r of untouched) listed.add(r.file);
   }
   // 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
@@ -327,7 +490,54 @@ function computeStopReport({ edits, state, now, workText, callers, mtimeMs }) {
     lines.push('  ' + unchecked.length + ' more changed, callers not checked: ' +
       unchecked.map((c) => shellQuoteArg(c.symbol) + '() in ' + shellQuoteArg(c.file)).join(', '));
   }
-  return { lines, state: next };
+  // `symbols` / `files`: what the report names, for its telemetry and its
+  // follow-up (D#163). Not part of `state`.
+  return { lines, state: next, symbols: next.reported.length - state.reported.length, files: [...listed].sort() };
+}
+
+// The follow-up remembers at most this many of a report's caller files.
+const MAX_FOLLOWUP_FILES = 64;
+
+/**
+ * What a report leaves behind (D#163): the `stop_check` record — for every
+ * report the model is shown, the one made only of the "more changed, callers
+ * not checked" line included — and the follow-up to judge at the next Stop,
+ * only when the report named caller files. `callers` counts every caller file
+ * the report found, the ones past the text's per-symbol cap included.
+ * @param {{lines:string[], state:{lastStopAt:number}, symbols?:number, files?:string[]}} report
+ * @returns {{check: object|null, pending: {at:number, files:string[]}|null}}
+ */
+function reportRecords(report) {
+  if (!report.lines.length) return { check: null, pending: null };
+  const files = report.files || [];
+  return {
+    check: { hook: 'stop', action: 'stop_check', symbols: report.symbols || 0, callers: files.length },
+    pending: files.length ? { at: report.state.lastStopAt, files: files.slice(0, MAX_FOLLOWUP_FILES) } : null,
+  };
+}
+
+/**
+ * Whether a report was acted on: a caller file it listed was edited after it —
+ * an Edit logged since `pending.at`, or an mtime at or after it (Write, `sed
+ * -i`, formatters; the same reading as "touched this turn"). Judged at the
+ * next Stop, which is the end of the continuation the feedback starts.
+ * @param {{at:number, files:string[]}} pending  left in the Stop state by the report
+ * @param {{ts:number, file:string}[]} edits  the session's edit log
+ * @param {(file:string)=>number|null} mtimeMs
+ * @returns {{adopted:boolean, listed:number, edited:number}}
+ */
+function followUpOf(pending, edits, mtimeMs) {
+  const listed = new Set(pending.files);
+  const edited = new Set();
+  for (const e of edits) {
+    if (e.ts >= pending.at && listed.has(e.file)) edited.add(e.file);
+  }
+  for (const f of listed) {
+    if (edited.has(f)) continue;
+    const m = mtimeMs(f);
+    if (m !== null && m >= pending.at) edited.add(f);
+  }
+  return { adopted: edited.size > 0, listed: listed.size, edited: edited.size };
 }
 
 function formatStopContext(lines) {
@@ -350,17 +560,32 @@ function readStdinJson() {
 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;
+  if (!input || !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 { recordRecommendation } = require('./recommendation-log');
+  const mtimeMs = (file) => {
+    try { return fs.statSync(path.join(root, file)).mtimeMs; } catch { return null; }
+  };
+  const state = sessionEdits.readStopState(root, input.session_id);
+  // The previous report's follow-up (D#163), at every Stop — the one ending
+  // the continuation that report started included. It only records: nothing
+  // is emitted, so a continuation cannot loop through it.
+  if (state.pending) {
+    const f = followUpOf(state.pending, sessionEdits.readEdits(root, input.session_id), mtimeMs);
+    recordRecommendation(root, { hook: 'stop', action: 'stop_followup', ...f });
+    delete state.pending;
+    sessionEdits.writeStopState(root, input.session_id, state);
+  }
+  // A continuation caused by a Stop hook is never re-checked.
+  if (input.stop_hook_active === true) return;
+
   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) => {
@@ -410,11 +635,12 @@ function runMain() {
             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; }
-      },
+      mtimeMs,
     });
   }
+  const rec = reportRecords(report);
+  if (rec.check) recordRecommendation(root, rec.check);
+  if (rec.pending) report.state.pending = rec.pending;
   sessionEdits.writeStopState(root, input.session_id, report.state);
 
   const text = formatStopContext(report.lines);
@@ -426,6 +652,6 @@ function runMain() {
 if (require.main === module) runMain();
 
 module.exports = {
-  extractSignatures, signatureChanged, findCallSiteLine, computeStopReport, formatStopContext,
-  MAX_SYMBOLS_CHECKED, MAX_CALLERS_LISTED,
+  extractSignatures, allSignatures, signatureChanged, findCallSiteLine, computeStopReport, formatStopContext,
+  followUpOf, reportRecords, MAX_SYMBOLS_CHECKED, MAX_CALLERS_LISTED, MAX_FOLLOWUP_FILES,
 };

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

@@ -88,6 +88,14 @@ function runMain() {
   if (!text) return;
   const { emitEventContext } = require('./hook-emit');
   process.stdout.write(emitEventContext('SubagentStart', text) + '\n');
+  // D#163: how many subagents were handed the facts. Whether they then used
+  // the index is in their transcripts, not here (scripts/subagent_share.py).
+  // The agent type is harness input; only a plain name is kept.
+  const agent = typeof input.agent_type === 'string' && /^[\w:.-]{1,64}$/.test(input.agent_type)
+    ? input.agent_type : null;
+  require('./recommendation-log').recordRecommendation(root, {
+    hook: 'subagent', action: 'subagent_context', ...(agent ? { agent } : {}),
+  });
 }
 
 if (require.main === module) runMain();

package/claude-plugin/scripts/user-prompt-context.js

@@ -42,6 +42,7 @@ const { hidden } = require('./proc-opts');
 // must not load (startup budget); it used to be a third hand-spelled copy of the
 // same three path segments (JS-05).
 const { MANIFEST_FILE: MANIFEST_PATH } = require('./cache-paths');
+const { capContext } = require('./hook-emit');
 
 // --- Per-type rate limiting (replaces single global cooldown) ---
 const COOLDOWNS = {
@@ -56,20 +57,26 @@ const COOLDOWNS = {
 // here, so an un-scoped flag was effectively a machine-wide mute: one `impact`
 // push in any repo silenced the next 30s of impact pushes in every other repo,
 // and `overview` did it for five minutes.
-function ctxFlagPath(type, cwd) {
-  return path.join(cgTmpDir(), `.code-graph-ctx-${cwdHash(cwd)}-${type}`);
+//
+// Keyed on (type, subject) when there is a subject — the symbol or path the
+// query is about. A type-only key let an impact push for one symbol swallow
+// the impact query for a DIFFERENT symbol asked a second later (hook audit
+// 2026-09-28). The subject is hashed: symbols and paths are not file-name safe.
+function ctxFlagPath(type, cwd, key) {
+  const suffix = key ? `-${cwdHash(String(key)).slice(0, 8)}` : '';
+  return path.join(cgTmpDir(), `.code-graph-ctx-${cwdHash(cwd)}-${type}${suffix}`);
 }
 
-function isCoolingDown(type, cwd = process.cwd()) {
+function isCoolingDown(type, cwd = process.cwd(), key) {
   try {
-    const stat = fs.statSync(ctxFlagPath(type, cwd));
+    const stat = fs.statSync(ctxFlagPath(type, cwd, key));
     return Date.now() - stat.mtimeMs < (COOLDOWNS[type] || 60000);
   } catch { return false; }
 }
 
-function markCooldown(type, cwd = process.cwd()) {
+function markCooldown(type, cwd = process.cwd(), key) {
   try {
-    fs.writeFileSync(ctxFlagPath(type, cwd), '');
+    fs.writeFileSync(ctxFlagPath(type, cwd, key), '');
   } catch { /* ok */ }
 }
 
@@ -111,8 +118,14 @@ const STOP_WORDS = new Set([
 
 const PLAIN_WORD_EXCLUDE = /^(possible|together|actually|something|different|important|following|available|necessary|currently|implement|operation|otherwise|beginning|knowledge|attention|according|certainly|sometimes|direction|recommend|structure|describe|question|complete|generate|anything|continue|consider|response|approach|happened|recently|probably|expected|previous|original|specific|directly|received|required|supposed|separate|designed|finished|provided|included|prepared|combined|properly|remember|whatever|although|document|handling|existing|everyone|standard|research|personal|relative|absolute|practice|language|thousand|national|evidence|refactor|understand|validate|analysis|debugging|configure|improving|resolving|creating|building|checking|updating|removing|changing|searching|cleaning|optimize|migration|overview|introduce|reviewing|thinking|managing|starting|yourself|features|problems|breaking|requires|argument|settings|includes|examples|comments|patterns|tutorial|concepts|supports|priority|organize|scenario|tracking|internal|external|abstract|concrete|strategy|evaluate|diagnose|platform|variable|optional|multiple)$/;
 
+// Text the harness submits on the user's behalf: background-task
+// notifications, teammate / agent / cross-session messages, reminders. 42 of
+// 175 real injections (24%) fired on these, answering a question nobody asked.
+const HARNESS_PROMPT = /^(?:<(?:task-notification|teammate-message|agent-message|cross-session-message|system-reminder|local-command-(?:stdout|stderr|caveat)|command-(?:name|message|args)|bash-(?:input|stdout|stderr))\b|Another Claude session sent a message:)/;
+
 function shouldSkip(msg) {
   const trimmed = msg.trim();
+  if (HARNESS_PROMPT.test(trimmed)) return 'harness';
   if (/^(yes|no|ok|commit|push|y|n|done|thanks|thank you|继续|确认|好的|好|是的|不|可以|行|对|提交|推送|没问题|谢谢|发布|更新|编译|安装|卸载|重启|重连|清理)\s*[.!?。！？]?\s*$/i.test(trimmed)) return 'simple';
   if (/^(修复|实施|执行|开始|按|实测|进入|用|重新)/.test(trimmed) && !/[a-zA-Z_]{3,}/.test(trimmed)) return 'action-only';
   return false;
@@ -397,11 +410,23 @@ function determineQueryType(intents, symbols, filePaths, isCoolingDownFn, messag
 
   const cd = isCoolingDownFn || (() => false);
 
-  if ((intents.impact || intents.modify) && hasStrict && !cd('impact')) return { type: 'impact', symbol: symbols.symbols[0] };
-  if (intents.callgraph && hasStrict && !cd('callgraph')) return { type: 'callgraph', symbol: symbols.symbols[0] };
-  if (filePaths.length > 0 && !cd('overview')) return { type: 'overview', path: filePaths[0].replace(/\/[^/]+$/, '/') };
-  if ((intents.search || intents.implement || hasQualified) && symbols.symbols.length > 0 && !cd('search')) return { type: 'search', symbol: symbols.symbols[0] };
-  if ((intents.understand || !hasAny) && symbols.symbols.length > 0 && !cd('search')) return { type: 'search', symbol: symbols.symbols[0] };
+  const sym = symbols.symbols[0];
+  // The file the prompt names disambiguates a same-named symbol (`impact
+  // url_for` is ambiguous in flask; `--file src/flask/helpers.py` answers).
+  const file = filePaths[0];
+
+  if ((intents.impact || intents.modify) && hasStrict && !cd('impact', sym)) return { type: 'impact', symbol: sym, ...(file ? { file } : {}) };
+  if (intents.callgraph && hasStrict && !cd('callgraph', sym)) return { type: 'callgraph', symbol: sym };
+  // The named file itself, not its parent dir: `src/context.ts` used to yield
+  // an overview of all of src/ — 18,497 chars, none of it about that file.
+  if (file && !cd('overview', file)) return { type: 'overview', path: file };
+  // Search only for an identifier-shaped name, like impact and callgraph. A
+  // plain English word (`lowConfidence`) searched as a concept injected code
+  // unrelated to the prompt (`undefined` → JSX attribute types, `networkx` →
+  // doc headings; 2026-09-28 usage evaluation B8), and UPS search injections
+  // were followed up 2 times in 51.
+  if ((intents.search || intents.implement || hasQualified) && hasStrict && !cd('search', sym)) return { type: 'search', symbol: sym };
+  if ((intents.understand || !hasAny) && hasStrict && !cd('search', sym)) return { type: 'search', symbol: sym };
 
   // Phase E fallback: nothing actionable above, but message has symptom phrasing.
   // Emit ONE-LINE prose hint (no CLI execution). Default-empty `message` keeps
@@ -501,7 +526,7 @@ function runMain() {
   const intents = detectIntents(message);
   // Key the cooldowns on the resolved project root, not the raw shell cwd, so a
   // `cd` into a subdir does not read as a different project and re-fire.
-  const query = determineQueryType(intents, symbols, filePaths, (type) => isCoolingDown(type, cwd), message);
+  const query = determineQueryType(intents, symbols, filePaths, (type, key) => isCoolingDown(type, cwd, key), message);
 
   if (!query) return;
 
@@ -510,12 +535,16 @@ function runMain() {
   if (query.type === 'symptom-hint') {
     markCooldown('symptom', cwd);
     process.stdout.write(
-      '[code-graph:hint] indexed repo — for vague-symptom prompts, try `semantic_code_search "<symptom>"` ' +
+      '[code-graph:hint] indexed repo — for vague-symptom prompts, try `code-graph-mcp search "<symptom words>"` ' +
       'or `module_overview <suspected-dir>` to surface candidate code structurally. Skip if not searching code.\n'
     );
     return;
   }
 
+  // A partial index answers wrongly, not just briefly (D5). Return before the
+  // cooldown so the same question is answered once the build is done.
+  if (require('./project-root').indexBuildInProgress(cwd)) return;
+
   const PREFIXES = {
     impact:    '[code-graph:impact] Blast radius — review before editing:',
     overview:  '[code-graph:structure] Module structure:',
@@ -556,17 +585,20 @@ function runMain() {
   // the same shape re-ran it — a 3s execFileSync timeout on EVERY turn, which is
   // the worst case wearing the cheapest disguise. The cooldown's job is rate
   // limiting; whether the run had something to say is a separate question.
-  markCooldown(query.type, cwd);
+  markCooldown(query.type, cwd, query.symbol || query.path);
 
   try {
     let result = '';
-    if (query.type === 'impact') result = run(['impact', query.symbol]);
+    if (query.type === 'impact') result = run(['impact', query.symbol, ...(query.file ? ['--file', query.file] : [])]);
     else if (query.type === 'callgraph') result = run(['callgraph', query.symbol, '--depth', '2']);
     else if (query.type === 'overview') result = run(['overview', query.path]);
     else if (query.type === 'search') result = run(['search', query.symbol, '--limit', '8']);
 
     if (result && result.trim()) {
-      process.stdout.write(`${PREFIXES[query.type]}\n${result.trim()}\n`);
+      // The shared 4,000-byte context budget. Written raw, a dir overview came
+      // back at 18,497 chars; past 10,000 Claude Code swaps the whole output
+      // for a file path and a preview.
+      process.stdout.write(capContext(`${PREFIXES[query.type]}\n${result.trim()}\n`));
     }
   } catch {
     /* return silently */

package/claude-plugin/skills/explore/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: explore
 description: |
-  Understand code structure efficiently using the AST index. Use BEFORE reading
-  files one by one — when starting work in unfamiliar code, exploring a module
-  before changes, or finding the right file to edit. One overview call replaces
-  5+ Read calls and saves significant context.
+  Understand code structure with the AST index before reading files one by
+  one — when starting work in unfamiliar code, exploring a module before a
+  change, or finding which file to edit. An overview lists a directory's
+  symbols and their callers in one call.
 ---
 
 # Explore Code (indexed project)
@@ -16,7 +16,10 @@ Use these BEFORE reading individual files:
 | Module structure | `code-graph-mcp overview <dir>` | 5+ Read calls |
 | Project architecture | `code-graph-mcp map --compact` | ls + README |
 | Who calls / what calls | `code-graph-mcp callgraph <symbol>` | Grep + manual trace |
-| Find by concept | `code-graph-mcp search "concept"` | 3+ Grep attempts |
-| Impact before edit | `code-graph-mcp impact <symbol>` | Grep for callers |
+| Find by concept | `code-graph-mcp search "concept"` (full-text) | 3+ Grep attempts |
+| Impact before a signature change | `code-graph-mcp impact <symbol>` | Grep for callers |
+| Every use (rename / remove) | `code-graph-mcp refs <symbol>`, then `grep -w` | Grep alone |
 
-**Workflow**: overview first → Read only the file you will edit.
+**Workflow**: overview first → Read only the file you will edit. Calls the graph could
+not resolve (dynamic dispatch, reflection, unresolved imports) are not in it, so confirm
+an empty answer with grep.

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