@sdsrs/code-graph 0.16.8 → 0.17.0

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

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

package/claude-plugin/scripts/adopt.js

@@ -11,6 +11,18 @@ const os = require('os');
 
 const SENTINEL_BEGIN = '<!-- code-graph-mcp:begin v1 -->';
 const SENTINEL_END = '<!-- code-graph-mcp:end -->';
+// Collision-detection marker. Slug encoding `[^a-zA-Z0-9-]→'-'` is lossy,
+// so two cwds (e.g. /foo/bar and /foo bar) can resolve to the same memory
+// dir. Adopt records its absolute cwd as the file's first-line HTML comment;
+// re-adopt from a different cwd surfaces a warning.
+const ADOPTED_BY_RE = /^<!-- adopted-by: (.+?) -->\r?\n?/;
+function readAdoptedBy(filePath) {
+  try {
+    const first = fs.readFileSync(filePath, 'utf8').split('\n', 1)[0];
+    const m = first.match(/^<!-- adopted-by: (.+?) -->/);
+    return m ? m[1] : null;
+  } catch { return null; }
+}
 const INDEX_LINE = [
   '- [code-graph-mcp](plugin_code_graph_mcp.md) — v0.10.0 起 tools/list 默认 7 核心 + 5 隐藏可调（省启动 token）',
   '  - 核心 7（默认暴露）：`get_call_graph`/`module_overview`/`semantic_code_search`/`ast_search`/`find_references`/`get_ast_node`/`project_map`',
@@ -68,20 +80,49 @@ function platformGuard() {
   return null;
 }
 
+// Project-marker check: cwd looks like a real project (not /tmp / $HOME).
+// Used to gate auto-mkdir of the auto-memory dir so adopt doesn't pollute
+// random directories. Mirrors the markers Claude Code itself recognizes.
+const PROJECT_MARKERS = [
+  '.git', '.code-graph', 'package.json', 'Cargo.toml',
+  'pyproject.toml', 'go.mod', 'pom.xml', 'build.gradle',
+];
+function isProjectRoot(cwd) {
+  return PROJECT_MARKERS.some(m => fs.existsSync(path.join(cwd, m)));
+}
+
 function adopt({ cwd, home, templatePath } = {}) {
   const blocked = platformGuard();
   if (blocked) return blocked;
 
+  const effectiveCwd = cwd || process.cwd();
   const dir = memoryDir(cwd, home);
   if (!fs.existsSync(dir)) {
-    return { ok: false, reason: 'no-memory-dir', dir };
+    // Auto-create only when cwd has a project marker. Without markers the
+    // user is likely in /tmp or $HOME, where adopt would litter
+    // ~/.claude/projects/ with bogus slugs.
+    if (!isProjectRoot(effectiveCwd)) {
+      return { ok: false, reason: 'not-a-project', dir, cwd: effectiveCwd };
+    }
+    fs.mkdirSync(dir, { recursive: true });
   }
   const target = path.join(dir, TARGET_NAME);
   const tpl = templatePath || TEMPLATE_PATH;
   if (!fs.existsSync(tpl)) {
     return { ok: false, reason: 'no-template', template: tpl };
   }
-  fs.copyFileSync(tpl, target);
+  // Slug-collision detection: read prior adopted-by marker before overwrite.
+  let collisionWith = null;
+  if (fs.existsSync(target)) {
+    const prevCwd = readAdoptedBy(target);
+    if (prevCwd && prevCwd !== effectiveCwd) collisionWith = prevCwd;
+  }
+  // Write marker + template. Marker is HTML comment → invisible in rendered
+  // markdown but preserved by needsRefresh's bytewise compare (skipped via
+  // ADOPTED_BY_RE strip below).
+  const tplBody = fs.readFileSync(tpl);
+  const marker = Buffer.from(`<!-- adopted-by: ${effectiveCwd} -->\n`);
+  fs.writeFileSync(target, Buffer.concat([marker, tplBody]));
 
   const indexPath = path.join(dir, 'MEMORY.md');
   const index = fs.existsSync(indexPath) ? fs.readFileSync(indexPath, 'utf8') : '# Memory Index\n';
@@ -89,14 +130,14 @@ function adopt({ cwd, home, templatePath } = {}) {
 
   // Already-adopted-and-well-formed: skip the write entirely.
   if (index.includes(desiredBlock)) {
-    return { ok: true, target, indexPath, indexed: false, healed: false };
+    return { ok: true, target, indexPath, indexed: false, healed: false, collisionWith };
   }
 
   const cleaned = stripSentinelBlock(index);
   const healed = cleaned !== index;
   const base = cleaned.endsWith('\n') ? cleaned : cleaned + '\n';
   fs.writeFileSync(indexPath, base + desiredBlock + '\n');
-  return { ok: true, target, indexPath, indexed: true, healed };
+  return { ok: true, target, indexPath, indexed: true, healed, collisionWith };
 }
 
 // v0.9.0 — "已 adopt" 判定：template 文件在 + MEMORY.md 内有我们的 sentinel 块。
@@ -124,7 +165,15 @@ function needsRefresh({ cwd, home, templatePath } = {}) {
   }
   const shipped = fs.readFileSync(tpl);
   const current = fs.readFileSync(target);
-  if (!shipped.equals(current)) return true;
+  // Strip the leading "<!-- adopted-by: ... -->\n" collision marker (D fix)
+  // before bytewise comparing — its presence/path naturally diverges from
+  // the shipped template.
+  let body = current;
+  const nl = current.indexOf(0x0a);
+  if (nl > 0 && ADOPTED_BY_RE.test(current.subarray(0, nl + 1).toString())) {
+    body = current.subarray(nl + 1);
+  }
+  if (!shipped.equals(body)) return true;
   const index = fs.readFileSync(indexPath, 'utf8');
   const desiredBlock = `${SENTINEL_BEGIN}\n${INDEX_LINE}\n${SENTINEL_END}`;
   return !index.includes(desiredBlock);
@@ -198,18 +247,31 @@ function formatResult(action, result) {
         return `[code-graph] Memory dir not found: ${result.dir}\n` +
                '  Run \`claude\` at least once in this project to create it.';
       }
+      if (result.reason === 'not-a-project') {
+        return `[code-graph] Not a project root: ${result.cwd}\n` +
+               '  No project marker (.git, Cargo.toml, package.json, pyproject.toml, ...).\n' +
+               '  cd into a real project before running adopt.';
+      }
       if (result.reason === 'no-template') {
         return `[code-graph] Template missing: ${result.template}`;
       }
       return `[code-graph] adopt failed: ${result.reason || 'unknown'}`;
     }
     const lines = [`[code-graph] Adopted → ${result.target}`];
+    if (result.collisionWith) {
+      lines.push(`[code-graph] ⚠ slug collision: this dir was previously adopted by ${result.collisionWith}.`);
+      lines.push('[code-graph]   Memory dir is shared — sentinels overwritten. ' +
+                 'Investigate path encoding clash (Claude Code slug = path with non-[a-zA-Z0-9-] → "-").');
+    }
     if (result.healed) lines.push(`[code-graph] Healed malformed sentinel block → ${result.indexPath}`);
     else if (result.indexed) lines.push(`[code-graph] Indexed → ${result.indexPath}`);
     else lines.push(`[code-graph] Index already up-to-date — no write`);
-    // v0.9.0: adoption auto-implies quietHooks; no env var needed for the common case.
-    lines.push('[code-graph] Active — quietHooks auto-enabled via adopted state.');
-    lines.push('[code-graph] Force inject:  CODE_GRAPH_QUIET_HOOKS=0   Force silent: =1');
+    // v0.17.0: SessionStart project_map injection is OFF by default (regardless
+    // of adoption). Adoption now only governs MEMORY.md sentinel + decision-table
+    // refresh; the noisy hook needs an explicit opt-in.
+    lines.push('[code-graph] Active. SessionStart project_map injection: OFF (default).');
+    lines.push('[code-graph] Opt in to map dump:  CODE_GRAPH_VERBOSE_HOOKS=1');
+    lines.push('[code-graph] Legacy override:     CODE_GRAPH_QUIET_HOOKS=0 (force noisy) / =1 (force quiet)');
     return lines.join('\n');
   }
   if (action === 'unadopt') {
@@ -231,6 +293,7 @@ if (require.main === module) {
 
 module.exports = {
   adopt, unadopt, memoryDir, formatResult, stripSentinelBlock,
-  isAdopted, isPluginModeInstall, maybeAutoAdopt, needsRefresh,
+  isAdopted, isPluginModeInstall, maybeAutoAdopt, needsRefresh, isProjectRoot,
   SENTINEL_BEGIN, SENTINEL_END, INDEX_LINE, TEMPLATE_PATH, TARGET_NAME,
+  PROJECT_MARKERS,
 };

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

@@ -6,8 +6,9 @@ const path = require('path');
 const os = require('os');
 const {
   adopt, unadopt, memoryDir, stripSentinelBlock,
-  isAdopted, isPluginModeInstall, maybeAutoAdopt, needsRefresh,
+  isAdopted, isPluginModeInstall, maybeAutoAdopt, needsRefresh, isProjectRoot,
   SENTINEL_BEGIN, SENTINEL_END, INDEX_LINE, TEMPLATE_PATH, TARGET_NAME,
+  PROJECT_MARKERS,
 } = require('./adopt');
 
 function makeSandbox() {
@@ -84,13 +85,17 @@ test('adopt preserves existing MEMORY.md content and appends', () => {
   } finally { sb.cleanup(); }
 });
 
-test('adopt fails gracefully when memory dir missing', () => {
+test('adopt fails gracefully when cwd is not a project root', () => {
+  // v0.16.9: behavior change — adopt now mkdir's the memory dir when cwd has
+  // a project marker (.git / Cargo.toml / package.json / ...). Bare mkdtemp
+  // without markers still fails with the more specific 'not-a-project' reason
+  // to prevent /tmp pollution.
   const home = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-adopt-home-'));
   const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-adopt-cwd-'));
   try {
     const res = adopt({ cwd, home });
     assert.strictEqual(res.ok, false);
-    assert.strictEqual(res.reason, 'no-memory-dir');
+    assert.strictEqual(res.reason, 'not-a-project');
   } finally {
     fs.rmSync(home, { recursive: true, force: true });
     fs.rmSync(cwd, { recursive: true, force: true });
@@ -329,7 +334,10 @@ test('maybeAutoAdopt runs adopt when plugin-mode + unadopted + no opt-out', () =
   } finally { sb.cleanup(); }
 });
 
-test('maybeAutoAdopt returns no-memory-dir when project memory missing', () => {
+test('maybeAutoAdopt fails with not-a-project when cwd has no project marker', () => {
+  // v0.16.9: bare mkdtemp cwd without .git/Cargo.toml/etc. surfaces
+  // 'not-a-project' so plugin-mode auto-adopt doesn't litter ~/.claude/projects/
+  // with bogus slugs from non-project working directories.
   const home = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-adopt-home-'));
   const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-adopt-cwd-'));
   try {
@@ -338,10 +346,9 @@ test('maybeAutoAdopt returns no-memory-dir when project memory missing', () => {
       scriptPath: '/home/u/.claude/plugins/cache/code-graph-mcp/scripts',
       env: {},
     });
-    // Plugin-mode + not adopted + no opt-out → attempt runs, but adopt() fails gracefully
     assert.strictEqual(res.attempted, true);
     assert.strictEqual(res.result.ok, false);
-    assert.strictEqual(res.result.reason, 'no-memory-dir');
+    assert.strictEqual(res.result.reason, 'not-a-project');
   } finally {
     fs.rmSync(home, { recursive: true, force: true });
     fs.rmSync(cwd, { recursive: true, force: true });
@@ -400,10 +407,14 @@ test('maybeAutoAdopt refreshes drifted target on re-run (reason=refreshed)', ()
     assert.strictEqual(res.attempted, true);
     assert.strictEqual(res.reason, 'refreshed');
     assert.strictEqual(res.result.ok, true);
-    // Target now matches shipped template
+    // Target now matches shipped template (after stripping the leading
+    // "<!-- adopted-by: ... -->\n" collision marker added by adopt v0.16.9).
     const shipped = fs.readFileSync(TEMPLATE_PATH);
     const current = fs.readFileSync(target);
-    assert.ok(shipped.equals(current), 'target re-synced to shipped template');
+    const nl = current.indexOf(0x0a);
+    const body = nl > 0 && /^<!-- adopted-by: /.test(current.subarray(0, nl).toString())
+      ? current.subarray(nl + 1) : current;
+    assert.ok(shipped.equals(body), 'target re-synced to shipped template');
     // Sentinel preserved in MEMORY.md
     assert.strictEqual(isAdopted({ cwd: sb.cwd, home: sb.home }), true);
   } finally { sb.cleanup(); }
@@ -482,3 +493,95 @@ test('Windows platform is rejected with clear reason', { skip: process.platform
     Object.defineProperty(process, 'platform', { value: orig, configurable: true });
   }
 });
+
+// ─── C fix: project-marker mkdir ─────────────────────────────────────────
+
+test('isProjectRoot detects each marker', () => {
+  for (const marker of PROJECT_MARKERS) {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-marker-'));
+    try {
+      assert.strictEqual(isProjectRoot(cwd), false, `bare cwd should not be a project`);
+      const markerPath = path.join(cwd, marker);
+      // Some markers are directories (.git, .code-graph), others are files.
+      if (marker.startsWith('.')) fs.mkdirSync(markerPath);
+      else fs.writeFileSync(markerPath, '');
+      assert.strictEqual(isProjectRoot(cwd), true, `${marker} should make cwd a project`);
+    } finally {
+      fs.rmSync(cwd, { recursive: true, force: true });
+    }
+  }
+});
+
+test('adopt auto-creates memory dir when cwd has a project marker', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-adopt-home-'));
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-adopt-cwd-'));
+  try {
+    // Add a project marker so adopt is allowed to create the memory dir.
+    fs.writeFileSync(path.join(cwd, 'package.json'), '{}');
+    // The memory dir does NOT exist yet — pre-fix behavior errored 'no-memory-dir'.
+    const dir = memoryDir(cwd, home);
+    assert.strictEqual(fs.existsSync(dir), false);
+
+    const res = adopt({ cwd, home });
+    assert.strictEqual(res.ok, true, `expected ok, got ${JSON.stringify(res)}`);
+    assert.strictEqual(fs.existsSync(dir), true, 'memory dir auto-created');
+    assert.strictEqual(fs.existsSync(path.join(dir, TARGET_NAME)), true, 'plugin file written');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+// ─── D fix: slug collision marker ────────────────────────────────────────
+
+test('adopt writes adopted-by marker as first line of plugin file', () => {
+  const sb = makeSandbox();
+  try {
+    adopt({ cwd: sb.cwd, home: sb.home });
+    const target = path.join(sb.dir, TARGET_NAME);
+    const firstLine = fs.readFileSync(target, 'utf8').split('\n', 1)[0];
+    assert.match(firstLine, /^<!-- adopted-by: .* -->$/, `expected adopted-by marker, got: ${firstLine}`);
+    assert.ok(firstLine.includes(sb.cwd), `marker should embed absolute cwd: ${firstLine}`);
+  } finally { sb.cleanup(); }
+});
+
+test('adopt detects slug collision when same memory dir is re-adopted from a different cwd', () => {
+  // Simulate two real cwds whose paths slugify to the same string. Here we
+  // skip real path encoding and just write a file pretending it came from a
+  // different cwd, then re-adopt — collision detection reads the prior marker.
+  const sb = makeSandbox();
+  try {
+    adopt({ cwd: sb.cwd, home: sb.home });
+    const target = path.join(sb.dir, TARGET_NAME);
+    // Tamper: rewrite the marker to look like a different cwd adopted first.
+    const body = fs.readFileSync(target, 'utf8').split('\n').slice(1).join('\n');
+    fs.writeFileSync(target, '<!-- adopted-by: /imaginary/other-project -->\n' + body);
+
+    const res = adopt({ cwd: sb.cwd, home: sb.home });
+    assert.strictEqual(res.ok, true);
+    assert.strictEqual(res.collisionWith, '/imaginary/other-project',
+      `expected collisionWith to surface prior cwd, got ${res.collisionWith}`);
+  } finally { sb.cleanup(); }
+});
+
+test('adopt collisionWith is null when re-adopting from same cwd (idempotent)', () => {
+  const sb = makeSandbox();
+  try {
+    adopt({ cwd: sb.cwd, home: sb.home });
+    const res = adopt({ cwd: sb.cwd, home: sb.home });
+    assert.strictEqual(res.ok, true);
+    assert.strictEqual(res.collisionWith, null);
+  } finally { sb.cleanup(); }
+});
+
+test('needsRefresh ignores the adopted-by marker when bytewise comparing', () => {
+  // Critical: the marker we add to target makes target ≠ template byte-for-byte.
+  // needsRefresh must skip the leading marker line before compare; otherwise
+  // every SessionStart would re-write the file and burn IO on a no-op.
+  const sb = makeSandbox();
+  try {
+    adopt({ cwd: sb.cwd, home: sb.home });
+    assert.strictEqual(needsRefresh({ cwd: sb.cwd, home: sb.home }), false,
+      'needsRefresh should be false right after adopt — marker must not trigger drift');
+  } finally { sb.cleanup(); }
+});

package/claude-plugin/scripts/find-binary.js

@@ -4,6 +4,7 @@ const { execFileSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
+const { readBinaryVersion } = require('./version-utils');
 
 const PLATFORM = os.platform();
 const ARCH = os.arch();
@@ -11,6 +12,24 @@ const CACHE_FILE = path.join(os.homedir(), '.cache', 'code-graph', 'binary-path'
 const BINARY_NAME = PLATFORM === 'win32' ? 'code-graph-mcp.exe' : 'code-graph-mcp';
 const PLATFORM_PKG = `@sdsrs/code-graph-${PLATFORM}-${ARCH}`;
 
+/** Read the npm pkg version from this script's package.json (claude-plugin/../package.json). */
+function getPackageVersion() {
+  try { return require('../../package.json').version; }
+  catch { return null; }
+}
+
+/** Compare semver-ish "M.m.p" strings; returns -1, 0, or 1. Non-numeric parts → 0. */
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map(s => parseInt(s, 10));
+  const pb = String(b).split('.').map(s => parseInt(s, 10));
+  for (let i = 0; i < 3; i++) {
+    const x = Number.isFinite(pa[i]) ? pa[i] : 0;
+    const y = Number.isFinite(pb[i]) ? pb[i] : 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
 /**
  * Candidate paths for npm global `node_modules`.
  *
@@ -157,8 +176,19 @@ function findBinaryUncached() {
   }
 
   // --- Auto-update cache (binary downloaded directly from GitHub release) ---
+  // Cache wins when its version >= the npm pkg version. After `npm update`
+  // refreshes the platform-pkg, an older auto-update cache binary must NOT
+  // shadow the freshly-installed one; this version check prevents the
+  // upgrade-race where users keep running stale binary until auto-update fires.
   const autoUpdateBin = path.join(os.homedir(), '.cache', 'code-graph', 'bin', BINARY_NAME);
-  if (isNativeBinary(autoUpdateBin)) return autoUpdateBin;
+  if (isNativeBinary(autoUpdateBin)) {
+    const cacheVer = readBinaryVersion(autoUpdateBin);
+    const pkgVer = getPackageVersion();
+    if (!pkgVer || !cacheVer || compareVersions(cacheVer, pkgVer) >= 0) {
+      return autoUpdateBin;
+    }
+    // Cache is older than npm pkg — fall through to platform-pkg.
+  }
 
   // --- Platform-specific npm package (@sdsrs/code-graph-{os}-{arch}) ---
   const platformBin = findPlatformBinary();
@@ -212,6 +242,7 @@ function clearCache() {
 module.exports = {
   findBinary, findBinaryUncached, clearCache,
   globalNodeModulesCandidates, findPlatformBinary,
+  getPackageVersion, compareVersions,
   CACHE_FILE, BINARY_NAME, PLATFORM_PKG,
 };
 

package/claude-plugin/scripts/find-binary.test.js

@@ -5,7 +5,8 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-const { globalNodeModulesCandidates, findPlatformBinary, BINARY_NAME } = require('./find-binary');
+const { globalNodeModulesCandidates, findPlatformBinary, BINARY_NAME,
+        compareVersions, getPackageVersion } = require('./find-binary');
 
 function mkDir(t, prefix) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
@@ -108,3 +109,39 @@ test('findPlatformBinary returns null when no platform pkg installed anywhere re
   }
   assert.equal(real, null);
 });
+
+// ─── compareVersions (B fix: cache version invalidation helper) ───────────
+
+test('compareVersions: equal', () => {
+  assert.equal(compareVersions('1.2.3', '1.2.3'), 0);
+});
+
+test('compareVersions: cache older than pkg', () => {
+  // After `npm update` to 0.16.8, an auto-update cache from 0.16.7 must NOT
+  // shadow the freshly-installed platform-pkg binary. Returns -1 here so
+  // findBinaryUncached falls through to platform-pkg.
+  assert.equal(compareVersions('0.16.7', '0.16.8'), -1);
+});
+
+test('compareVersions: cache newer than pkg', () => {
+  // Auto-update may legitimately be ahead of npm pkg (cache fetched 0.17.0
+  // before npm shipped it). Returns 1 → cache wins.
+  assert.equal(compareVersions('0.17.0', '0.16.8'), 1);
+});
+
+test('compareVersions: minor and patch boundaries', () => {
+  assert.equal(compareVersions('1.0.0', '0.999.999'), 1);
+  assert.equal(compareVersions('1.10.0', '1.9.99'), 1);  // numeric, not lexical
+  assert.equal(compareVersions('1.0.10', '1.0.9'), 1);
+});
+
+test('compareVersions: tolerates non-numeric / short input', () => {
+  // Non-numeric → treated as 0; shorter strings padded with 0.
+  assert.equal(compareVersions('1.2', '1.2.0'), 0);
+  assert.equal(compareVersions('foo', '0.0.0'), 0);
+});
+
+test('getPackageVersion reads root package.json', () => {
+  const v = getPackageVersion();
+  assert.match(v, /^\d+\.\d+\.\d+$/, `expected semver-ish, got: ${v}`);
+});

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

@@ -11,13 +11,22 @@ const {
 const { readBinaryVersion, isDevMode, getNewestMtime } = require('./version-utils');
 const { maybeAutoAdopt, isAdopted } = require('./adopt');
 
-// v0.9.0 — quietHooks 推导：显式 env override > adopted 状态。
-// CODE_GRAPH_QUIET_HOOKS='0' 强制 noisy；'1' 强制 quiet；未设 → 跟随 adopted。
-function computeQuietHooks({ adopted, env = {} } = {}) {
+// v0.17.0 — quietHooks: unconditional quiet 默认。
+// 项目地图与 MEMORY.md plugin contract + on-demand `project_map` 工具高度重叠，
+// 默认每次 SessionStart 都注入 ≈2.3 KB 是不必要的常驻上下文成本。
+// 优先级（高到低）：
+//   1. legacy CODE_GRAPH_QUIET_HOOKS='0'  → forced noisy（向后兼容）
+//   2. legacy CODE_GRAPH_QUIET_HOOKS='1'  → forced quiet（向后兼容）
+//   3. CODE_GRAPH_VERBOSE_HOOKS='1'       → opt-in noisy（新）
+//   4. 默认                                 → quiet
+// `adopted` 参数已弃用（unconditional 默认不再依赖该信号），保留接口签名只为
+// 不破坏既有调用 / 测试。
+function computeQuietHooks({ env = {} } = {}) {
   const envQuiet = env.CODE_GRAPH_QUIET_HOOKS;
   if (envQuiet === '0') return false;
   if (envQuiet === '1') return true;
-  return !!adopted;
+  if (env.CODE_GRAPH_VERBOSE_HOOKS === '1') return false;
+  return true;
 }
 
 function launchBackgroundAutoUpdate(spawnFn = spawn, env = process.env) {
@@ -277,10 +286,11 @@ function runSessionInit() {
     }
   }
 
-  // quietHooks: adopted → quiet by default (rely on MEMORY.md pointer + on-demand
-  // project_map tool); env '1'/'0' overrides for explicit control.
+  // quietHooks: default quiet (project_map injection duplicates MEMORY.md +
+  // on-demand tool). CODE_GRAPH_VERBOSE_HOOKS=1 to opt in to the dump;
+  // legacy CODE_GRAPH_QUIET_HOOKS=0/1 still force the old behavior.
   const adopted = isAdopted();
-  const quietHooks = computeQuietHooks({ adopted, env: process.env });
+  const quietHooks = computeQuietHooks({ env: process.env });
 
   const mapInjected = binaryCheck.available && !quietHooks ? injectProjectMap() : false;
   const consistencyIssues = binaryCheck.available

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

@@ -84,27 +84,46 @@ test('consistencyCheck returns empty array when binary version matches plugin',
 });
 
 // ──────────────────────────────────────────────────────────────────────────
-// v0.9.0 — quietHooks inference from adopted state
+// v0.17.0 — quietHooks: unconditional quiet default
+// Priority: legacy QUIET_HOOKS=0/1 > new VERBOSE_HOOKS=1 > default true.
+// `adopted` param is dead (unconditional default does not consult it) but
+// the destructured signature still accepts it for backward compat.
 // ──────────────────────────────────────────────────────────────────────────
 
-test('computeQuietHooks: env "0" forces noisy regardless of adoption', () => {
-  assert.equal(computeQuietHooks({ adopted: true, env: { CODE_GRAPH_QUIET_HOOKS: '0' } }), false);
-  assert.equal(computeQuietHooks({ adopted: false, env: { CODE_GRAPH_QUIET_HOOKS: '0' } }), false);
+test('computeQuietHooks: legacy QUIET_HOOKS="0" forces noisy', () => {
+  assert.equal(computeQuietHooks({ env: { CODE_GRAPH_QUIET_HOOKS: '0' } }), false);
 });
 
-test('computeQuietHooks: env "1" forces quiet regardless of adoption', () => {
-  assert.equal(computeQuietHooks({ adopted: true, env: { CODE_GRAPH_QUIET_HOOKS: '1' } }), true);
-  assert.equal(computeQuietHooks({ adopted: false, env: { CODE_GRAPH_QUIET_HOOKS: '1' } }), true);
+test('computeQuietHooks: legacy QUIET_HOOKS="1" forces quiet', () => {
+  assert.equal(computeQuietHooks({ env: { CODE_GRAPH_QUIET_HOOKS: '1' } }), true);
 });
 
-test('computeQuietHooks: env unset → follows adopted state', () => {
-  assert.equal(computeQuietHooks({ adopted: true, env: {} }), true);
-  assert.equal(computeQuietHooks({ adopted: false, env: {} }), false);
+test('computeQuietHooks: VERBOSE_HOOKS="1" opts in to noisy', () => {
+  assert.equal(computeQuietHooks({ env: { CODE_GRAPH_VERBOSE_HOOKS: '1' } }), false);
+});
+
+test('computeQuietHooks: legacy QUIET_HOOKS="1" wins over VERBOSE_HOOKS="1"', () => {
+  // Conflicting opt-ins: legacy explicit-quiet wins over new verbose opt-in.
+  // (Legacy QUIET_HOOKS="0" + VERBOSE_HOOKS="1" both mean noisy — no conflict.)
+  assert.equal(
+    computeQuietHooks({ env: { CODE_GRAPH_QUIET_HOOKS: '1', CODE_GRAPH_VERBOSE_HOOKS: '1' } }),
+    true
+  );
+});
+
+test('computeQuietHooks: env unset → quiet by default', () => {
+  assert.equal(computeQuietHooks({ env: {} }), true);
+});
+
+test('computeQuietHooks: no args → quiet by default', () => {
+  assert.equal(computeQuietHooks(), true);
 });
 
-test('computeQuietHooks: env unset, no env arg → follows adopted state', () => {
-  assert.equal(computeQuietHooks({ adopted: true }), true);
-  assert.equal(computeQuietHooks({ adopted: false }), false);
+test('computeQuietHooks: legacy `adopted` param is ignored under new default', () => {
+  // adopted=true used to imply quiet; now quiet is unconditional.
+  // adopted=false used to imply noisy; now still quiet by default.
+  assert.equal(computeQuietHooks({ adopted: true, env: {} }), true);
+  assert.equal(computeQuietHooks({ adopted: false, env: {} }), true);
 });
 
 test('consistencyCheck returns version-mismatch when versions differ', (t) => {

package/claude-plugin/templates/plugin_code_graph_mcp.md

@@ -8,13 +8,19 @@ type: reference
 > Invited-memory 模式：MCP `instructions` 仅留指针，决策细则集中在此。
 >
 > **v0.9.0 起**：插件（`/plugin install`）模式下首次 SessionStart 自动 adopt，
-> 本文件自动写入，自动切换 quietHooks（跳过每次 project_map 注入）。
+> 本文件自动写入到项目 memory 目录。
 > 退出：`CODE_GRAPH_NO_AUTO_ADOPT=1` 阻止，`code-graph-mcp unadopt` 回退。
-> 手动强控：`CODE_GRAPH_QUIET_HOOKS=0` 强制注入 / `=1` 强制静默（覆盖 adoption 推导）。
 >
 > **v0.11.0 起**：已 adopt 的项目在下次 SessionStart 会自动对齐到插件 shipped
 > 的最新决策表（本文件 SHA 与 template 差异时覆盖）。手动编辑会被覆盖——
 > 要锁定自己的版本，设 `CODE_GRAPH_NO_TEMPLATE_REFRESH=1`（不影响首次 adopt）。
+>
+> **v0.17.0 起**：SessionStart `project_map` 注入 **默认 OFF**（不再随 adoption
+> 切换）。本文件 + 7 个工具描述已经覆盖路由所需的全部决策信息，每次会话再
+> dump ≈2.3 KB 的项目地图是冗余的常驻上下文成本。
+> 显式启用：`CODE_GRAPH_VERBOSE_HOOKS=1` —— Bash 调 `code-graph-mcp map --compact`
+> 也是等价的按需替代。
+> 向后兼容：`CODE_GRAPH_QUIET_HOOKS=0` 强制 noisy / `=1` 强制 quiet（优先级最高）。
 
 ## 何时调用 MCP/CLI（替代多步 Grep/Read）
 
@@ -63,7 +69,7 @@ type: reference
 
 ## 工作流惯例
 
-1. 起手 `project_map --compact` 看架构
+1. 起手 `project_map`（或 Bash 调 `code-graph-mcp map --compact`）看架构
 2. `semantic_code_search` 默认带 `compact=true`，省 token
 3. 展开节点：`get_ast_node node_id=N compact=true` 看签名 / 不带 compact 看全文
 4. 改前评估影响：`get_ast_node symbol_name=X include_impact=true`（核心 7 内，首选）
@@ -100,7 +106,8 @@ code-graph-mcp health-check              # 索引健康
 
 ## 卸载 / 回退
 
-- `code-graph-mcp unadopt` — 精确移除 sentinel 段 + 本文件，quietHooks 自动回到 false（下次 SessionStart 恢复 project_map 注入）。
+- `code-graph-mcp unadopt` — 精确移除 sentinel 段 + 本文件。
 - `CODE_GRAPH_NO_AUTO_ADOPT=1`（`~/.claude/settings.json` env） — 阻止未来自动 adopt，不影响已 adopted 状态。
 - `CODE_GRAPH_NO_TEMPLATE_REFRESH=1`（v0.11.0+） — 锁定本文件不随插件升级刷新；允许手动编辑长久保留。
-- `CODE_GRAPH_QUIET_HOOKS=0` — 强制恢复 project_map 注入（即使已 adopted）。
+- `CODE_GRAPH_VERBOSE_HOOKS=1`（v0.17.0+） — opt in 到 SessionStart `project_map` 注入（默认 OFF）。
+- `CODE_GRAPH_QUIET_HOOKS=0` — 强制恢复 `project_map` 注入；优先级高于 VERBOSE_HOOKS（向后兼容路径）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.16.8",
+  "version": "0.17.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": {
@@ -28,16 +28,17 @@
   ],
   "scripts": {
     "build": "cargo build --release --no-default-features && node scripts/copy-binary.js",
-    "prepare": "git rev-parse --git-dir > /dev/null 2>&1 && ln -sf ../../scripts/pre-commit.sh .git/hooks/pre-commit || true"
+    "prepare": "git rev-parse --git-dir > /dev/null 2>&1 && ln -sf ../../scripts/pre-commit.sh .git/hooks/pre-commit || true",
+    "preuninstall": "node claude-plugin/scripts/lifecycle.js uninstall || true"
   },
   "engines": {
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.16.8",
-    "@sdsrs/code-graph-linux-arm64": "0.16.8",
-    "@sdsrs/code-graph-darwin-x64": "0.16.8",
-    "@sdsrs/code-graph-darwin-arm64": "0.16.8",
-    "@sdsrs/code-graph-win32-x64": "0.16.8"
+    "@sdsrs/code-graph-linux-x64": "0.17.0",
+    "@sdsrs/code-graph-linux-arm64": "0.17.0",
+    "@sdsrs/code-graph-darwin-x64": "0.17.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.17.0",
+    "@sdsrs/code-graph-win32-x64": "0.17.0"
   }
 }