@sdsrs/code-graph 0.48.0 → 0.49.0

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

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

package/claude-plugin/scripts/adopt.js

@@ -45,8 +45,8 @@ const INDEX_LINE =
   '- [code-graph-mcp](plugin_code_graph_mcp.md) ' +
   '[impact-analysis, callgraph, find-references, module-overview, semantic-search, ast-search, dead-code, find-similar-code, dependency-graph, trace-http-chain] — ' +
   '改 X 影响面/谁调用 X/X 被谁用/看 X 源码/Y 模块长啥样/概念查询 优先于 Grep；字面匹配走 Grep。' +
-  '核心 7（get_call_graph/module_overview/semantic_code_search/ast_search/find_references/get_ast_node/project_map）' +
-  '+ 进阶 5（impact_analysis/trace_http_chain/dependency_graph/find_similar_code/find_dead_code），决策表见全文';
+  'Bash 直呼 CLI 最快（零加载）：`code-graph-mcp callgraph X / show X / overview <dir> / grep "pat" / impact X`；' +
+  'MCP 核心 7（get_call_graph/module_overview/semantic_code_search/ast_search/find_references/get_ast_node/project_map），决策表见全文';
 
 // memdir L1 升格 (per sdscc 重构方案 §5.0): the INDEX_LINE that lands in
 // MEMORY.md is what Claude sees first on every keyword match. Tailoring it
@@ -234,9 +234,12 @@ function detectProjectType(cwd = process.cwd(), env = process.env) {
 // most for THIS project.
 function buildIndexLine(projectType = 'generic') {
   const prefix = '- [code-graph-mcp](plugin_code_graph_mcp.md) ';
+  // v0.49 — CLI form leads: in Claude Code the MCP tools are deferred (need a
+  // ToolSearch load before first call) while Bash is always live; the only
+  // conversions observed in real coding nights were CLI invocations.
   const coreSuffix =
-    '核心 7（get_call_graph/module_overview/semantic_code_search/ast_search/find_references/get_ast_node/project_map）' +
-    '+ 进阶 5（impact_analysis/trace_http_chain/dependency_graph/find_similar_code/find_dead_code），决策表见全文';
+    'Bash 直呼 CLI 最快（零加载）：`code-graph-mcp callgraph X / show X / overview <dir> / grep "pat" / impact X`；' +
+    'MCP 核心 7（get_call_graph/module_overview/semantic_code_search/ast_search/find_references/get_ast_node/project_map），决策表见全文';
   switch (projectType) {
     case 'web-rs':
     case 'web-node':

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

@@ -110,6 +110,9 @@ function runGrepAnswer(opts = {}) {
       encoding: 'utf8',
       maxBuffer: 4 * 1024 * 1024,
       stdio: ['ignore', 'pipe', 'ignore'],
+      // Hook-internal run: a delivered answer, not a model-initiated conversion.
+      // The CLI skips its recommendations.jsonl `use` record when this is set.
+      env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
     });
     if (res.error || res.signal || res.status !== 0) {
       return { status: 'unavailable' };
@@ -125,4 +128,95 @@ function runGrepAnswer(opts = {}) {
   }
 }
 
-module.exports = { runGrepAnswer, truncateAtLine, sanitizeSearchPath };
+/**
+ * v0.49 — Run `code-graph-mcp show <symbol>` for up to 3 declaration symbols
+ * and concatenate the bodies. Powers the show-mode deny (declaration-anchor +
+ * context-flag greps: the model wants to READ the functions, so hand it the
+ * functions). Same bounded/best-effort posture as runGrepAnswer; symbols that
+ * fail to resolve are skipped, all-fail → no-hits (caller falls back to grep).
+ */
+function runShowAnswer(opts = {}) {
+  const {
+    cwd,
+    symbols,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    maxBytes = DEFAULT_MAX_BYTES,
+  } = opts;
+  try {
+    if (!Array.isArray(symbols) || symbols.length === 0) {
+      return { status: 'unavailable' };
+    }
+    let binary = opts.binary;
+    if (binary === undefined) {
+      binary = process.env._CG_ANSWER_BINARY || require('./find-binary').findBinary();
+    }
+    if (!binary) return { status: 'unavailable' };
+
+    const parts = [];
+    for (const sym of symbols.slice(0, 3)) {
+      if (typeof sym !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(sym)) continue;
+      const res = spawnSync(binary, ['show', sym], {
+        cwd,
+        timeout: timeoutMs,
+        encoding: 'utf8',
+        maxBuffer: 4 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'ignore'],
+        env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
+      });
+      if (res.error || res.signal || res.status !== 0) continue;
+      const out = (res.stdout || '').trim();
+      if (!out || out.startsWith(NO_MATCH_PREFIX)) continue;
+      parts.push(`$ code-graph-mcp show ${sym}\n${out}`);
+    }
+    if (parts.length === 0) return { status: 'no-hits' };
+    const { text, truncated } = truncateAtLine(parts.join('\n\n'), maxBytes);
+    return { status: 'hits', text, truncated };
+  } catch {
+    return { status: 'unavailable' };
+  }
+}
+
+/**
+ * v0.49 — Run `code-graph-mcp overview <dir>` for the read-fanout hint, so the
+ * hint DELIVERS the module map instead of advising a tool call (hints measured
+ * 0/40 transfer on 2026-06-12; delivered answers satisfied 5/5 in place).
+ */
+function runOverviewAnswer(opts = {}) {
+  const {
+    cwd,
+    dir,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    maxBytes = DEFAULT_MAX_BYTES,
+  } = opts;
+  try {
+    if (!dir || typeof dir !== 'string' || dir.length > 300) {
+      return { status: 'unavailable' };
+    }
+    let binary = opts.binary;
+    if (binary === undefined) {
+      binary = process.env._CG_ANSWER_BINARY || require('./find-binary').findBinary();
+    }
+    if (!binary) return { status: 'unavailable' };
+    const res = spawnSync(binary, ['overview', dir], {
+      cwd,
+      timeout: timeoutMs,
+      encoding: 'utf8',
+      maxBuffer: 4 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env: { ...process.env, CODE_GRAPH_INTERNAL: '1' },
+    });
+    if (res.error || res.signal || res.status !== 0) {
+      return { status: 'unavailable' };
+    }
+    const out = (res.stdout || '').trim();
+    if (!out || out.startsWith(NO_MATCH_PREFIX)) return { status: 'no-hits' };
+    const { text, truncated } = truncateAtLine(out, maxBytes);
+    return { status: 'hits', text, truncated };
+  } catch {
+    return { status: 'unavailable' };
+  }
+}
+
+module.exports = {
+  runGrepAnswer, runShowAnswer, runOverviewAnswer, truncateAtLine, sanitizeSearchPath,
+};

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

@@ -4,7 +4,7 @@ const assert = require('node:assert/strict');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { runGrepAnswer, truncateAtLine } = require('./cg-answer');
+const { runGrepAnswer, runShowAnswer, truncateAtLine } = require('./cg-answer');
 
 // Stub "binary": a node script that reacts to its first real arg so one stub
 // covers hits / no-hits / error / timeout cases.
@@ -58,6 +58,19 @@ test('runGrepAnswer: passes grep subcommand, pattern and path as argv', () => {
   assert.match(r.text, /args=\["grep","fts5_search","src\/storage\/"\]/);
 });
 
+test('runGrepAnswer: child env carries CODE_GRAPH_INTERNAL=1 (not a funnel conversion)', () => {
+  // Stub variant that echoes the marker back in its output.
+  const envStub = path.join(stubDir, 'cg-env-stub.js');
+  fs.writeFileSync(envStub, `#!/usr/bin/env node
+process.stdout.write('internal=' + (process.env.CODE_GRAPH_INTERNAL || '') + '\\n');
+`);
+  fs.chmodSync(envStub, 0o755);
+  const r = runGrepAnswer({ cwd: stubDir, pattern: 'whatever', binary: envStub });
+  assert.equal(r.status, 'hits');
+  assert.match(r.text, /internal=1/,
+    'hook-internal CLI runs must be marked so record_cli_use skips them');
+});
+
 test('runGrepAnswer: omits path argv when no searchPath', () => {
   const r = runGrepAnswer({ cwd: stubDir, pattern: 'fts5_search', binary: stubBinary() });
   assert.match(r.text, /args=\["grep","fts5_search"\]/);
@@ -160,3 +173,34 @@ test('runGrepAnswer: glob searchPath is truncated before spawn (defensive layer)
   assert.equal(r.status, 'hits');
   assert.match(r.text, /args=\["grep","fts5_search","src\/storage"\]/);
 });
+
+// ── runShowAnswer (v0.49) — show-mode deny bodies ────────────────────
+
+test('runShowAnswer: concatenates per-symbol show output with $ headers', () => {
+  const r = runShowAnswer({ cwd: stubDir, symbols: ['alpha_one', 'beta_two'], binary: stubBinary() });
+  assert.equal(r.status, 'hits');
+  assert.match(r.text, /\$ code-graph-mcp show alpha_one/);
+  assert.match(r.text, /\$ code-graph-mcp show beta_two/);
+});
+
+test('runShowAnswer: skips non-identifier symbols, all-skipped → unavailable-safe no-hits', () => {
+  const r = runShowAnswer({ cwd: stubDir, symbols: ['$(rm -rf)', 'a|b'], binary: stubBinary() });
+  assert.equal(r.status, 'no-hits');
+});
+
+test('runShowAnswer: caps at 3 symbols', () => {
+  const r = runShowAnswer({
+    cwd: stubDir, symbols: ['s_one', 's_two', 's_three', 's_four'], binary: stubBinary(),
+  });
+  assert.equal(r.status, 'hits');
+  assert.doesNotMatch(r.text, /show s_four/);
+});
+
+test('runShowAnswer: empty symbol list → unavailable', () => {
+  assert.equal(runShowAnswer({ cwd: stubDir, symbols: [], binary: stubBinary() }).status, 'unavailable');
+});
+
+test('runShowAnswer: failing binary → no-hits (caller falls back to grep answer)', () => {
+  const r = runShowAnswer({ cwd: stubDir, symbols: ['ExplodePlease'], binary: stubBinary() });
+  assert.equal(r.status, 'no-hits');
+});

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,29 @@ 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.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) {
@@ -257,14 +293,16 @@ function buildHint() {
 function buildBlockReason() {
   // Shown to Claude via PreToolUse `decision: block` reason. Must give a
   // concrete alternate command Claude can re-issue without further thinking.
+  // 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.
   return [
     '[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 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');
 }
 
@@ -291,6 +329,37 @@ function buildBlockReasonWithAnswer(pattern, searchPath, answer) {
   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) {
+  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.');
+  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.
@@ -338,6 +407,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 +445,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 +482,21 @@ 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';
     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 } : {}),
     });
     process.stdout.write(JSON.stringify({
       hookSpecificOutput: {
         hookEventName: 'PreToolUse',
         permissionDecision: 'deny',
-        permissionDecisionReason: answer.status === 'hits'
-          ? buildBlockReasonWithAnswer(pattern, searchPath, answer)
-          : buildBlockReason(),
+        permissionDecisionReason: !answered
+          ? buildBlockReason()
+          : answeredMode === 'show'
+            ? buildShowDenyReason(answer)
+            : buildBlockReasonWithAnswer(pattern, searchPath, answer),
       },
     }) + '\n');
     return;
@@ -409,6 +513,11 @@ 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
   extractPatterns,    // v0.32.1 — exposed for tests
   extractSearchPath,  // v0.47.0 — deny-with-answer
   normalizeCommandPaths, // v0.47.1 — abs-path matcher fix

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

@@ -4,6 +4,11 @@ const assert = require('node:assert/strict');
 const {
   shouldHint,
   shouldBlock,
+  classifyBlock,
+  extractDeclSymbols,
+  translateBreToRg,
+  buildShowDenyReason,
+  extractSedReadTargets,
   extractPatterns,
   extractSearchPath,
   normalizeCommandPaths,
@@ -317,30 +322,81 @@ test('shouldBlock: rg with CamelCase on lib/', () => {
 
 // ── shouldBlock: should NOT block (downgrade to hint) — precision flags ─
 
-test('shouldBlock: grep -l (files-with-matches) → hint only', () => {
-  assert.equal(shouldBlock('grep -rl "EmbeddingModel" src/'), false);
+test('shouldBlock: grep -l (files-with-matches) → deny, grep answer covers file lists (v0.49)', () => {
+  assert.equal(shouldBlock('grep -rl "EmbeddingModel" src/'), true);
+  assert.deepEqual(classifyBlock('grep -rl "EmbeddingModel" src/'), { mode: 'grep' });
 });
 
-test('shouldBlock: --include=*.rs → user already filtering, hint only', () => {
-  assert.equal(shouldBlock('grep -rn --include="*.rs" "EmbeddingModel" src/'), false);
+test('shouldBlock: --include=*.rs → deny, path-scoped grep answer covers it (v0.49)', () => {
+  assert.equal(shouldBlock('grep -rn --include="*.rs" "EmbeddingModel" src/'), true);
 });
 
-test('shouldBlock: --exclude-dir=tests → hint only', () => {
+test('shouldBlock: --exclude=tests → hint only (answer cannot honor exclusion)', () => {
   assert.equal(shouldBlock('grep -rn --exclude=tests "EmbeddingModel" src/'), false);
 });
 
-test('shouldBlock: -A 3 context flag → hint only', () => {
+test('shouldBlock: -L / -v inverted intents → hint only', () => {
+  assert.equal(shouldBlock('grep -rL "EmbeddingModel" src/'), false);
+  assert.equal(shouldBlock('grep -rnv "EmbeddingModel" src/'), false);
+});
+
+test('shouldBlock: -A 3 with bare identifier → hint only (cannot honor ±N lines)', () => {
   assert.equal(shouldBlock('grep -rn -A 3 "EmbeddingModel" src/'), false);
 });
 
-test('shouldBlock: -B 2 context flag → hint only', () => {
+test('shouldBlock: -B 2 with bare identifier → hint only', () => {
   assert.equal(shouldBlock('grep -rn -B 2 "EmbeddingModel" src/'), false);
 });
 
-test('shouldBlock: -C 5 context flag → hint only', () => {
+test('shouldBlock: -C 5 with bare identifier → hint only', () => {
   assert.equal(shouldBlock('grep -rn -C 5 "EmbeddingModel" src/'), false);
 });
 
+// ── translateBreToRg (v0.49) — BRE→rust-regex dialect bridge ─────────
+
+test('translateBreToRg: plain grep BRE alternation unescaped', () => {
+  assert.equal(
+    translateBreToRg('grep -rn "UnifiedPickerEngine\\|engine.run" src/', 'UnifiedPickerEngine\\|engine.run'),
+    'UnifiedPickerEngine|engine.run');
+});
+
+test('translateBreToRg: rg patterns untouched (already extended)', () => {
+  assert.equal(translateBreToRg('rg "a\\|b" src/', 'a\\|b'), 'a\\|b');
+});
+
+test('translateBreToRg: grep -E untouched', () => {
+  assert.equal(translateBreToRg('grep -rnE "a\\|b" src/', 'a\\|b'), 'a\\|b');
+});
+
+test('translateBreToRg: unescapes groups/braces/quantifiers for plain grep', () => {
+  assert.equal(translateBreToRg('grep "fn \\(x\\)\\+" src/', 'fn \\(x\\)\\+'), 'fn (x)+');
+});
+
+// ── classifyBlock: show mode (v0.49) — the daagu 22/128 function-body reads ──
+
+test('classifyBlock: declaration anchor + -A → show mode with symbols', () => {
+  assert.deepEqual(
+    classifyBlock('rg -n "def cascade_failure|def reset_task" -A 25 backend/app/'),
+    { mode: 'show', symbols: ['cascade_failure', 'reset_task'] });
+});
+
+test('classifyBlock: multi-decl alternation caps at 3 symbols', () => {
+  const c = classifyBlock('rg -n "def a_one|def b_two|class CThree|fn d_four" -A 10 src/');
+  assert.equal(c.mode, 'show');
+  assert.deepEqual(c.symbols, ['a_one', 'b_two', 'CThree']);
+});
+
+test('classifyBlock: declaration anchor WITHOUT context flag → plain grep deny', () => {
+  assert.deepEqual(classifyBlock('grep -rn "def fetch_user" backend/app/services/'),
+    { mode: 'grep' });
+});
+
+test('extractDeclSymbols: dedupes and spans fn/def/class/struct anchors', () => {
+  assert.deepEqual(
+    extractDeclSymbols(['fn alpha_one', 'struct BetaTwo', 'fn alpha_one']),
+    ['alpha_one', 'BetaTwo']);
+});
+
 // ── shouldBlock: should NOT block — marker-only patterns ────────────
 
 test('shouldBlock: bare TODO marker → hint only (no cg equivalent)', () => {
@@ -402,8 +458,8 @@ test('buildBlockReason: lists cg grep + ast-search + callgraph', () => {
   assert.match(out, /code-graph-mcp callgraph/);
 });
 
-test('buildBlockReason: documents the escape hatch env var', () => {
-  assert.match(buildBlockReason(), /CODE_GRAPH_NO_BLOCK_GREP=1/);
+test('buildBlockReason: NEVER documents the escape hatch (v0.49 — the "THIS command only" scoping was adopted as a permanent prefix in 8s on 2026-06-12)', () => {
+  assert.doesNotMatch(buildBlockReason(), /CODE_GRAPH_NO_BLOCK_GREP/);
 });
 
 test('buildBlockReason: under 700-byte budget (single CC message)', () => {
@@ -583,11 +639,11 @@ test('replay: real abs-path symbol grep → BLOCK after normalization', () => {
   assert.equal(shouldBlock(norm), true);
 });
 
-test('replay: real abs-path -rln grep → HINT only after normalization (precision flag)', () => {
+test('replay: real abs-path -rln grep → DENY after normalization (v0.49: file lists answerable)', () => {
   const cmd = `grep -rln "load_active_config_standalone" ${DAAGU}/backend/tests/ | head -5`;
   const norm = normalizeCommandPaths(cmd, DAAGU);
   assert.equal(shouldHint(norm), true);
-  assert.equal(shouldBlock(norm), false);                     // -l cluster disqualifies block
+  assert.deepEqual(classifyBlock(norm), { mode: 'grep' });    // grep answer lists files per hit
 });
 
 test('replay: abs-path config-only grep stays silent after normalization', () => {
@@ -671,13 +727,6 @@ test('buildBlockReasonWithAnswer: NEVER advertises the bypass (v0.48 — one den
   assert.doesNotMatch(reason, /CODE_GRAPH_NO_BLOCK_GREP/);
 });
 
-test('buildBlockReason: scopes the escape to THIS command only', () => {
-  const reason = buildBlockReason();
-  assert.match(reason, /CODE_GRAPH_NO_BLOCK_GREP=1/);
-  assert.match(reason, /THIS command only/);
-  assert.match(reason, /not a default/);
-});
-
 test('buildBlockReasonWithAnswer: no searchPath → command has no path arg', () => {
   const reason = buildBlockReasonWithAnswer('fts5_search', undefined, {
     status: 'hits', text: 'hit', truncated: false,
@@ -1040,3 +1089,30 @@ test('rebaseRelativePaths: glob token rebases when its glob-truncated dir exists
   assert.equal(
     sanitizeSearchPath(extractSearchPath(rebased)), 'backend/app/services/llm_engine');
 });
+
+// ── extractSedReadTargets (v0.49) — sed-range reads feed read-fanout ──
+
+test('extractSedReadTargets: plain and quoted ranges, abs and rel paths', () => {
+  assert.deepEqual(
+    extractSedReadTargets('sed -n 620,700p /abs/proj/backend/app/services/market.py'),
+    ['/abs/proj/backend/app/services/market.py']);
+  assert.deepEqual(
+    extractSedReadTargets("sed -n '230,310p' backend/app/services/tushare.py"),
+    ['backend/app/services/tushare.py']);
+});
+
+test('extractSedReadTargets: multiple segments in one command, deduped', () => {
+  const cmd = 'sed -n 60,200p src/a.py; echo ===; sed -n 250,300p src/b.py && sed -n 250,300p src/b.py';
+  assert.deepEqual(extractSedReadTargets(cmd), ['src/a.py', 'src/b.py']);
+});
+
+test('extractSedReadTargets: non-range sed (substitution) ignored', () => {
+  assert.deepEqual(extractSedReadTargets("sed -i 's/a/b/' src/a.py"), []);
+  assert.deepEqual(extractSedReadTargets('sed -n /pattern/p src/a.py'), []);
+});
+
+test('extractSedReadTargets: pipeline sed after grep still extracted', () => {
+  assert.deepEqual(
+    extractSedReadTargets('grep -n "x" src/a.py | sed -n 1,5p src/b.py'),
+    ['src/b.py']);
+});

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

@@ -27,6 +27,8 @@ const path = require('path');
 const crypto = require('crypto');
 const { cgTmpDir } = require('./tmp-dir');
 const { recordRecommendation } = require('./recommendation-log');
+const { resolveProjectRoot } = require('./project-root');
+const { runOverviewAnswer } = require('./cg-answer');
 
 // --- Configuration ---
 
@@ -119,50 +121,87 @@ function buildHint(dir) {
   return `[code-graph] 5+ Reads into ${dir}/ — \`code-graph-mcp overview ${dir}/\` gives symbols+callers in one call (MCP: \`module_overview path=${dir}\`). Skip if you need raw file contents.`;
 }
 
+// v0.49 — the hint DELIVERS the overview instead of advising a tool call
+// (advice measured 0/40 transfer on 2026-06-12; delivered answers satisfied
+// 5/5 in place). Falls back to the advice-only line when the CLI is
+// unavailable or the dir has no overview.
+function buildHintWithAnswer(dir, answer) {
+  const lines = [
+    `[code-graph] 5+ Reads into ${dir}/ — module overview from the AST index (saves the remaining file-by-file reads):`,
+    answer.text,
+  ];
+  if (answer.truncated) {
+    lines.push(`(truncated — \`code-graph-mcp overview ${dir}/\` for the full map)`);
+  }
+  return lines.join('\n');
+}
+
 function isSilenced(env = process.env) {
   return env.CODE_GRAPH_QUIET_HOOKS === '1';
 }
 
+// v0.49 — answer tier opt-out, shared name with the grep hook's deny-answer
+// opt-out: =1 restores advice-only hints (no CLI run inside the hook).
+function isAnswerDisabled(env = process.env) {
+  return env.CODE_GRAPH_NO_ANSWER_IN_DENY === '1';
+}
+
+// --- Shared tracking core (also driven by pre-grep-guide's sed-range path) ---
+
+/// Record one read of `rel` (project-root-relative source path) and fire the
+/// fanout hint when the threshold crosses. Emits to stdout + records the
+/// recommendation. Returns true when a hint fired.
+function trackReadAndMaybeHint(root, rel, now = Date.now()) {
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false;
+  const dir = path.dirname(rel);
+  if (!dir || dir === '.' || dir === '') return false;  // top-level file: not fanout
+
+  const state = loadState(root, now);
+  recordRead(state, dir, now);
+  let fired = false;
+  if (shouldHint(state, dir, now)) {
+    markHint(state, dir, now);
+    fired = true;
+  }
+  saveState(root, state);
+  if (!fired) return false;
+
+  let answer = { status: 'unavailable' };
+  if (!isAnswerDisabled()) {
+    answer = runOverviewAnswer({ cwd: root, dir });
+  }
+  const answered = answer.status === 'hits';
+  recordRecommendation(root, { hook: 'read', action: 'hint', answered });
+  process.stdout.write((answered ? buildHintWithAnswer(dir, answer) : buildHint(dir)) + '\n');
+  return true;
+}
+
 // --- Main execution ---
 
 function runMain() {
   if (isSilenced()) return;
-  const cwd = process.cwd();
-  const dbPath = path.join(cwd, '.code-graph', 'index.db');
-  if (!fs.existsSync(dbPath)) return;
+  // v0.49 — walk up from the shell cwd (subdir-cwd fix; the read hook had
+  // recorded NOTHING in daagu history because sessions sat in backend/).
+  const root = resolveProjectRoot(process.cwd());
+  if (root === null) return;
 
   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 { return; }
 
   const filePath = (input.tool_input && input.tool_input.file_path) || '';
   if (!isSourceFile(filePath)) return;
 
-  // Normalize to a cwd-relative path. If the file is outside cwd, skip —
-  // a hint pointing at an unrelated dir helps no one.
+  // Normalize to a root-relative path. Read sends absolute paths; files
+  // outside the project (other repos, ~/.claude/) stay silent.
   let rel;
   try {
-    rel = path.relative(cwd, filePath);
+    rel = path.relative(root, filePath);
   } catch { return; }
-  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return;
-
-  const dir = path.dirname(rel);
-  if (!dir || dir === '.' || dir === '') return;  // top-level file: not fanout
 
-  const now = Date.now();
-  const state = loadState(cwd, now);
-  recordRead(state, dir, now);
-  let fired = false;
-  if (shouldHint(state, dir, now)) {
-    markHint(state, dir, now);
-    fired = true;
-  }
-  saveState(cwd, state);
-  if (fired) {
-    recordRecommendation(cwd, { hook: 'read', action: 'hint' });
-    process.stdout.write(buildHint(dir) + '\n');
-  }
+  trackReadAndMaybeHint(root, rel);
 }
 
 if (require.main === module) {
@@ -172,6 +211,7 @@ if (require.main === module) {
 module.exports = {
   isSourceFile, dirOf, cwdHash, statePath,
   loadState, saveState, recordRead, shouldHint, markHint,
-  buildHint, isSilenced,
+  buildHint, buildHintWithAnswer, isSilenced, isAnswerDisabled,
+  trackReadAndMaybeHint,   // v0.49 — shared with pre-grep-guide's sed-range path
   FANOUT_THRESHOLD, COOLDOWN_MS, STATE_TTL_MS, SRC_EXT,
 };

package/claude-plugin/scripts/pre-read-guide.test.js

@@ -8,7 +8,8 @@ const crypto = require('crypto');
 
 const {
   isSourceFile, dirOf, recordRead, shouldHint, markHint,
-  buildHint, isSilenced,
+  buildHint, buildHintWithAnswer, isSilenced, isAnswerDisabled,
+  trackReadAndMaybeHint,
   FANOUT_THRESHOLD, COOLDOWN_MS, STATE_TTL_MS,
   loadState, saveState, statePath,
 } = require('./pre-read-guide');
@@ -243,3 +244,60 @@ test('flow: 5 reads to same dir → hint, 6th read same dir → no hint (cooldow
   recordRead(s, 'src/foo', 1005);
   assert.equal(shouldHint(s, 'src/foo', 1005), false);
 });
+
+// ── v0.49: answer-in-hint + shared tracking core ─────────────────────
+
+test('buildHintWithAnswer: embeds overview text and truncation pointer', () => {
+  const out = buildHintWithAnswer('src/storage', { text: 'Module src/storage\n  conn (57 callers)', truncated: true });
+  assert.match(out, /^\[code-graph\] 5\+ Reads into src\/storage\//);
+  assert.match(out, /conn \(57 callers\)/);
+  assert.match(out, /truncated — `code-graph-mcp overview src\/storage\/`/);
+});
+
+test('isAnswerDisabled: CODE_GRAPH_NO_ANSWER_IN_DENY=1 → advice-only hints', () => {
+  assert.equal(isAnswerDisabled({ CODE_GRAPH_NO_ANSWER_IN_DENY: '1' }), true);
+  assert.equal(isAnswerDisabled({}), false);
+});
+
+test('trackReadAndMaybeHint: fires on 5th read with stubbed overview answer', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'readfan-track-'));
+  // Stub CLI: prints a fake overview (hook resolves binary via _CG_ANSWER_BINARY).
+  const stub = path.join(root, 'stub.js');
+  fs.writeFileSync(stub, '#!/usr/bin/env node\nprocess.stdout.write("Module overview stub: 3 symbols\\n");');
+  fs.chmodSync(stub, 0o755);
+  const oldEnv = process.env._CG_ANSWER_BINARY;
+  process.env._CG_ANSWER_BINARY = stub;
+  // .code-graph present so recordRecommendation appends.
+  fs.mkdirSync(path.join(root, '.code-graph'), { recursive: true });
+
+  const written = [];
+  const origWrite = process.stdout.write.bind(process.stdout);
+  process.stdout.write = (chunk) => { written.push(String(chunk)); return true; };
+  try {
+    let fired = false;
+    for (let i = 0; i < 5; i++) {
+      fired = trackReadAndMaybeHint(root, 'src/storage/file' + i + '.rs');
+    }
+    assert.equal(fired, true, '5th same-dir read must fire');
+    assert.match(written.join(''), /Module overview stub/, 'hint must EMBED the overview answer');
+    const recs = fs.readFileSync(path.join(root, '.code-graph', 'recommendations.jsonl'), 'utf8');
+    assert.match(recs, /"hook":"read"/);
+    assert.match(recs, /"answered":true/);
+  } finally {
+    process.stdout.write = origWrite;
+    if (oldEnv === undefined) delete process.env._CG_ANSWER_BINARY;
+    else process.env._CG_ANSWER_BINARY = oldEnv;
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('trackReadAndMaybeHint: top-level and outside-root paths never fire', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'readfan-skip-'));
+  try {
+    assert.equal(trackReadAndMaybeHint(root, 'main.rs'), false);
+    assert.equal(trackReadAndMaybeHint(root, '../other/file.rs'), false);
+    assert.equal(trackReadAndMaybeHint(root, '/abs/file.rs'), false);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

package/claude-plugin/scripts/project-root.js

@@ -0,0 +1,30 @@
+'use strict';
+// Shared project-root resolution for the PreToolUse hooks (v0.49 — extracted
+// from pre-grep-guide so pre-read-guide gets the same subdir-cwd fix without a
+// circular require).
+//
+// The hook's process.cwd() follows the PERSISTENT shell, not the project root:
+// after the model runs `cd backend/`, every per-cwd gate (index.db existence,
+// relative-path matching) fails silently for the rest of the session (daagu
+// 2026-06-11: 38/40 head-greps dark; the read hook never recorded AT ALL).
+// Walk up to the nearest ancestor holding `.code-graph/index.db`; stop at
+// $HOME (checked, not crossed) and fs root.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+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;
+  }
+}
+
+module.exports = { resolveProjectRoot };

package/claude-plugin/templates/plugin_code_graph_mcp.md

@@ -38,6 +38,11 @@ type: reference
 
 ## 何时调用 MCP/CLI（替代多步 Grep/Read）
 
+> **v0.49 起 CLI 优先**：Claude Code 里 MCP 工具是 deferred（首次调用前要
+> ToolSearch 加载），而 Bash 永远在线——真实编程夜（2026-06-12）观测到的全部
+> 转化都是 CLI 调用。结构化查询的最快路径是 Bash 直呼
+> `code-graph-mcp callgraph X / show X / overview <dir> / grep "pat" / impact X`。
+>
 > v0.10.0 起：tools/list 默认只暴露 7 个核心工具；下表"进阶 5"中的工具
 > 已从 tools/list 隐藏以节省 session 启动 tokens。**Claude Code 里请走 CLI
 > 子命令**（MCP schema 不在 list，Claude Code 的 ToolSearch 不会加载，直接

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "MCP server that indexes codebases into an AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing",
   "license": "MIT",
   "repository": {
@@ -35,10 +35,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.48.0",
-    "@sdsrs/code-graph-linux-arm64": "0.48.0",
-    "@sdsrs/code-graph-darwin-x64": "0.48.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.48.0",
-    "@sdsrs/code-graph-win32-x64": "0.48.0"
+    "@sdsrs/code-graph-linux-x64": "0.49.0",
+    "@sdsrs/code-graph-linux-arm64": "0.49.0",
+    "@sdsrs/code-graph-darwin-x64": "0.49.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.49.0",
+    "@sdsrs/code-graph-win32-x64": "0.49.0"
   }
 }