@sdsrs/code-graph 0.160.0 → 0.162.0

package/README.md

@@ -151,6 +151,14 @@ known boundaries, not bugs to report:
   `impact` reports separately as `value reference(s) — callbacks / fn-pointers /
   type positions`. Together with the row above, this is why `include_dead`
   results are candidates to verify rather than a verdict.
+- **Dispatch by name.** A function reached through a string key, a reflection
+  call or an event name (`handlers["save"]`, `getattr(obj, "save")`,
+  `send(:save)`, `bus.on("save", …)`) has no edge. When `callgraph`, `impact`
+  or `refs` finds no caller for a function, the answer lists up to 5 lines
+  where the name appears in such a shape or is passed as a value (`boundaries`
+  in `--json` and MCP), and a `code-graph-mcp grep` that shows every
+  occurrence. It is a disclosure, not an edge, and a lexical one: a line it
+  does not list is not proof that nothing dispatches to the function.
 
 ## Architecture
 
@@ -159,6 +167,7 @@ src/
 ├── domain.rs     # Shared constants, relation types, env-var config
 ├── resolve.rs    # Shared symbol resolution + ambiguity verdicts (CLI and MCP)
 ├── outcome.rs    # Retrieval-adoption metrics from session transcripts
+├── budget.rs     # Output budgets (--budget / max_tokens): rank, shorten, drop, next step
 ├── cli/          # Every `code-graph-mcp <cmd>` subcommand (one file per command)
 ├── mcp/          # MCP protocol layer (JSON-RPC, tool registry, server)
 │   └── server/   # McpServer with IndexingState + CacheState sub-structs
@@ -341,6 +350,8 @@ cargo uninstall code-graph-mcp       # or delete the target/release binary
 | `ast_search` | Search AST nodes by text and/or structural filters (type, return type, params) |
 | `find_references` | Find all references to a symbol (callers, importers, inheritors, implementors, value/type references). Supports `compact` mode |
 
+**Output budget.** `project_map`, `module_overview`, `get_call_graph` and `get_ast_node` take an optional `max_tokens` (100-100000, counted as bytes/3 of the JSON answer). The answer is ranked by caller count; lower-ranked items are first shortened (no key symbols, no signature, no source body), then left out, and never cut in the middle. A `budget` object reports what was shortened or left out and `budget.next` holds the CLI command that returns it (one per section that lost entries, joined by `; `). On `module_overview` and `project_map`, `budget.over_budget` is `true` when even the fixed part of the answer is larger than the budget. Without `max_tokens` the answer is unchanged. Every existing size cut in these four tools (`hot_functions_truncated`, `active_capped`, the call-graph rollup, `compressed_node`, `_truncated`) now carries a `next` command too.
+
 **Hidden aliases.** These names are not in `tools/list` but still dispatch via `tools/call`, so existing clients keep working: `trace_http_chain` / `find_http_route` (→ `get_call_graph` with `route_path`), `read_snippet` (→ `get_ast_node`), `dependency_graph`, `find_similar_code`, `find_dead_code`, plus the management tools `start_watch`, `stop_watch`, `get_index_status` and `rebuild_index`. `impact_analysis` is **removed** — calling it returns `Unknown tool`; use `get_ast_node` with `include_impact=true`, or the CLI's `impact --json` for the full report.
 
 ## CLI Commands
@@ -384,6 +395,8 @@ All tools are also available as CLI subcommands for shell scripts, hooks, and te
 
 Common options: `--json` (JSON output), `--compact` (compact output), `--limit N`, `--depth N`, `--file <path>`.
 
+`map`, `overview`, `callgraph` and `show` take `--budget <tokens>` (100-100000, counted as bytes/3 of the text answer; not with `--json` or `--compact`). Items with the fewest callers are shortened first (a module loses its key symbols, a symbol its signature, a definition its body, a call-graph node its type), then left out, deepest call-graph nodes first. Nothing is cut in the middle, and in `overview` of a directory one file takes at most 70% of the budget. A notice line says what was left out and is followed by `next: <command>`, which prints it. The existing `... and N more` lines of `map` are followed by a `next:` line too.
+
 As of **v0.37.0** the CLI is [clap](https://docs.rs/clap)-based: **every subcommand has `--help`** for its full flag list (`code-graph-mcp <command> --help`), value flags accept both `--flag value` and `--flag=value`, and unknown flags or malformed arguments fail fast with a clear error and a non-zero exit code (`2`) instead of being silently ignored. For example, `trace` hides downstream middleware with `--no-middleware` (shown by default), and `snapshot` is a `create`/`inspect` subcommand pair.
 
 ## Plugin Skills

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

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

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

@@ -347,10 +347,45 @@ function runGrepAnswer(opts = {}) {
  *   `no-binary` distinguishes a missing/unlocatable binary from a runtime
  *   `unavailable`, so the deny funnel can see a dark flagship answer-in-deny.
  */
+/**
+ * The files of the definitions a `show` printed: each definition opens with an
+ * unindented header `<kind> <name>  <path>:<start>-<end>  <signature>`, its body
+ * indented below. null when an unindented line is not such a header, so a
+ * caller that must account for every definition can refuse.
+ */
+function showDefinitionFiles(out) {
+  const defs = [];
+  for (const line of out.split('\n')) {
+    if (line === '' || /^\s/.test(line)) continue;
+    const m = /^(\S+) \S+ {2}(\S+):\d+-\d+(?: |$)/.exec(line);
+    if (!m) return null;
+    defs.push({ kind: m[1], file: m[2] });
+  }
+  return defs.length ? defs : null;
+}
+
+/** Whether a root-relative file lies under a grep path ('' = the whole root). */
+function pathWithin(file, within) {
+  const w = within.replace(/^(\.\/)+/, '').replace(/\/+$/, '');
+  return w === '' || w === '.' || file === w || file.startsWith(w + '/');
+}
+
 function runShowAnswer(opts = {}) {
   const {
     cwd,
     symbols,
+    // A grep path the answer must stay inside (D#125 #2): `show` prints every
+    // same-named definition in the project. With `within`, a symbol is answered
+    // only when EVERY definition `show` prints lies inside the path and is one
+    // the grep's declaration keyword matches (`kinds`: symbol → the label and
+    // file-extension shapes it matches); a symbol with no definition inside is
+    // skipped (the grep finds none either), and any other mix refuses the whole
+    // answer. Narrowing with `show --file` was tried and removed: the label is
+    // coarser than the keyword, so a narrowed answer dropped real matches, and
+    // the inject printed the unnarrowed text (review of D#125, round 2).
+    // undefined: unscoped, as before.
+    within,
+    kinds,
     timeoutMs = DEFAULT_TIMEOUT_MS,
     maxBytes = DEFAULT_MAX_BYTES,
   } = opts;
@@ -365,6 +400,8 @@ function runShowAnswer(opts = {}) {
     // Which symbols actually resolved — the rewrite re-runs exactly these, so a
     // symbol that printed nothing here cannot turn into an exit-1 in the Bash call.
     const resolved = [];
+    // The argv that re-runs each resolved symbol, scoped when `within` is set.
+    const argvs = [];
     for (const sym of symbols.slice(0, 3)) {
       if (typeof sym !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(sym)) continue;
       const res = runCg(binary, ['show', sym], { cwd, timeoutMs });
@@ -383,12 +420,24 @@ function runShowAnswer(opts = {}) {
       if (classifyRun(res, { exitOneIsNoHits: false }) !== 'ok') continue;
       const out = (res.stdout || '').trim();
       if (isEmptyAnswer(out)) continue;
-      parts.push(`$ code-graph-mcp show ${sym}\n${out}`);
+      const argv = ['show', sym];
+      if (within !== undefined) {
+        const defs = showDefinitionFiles(out);
+        if (!defs) return { status: 'unavailable', reason: 'scope' };
+        if (!defs.some((d) => pathWithin(d.file, within))) continue;
+        const shapes = (kinds && kinds[sym]) || [];
+        const ext = (f) => (f.match(/\.([A-Za-z0-9]+)$/) || [])[1];
+        const matches = (d) => pathWithin(d.file, within)
+          && shapes.some((k) => k.labels.includes(d.kind) && k.exts.includes(ext(d.file)));
+        if (!defs.every(matches)) return { status: 'unavailable', reason: 'scope' };
+      }
+      parts.push(`$ code-graph-mcp ${argv.join(' ')}\n${out}`);
       resolved.push(sym);
+      argvs.push(argv);
     }
     if (parts.length === 0) return { status: 'no-hits' };
     const { text, truncated } = truncateAtLine(parts.join('\n\n'), maxBytes);
-    return { status: 'hits', text, truncated, symbols: resolved };
+    return { status: 'hits', text, truncated, symbols: resolved, argvs };
   } catch {
     return { status: 'unavailable' };
   }

package/claude-plugin/scripts/hook-emit.js

@@ -154,7 +154,33 @@ function emitPostToolContext(text) {
   });
 }
 
+/**
+ * additionalContext envelope for the two non-tool events the plugin answers
+ * (P1 #3). Both carry no decision:
+ *   - SubagentStart: "Context only" — the text is added to the subagent's
+ *     context before its first prompt.
+ *   - Stop: `hookSpecificOutput.additionalContext` is the documented
+ *     non-error form — the turn continues so Claude can act on it, labelled
+ *     "Stop hook feedback", instead of `decision: "block"`'s hook error.
+ * Source: https://code.claude.com/docs/en/hooks (SubagentStart / Stop
+ * decision control), checked against Claude Code 2.1.283.
+ * @param {'SubagentStart'|'Stop'} eventName
+ * @param {string} text
+ * @returns {string} JSON line
+ */
+function emitEventContext(eventName, text) {
+  if (eventName !== 'SubagentStart' && eventName !== 'Stop') {
+    throw new Error(`emitEventContext: unsupported event ${eventName}`);
+  }
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      additionalContext: capContext(text),
+    },
+  });
+}
+
 module.exports = {
   emitPreToolContext, emitPreToolAllowContext, emitPreToolRewrite, emitPostToolContext,
-  capContext, MAX_INJECTED_BYTES,
+  emitEventContext, capContext, MAX_INJECTED_BYTES,
 };

package/claude-plugin/scripts/hook-fail-open.js

@@ -41,6 +41,11 @@ const HOOK_TIMEOUT_SECONDS = {
   'post-grep-inject.js': 5,
   'user-prompt-context.js': 5,
   'session-init.js': 5,
+  // P1 #3. SubagentStart delays the subagent's first turn: one health-check
+  // (~125 ms here) is all it spends. Stop delays the end of the turn: one
+  // `git rev-parse`, then per changed symbol one `git show` + one `refs`.
+  'subagent-start.js': 3,
+  'stop-impact.js': 5,
 };
 
 // Left for the hook to render its answer and exit after the last child returns.

package/claude-plugin/scripts/lifecycle.js

@@ -923,6 +923,8 @@ const OUR_HOOK_SCRIPTS = [
   'pre-grep-guide.js',   // v0.32.0 — was in plugin-cache only, never fired
   'pre-read-guide.js',   // v0.32.0 — was in plugin-cache only, never fired
   'post-grep-inject.js', // compound-grep — PostToolUse(Bash) permission-neutral answer inject
+  'subagent-start.js',   // P1 #3 — SubagentStart index facts for Explore/Plan/general-purpose
+  'stop-impact.js',      // P1 #3 — Stop: changed signatures with untouched callers
 ];
 
 // Description markers — primary cleanup discriminator (immune to env/path
@@ -933,6 +935,8 @@ const SETTINGS_HOOK_DESC = {
   postToolUseEdit:  '[code-graph-mcp v0.32+] PostToolUse Write|Edit incremental-index update',
   postToolUseInject:'[code-graph-mcp v0.32+] PostToolUse Bash compound-grep answer inject (permission-neutral additionalContext)',
   userPromptSubmit: '[code-graph-mcp v0.32+] UserPromptSubmit context push',
+  subagentStart:    '[code-graph-mcp v0.32+] SubagentStart index facts for Explore/Plan/general-purpose subagents',
+  stop:             '[code-graph-mcp v0.32+] Stop signature-change check (callers in files not edited this turn)',
 };
 
 const OUR_DESCRIPTIONS = [
@@ -946,6 +950,8 @@ const OUR_DESCRIPTIONS = [
   SETTINGS_HOOK_DESC.postToolUseEdit,
   SETTINGS_HOOK_DESC.postToolUseInject,
   SETTINGS_HOOK_DESC.userPromptSubmit,
+  SETTINGS_HOOK_DESC.subagentStart,
+  SETTINGS_HOOK_DESC.stop,
 ];
 
 function isOurHookEntry(entry) {
@@ -1024,6 +1030,18 @@ function buildSettingsHookEntries() {
     UserPromptSubmit: [
       { description: SETTINGS_HOOK_DESC.userPromptSubmit, matcher: '', hooks: [scriptCmd('user-prompt-context.js')] },
     ],
+    // P1 #3. SubagentStart matches on the agent TYPE (built-in names per the
+    // hooks reference); Explore and Plan skip CLAUDE.md, general-purpose is
+    // the default Agent type. Custom/plugin agents are left alone — their
+    // own frontmatter decides what they know.
+    SubagentStart: [
+      { description: SETTINGS_HOOK_DESC.subagentStart, matcher: 'Explore|Plan|general-purpose', hooks: [scriptCmd('subagent-start.js')] },
+    ],
+    // Stop takes no matcher; '' keys the coverage survey as `Stop:*`, the same
+    // way UserPromptSubmit's does.
+    Stop: [
+      { description: SETTINGS_HOOK_DESC.stop, matcher: '', hooks: [scriptCmd('stop-impact.js')] },
+    ],
   };
 }
 
@@ -1212,7 +1230,17 @@ function surveyHookCoverage(settings) {
 // payload is engaging (a source-tree search → a deny/hint IS emitted); the Edit
 // payload's short old_string short-circuits before any binary spawn; the rest
 // just exercise the require-chain + stdin parse.
-function hookFirePayload(matcher) {
+function hookFirePayload(matcher, event = '') {
+  // Non-tool events are keyed by EVENT: Stop shares UserPromptSubmit's ''
+  // matcher, and a prompt payload would drive the wrong path. Both new hooks
+  // stay silent on these (no session edit log / no health report in the
+  // throwaway fixture); the probe proves they load and exit 0.
+  if (event === 'Stop') {
+    return { hook_event_name: 'Stop', session_id: 'hook-fire-probe', stop_hook_active: false };
+  }
+  if (event === 'SubagentStart') {
+    return { hook_event_name: 'SubagentStart', agent_id: 'hook-fire-probe', agent_type: 'Explore' };
+  }
   switch (matcher) {
     case 'Bash':
       // A QUOTED, identifier-like pattern → classifyBlock-positive → the
@@ -1251,7 +1279,7 @@ function defaultHookFireProbes() {
       const cmd = e.hooks && e.hooks[0] && e.hooks[0].command;
       const m = (cmd || '').match(/"([^"]+\.js)"/);
       if (!m) continue;
-      probes.push({ label: `${event}:${e.matcher || '*'}`, script: m[1], payload: hookFirePayload(e.matcher || '') });
+      probes.push({ label: `${event}:${e.matcher || '*'}`, script: m[1], payload: hookFirePayload(e.matcher || '', event) });
     }
   }
   return probes;

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

@@ -52,8 +52,15 @@ const {
   operandMatches,
   firstShellClause,
   normalizeCommandPaths,
+  rootOnlyInSearchPath,
+  isDirectory,
+  declKindsBySymbol,
+  extractPatterns,
   rebaseRelativePaths,
   resolveProjectRoot,
+  rewritePlan,
+  showAnswersPattern,
+  searchesSameFiles,
 } = require('./pre-grep-guide');
 
 // The command HEAD is grep/rg/ag (or git grep, or a KEY=VALUE/env prefix). Kept
@@ -288,8 +295,22 @@ function runMain() {
   if (segCwd === null) return;
   if ((segCwd !== root || relPrefix)
       && !operandMatches(firstShellClause(rawSegs[idx]), extractSearchPath(segment), root, segCwd)) return;
+  // D#125 #1 — the root strip rewrote a pattern that held the root.
+  if (!rootOnlyInSearchPath(rawSegs[idx], root, extractSearchPath(segment))) return;
   // Run the answer exactly like the deny path.
   const rawPattern = pickBlockPattern(segment);
+  // D#133 — the inject had no grammar of its own: a flag it did not know was
+  // dropped, so `"-rv"` (grep reads -r -v: the shell strips the quotes), ag's
+  // `-n` (no recursion), `rg --max-depth`, an abbreviated `--inv`, or a glob
+  // the shell expands one level deep (`src/*.js`) got an answer for another
+  // search. The grep clause must now read under the rewrite's grammar, the
+  // per-verb flag allowlist included, as the same pattern and path the answer
+  // uses. One grammar for both hooks, not a list of shapes to refuse. It also
+  // declines a plain grep without -r on a directory (D#125 #3), which a
+  // separate check here used to do.
+  const plan = rewritePlan(firstShellClause(segment), { isDir: (t) => isDirectory(path.resolve(root, t)) });
+  const norm = (p) => (p === undefined ? undefined : p.replace(/^\.\//, '').replace(/\/+$/, ''));
+  if (!plan || plan.pattern !== rawPattern || norm(plan.target) !== norm(extractSearchPath(segment))) return;
   // Grep-response gate (2026-07-03 audit: 18/18 injects were 0 CONSUMED because they
   // re-stated hits the model already had). If the command's OWN output already
   // surfaced the grepped symbol, the inject is redundant → skip it, saving the
@@ -382,7 +403,16 @@ function runMain() {
   if (answer.status !== 'hits') {
     if (block.mode === 'show') {
       answeredMode = 'show';
-      answer = runShowAnswer({ cwd: root, symbols: block.symbols });
+      // Scoped like the rewrite: the grep's path and declaration kinds; a grep
+      // with a file filter gets the grep answer, which honors it. So does a
+      // pattern `show` does not answer exactly (`fn foo` also matches
+      // `fn foobar`; D#133).
+      answer = flags.includes('-g') || flags.includes('-t') || !showAnswersPattern(rawPattern, segment)
+        ? { status: 'unavailable' }
+        : runShowAnswer({
+          cwd: root, symbols: block.symbols, within: searchPath ?? '',
+          kinds: declKindsBySymbol(extractPatterns(segment)),
+        });
       if (answer.status !== 'hits' && pattern) {
         answeredMode = 'grep';
         answer = runGrepAnswer({ cwd: root, pattern, searchPath, flags });
@@ -426,6 +456,15 @@ function runMain() {
     return;
   }
 
+  // D#133 #8 — a grep or show answer must read the files the grep read
+  // (untracked hidden or ignored ones, git grep's tracked-only set). Checked
+  // only for an answer about to be injected: it runs git. The call graph does
+  // not depend on which files a grep reads. A `show` answer reads the index,
+  // which skips more (review of D#133, H-2).
+  if (answeredMode !== 'callgraph' && !searchesSameFiles({
+    root, target: searchPath, verb: plan.verb, show: answeredMode === 'show',
+  })) return;
+
   recordRecommendation(root, {
     hook: 'grep', action: 'inject', answered: true,
     ...(pattern ? { pattern } : {}),

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

@@ -49,6 +49,22 @@ try {
   input = JSON.parse(fs.readFileSync(0, 'utf8'));
 } catch { process.exit(0); }
 
+// P1 #3 — the Stop hook (stop-impact.js) checks, at the end of the turn, which
+// edited symbols changed signature and which of their callers were left alone.
+// It needs to know what was edited in THIS session, so every Edit is logged
+// here — first file-only (so "files touched this turn" is complete even for
+// edits the signature extraction below gives up on), then again with the
+// symbol once one is known. Append-only, best-effort: it cannot fail the Edit.
+const sessionEdits = require('./session-edits');
+const editedAbs = (input.tool_input && input.tool_input.file_path) || '';
+const editedRel = editedAbs ? path.relative(cwd, path.resolve(cwd, editedAbs)) : '';
+const logEdit = (symbol) => {
+  if (editedRel && !editedRel.startsWith('..') && !path.isAbsolute(editedRel)) {
+    sessionEdits.recordEdit(cwd, input.session_id, { file: editedRel.split(path.sep).join('/'), symbol });
+  }
+};
+logEdit(null);
+
 const oldStr = (input.tool_input && input.tool_input.old_string) || '';
 if (!oldStr || oldStr.length < 10) process.exit(0);
 
@@ -159,6 +175,11 @@ function isCommonKeyword(s) {
   return /^(if|for|while|switch|catch|else|return|new|get|set|try)$/i.test(s);
 }
 
+// Before the cooldown: the cooldown throttles the impact PUSH, not the record
+// of what was edited — a second signature edit inside two minutes is exactly
+// the one the Stop check must still see.
+logEdit(symbol);
+
 // --- Per-symbol cooldown: 2 minutes ---
 // Project-scoped (see cwdHash in tmp-dir.js). A symbol name is the LEAST
 // project-unique key there is — `main`, `run`, `new`, `parse` collide across