@sdsrs/code-graph 0.48.0 → 0.50.0

package/claude-plugin/scripts/lifecycle.js

@@ -75,6 +75,48 @@ function hasInstalledPluginRecord() {
   return !!(installed && installed.plugins && Array.isArray(installed.plugins[PLUGIN_ID]) && installed.plugins[PLUGIN_ID].length > 0);
 }
 
+/** The installPath Claude Code currently considers active (installed_plugins.json), or null. */
+function activeInstallPath() {
+  const installed = readJson(installedPluginsPath());
+  const recs = installed && installed.plugins && installed.plugins[PLUGIN_ID];
+  if (!Array.isArray(recs) || !recs[0] || typeof recs[0].installPath !== 'string') return null;
+  return recs[0].installPath;
+}
+
+/**
+ * Stale-relic detection: is THIS script running from an old plugin-cache
+ * version dir while installed_plugins.json points at a different (active)
+ * install that exists on disk?
+ *
+ * Why: a still-running Claude Code process keeps firing SessionStart from the
+ * install path it loaded at startup. After auto-update installs vN+1 and
+ * re-anchors manifest + settings.json, the next SessionStart in that old
+ * process runs the vN scripts, whose syncLifecycleConfig sees
+ * `manifest.version !== currentVersion` and — direction-blind — calls
+ * update(), dragging manifest and every settings.json hook path back to the
+ * vN dir. The two versions then ping-pong (observed live 2026-06-12: manifest
+ * 0.49.0 → rewritten 0.48.0 fifteen minutes after a successful update).
+ *
+ * The authority is installed_plugins.json, not version direction: a deliberate
+ * downgrade via /plugin lands installPath == the old dir, so the old scripts
+ * keep full self-heal rights. Dev checkouts and npm installs are exempt
+ * (pluginRoot not under the plugins cache).
+ */
+function isStaleRelicContext({
+  pluginRoot = PLUGIN_ROOT,
+  cacheRoot = pluginsCacheDir(),
+  activePath = activeInstallPath(),
+  existsSync = fs.existsSync,
+} = {}) {
+  if (!activePath) return false;
+  const root = path.resolve(pluginRoot);
+  const cache = path.resolve(cacheRoot);
+  if (root !== cache && !root.startsWith(cache + path.sep)) return false;
+  const active = path.resolve(activePath);
+  if (active === root) return false;
+  return existsSync(path.join(active, 'scripts', 'lifecycle.js'));
+}
+
 function isOurComposite(settings) {
   return settings.statusLine &&
     settings.statusLine.command &&
@@ -377,6 +419,50 @@ function registerHooksToSettings(settings) {
   return before !== JSON.stringify(settings.hooks);
 }
 
+// Inventory of (event, matcher) tuples we expect to find in settings.json after
+// install. Consumed by doctor (report + fix) and session-init (self-heal):
+// `missing` = entry absent; `stale` = present but the registered command no
+// longer matches what we'd write now (points at an old plugin-cache version
+// dir / moved path). A stale path can run pre-recordRecommendation hook code,
+// so the hook fires but the conversion metric stays dark — invisible to a
+// present/absent check. This is the 0.45.1-registered-while-0.45.4-active
+// case the RCA surfaced.
+function surveyHookCoverage(settings) {
+  const desired = buildSettingsHookEntries();
+  const expected = [];
+  const desiredCmd = {}; // key -> command string we would write now
+  for (const [event, entries] of Object.entries(desired)) {
+    for (const e of entries) {
+      const key = `${event}:${e.matcher || '*'}`;
+      expected.push(key);
+      desiredCmd[key] = e.hooks && e.hooks[0] && e.hooks[0].command;
+    }
+  }
+
+  const present = new Set();
+  const presentCmd = {}; // key -> command currently registered
+  if (settings && settings.hooks) {
+    for (const [event, entries] of Object.entries(settings.hooks)) {
+      if (!Array.isArray(entries)) continue;
+      for (const entry of entries) {
+        if (isOurHookEntry(entry)) {
+          const key = `${event}:${entry.matcher || '*'}`;
+          present.add(key);
+          if (entry.hooks && entry.hooks[0] && entry.hooks[0].command) {
+            presentCmd[key] = entry.hooks[0].command;
+          }
+        }
+      }
+    }
+  }
+
+  const missing = expected.filter(k => !present.has(k));
+  const stale = expected.filter(k =>
+    present.has(k) && desiredCmd[k] && presentCmd[k] && presentCmd[k] !== desiredCmd[k]
+  );
+  return { expected, present: [...present], missing, stale };
+}
+
 // --- Install (idempotent) ---
 
 function install() {
@@ -673,6 +759,8 @@ module.exports = {
   getPluginVersion, cleanupOldCacheVersions,
   removeHooksFromSettings, isOurHookEntry,
   registerHooksToSettings, buildSettingsHookEntries,                  // v0.32.0
+  surveyHookCoverage, compositeCommand,                                // v0.49.1 — version-aware self-heal
+  activeInstallPath, isStaleRelicContext,                              // v0.49.1 — stale-relic downgrade guard
   SETTINGS_HOOK_DESC, OUR_HOOK_SCRIPTS, OUR_DESCRIPTIONS,              // v0.32.0 — for tests
   PLUGIN_ROOT,                                                         // v0.32.1 — for tests / consumers
   registerStatuslineProvider, unregisterStatuslineProvider,

package/claude-plugin/scripts/lifecycle.test.js

@@ -660,4 +660,43 @@ test('scanForBrokenPaths is exported and returns the issue structure', (t) => {
   assert.ok(Array.isArray(issues));
   assert.ok(issues.some(i => i.type === 'hook' && i.event === 'PreToolUse' && i.path.includes('/nonexistent/')),
     'scanForBrokenPaths must report the seeded broken hook entry');
-});
+});
+// ── isStaleRelicContext (v0.49.1 downgrade-war guard) ──────────────────────
+
+test('isStaleRelicContext: relic in plugins cache defers to a different active install', (t) => {
+  const { isStaleRelicContext } = require('./lifecycle');
+  const cacheRoot = '/home/u/.claude/plugins/cache';
+  const relicRoot = `${cacheRoot}/code-graph-mcp/code-graph-mcp/0.48.0`;
+  const activeRoot = `${cacheRoot}/code-graph-mcp/code-graph-mcp/0.49.0`;
+
+  // The downgrade-war case: running from old cache dir, active points elsewhere.
+  assert.equal(isStaleRelicContext({
+    pluginRoot: relicRoot, cacheRoot, activePath: activeRoot,
+    existsSync: () => true,
+  }), true);
+
+  // Running FROM the active install → full self-heal rights.
+  assert.equal(isStaleRelicContext({
+    pluginRoot: activeRoot, cacheRoot, activePath: activeRoot,
+    existsSync: () => true,
+  }), false);
+
+  // Dev checkout / npm install (pluginRoot outside the plugins cache) → exempt.
+  assert.equal(isStaleRelicContext({
+    pluginRoot: '/repo/code-graph-mcp/claude-plugin', cacheRoot, activePath: activeRoot,
+    existsSync: () => true,
+  }), false);
+
+  // No installed_plugins record → exempt (nothing authoritative to defer to).
+  assert.equal(isStaleRelicContext({
+    pluginRoot: relicRoot, cacheRoot, activePath: null,
+    existsSync: () => true,
+  }), false);
+
+  // Active path recorded but its lifecycle.js is gone (cache wiped) → the
+  // relic is the only working copy left; keep self-heal rights.
+  assert.equal(isStaleRelicContext({
+    pluginRoot: relicRoot, cacheRoot, activePath: activeRoot,
+    existsSync: () => false,
+  }), false);
+});

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

@@ -11,10 +11,14 @@ const fs = require('fs');
 const path = require('path');
 const { findBinary } = require('./find-binary');
 const { cgTmpDir } = require('./tmp-dir');
+const { resolveProjectRoot } = require('./project-root');
+const { recordRecommendation } = require('./recommendation-log');
 
-const cwd = process.cwd();
-const dbPath = path.join(cwd, '.code-graph', 'index.db');
-if (!fs.existsSync(dbPath)) process.exit(0);
+// v0.49 — walk up from the shell cwd (subdir-cwd fix). The per-cwd index.db
+// gate kept this hook dark for entire sessions after `cd backend/` — daagu
+// 2026-06-12: 115 edits, zero impact injections.
+const cwd = resolveProjectRoot(process.cwd());
+if (cwd === null) process.exit(0);
 
 // Resolve binary the same way the other hooks do — bare PATH lookup misses
 // npm-global installs on systems where the global bin dir isn't on PATH for
@@ -22,10 +26,15 @@ if (!fs.existsSync(dbPath)) process.exit(0);
 const binary = findBinary();
 if (!binary) process.exit(0);
 
+// Hook-internal CLI runs are deliveries, not model-initiated conversions —
+// the marker keeps them out of the recommendations.jsonl `use` funnel leg.
+const internalEnv = { ...process.env, CODE_GRAPH_INTERNAL: '1' };
+
 // --- Parse tool input ---
 let input;
 try {
-  input = JSON.parse(fs.readFileSync('/dev/stdin', 'utf8'));
+  // fd 0, not '/dev/stdin': the path form fails ENXIO on socketpair stdin.
+  input = JSON.parse(fs.readFileSync(0, 'utf8'));
 } catch { process.exit(0); }
 
 const oldStr = (input.tool_input && input.tool_input.old_string) || '';
@@ -72,6 +81,7 @@ if (!symbol || symbol.length < 3) {
         try {
           const raw = execFileSync(binary, ['grep', candidate, filePath, '--json'], {
             cwd, timeout: 2000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+            env: internalEnv,
           });
           const grepResult = JSON.parse(raw);
           // Pick this candidate if it has few matches (precise location)
@@ -122,11 +132,14 @@ let jsonResult;
 try {
   const args = ['impact', symbol, '--json'];
   if (relFile && !relFile.startsWith('..')) args.push('--file', relFile);
-  const raw = execFileSync('code-graph-mcp', args, {
+  // v0.49 — use the resolved binary (bare 'code-graph-mcp' was PATH-dependent,
+  // diverging from the findBinary() result the rest of the hook trusts).
+  const raw = execFileSync(binary, args, {
     cwd,
     timeout: 2500,
     encoding: 'utf8',
     stdio: ['pipe', 'pipe', 'pipe'],
+    env: internalEnv,
   });
   jsonResult = JSON.parse(raw);
 } catch {
@@ -154,6 +167,9 @@ if (directCallers < 1) process.exit(0);
 // Mark cooldown
 try { fs.writeFileSync(cooldownFile, ''); } catch { /* ok */ }
 
+// Funnel visibility (v0.49): an injected impact summary is a delivered answer.
+recordRecommendation(cwd, { hook: 'edit', action: 'hint', answered: true });
+
 // --- Inject compact impact summary ---
 const routeCount = jsonResult.affected_routes || 0;
 const testCount = jsonResult.tests_affected || 0;

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

@@ -18,12 +18,15 @@
 //      2026-06-11 replay: 38/40 head-greps dark to this)
 //   6. Same command-hash not hinted within last 60s (per-command cooldown)
 //
-// BLOCK fires when shouldHint AND (shouldBlock):
-//   7. No precision flag in the command (-l / -A / -B / -C / --include / --exclude)
-//   8. Pattern looks identifier-like (CamelCase ≥4ch, or snake_case with _, or
-//      a declaration anchor like `fn X` / `class X` / `def X`)
-//   9. Pattern is not a bare marker word (TODO/FIXME/XXX/HACK/WARN/ERROR/NOTE)
+// BLOCK fires when shouldHint AND (classifyBlock, v0.49 intent-aware):
+//   7. Pattern looks identifier-like (CamelCase ≥4ch, or snake_case with _, or
+//      a declaration anchor like `fn X` / `class X` / `def X`), quoted
+//   8. Pattern is not a bare marker word (TODO/FIXME/XXX/HACK/WARN/ERROR/NOTE)
+//   9. No unanswerable-intent flag (-L / -v / --exclude*) — those stay hint
 //  10. CODE_GRAPH_NO_BLOCK_GREP != "1" (block escape, independent of QUIET_HOOKS)
+//  Mode: context flags (-A/-B/-C) + declaration anchors → 'show' (deny carries
+//  the symbol BODIES via `cg show`); context flags without named decls → hint;
+//  everything else (incl. -l / --include) → 'grep' (deny carries the hits).
 //
 // A `CODE_GRAPH_NO_BLOCK_GREP=1`-prefixed grep that would otherwise hint is
 // recorded as `action:'bypass'` and allowed silently (v0.48) — previously the
@@ -34,12 +37,11 @@
 // lookups, or the rare legitimate use of raw grep on indexed source.
 
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
 const crypto = require('crypto');
 const { cgTmpDir } = require('./tmp-dir');
 const { recordRecommendation } = require('./recommendation-log');
-const { runGrepAnswer, sanitizeSearchPath } = require('./cg-answer');
+const { runGrepAnswer, runShowAnswer, sanitizeSearchPath } = require('./cg-answer');
 
 // --- Pure logic (testable) ---
 
@@ -83,17 +85,21 @@ function shouldHint(cmd) {
   return true;
 }
 
-// v0.32.0 block tier — strictly narrower than shouldHint. The disqualifying
-// flags (-l, -A, -B, -C, --include, --exclude) mean the user is already doing
-// precise filtering and a blanket "use cg" suggestion would be wrong. The
-// identifier-like check restricts blocks to "I'm looking for a symbol" — the
-// exact use case cg replaces. Marker-only patterns (TODO/FIXME) are legit raw
-// text scans with no cg equivalent.
-// Match any short-flag cluster containing l/L/A/B/C (e.g. `-l`, `-rl`, `-rln`,
-// `-A`, `-rA3`). Combined flag clusters are common in real-world usage and the
-// "precision intent" applies as soon as ANY of these letters appears.
-const BLOCK_DISQUALIFYING_FLAGS =
-  /(?:^|\s)-[a-zA-Z]*[lLABC][a-zA-Z]*(?:\s|=|\d|$)|--(?:files-with-matches|files-without-match|include|exclude|exclude-dir|after-context|before-context|context)\b/;
+// v0.49 intent-aware block tiers. The v0.32 rationale ("precision flags mean
+// the user is filtering — a blanket *suggestion* would be wrong") was written
+// for the suggestion era; in the answer era the deny CARRIES the result, so a
+// flag only disqualifies when the answer cannot honor its intent. 2026-06-12
+// daagu replay: 22/128 head-greps were `rg "def X|class Y" -A 25` — function-
+// body reads the old rule exempted to (ignored) hints; `cg show` answers them.
+//
+// Context flags (-A/-B/-C): intent = read surrounding code. Answerable via
+// `show` only when the pattern names declarations; bare-identifier + context
+// stays hint (a grep-style answer can't honor ±N lines).
+const CONTEXT_FLAG =
+  /(?:^|\s)-[a-zA-Z]*[ABC][a-zA-Z]*(?:\s|=|\d|$)|--(?:after-context|before-context|context)\b/;
+// Intents the cg answer cannot honor: inverted file lists, exclusion scoping.
+const UNANSWERABLE_FLAGS =
+  /(?:^|\s)-[a-zA-Z]*[Lv][a-zA-Z]*(?:\s|=|\d|$)|--(?:files-without-match|invert-match|exclude|exclude-dir)\b/;
 // v0.32.1: drop the `type` declaration keyword (too common in English prose
 // like "# type checking") and anchor declaration anchors to pattern start
 // (otherwise `"some type X"` matches). CamelCase and snake_case still match
@@ -120,13 +126,41 @@ function extractPatterns(cmd) {
   return matches.map(m => m[1] !== undefined ? m[1] : m[2]);
 }
 
-function shouldBlock(cmd) {
-  if (!shouldHint(cmd)) return false;             // narrower than hint
-  if (BLOCK_DISQUALIFYING_FLAGS.test(cmd)) return false;
-  if (MARKER_ONLY.test(cmd)) return false;        // bare TODO/FIXME — no cg equivalent
+// Declaration anchors inside a pattern (`def cascade_failure|class TaskState`)
+// name the exact symbols the model wants to READ — extract them for `show`.
+const DECL_SYMBOL = /(?:fn|def|class|function|struct|impl|trait)\s+([A-Za-z_][A-Za-z0-9_]*)/g;
+
+function extractDeclSymbols(patterns) {
+  const out = [];
+  for (const p of patterns) {
+    for (const m of p.matchAll(DECL_SYMBOL)) {
+      if (!out.includes(m[1])) out.push(m[1]);
+    }
+  }
+  return out;
+}
+
+/// Block-tier classification (strictly narrower than shouldHint):
+///   {mode:'show', symbols} — declaration anchors + context flags → deliver bodies
+///   {mode:'grep'}          — symbol search (incl. -l / --include) → deliver hits
+///   null                   — hint tier (marker scans, unquoted, unanswerable flags)
+function classifyBlock(cmd) {
+  if (!shouldHint(cmd)) return null;              // narrower than hint
+  if (UNANSWERABLE_FLAGS.test(cmd)) return null;  // intent the answer can't honor
+  if (MARKER_ONLY.test(cmd)) return null;         // bare TODO/FIXME — no cg equivalent
   const patterns = extractPatterns(cmd);
-  if (patterns.length === 0) return false;        // unquoted pattern — conservative, hint
-  return patterns.some(p => IDENTIFIER_LIKE.test(p));
+  if (patterns.length === 0) return null;         // unquoted pattern — conservative, hint
+  if (!patterns.some(p => IDENTIFIER_LIKE.test(p))) return null;
+  if (CONTEXT_FLAG.test(cmd)) {
+    const symbols = extractDeclSymbols(patterns);
+    if (symbols.length === 0) return null;        // context read without named decls
+    return { mode: 'show', symbols: symbols.slice(0, 3) };
+  }
+  return { mode: 'grep' };
+}
+
+function shouldBlock(cmd) {
+  return classifyBlock(cmd) !== null;
 }
 
 // v0.47.1 — CC harness steers Bash toward ABSOLUTE paths (cd in compound
@@ -143,23 +177,9 @@ function normalizeCommandPaths(cmd, cwd) {
   return cmd.split(cwd.endsWith('/') ? cwd : cwd + '/').join('');
 }
 
-// v0.48 — the hook's process.cwd() follows the PERSISTENT shell, not the
-// project root: after the model runs `cd backend/`, every later bare grep used
-// to fail the index.db gate silently for the rest of the session (daagu
-// 2026-06-11: 38/40 head-greps dark). Walk up to the nearest ancestor holding
-// `.code-graph/index.db`; stop at $HOME (checked, not crossed) and fs root.
-function resolveProjectRoot(startDir, opts = {}) {
-  const home = opts.home !== undefined ? opts.home : os.homedir();
-  const exists = opts.exists || fs.existsSync;
-  let dir = path.resolve(startDir || '.');
-  for (;;) {
-    if (exists(path.join(dir, '.code-graph', 'index.db'))) return dir;
-    if (dir === home) return null;
-    const parent = path.dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
+// v0.48 — subdir-cwd fix; v0.49 — extracted to project-root.js so the read
+// hook shares it. Re-exported below for test/back-compat.
+const { resolveProjectRoot } = require('./project-root');
 
 // v0.48 — companion to resolveProjectRoot: when the shell sits in a subdir,
 // bare relative path args (`app --include=*.py` from backend/) are
@@ -199,13 +219,67 @@ function rebaseRelativePaths(cmd, relPrefix, rootDir, exists = fs.existsSync) {
   }).join('');
 }
 
-// v0.48 — bypass detection on the RAW command. The deny message documents
-// `CODE_GRAPH_NO_BLOCK_GREP=1` as a per-command escape; record its use so the
-// conversion funnel can see escape adoption instead of going dark.
+// v0.48 — bypass detection on the RAW command. (The deny copy stopped teaching
+// the escape in v0.49, but models that already know it — or learned it from a
+// session summary — must stay visible to the funnel.)
 function commandHasBypass(cmd) {
   return typeof cmd === 'string' && /(?:^|\s)CODE_GRAPH_NO_BLOCK_GREP=1(?:\s|$)/.test(cmd);
 }
 
+// v0.49 — `sed -n X,Yp file.py` is a Read the Read hook can't see; the
+// 2026-06-12 night used it heavily for structure exploration (four sed-range
+// reads of stock_picker/ in 3 min). Extract targets so they count toward the
+// shared read-fanout state.
+const SED_RANGE = /(?:^|[|;&]\s*)sed\s+-n\s+(?:['"]\d+,\d+p['"]|\d+,\d+p)\s+("[^"]+"|'[^']+'|[^\s;|&]+)/g;
+
+function extractSedReadTargets(cmd) {
+  if (!cmd || typeof cmd !== 'string' || cmd.length > 2000) return [];
+  const out = [];
+  for (const m of cmd.matchAll(SED_RANGE)) {
+    const tok = m[1].replace(/^["']|["']$/g, '');
+    if (tok && !out.includes(tok)) out.push(tok);
+  }
+  return out;
+}
+
+// v0.50 — a compound command (`grep …; sed -n 1,60p f` / `grep … && wc`) is
+// denied WHOLE, but the answer covers only the grep. The 2026-06-13 mem-project
+// deny swallowed a `; sed` read while the copy said "use these results directly
+// instead of re-running" — the tail's intent was silently dropped. Extract the
+// first top-level `;`/`&&` tail (quote-aware) so the deny can flag it for
+// re-issue. `||` tails are skipped: the answer delivered hits, so the on-failure
+// branch would not have run anyway. Pipes/redirects are the same pipeline.
+function extractUnansweredTail(cmd) {
+  if (!cmd || typeof cmd !== 'string' || cmd.length > 2000) return null;
+  let quote = null;
+  for (let i = 0; i < cmd.length; i++) {
+    const c = cmd[i];
+    if (quote) {
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") { quote = c; continue; }
+    if (c === ';' || (c === '&' && cmd[i + 1] === '&')) {
+      const tail = cmd.slice(i + (c === ';' ? 1 : 2)).trim();
+      return tail || null;
+    }
+  }
+  return null;
+}
+
+// Shared deny-copy footer for the unanswered compound tail. Budget-conscious:
+// two lines, verbatim command so the model can re-issue without thinking.
+// Wording is path-neutral — it must stay true for BOTH the answered deny
+// ("grep half answered, tail wasn't") and the static fallback (nothing was).
+function appendUnansweredTailNote(lines, tail) {
+  if (!tail) return;
+  const shown = tail.length > 300 ? tail.slice(0, 300) + '…' : tail;
+  lines.push(
+    'NOTE: the rest of this compound command (after the grep) did NOT run — re-issue it separately:',
+    `$ ${shown}`,
+  );
+}
+
 // v0.47.0 — pull the first source-tree path token out of the denied command so
 // the inline answer can scope its search the same way the raw grep would have.
 function extractSearchPath(cmd) {
@@ -246,7 +320,7 @@ function buildHint() {
   // Terse, no banner spam. Single message budget ~600 bytes.
   return [
     '[code-graph] Raw `grep`/`rg` on indexed source — consider AST-aware equivalents:',
-    '  • code-graph-mcp grep "<pat>" <path>          # grep + containing fn/module per hit',
+    '  • code-graph-mcp grep "<pat>" [paths...]      # grep + containing fn/module per hit (-F literal, -i, -w, -l, -C N)',
     '  • code-graph-mcp ast-search "<pat>" --type fn # filter by type/returns/params',
     '  • code-graph-mcp callgraph SYMBOL             # callers + callees, repo-wide',
     '  • code-graph-mcp show SYMBOL                  # one symbol: signature + source',
@@ -254,18 +328,22 @@ function buildHint() {
   ].join('\n');
 }
 
-function buildBlockReason() {
+function buildBlockReason(unansweredTail) {
   // Shown to Claude via PreToolUse `decision: block` reason. Must give a
   // concrete alternate command Claude can re-issue without further thinking.
-  return [
+  // v0.49 — NO escape-hatch line anywhere in deny copy: the daagu 2026-06-12
+  // night proved even the "THIS command only" scoping reads as a teachable
+  // permanent prefix (adopted in 8s, reused 11×, incl. on the exact identifier
+  // searches this hook targets). The env opt-out stays documented in README.
+  const lines = [
     '[code-graph] Raw `grep -rn` on indexed source — denied by code-graph hook.',
     'Use the AST-aware equivalent (returns containing fn/module per hit, repo-wide):',
-    '  code-graph-mcp grep "<pattern>" <path>          # FTS + AST context per hit',
+    '  code-graph-mcp grep "<pattern>" [paths...]      # AST context per hit; -F literal, -i, -w, -l, -C N, --max-count 0',
     '  code-graph-mcp ast-search "<pattern>" --type fn # filter by node type',
     '  code-graph-mcp callgraph SYMBOL                 # callers + callees',
-    'If this specific search truly needs raw-text regex (log/comment scan), prepend',
-    '`CODE_GRAPH_NO_BLOCK_GREP=1` to THIS command only — a per-command escape, not a default prefix.',
-  ].join('\n');
+  ];
+  appendUnansweredTailNote(lines, unansweredTail);
+  return lines.join('\n');
 }
 
 // v0.47.0 — deny WITH the answer inline. Hint-only had ~0% transfer and a bare
@@ -275,7 +353,7 @@ function buildBlockReason() {
 // advertising the bypass taught it a permanent prefix within 5 seconds (daagu
 // 2026-06-11: one deny → 14 bypassed greps). The static deny keeps a scoped
 // escape because there we give no answer.
-function buildBlockReasonWithAnswer(pattern, searchPath, answer) {
+function buildBlockReasonWithAnswer(pattern, searchPath, answer, unansweredTail) {
   const cmdShown = `code-graph-mcp grep "${pattern}"${searchPath ? ` ${searchPath}` : ''}`;
   const lines = [
     '[code-graph] Raw `grep` on indexed source — denied; the AST-aware equivalent already ran for you:',
@@ -288,14 +366,47 @@ function buildBlockReasonWithAnswer(pattern, searchPath, answer) {
   lines.push(
     'Each hit shows its containing fn/module — use these results directly instead of re-running the search.',
   );
+  appendUnansweredTailNote(lines, unansweredTail);
+  return lines.join('\n');
+}
+
+// v0.49 — show-mode deny: the model grepped for symbol DEFINITIONS with
+// context flags (-A/-B/-C = "show me the body"); the answer IS the bodies,
+// fetched via `code-graph-mcp show`. answer.text already carries per-symbol
+// `$ code-graph-mcp show <sym>` headers.
+function buildShowDenyReason(answer, unansweredTail) {
+  const lines = [
+    '[code-graph] Raw grep for symbol definitions — denied; here are the definitions from the AST index:',
+    answer.text,
+  ];
+  if (answer.truncated) {
+    lines.push('(truncated — re-run the `code-graph-mcp show <symbol>` command above for full source)');
+  }
+  lines.push('Use these directly instead of re-running the search.');
+  appendUnansweredTailNote(lines, unansweredTail);
   return lines.join('\n');
 }
 
+// v0.49 — plain `grep` speaks BRE: alternation/grouping arrive escaped
+// (`a\|b`, `\(x\)`) and 0-hit against cg grep's rust-regex dialect, wasting
+// the answer on the ALLOW fallthrough (2026-06-12: both answered:false denies
+// were dialect/path-shape misses). Unescape for plain grep only — rg/ag and
+// grep -E/-P are already extended.
+function translateBreToRg(cmd, pattern) {
+  if (typeof pattern !== 'string' || !pattern) return pattern;
+  const verb = (cmd.match(GREP_HEAD) || [])[1];
+  if (verb !== 'grep') return pattern;
+  if (/(?:^|\s)-[a-zA-Z]*[EP][a-zA-Z]*(?:\s|=|\d|$)|--(?:extended-regexp|perl-regexp)\b/.test(cmd)) {
+    return pattern;
+  }
+  return pattern.replace(/\\([|(){}+?])/g, '$1');
+}
+
 // v0.47.0 — cg grep found nothing. Regex-dialect differences (BRE `\|` vs
 // ripgrep) mean 0 hits is NOT proof of absence, so denying here could mislead.
 // Let the raw grep through with an honest one-liner.
 function buildNoHitsFyi(pattern) {
-  return `[code-graph] FYI: \`code-graph-mcp grep "${pattern}"\` found no matches — raw grep proceeding.`;
+  return `[code-graph] FYI: \`code-graph-mcp grep "${pattern}"\` found no matches — raw grep proceeding. (Regex-metachar patterns: \`code-graph-mcp grep -F\` searches literally.)`;
 }
 
 // --- Main execution (only when run directly) ---
@@ -338,6 +449,24 @@ function runMain() {
   } catch { return; }
 
   const rawCmd = (input.tool_input && input.tool_input.command) || '';
+
+  // v0.49 — sed-range reads count toward the read-fanout state (the Read hook
+  // never sees Bash-side file reads). A fired fanout hint already delivered an
+  // overview — skip grep hinting for this command to avoid double output.
+  const sedTargets = extractSedReadTargets(rawCmd);
+  if (sedTargets.length > 0) {
+    const readGuide = require('./pre-read-guide');
+    let fanoutFired = false;
+    for (const t of sedTargets) {
+      if (!readGuide.isSourceFile(t)) continue;
+      const abs = path.isAbsolute(t) ? t : path.resolve(shellCwd, t);
+      if (readGuide.trackReadAndMaybeHint(root, path.relative(root, abs))) {
+        fanoutFired = true;
+      }
+    }
+    if (fanoutFired) return;
+  }
+
   // v0.47.1 — match against the root-stripped form so absolute paths under the
   // project root behave exactly like their relative spelling. v0.48 — then
   // rebase bare subdir-relative tokens onto the root. Cooldown stays keyed on
@@ -358,18 +487,30 @@ function runMain() {
 
   markCooldown(rawCmd);
 
-  if (!isBlockDisabled() && shouldBlock(cmd)) {
+  const block = isBlockDisabled() ? null : classifyBlock(cmd);
+  if (block) {
     // v0.47.0 — run the AST-aware equivalent inside the hook and embed the
     // results in the deny reason ("answer in the deny"). Degrades to the
     // v0.46 static deny on any failure; downgrades to allow+FYI on 0 hits
     // (regex-dialect differences mean 0 hits ≠ proof of absence).
+    // v0.49 — intent-aware: declaration+context greps get `show` bodies,
+    // falling back to the grep answer, then the static deny.
     let answer = { status: 'unavailable' };
-    const pattern = pickBlockPattern(cmd);
+    const pattern = translateBreToRg(cmd, pickBlockPattern(cmd));
     // v0.48 — glob-truncated once, shared by the run and the deny message
     // (a literal `dir/*.py` argv made rg exit 1 → answered:false static deny).
     const searchPath = sanitizeSearchPath(extractSearchPath(cmd));
-    if (!isAnswerDisabled() && pattern) {
-      answer = runGrepAnswer({ cwd: root, pattern, searchPath });
+    let answeredMode = block.mode;
+    if (!isAnswerDisabled()) {
+      if (block.mode === 'show') {
+        answer = runShowAnswer({ cwd: root, symbols: block.symbols });
+        if (answer.status !== 'hits' && pattern) {
+          answeredMode = 'grep';
+          answer = runGrepAnswer({ cwd: root, pattern, searchPath });
+        }
+      } else if (pattern) {
+        answer = runGrepAnswer({ cwd: root, pattern, searchPath });
+      }
     }
 
     if (answer.status === 'no-hits') {
@@ -383,16 +524,27 @@ function runMain() {
     // ignored by Claude Code — the grep ran anyway. The hookSpecificOutput form
     // is the documented modern path. Exit 0 — this is a routing decision, not
     // a hook failure (exit 2 would mark the tool call as "hook errored").
+    const answered = answer.status === 'hits';
+    // v0.50 — flag the unanswered `;`/`&&` tail. Extracted from rawCmd: its
+    // paths are valid in the model's shell cwd, where the re-issue will run.
+    const unansweredTail = extractUnansweredTail(rawCmd);
     recordRecommendation(root, {
-      hook: 'grep', action: 'deny', answered: answer.status === 'hits',
+      hook: 'grep', action: 'deny', answered,
+      // mode segments which answer type converts (show=bodies, grep=hits).
+      ...(answered ? { mode: answeredMode } : {}),
+      // tail segments compound-command denies — lets the funnel compare
+      // re-issue behavior for denies that carried a tail note.
+      ...(unansweredTail ? { tail: true } : {}),
     });
     process.stdout.write(JSON.stringify({
       hookSpecificOutput: {
         hookEventName: 'PreToolUse',
         permissionDecision: 'deny',
-        permissionDecisionReason: answer.status === 'hits'
-          ? buildBlockReasonWithAnswer(pattern, searchPath, answer)
-          : buildBlockReason(),
+        permissionDecisionReason: !answered
+          ? buildBlockReason(unansweredTail)
+          : answeredMode === 'show'
+            ? buildShowDenyReason(answer, unansweredTail)
+            : buildBlockReasonWithAnswer(pattern, searchPath, answer, unansweredTail),
       },
     }) + '\n');
     return;
@@ -409,6 +561,12 @@ if (require.main === module) {
 module.exports = {
   shouldHint,
   shouldBlock,
+  classifyBlock,         // v0.49 — intent-aware block tiers
+  extractDeclSymbols,    // v0.49 — show-mode symbol extraction
+  translateBreToRg,      // v0.49 — BRE→rust-regex dialect bridge
+  buildShowDenyReason,   // v0.49 — show-mode deny copy
+  extractSedReadTargets, // v0.49 — sed-range reads feed the read-fanout state
+  extractUnansweredTail, // v0.50 — compound-tail honesty in answered denies
   extractPatterns,    // v0.32.1 — exposed for tests
   extractSearchPath,  // v0.47.0 — deny-with-answer
   normalizeCommandPaths, // v0.47.1 — abs-path matcher fix