@sdsrs/code-graph 0.48.0 → 0.50.0

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

@@ -4,6 +4,12 @@ const assert = require('node:assert/strict');
 const {
   shouldHint,
   shouldBlock,
+  classifyBlock,
+  extractDeclSymbols,
+  translateBreToRg,
+  buildShowDenyReason,
+  extractSedReadTargets,
+  extractUnansweredTail,
   extractPatterns,
   extractSearchPath,
   normalizeCommandPaths,
@@ -317,30 +323,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 +459,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 +640,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 +728,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,
@@ -692,6 +742,78 @@ test('buildBlockReasonWithAnswer: truncated flag adds marker', () => {
   assert.match(reason, /truncated/);
 });
 
+// ── v0.50 compound-command tail: deny answers the grep, NOT the rest ─
+
+test('extractUnansweredTail: `; sed` tail after piped grep (2026-06-13 real deny shape)', () => {
+  assert.equal(
+    extractUnansweredTail(
+      'grep -n "mem_update\\|registerTool" tests/server.test.mjs | head -20; sed -n \'1,60p\' tests/server.test.mjs'),
+    "sed -n '1,60p' tests/server.test.mjs");
+});
+
+test('extractUnansweredTail: && tail is unanswered (would have run on grep success)', () => {
+  assert.equal(
+    extractUnansweredTail('grep -rn "fts5_search" src/ && wc -l src/storage/db.rs'),
+    'wc -l src/storage/db.rs');
+});
+
+test('extractUnansweredTail: quoted separators are pattern text, not a tail', () => {
+  assert.equal(extractUnansweredTail('grep -rn "a;b" src/'), null);
+  assert.equal(extractUnansweredTail("grep -rn 'a && b' src/"), null);
+});
+
+test('extractUnansweredTail: pipes and redirects are the same pipeline, not a tail', () => {
+  assert.equal(extractUnansweredTail('grep -rn "Foo" src/ 2>&1 | head -10'), null);
+});
+
+test('extractUnansweredTail: || branch would NOT have run on hits — no tail', () => {
+  assert.equal(extractUnansweredTail('grep -rn "Foo" src/ || echo none'), null);
+});
+
+test('extractUnansweredTail: trailing separator with nothing after → no tail', () => {
+  assert.equal(extractUnansweredTail('grep -rn "Foo" src/;'), null);
+});
+
+test('buildBlockReasonWithAnswer: compound tail → note says the rest did NOT run', () => {
+  const reason = buildBlockReasonWithAnswer('fts5_search', 'src/', {
+    status: 'hits', text: 'hit', truncated: false,
+  }, "sed -n '1,60p' tests/server.test.mjs");
+  assert.match(reason, /did NOT run/);
+  assert.match(reason, /sed -n '1,60p' tests\/server\.test\.mjs/);
+});
+
+test('buildBlockReasonWithAnswer: no tail → no compound note', () => {
+  const reason = buildBlockReasonWithAnswer('fts5_search', 'src/', {
+    status: 'hits', text: 'hit', truncated: false,
+  });
+  assert.doesNotMatch(reason, /did NOT run/);
+});
+
+test('buildShowDenyReason: compound tail → note says the rest did NOT run', () => {
+  const reason = buildShowDenyReason(
+    { status: 'hits', text: 'fn body', truncated: false },
+    'cargo test -q');
+  assert.match(reason, /did NOT run/);
+  assert.match(reason, /cargo test -q/);
+});
+
+test('buildShowDenyReason: no tail → no compound note', () => {
+  const reason = buildShowDenyReason({ status: 'hits', text: 'fn body', truncated: false });
+  assert.doesNotMatch(reason, /did NOT run/);
+});
+
+test('buildBlockReason: compound tail → static deny also flags the unanswered tail', () => {
+  const reason = buildBlockReason("sed -n '1,60p' tests/server.test.mjs");
+  assert.match(reason, /did NOT run/);
+  assert.match(reason, /sed -n '1,60p' tests\/server\.test\.mjs/);
+});
+
+test('buildBlockReason: no tail → unchanged static deny', () => {
+  const reason = buildBlockReason();
+  assert.match(reason, /denied by code-graph hook/);
+  assert.doesNotMatch(reason, /did NOT run/);
+});
+
 test('buildNoHitsFyi: names the pattern and says raw grep proceeds', () => {
   const fyi = buildNoHitsFyi('GhostSymbol');
   assert.match(fyi, /GhostSymbol/);
@@ -854,6 +976,75 @@ test('e2e: CODE_GRAPH_NO_ANSWER_IN_DENY=1 → static deny even when stub would h
   }
 });
 
+test('e2e: compound `grep …; sed` → deny answers grep AND flags the unanswered sed tail', () => {
+  const uniq = `StubTail${Date.now()}`;
+  const fixture = e2eFixture(
+    `process.stdout.write('src/foo.rs:7  fn ' + process.argv[3] + '()\\n');`);
+  const cmd = `grep -n "${uniq}" src/foo.rs | head -20; sed -n '100,160p' src/foo.rs`;
+  try {
+    fsE2e.mkdirSync(pathE2e.join(fixture.dir, 'src'), { recursive: true });
+    fsE2e.writeFileSync(pathE2e.join(fixture.dir, 'src', 'foo.rs'), 'fn x() {}\n');
+    const res = runHook(cmd, fixture);
+    assert.equal(res.status, 0);
+    const out = JSON.parse(res.stdout);
+    assert.equal(out.hookSpecificOutput.permissionDecision, 'deny');
+    const reason = out.hookSpecificOutput.permissionDecisionReason;
+    assert.match(reason, /src\/foo\.rs:7/);            // grep half answered
+    assert.match(reason, /did NOT run/);               // tail flagged honestly
+    assert.match(reason, /sed -n '100,160p' src\/foo\.rs/); // verbatim re-issue line
+    // funnel: the deny record marks that a tail note was carried
+    const recs = fsE2e.readFileSync(
+      pathE2e.join(fixture.dir, '.code-graph', 'recommendations.jsonl'), 'utf8');
+    const rec = JSON.parse(recs.trim().split('\n').pop());
+    assert.equal(rec.action, 'deny');
+    assert.equal(rec.tail, true);
+  } finally {
+    cleanupFixture(fixture, cmd);
+  }
+});
+
+test('e2e: compound cmd + answer failure → STATIC deny still flags tail + records tail:true', () => {
+  const uniq = `StubTailBoom${Date.now()}`;
+  const fixture = e2eFixture(`process.exit(3);`);
+  const cmd = `grep -n "${uniq}" src/foo.rs && cargo test -q`;
+  try {
+    fsE2e.mkdirSync(pathE2e.join(fixture.dir, 'src'), { recursive: true });
+    fsE2e.writeFileSync(pathE2e.join(fixture.dir, 'src', 'foo.rs'), 'fn x() {}\n');
+    const res = runHook(cmd, fixture);
+    assert.equal(res.status, 0);
+    const out = JSON.parse(res.stdout);
+    assert.equal(out.hookSpecificOutput.permissionDecision, 'deny');
+    const reason = out.hookSpecificOutput.permissionDecisionReason;
+    assert.match(reason, /denied by code-graph hook/);  // static fallback path
+    assert.match(reason, /did NOT run/);
+    assert.match(reason, /cargo test -q/);
+    const rec = JSON.parse(fsE2e.readFileSync(
+      pathE2e.join(fixture.dir, '.code-graph', 'recommendations.jsonl'), 'utf8').trim());
+    assert.equal(rec.answered, false);
+    assert.equal(rec.tail, true);
+  } finally {
+    cleanupFixture(fixture, cmd);
+  }
+});
+
+test('e2e: simple (non-compound) denied grep → no tail field in the deny record', () => {
+  const uniq = `StubNoTail${Date.now()}`;
+  const fixture = e2eFixture(
+    `process.stdout.write('src/foo.rs:7  fn ' + process.argv[3] + '()\\n');`);
+  const cmd = `grep -rn "${uniq}" src/`;
+  try {
+    const res = runHook(cmd, fixture);
+    const out = JSON.parse(res.stdout);
+    assert.equal(out.hookSpecificOutput.permissionDecision, 'deny');
+    const rec = JSON.parse(fsE2e.readFileSync(
+      pathE2e.join(fixture.dir, '.code-graph', 'recommendations.jsonl'), 'utf8').trim());
+    assert.equal(rec.action, 'deny');
+    assert.equal('tail' in rec, false);
+  } finally {
+    cleanupFixture(fixture, cmd);
+  }
+});
+
 // ── v0.48 subdir-cwd dark fix: resolveProjectRoot / rebaseRelativePaths ──
 // daagu 2026-06-11: the persistent shell `cd backend/` darkened 38/40
 // head-greps for the rest of the night — gate 5 checked process.cwd() only.
@@ -1040,3 +1231,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/scripts/session-init.js

@@ -6,7 +6,7 @@ const fs = require('fs');
 const {
   install, update, readManifest, getPluginVersion, checkScopeConflict,
   cleanupDisabledStatusline, isPluginInactive, readJson, CACHE_DIR,
-  settingsPath,
+  settingsPath, isStaleRelicContext,
 } = require('./lifecycle');
 const { readBinaryVersion, isDevMode, getNewestMtime } = require('./version-utils');
 const { maybeAutoAdopt, isAdopted } = require('./adopt');
@@ -55,6 +55,15 @@ function launchBackgroundAutoUpdate(spawnFn = spawn, env = process.env) {
 }
 
 function syncLifecycleConfig() {
+  // v0.49.1: stale-relic guard. A still-running Claude Code process fires
+  // SessionStart from the plugin-cache dir it loaded at startup; after
+  // auto-update installs a newer version, those old scripts would see
+  // `manifest.version !== currentVersion` below and — direction-blind —
+  // call update(), dragging manifest + every settings.json hook path back
+  // to the old dir (upgrade↔downgrade ping-pong, observed live 2026-06-12).
+  // installed_plugins.json is the authority on which install may self-heal.
+  if (isStaleRelicContext()) return 'deferred-to-active-install';
+
   const manifest = readManifest();
   const currentVersion = getPluginVersion();
 
@@ -81,6 +90,14 @@ function syncLifecycleConfig() {
     install();
     return 'self-healed-bad-path';
   }
+  // v0.49.1: also self-heal when the composite path exists but is not the one
+  // we'd write now (old plugin-cache version dir that still exists on disk —
+  // invisible to the existence check above; same fault class as the binary pin).
+  const { compositeCommand } = require('./lifecycle');
+  if (settings.statusLine.command !== compositeCommand()) {
+    install();
+    return 'self-healed-stale-statusline';
+  }
   // Self-heal if any hook command points to a non-existent script (path pollution)
   if (settings.hooks) {
     for (const entries of Object.values(settings.hooks)) {
@@ -101,18 +118,20 @@ function syncLifecycleConfig() {
   // (e.g. user manually edited settings.json, or settings.json got rewritten
   // by another tool that didn't preserve our entries). Without this, the
   // user silently loses PreToolUse/PostToolUse hooks until next plugin update.
-  const { isOurHookEntry, buildSettingsHookEntries } = require('./lifecycle');
-  const desired = buildSettingsHookEntries();
-  for (const [event, desiredEntries] of Object.entries(desired)) {
-    const presentMatchers = new Set(
-      (settings.hooks?.[event] || []).filter(isOurHookEntry).map(e => e.matcher || '*')
-    );
-    for (const e of desiredEntries) {
-      if (!presentMatchers.has(e.matcher || '*')) {
-        install();
-        return 'self-healed-missing-settings-hook';
-      }
-    }
+  // v0.49.1: upgraded from matcher-presence to surveyHookCoverage so a
+  // present-but-stale command path (old plugin-cache version dir that still
+  // exists) also heals. Previously only doctor checked staleness, so if the
+  // auto-update re-register step failed silently, users kept running old hook
+  // code indefinitely — the settings.json sibling of the binary-pin bug.
+  const { surveyHookCoverage } = require('./lifecycle');
+  const cov = surveyHookCoverage(settings);
+  if (cov.missing.length > 0) {
+    install();
+    return 'self-healed-missing-settings-hook';
+  }
+  if (cov.stale.length > 0) {
+    install();
+    return 'self-healed-stale-settings-hook';
   }
   return 'noop';
 }
@@ -298,6 +317,11 @@ function runSessionInit() {
   }
 
   const lifecycle = syncLifecycleConfig();
+  // v0.49.1: a stale relic (see isStaleRelicContext) must not write ANY
+  // versioned state — that includes the adoption template: maybeAutoAdopt's
+  // drift-refresh would "refresh" MEMORY.md back to the relic's OLD shipped
+  // template, the adoption-surface twin of the settings.json downgrade war.
+  const isRelic = lifecycle === 'deferred-to-active-install';
 
   // Verify binary availability — catch issues early with actionable diagnostics
   const binaryCheck = verifyBinary();
@@ -308,7 +332,7 @@ function runSessionInit() {
   // v0.9.0 C' 上下文感知默认：插件模式下首次 SessionStart 自动 adopt。
   // v0.11.0: 已 adopt 的项目如果 shipped template 漂移也会触发一次刷新。
   // 两种情况都发一次 stderr 提示，让用户知道发生了什么 + 如何回退。
-  const autoAdopt = maybeAutoAdopt({ scriptPath: __dirname });
+  const autoAdopt = isRelic ? { attempted: false, result: null } : maybeAutoAdopt({ scriptPath: __dirname });
   if (autoAdopt.attempted && autoAdopt.result && autoAdopt.result.ok) {
     if (autoAdopt.reason === 'refreshed') {
       process.stderr.write(

package/claude-plugin/templates/plugin_code_graph_mcp.md

@@ -38,6 +38,14 @@ 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`。
+> `grep` 是 drop-in 替代：`-F` 字面 / `-i` / `-w` / `-l` / `-A/-B/-C N` 上下文 /
+> 多路径 / `--max-count 0`，退出码兼容 grep（0/1/2），召回达 git-grep 级
+> （tracked-but-gitignored 也能搜到），每条命中标注所属 fn/class。
+>
 > v0.10.0 起：tools/list 默认只暴露 7 个核心工具；下表"进阶 5"中的工具
 > 已从 tools/list 隐藏以节省 session 启动 tokens。**Claude Code 里请走 CLI
 > 子命令**（MCP schema 不在 list，Claude Code 的 ToolSearch 不会加载，直接