@sdsrs/code-graph 0.31.0 → 0.32.3

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

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 'use strict';
 // PreToolUse(Bash) hook: detect raw `grep`/`rg`/`ag` on the indexed source tree
-// and suggest code-graph CLI alternatives. Closes the "Bash comfort zone" leak —
-// pre-training bias has Claude reach for `grep -rn` ~13× more than the indexed
-// CLI on bash-heavy days (15-day baseline: 429 raw grep vs 191 functional CLI).
+// and either BLOCK with suggestion (v0.32+) or HINT (legacy path). Closes the
+// "Bash comfort zone" leak — pre-training bias has Claude reach for `grep -rn`
+// ~13× more than the indexed CLI on bash-heavy days (15-day baseline: 429 raw
+// grep vs 191 functional CLI). v0.25.0 hint-only had ~0% transfer rate; v0.32.0
+// upgrades the narrowest "I'm searching for a symbol" subset to block-with-reason.
 //
-// Fires when ALL conditions met:
+// HINT fires when ALL conditions met (shouldHint):
 //   1. Command HEAD is grep/rg/ag (NOT piped — pipe-greps are output filters)
 //   2. Args include an indexed source-tree path (src/ tests/ lib/ scripts/ ...)
 //   3. Not searching only a config/lockfile (Cargo.toml/.gitignore/*.md/*.json)
@@ -13,13 +15,20 @@
 //   5. .code-graph/index.db exists in CWD
 //   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)
+//  10. CODE_GRAPH_NO_BLOCK_GREP != "1" (block escape, independent of QUIET_HOOKS)
+//
 // Exits silently otherwise — zero noise for build greps, log filters, config
 // lookups, or the rare legitimate use of raw grep on indexed source.
 
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
 const crypto = require('crypto');
+const { cgTmpDir } = require('./tmp-dir');
 
 // --- Pure logic (testable) ---
 
@@ -56,20 +65,68 @@ 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.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
+// anywhere — they're distinctive enough on their own.
+const IDENTIFIER_LIKE =
+  /[A-Z][a-zA-Z0-9]{3,}|[a-z][a-z0-9]*_[a-z0-9_]+|^\s*(?:fn|def|class|function|struct|impl|trait)\s+\w/;
+const MARKER_ONLY =
+  /^[^"']*["']\s*(?:TODO|FIXME|XXX|HACK|WARN|WARNING|ERROR|NOTE)\s*["']/i;
+
+// v0.32.1: pull the pattern argument(s) out of the command before running
+// IDENTIFIER_LIKE — testing the full cmd false-positives on CamelCase /
+// snake_case in PATH ARGUMENTS like `src/EmbeddingModel.rs` or
+// `src/some_module/`. The pattern arg is what the user is actually searching
+// for, and that's the only thing we should evaluate against "is this a
+// symbol-shaped target".
+function extractPatterns(cmd) {
+  if (!cmd || typeof cmd !== 'string') return [];
+  // Strip leading verb + env prefix
+  const stripped = cmd.replace(/^\s*(?:env\s+\S+=\S+\s+)*(?:grep|rg|ag)\s+/, '');
+  // Collect every quoted argument — first one is the pattern in standard grep
+  // usage; subsequent ones (e.g. `-e "second"`) are also patterns or filter
+  // expressions and worth screening too.
+  const matches = [...stripped.matchAll(/"([^"]+)"|'([^']+)'/g)];
+  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
+  const patterns = extractPatterns(cmd);
+  if (patterns.length === 0) return false;        // unquoted pattern — conservative, hint
+  return patterns.some(p => IDENTIFIER_LIKE.test(p));
+}
+
 function commandHash(cmd) {
   return crypto.createHash('sha1').update(cmd).digest('hex').slice(0, 12);
 }
 
+function flagPath(cmd) {
+  return path.join(cgTmpDir(), `.code-graph-bash-${commandHash(cmd)}`);
+}
+
 function isOnCooldown(cmd, now = Date.now(), windowMs = 60000) {
-  const flag = path.join(os.tmpdir(), `.code-graph-bash-${commandHash(cmd)}`);
   try {
-    return now - fs.statSync(flag).mtimeMs < windowMs;
+    return now - fs.statSync(flagPath(cmd)).mtimeMs < windowMs;
   } catch { return false; }
 }
 
 function markCooldown(cmd) {
-  const flag = path.join(os.tmpdir(), `.code-graph-bash-${commandHash(cmd)}`);
-  try { fs.writeFileSync(flag, ''); } catch { /* ok */ }
+  try { fs.writeFileSync(flagPath(cmd), ''); } catch { /* ok */ }
 }
 
 function buildHint() {
@@ -84,6 +141,19 @@ function buildHint() {
   ].join('\n');
 }
 
+function buildBlockReason() {
+  // Shown to Claude via PreToolUse `decision: block` reason. Must give a
+  // concrete alternate command Claude can re-issue without further thinking.
+  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',
+    'For raw-text scans (log/comment/marker), re-run with `CODE_GRAPH_NO_BLOCK_GREP=1` prepended.',
+  ].join('\n');
+}
+
 // --- Main execution (only when run directly) ---
 
 // Kill switch: matches user-prompt-context.js convention. =1 forces silence
@@ -94,6 +164,13 @@ function isSilenced(env = process.env) {
   return env.CODE_GRAPH_QUIET_HOOKS === '1';
 }
 
+// v0.32.0 — independent of QUIET_HOOKS. =1 downgrades block tier to hint
+// (legacy v0.25.0–v0.31 behavior). Useful when raw-text scan is intentional
+// but the user still wants the hint for future commands.
+function isBlockDisabled(env = process.env) {
+  return env.CODE_GRAPH_NO_BLOCK_GREP === '1';
+}
+
 function runMain() {
   if (isSilenced()) return;
   const cwd = process.cwd();
@@ -110,6 +187,23 @@ function runMain() {
   if (isOnCooldown(cmd)) return;
 
   markCooldown(cmd);
+
+  if (!isBlockDisabled() && shouldBlock(cmd)) {
+    // PreToolUse block via current CC schema (`hookSpecificOutput.permissionDecision`).
+    // Verified empirically 2026-05-24: legacy `{decision:"block",reason}` was
+    // 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").
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: buildBlockReason(),
+      },
+    }) + '\n');
+    return;
+  }
+
   process.stdout.write(buildHint() + '\n');
 }
 
@@ -119,9 +213,13 @@ if (require.main === module) {
 
 module.exports = {
   shouldHint,
+  shouldBlock,
+  extractPatterns,    // v0.32.1 — exposed for tests
   buildHint,
+  buildBlockReason,
   commandHash,
   isOnCooldown,
   markCooldown,
   isSilenced,
+  isBlockDisabled,
 };

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

@@ -1,7 +1,16 @@
 'use strict';
 const test = require('node:test');
 const assert = require('node:assert/strict');
-const { shouldHint, buildHint, commandHash, isSilenced } = require('./pre-grep-guide');
+const {
+  shouldHint,
+  shouldBlock,
+  extractPatterns,
+  buildHint,
+  buildBlockReason,
+  commandHash,
+  isSilenced,
+  isBlockDisabled,
+} = require('./pre-grep-guide');
 
 // ── Should fire: bare grep/rg/ag on indexed source tree ─────────────
 
@@ -262,3 +271,256 @@ test('regression: cargo test pipe filter NOT fires (sess 45691293)', () => {
 test('regression: grep -m1 "^version" Cargo.toml NOT fires', () => {
   assert.equal(shouldHint('grep -m1 "^version" Cargo.toml'), false);
 });
+
+// ════════════════════════════════════════════════════════════════════
+// v0.32.0 — Block tier (shouldBlock, buildBlockReason, isBlockDisabled)
+// ════════════════════════════════════════════════════════════════════
+
+// ── shouldBlock: SHOULD block — identifier-shaped symbol scan ───────
+
+test('shouldBlock: CamelCase identifier on src/', () => {
+  assert.equal(shouldBlock('grep -rn "EmbeddingModel" src/'), true);
+});
+
+test('shouldBlock: snake_case identifier on src/', () => {
+  assert.equal(shouldBlock('grep -rn "fts5_search" src/storage/'), true);
+});
+
+test('shouldBlock: fn declaration anchor on src/', () => {
+  assert.equal(shouldBlock('grep -rn "fn fts5_search" src/storage/'), true);
+});
+
+test('shouldBlock: alternation with identifiers on src/', () => {
+  assert.equal(shouldBlock('grep -rn "fn fts5_search\\|MATCH" src/storage/'), true);
+});
+
+test('shouldBlock: class declaration on src/', () => {
+  assert.equal(shouldBlock('grep -rn "class UserService" src/'), true);
+});
+
+test('shouldBlock: def declaration on backend/app/', () => {
+  assert.equal(shouldBlock('grep -rn "def fetch_user" backend/app/services/'), true);
+});
+
+test('shouldBlock: rg with CamelCase on lib/', () => {
+  assert.equal(shouldBlock('rg "AuthHandler" lib/'), true);
+});
+
+// ── 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: --include=*.rs → user already filtering, hint only', () => {
+  assert.equal(shouldBlock('grep -rn --include="*.rs" "EmbeddingModel" src/'), false);
+});
+
+test('shouldBlock: --exclude-dir=tests → hint only', () => {
+  assert.equal(shouldBlock('grep -rn --exclude=tests "EmbeddingModel" src/'), false);
+});
+
+test('shouldBlock: -A 3 context flag → hint only', () => {
+  assert.equal(shouldBlock('grep -rn -A 3 "EmbeddingModel" src/'), false);
+});
+
+test('shouldBlock: -B 2 context flag → hint only', () => {
+  assert.equal(shouldBlock('grep -rn -B 2 "EmbeddingModel" src/'), false);
+});
+
+test('shouldBlock: -C 5 context flag → hint only', () => {
+  assert.equal(shouldBlock('grep -rn -C 5 "EmbeddingModel" src/'), false);
+});
+
+// ── shouldBlock: should NOT block — marker-only patterns ────────────
+
+test('shouldBlock: bare TODO marker → hint only (no cg equivalent)', () => {
+  assert.equal(shouldBlock('grep -rn "TODO" src/'), false);
+});
+
+test('shouldBlock: bare FIXME marker → hint only', () => {
+  assert.equal(shouldBlock('grep -rn "FIXME" src/'), false);
+});
+
+test('shouldBlock: bare XXX marker → hint only', () => {
+  assert.equal(shouldBlock('grep -rn "XXX" src/'), false);
+});
+
+test('shouldBlock: bare HACK marker → hint only', () => {
+  assert.equal(shouldBlock('grep -rn "HACK" src/'), false);
+});
+
+// ── shouldBlock: should NOT block — non-identifier text ─────────────
+
+test('shouldBlock: short lowercase word "foo" → hint only', () => {
+  // No CamelCase, no _, no declaration anchor → not symbol-shaped
+  assert.equal(shouldBlock('grep -rn "foo" src/'), false);
+});
+
+test('shouldBlock: short alphanumeric "v1" → hint only', () => {
+  assert.equal(shouldBlock('grep -rn "v1" src/'), false);
+});
+
+// ── shouldBlock: should NOT block — inherits shouldHint=false ──────
+
+test('shouldBlock: pipe-grep → false (already shouldHint=false)', () => {
+  assert.equal(shouldBlock('cargo test 2>&1 | grep "EmbeddingModel"'), false);
+});
+
+test('shouldBlock: code-graph-mcp already used → false', () => {
+  assert.equal(shouldBlock('code-graph-mcp grep "EmbeddingModel" src/'), false);
+});
+
+test('shouldBlock: empty / non-string → false', () => {
+  assert.equal(shouldBlock(''), false);
+  assert.equal(shouldBlock(null), false);
+});
+
+test('shouldBlock: grep on Cargo.toml only → false', () => {
+  assert.equal(shouldBlock('grep "EmbeddingModel" Cargo.toml'), false);
+});
+
+// ── buildBlockReason content ────────────────────────────────────────
+
+test('buildBlockReason: includes "denied"', () => {
+  assert.match(buildBlockReason(), /denied/i);
+});
+
+test('buildBlockReason: lists cg grep + ast-search + callgraph', () => {
+  const out = buildBlockReason();
+  assert.match(out, /code-graph-mcp grep/);
+  assert.match(out, /code-graph-mcp ast-search/);
+  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: under 700-byte budget (single CC message)', () => {
+  const out = buildBlockReason();
+  assert.ok(out.length < 700, `reason length ${out.length} exceeds budget`);
+});
+
+// ── isBlockDisabled escape hatch ────────────────────────────────────
+
+test('isBlockDisabled: default (no env) → false (block enabled)', () => {
+  assert.equal(isBlockDisabled({}), false);
+});
+
+test('isBlockDisabled: CODE_GRAPH_NO_BLOCK_GREP=1 → true', () => {
+  assert.equal(isBlockDisabled({ CODE_GRAPH_NO_BLOCK_GREP: '1' }), true);
+});
+
+test('isBlockDisabled: CODE_GRAPH_NO_BLOCK_GREP=0 → false', () => {
+  assert.equal(isBlockDisabled({ CODE_GRAPH_NO_BLOCK_GREP: '0' }), false);
+});
+
+test('isBlockDisabled: independent of CODE_GRAPH_QUIET_HOOKS', () => {
+  // QUIET_HOOKS=1 silences entirely (no block, no hint).
+  // NO_BLOCK_GREP=1 downgrades block to hint only.
+  // The two flags must be orthogonal — neither implies the other.
+  assert.equal(isBlockDisabled({ CODE_GRAPH_QUIET_HOOKS: '1' }), false);
+  assert.equal(isSilenced({ CODE_GRAPH_NO_BLOCK_GREP: '1' }), false);
+});
+
+// ════════════════════════════════════════════════════════════════════
+// v0.32.1 — extractPatterns + I1/I4 false-positive regressions
+// ════════════════════════════════════════════════════════════════════
+
+// ── extractPatterns: pulls quoted args from grep/rg/ag commands ──────
+
+test('extractPatterns: single double-quoted pattern', () => {
+  assert.deepEqual(extractPatterns('grep -rn "EmbeddingModel" src/'), ['EmbeddingModel']);
+});
+
+test('extractPatterns: single-quoted pattern', () => {
+  assert.deepEqual(extractPatterns("grep -rn 'fts5_search' src/"), ['fts5_search']);
+});
+
+test('extractPatterns: env-prefixed verb', () => {
+  assert.deepEqual(extractPatterns('env LANG=C grep -rn "Foo" src/'), ['Foo']);
+});
+
+test('extractPatterns: multiple -e patterns', () => {
+  // Multi-pattern grep: both quoted args should be returned.
+  const got = extractPatterns('grep -rn -e "first" -e "second" src/');
+  assert.deepEqual(got, ['first', 'second']);
+});
+
+test('extractPatterns: pattern with alternation', () => {
+  assert.deepEqual(
+    extractPatterns('grep -rn "fn fts5_search\\|MATCH" src/storage/'),
+    ['fn fts5_search\\|MATCH']
+  );
+});
+
+test('extractPatterns: no quotes at all → empty array', () => {
+  // Unquoted pattern (`grep foo src/`) — we deliberately don't try to parse
+  // shell tokenization; shouldBlock falls back to hint in this case.
+  assert.deepEqual(extractPatterns('grep -rn foo src/'), []);
+});
+
+test('extractPatterns: empty / non-string → empty array', () => {
+  assert.deepEqual(extractPatterns(''), []);
+  assert.deepEqual(extractPatterns(null), []);
+  assert.deepEqual(extractPatterns(undefined), []);
+});
+
+test('extractPatterns: rg / ag head also stripped', () => {
+  assert.deepEqual(extractPatterns('rg "Foo" lib/'), ['Foo']);
+  assert.deepEqual(extractPatterns('ag "Bar" src/'), ['Bar']);
+});
+
+// ── I1 regression: identifier-shaped PATHS no longer trigger block ──
+
+test('I1: grep -rn "abc" src/EmbeddingModel.rs → HINT (path has CamelCase, pattern doesn\'t)', () => {
+  // CamelCase is in the FILENAME, not the pattern. v0.32.0 false-blocked
+  // this. Pattern "abc" has no identifier shape → must downgrade to hint.
+  assert.equal(shouldBlock('grep -rn "abc" src/EmbeddingModel.rs'), false);
+});
+
+test('I1: grep -rn "x" src/some_module/file.rs → HINT (path has snake_case)', () => {
+  assert.equal(shouldBlock('grep -rn "x" src/some_module/file.rs'), false);
+});
+
+test('I1: grep -rn "the quick brown fox" src/EmbeddingModel.rs → HINT (English prose pattern)', () => {
+  assert.equal(shouldBlock('grep -rn "the quick brown fox" src/EmbeddingModel.rs'), false);
+});
+
+test('I1: unquoted pattern grep -rn foo src/ → HINT (conservative fallback)', () => {
+  // Without quotes we can't safely identify the pattern arg via shell rules
+  // alone. Conservative: hint only.
+  assert.equal(shouldBlock('grep -rn foo src/'), false);
+});
+
+test('I1: identifier pattern still blocks even with non-identifier path', () => {
+  // Sanity check the inverse — block tier shouldn't get over-relaxed.
+  // Path is plain `src/` but pattern is CamelCase → still block.
+  assert.equal(shouldBlock('grep -rn "EmbeddingModel" src/'), true);
+});
+
+// ── I4 regression: declaration-anchor + `type` keyword fixes ─────────
+
+test('I4: grep -rn "# type checking" src/ → HINT (comment scan, "type" not a decl keyword anymore)', () => {
+  assert.equal(shouldBlock('grep -rn "# type checking" src/'), false);
+});
+
+test('I4: grep -rn "some type X" src/ → HINT (type not at pattern start, no longer over-matches)', () => {
+  assert.equal(shouldBlock('grep -rn "some type X" src/'), false);
+});
+
+test('I4: grep -rn "the def keyword" src/ → HINT (def not at pattern start)', () => {
+  // "the def keyword" had `\bdef\s+\w` match `def k` previously.
+  // ^\s*(?:fn|def|...) anchor stops this.
+  assert.equal(shouldBlock('grep -rn "the def keyword" src/'), false);
+});
+
+test('I4: grep -rn "def calc_total" src/ → BLOCK (def at start + snake_case)', () => {
+  // Real declaration search — still blocks correctly.
+  assert.equal(shouldBlock('grep -rn "def calc_total" src/'), true);
+});
+
+test('I4: grep -rn "fn render" src/ → BLOCK (decl anchor at start)', () => {
+  assert.equal(shouldBlock('grep -rn "fn render" src/'), true);
+});

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

@@ -24,8 +24,8 @@
 
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
 const crypto = require('crypto');
+const { cgTmpDir } = require('./tmp-dir');
 
 // --- Configuration ---
 
@@ -66,7 +66,7 @@ function cwdHash(cwd) {
 }
 
 function statePath(cwd) {
-  return path.join(os.tmpdir(), `.code-graph-readfan-${cwdHash(cwd)}.json`);
+  return path.join(cgTmpDir(), `.code-graph-readfan-${cwdHash(cwd)}.json`);
 }
 
 function loadState(cwd, now = Date.now()) {

package/claude-plugin/scripts/session-init.js

@@ -86,6 +86,23 @@ function syncLifecycleConfig() {
       }
     }
   }
+  // v0.32.0: self-heal if our settings.json hook coverage is incomplete
+  // (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';
+      }
+    }
+  }
   return 'noop';
 }
 

package/claude-plugin/scripts/tmp-dir.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+'use strict';
+// Shared temp-dir helper for hook + auto-update scripts.
+//
+// Why this exists: Claude Code overrides $TMPDIR to ~/.claude/tmp/ so it can
+// capture process stdout for transcript replay. That makes `os.tmpdir()`
+// resolve to the same directory that holds 9000+ transcript subdirs. Putting
+// hook cooldown flags directly there has two failure modes:
+//
+//   1. Diagnostic blindness — every doc / memory / debug query that checks
+//      `/tmp/.code-graph-bash-*` for hook firing returns empty even when the
+//      hook is working perfectly. v0.32.0's "PreToolUse dark under green
+//      health" investigation chased this red herring for ~2 hours before the
+//      $TMPDIR override was identified.
+//   2. §8 SAFETY recursive-traversal trap — `~/.claude/tmp/<id>.output` is
+//      where CC writes captured process output; scattering 0-byte flag files
+//      alongside them amplifies the "grep -r ~/.claude/tmp/" footgun.
+//
+// Fix: pin all hook + auto-update artifacts to a `code-graph-mcp/` subdir of
+// whatever `os.tmpdir()` resolves to. Contained, deterministic, easy to GC.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const CG_TMP_DIR = path.join(os.tmpdir(), 'code-graph-mcp');
+
+function cgTmpDir() {
+  try { fs.mkdirSync(CG_TMP_DIR, { recursive: true }); } catch { /* ok */ }
+  return CG_TMP_DIR;
+}
+
+module.exports = { cgTmpDir, CG_TMP_DIR };

package/claude-plugin/scripts/tmp-dir.test.js

@@ -0,0 +1,50 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { cgTmpDir, CG_TMP_DIR } = require('./tmp-dir');
+
+test('CG_TMP_DIR is a "code-graph-mcp" subdir of os.tmpdir()', () => {
+  assert.strictEqual(path.basename(CG_TMP_DIR), 'code-graph-mcp');
+  assert.strictEqual(path.dirname(CG_TMP_DIR), os.tmpdir());
+});
+
+test('cgTmpDir() returns the same path and creates the directory', () => {
+  // Pre-condition: nuke it if it exists from a prior run, to prove cgTmpDir()
+  // actually creates it on demand (not just reports a pre-existing path).
+  try { fs.rmSync(CG_TMP_DIR, { recursive: true, force: true }); } catch { /* ok */ }
+  assert.ok(!fs.existsSync(CG_TMP_DIR), 'pre-condition: dir must be absent');
+
+  const p = cgTmpDir();
+  assert.strictEqual(p, CG_TMP_DIR);
+  assert.ok(fs.existsSync(p), 'cgTmpDir() must create the directory');
+  assert.ok(fs.statSync(p).isDirectory(), 'created entry must be a directory');
+});
+
+test('cgTmpDir() is idempotent — second call does not throw on existing dir', () => {
+  cgTmpDir();
+  // Should not throw even though dir now exists.
+  assert.doesNotThrow(() => cgTmpDir());
+});
+
+test('cgTmpDir() does not leak files into os.tmpdir() root', () => {
+  // Regression guard: the v0.32.x bug was hook artifacts landing directly
+  // in os.tmpdir() (= ~/.claude/tmp/ under Claude Code's $TMPDIR override),
+  // colliding with transcript subdirs. After the fix, no `.code-graph-bash-*`
+  // / `.cg-impact-*` / `.code-graph-readfan-*` filename should ever appear
+  // outside CG_TMP_DIR — only inside it.
+  const dir = cgTmpDir();
+  const flag = path.join(dir, '.code-graph-bash-test');
+  fs.writeFileSync(flag, '');
+  try {
+    // The sibling of CG_TMP_DIR (= os.tmpdir()) must NOT now contain the flag.
+    const parent = path.dirname(dir);
+    const stray = path.join(parent, '.code-graph-bash-test');
+    assert.ok(!fs.existsSync(stray), 'flag must not exist in os.tmpdir() root');
+  } finally {
+    try { fs.unlinkSync(flag); } catch { /* ok */ }
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.31.0",
+  "version": "0.32.3",
   "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.31.0",
-    "@sdsrs/code-graph-linux-arm64": "0.31.0",
-    "@sdsrs/code-graph-darwin-x64": "0.31.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.31.0",
-    "@sdsrs/code-graph-win32-x64": "0.31.0"
+    "@sdsrs/code-graph-linux-x64": "0.32.3",
+    "@sdsrs/code-graph-linux-arm64": "0.32.3",
+    "@sdsrs/code-graph-darwin-x64": "0.32.3",
+    "@sdsrs/code-graph-darwin-arm64": "0.32.3",
+    "@sdsrs/code-graph-win32-x64": "0.32.3"
   }
 }