@sdsrs/code-graph 0.163.0 → 0.164.0

package/README.md

@@ -231,7 +231,7 @@ and `code-graph-mcp doctor` prints the manual update command.
 
 #### Invited-memory mode (quieter prompts)
 
-By default, every user prompt the plugin deems code-related gets a small context injection from `code-graph` CLI output. If you'd rather rely on MEMORY.md + explicit tool calls, opt into invited-memory mode:
+By default, every user prompt the plugin deems code-related gets a small context injection from `code-graph` CLI output. If you'd rather rely on explicit tool calls, opt into invited-memory mode:
 
 1. Adopt the plugin contract into your project (idempotent, self-heals):
    ```bash
@@ -244,7 +244,7 @@ By default, every user prompt the plugin deems code-related gets a small context
      "env": { "CODE_GRAPH_QUIET_HOOKS": "1" }
    }
    ```
-3. Restart Claude Code. Session startup skips the project-map injection, UserPromptSubmit stops auto-injecting context, and the MCP `instructions` become a short pointer to the MEMORY.md file.
+3. Restart Claude Code. Session startup skips the project-map injection, UserPromptSubmit stops auto-injecting context, and the MCP `instructions` shrink to a one-line command pointer.
 
 ### Option 2: Claude Code MCP Server Only
 
@@ -545,14 +545,13 @@ defaults are what you get by doing nothing.
 | Variable | Effect |
 |---|---|
 | `CODE_GRAPH_NO_AUTO_UPDATE=1` | Never check GitHub for a new release. |
-| `CODE_GRAPH_NO_AUTO_ADOPT=1` | Do not write the steering block into a project's `CLAUDE.md` on SessionStart. |
-| `CODE_GRAPH_NO_TEMPLATE_REFRESH=1` | Keep hand edits to the generated steering block — it is otherwise refreshed to the current template. |
-| `CODE_GRAPH_NO_GITIGNORE=1` | Never touch `.gitignore` — not even to add the `.code-graph/` entry. |
+| `CODE_GRAPH_NO_AUTO_ADOPT=1` | Skip SessionStart's adoption check: no cleanup of this plugin's legacy memory-dir files and no notice about an out-of-date steering block. SessionStart never writes `CLAUDE.md` itself; `code-graph-mcp adopt` does. |
+| `CODE_GRAPH_NO_TEMPLATE_REFRESH=1` | Do not report a steering block that has drifted from the current template (SessionStart only reports it; `code-graph-mcp adopt` refreshes it). |
+| `CODE_GRAPH_NO_GITIGNORE=1` | Do not write the `.code-graph/` ignore rule. It goes to the repository's local `.git/info/exclude`, never to the tracked `.gitignore`, and only when neither file names the directory already. |
 | `CODE_GRAPH_QUIET_HOOKS=1` | Hooks inject a one-line pointer instead of the full decision table. |
 | `CODE_GRAPH_VERBOSE_HOOKS=1` | The opposite: opt into the noisy form. |
 | `CODE_GRAPH_NO_BLOCK_GREP=1` | Never turn a `grep` hint into a block — prefix a single command with it to get past one. |
 | `CODE_GRAPH_NO_INJECT=1` | No post-tool AST context injection. |
-| `CODE_GRAPH_NO_RECENT_IMPACT=1` | Skip the recent-impact section of the SessionStart briefing. |
 | `CODE_GRAPH_HOOK_INDEX=on\|off` | Force the incremental-index hook on or off instead of letting it decide. |
 | `CODE_GRAPH_MODEL_DIR=<dir>` | Load the embedding model from here (air-gapped installs). |
 | `CODE_GRAPH_DISABLE_MODEL_DOWNLOAD=1` | Never fetch the model; fail instead. |

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

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

package/claude-plugin/agents/code-explorer.md

@@ -1,26 +1,29 @@
 ---
 name: code-explorer
 description: Deep code understanding expert using AST knowledge graph. Use when exploring unfamiliar code, tracing complex relationships, or understanding module architecture.
-tools: ["Read", "Grep", "Glob", "Bash", "mcp__code-graph__semantic_code_search", "mcp__code-graph__get_call_graph", "mcp__code-graph__get_ast_node", "mcp__code-graph__project_map", "mcp__code-graph__module_overview", "mcp__code-graph__ast_search", "mcp__code-graph__find_references", "mcp__plugin_code-graph-mcp_code-graph__semantic_code_search", "mcp__plugin_code-graph-mcp_code-graph__get_call_graph", "mcp__plugin_code-graph-mcp_code-graph__get_ast_node", "mcp__plugin_code-graph-mcp_code-graph__project_map", "mcp__plugin_code-graph-mcp_code-graph__module_overview", "mcp__plugin_code-graph-mcp_code-graph__ast_search", "mcp__plugin_code-graph-mcp_code-graph__find_references"]
+tools: ["Read", "Grep", "Glob", "Bash", "mcp__plugin_code-graph-mcp_code-graph__semantic_code_search", "mcp__plugin_code-graph-mcp_code-graph__get_call_graph", "mcp__plugin_code-graph-mcp_code-graph__get_ast_node", "mcp__plugin_code-graph-mcp_code-graph__project_map", "mcp__plugin_code-graph-mcp_code-graph__module_overview", "mcp__plugin_code-graph-mcp_code-graph__ast_search", "mcp__plugin_code-graph-mcp_code-graph__find_references"]
 model: sonnet
 ---
 
 You are a code exploration specialist with access to an AST knowledge graph.
 
-<!-- The tool allowlist carries both MCP namespace spellings on purpose (DOC-07);
-     rationale in CHANGELOG. Delete at most one half, never both. -->
+<!-- The tool allowlist names only the plugin-hosted MCP spelling
+     (`mcp__plugin_code-graph-mcp_code-graph__*`): that is what a live plugin
+     install exposes (checked 2026-09-28 on Claude Code 2.1.284). The bare
+     `mcp__code-graph__*` half DOC-07 kept as a bet matched no tool. -->
 
 ## Strategy
 
-1. **Start with semantic_code_search** to locate relevant code by meaning, or **module_overview** / **project_map** to map an unfamiliar directory or the whole repo
-2. **Use get_call_graph** to understand function relationships and call chains (pass `route_path='GET /api/x'` to trace an HTTP handler downstream)
-3. **Use get_ast_node** to get symbol metadata, source, and callers/callees (`context_lines` for surrounding source, `include_impact` for blast radius)
-4. **Use find_references** for rename/remove audits and **ast_search** to enumerate symbols by type / return / params
-5. **Fall back to Grep/Read** only when code-graph tools lack coverage (e.g., config files, non-code assets)
+The CLI answers from Bash with no tool loading; the MCP tools return the same data.
+
+1. **Map first**: `code-graph-mcp overview <dir>` (MCP `module_overview`) or `code-graph-mcp map --compact` (`project_map`) for an unfamiliar area.
+2. **Locate**: `code-graph-mcp show X` for a named symbol; `code-graph-mcp search "words"` or MCP `semantic_code_search` when you only know what the code does.
+3. **Relate**: `code-graph-mcp callgraph X` (`get_call_graph`; `route_path='GET /api/x'` traces an HTTP handler) and `code-graph-mcp impact X` (`get_ast_node include_impact=true`).
+4. **Audit uses**: `code-graph-mcp refs X` (`find_references`), then grep for what the graph cannot see; `ast_search` enumerates symbols by type / return / params.
+5. **Read** the files the answer points to; use Grep for literal strings and non-code files.
 
 ## Rules
 
-- Always prefer structured graph queries over raw text search
-- Return structured findings: name, file, line, relationships
-- When reporting call chains, include depth and direction
-- Estimate token cost: if Read would require >3 files, prefer code-graph tools
+- Calls through dynamic dispatch, reflection or unresolved imports are not in the graph: an empty caller list is not proof of no callers.
+- Return structured findings: name, file, line, relationships.
+- When reporting call chains, include depth and direction.

package/claude-plugin/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "code-graph-mcp hooks — only SessionStart is loaded by Claude Code from plugin-cache; PreToolUse / PostToolUse / UserPromptSubmit / Stop / SessionEnd entries here are SILENTLY IGNORED (empirical 2026-05-24). lifecycle.js install/update registers those into ~/.claude/settings.json instead (v0.32.0+), so re-adding them here would be dead config, not a second chance — pinned by the SessionStart-only guard in hooks.test.js. Keep this file to the keys Claude Code's schema allows (description, hooks, modules, surface); anything else is warned about at startup and dropped.",
+  "description": "code-graph-mcp hooks, loaded by Claude Code from the plugin: SessionStart plus the tool, prompt, subagent and stop hooks. Since 0.164 they all live here; SessionStart removes the copies earlier versions wrote into ~/.claude/settings.json (a plugin's hooks.json is loaded for every event by current Claude Code). Keep this file to the keys Claude Code's schema allows (description, hooks, modules, surface); maintainer notes go in hooks.test.js.",
   "hooks": {
     "SessionStart": [
       {
@@ -12,6 +12,96 @@
           }
         ]
       }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-edit-guide.js\"",
+            "timeout": 4
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-grep-guide.js\"",
+            "timeout": 3
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-read-guide.js\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/incremental-index.js\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/post-grep-inject.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/user-prompt-context.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "Explore|Plan|general-purpose",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/subagent-start.js\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/stop-impact.js\"",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }

package/claude-plugin/scripts/adopt.js

@@ -69,29 +69,26 @@ function writeFileAtomic(filePath, data, { followLink = false } = {}) {
 // The managed block written into <cwd>/CLAUDE.md. Concise + always-loaded: a
 // scannable trigger table that primes the right tool, ending with a pointer to
 // the full table at .claude/plugin_code_graph_mcp.md (opened on demand, never
-// auto-loaded). Project-type tailoring swaps a couple of rows (web → HTTP-route
-// tracing; frontend → reference audits) — body of the detail doc is unchanged.
+// auto-loaded). Project-type tailoring adds a row for web projects (HTTP-route
+// tracing) — body of the detail doc is unchanged.
 //
-// Every row spends the bare name `code-graph-mcp`, and a plugin-only install has
-// it nowhere on PATH: findBinary() resolves the plugin's own download at
-// ~/.cache/code-graph/bin (auto-update.js `cachedBinaryPath`), and the global-npm
-// tiers below it exist only for users who ran `npm i -g` themselves. Issue #41 is
-// what that reads like from the other side — a table of commands the user's shell
-// answers with "command not found". Hence the fallback line below the table.
+// Every row spends the bare name `code-graph-mcp`. Issue #41 was a plugin-only
+// install whose shell answered it with "command not found"; Claude Code now puts
+// the plugin's `bin/` launcher on the Bash PATH, so the `~/.cache/code-graph/bin`
+// fallback line this block used to carry is gone (it also could not run
+// `adopt`/`doctor`, which are JS-dispatched).
 //
-// It names a path SHAPE, never a resolved one. This file goes into a git-tracked
-// CLAUDE.md (the adopt output says so two screens down), so a resolved
-// /home/<user>/… is right on one machine and wrong on every teammate's — and
-// buildBlock's byte-determinism is exactly what needsRefresh diffs, so
-// machine-varying content would rewrite the block on every clone's next
-// SessionStart. No `.exe` variant for the same reason it is safe not to have one:
-// platformGuard() refuses adopt on win32, so this block never exists there.
+// The block is byte-deterministic and machine-independent: it goes into a
+// CLAUDE.md that may be git-tracked, and needsRefresh diffs it bytewise, so a
+// resolved /home/<user>/… path would be right on one machine only.
 const BLOCK_HEADING = '## Code Graph (repo-wide AST index)';
 
 function buildTriggerRows(projectType = 'generic') {
   const base = [
     ['Who calls X / what X calls', '`code-graph-mcp callgraph X`'],
-    ['Impact before editing a fn', '`code-graph-mcp impact X`'],
+    ['Impact before changing a signature', '`code-graph-mcp impact X`'],
+    ['Tests to re-run after changing files', '`code-graph-mcp affected <files>`'],
+    ['Rename / remove audit', '`code-graph-mcp refs X`, then `grep -w X`'],
     ['Unfamiliar dir / module', '`code-graph-mcp overview <dir>`'],
     ['Symbol source / signature', '`code-graph-mcp show X`'],
     ['Concept search (no exact name)', '`code-graph-mcp search "…"` (vector: MCP `semantic_code_search`)'],
@@ -106,11 +103,6 @@ function buildTriggerRows(projectType = 'generic') {
       return [base[0], base[1],
         ['HTTP route → handler chain', '`code-graph-mcp trace "GET /api/x"`'],
         ...base.slice(2)];
-    case 'frontend':
-      // Rename/refactor audits dominate; surface find-references explicitly.
-      return [base[0],
-        ['Rename / refactor audit (refs)', '`code-graph-mcp refs X`'],
-        ...base.slice(1)];
     default:
       return base;
   }
@@ -126,14 +118,13 @@ function buildBlock(projectType = 'generic') {
   const body = [
     BLOCK_HEADING,
     '',
-    'AST + FTS + vector index of the whole repo — prefer over multi-round Grep/Read for',
-    'structural queries (LSP only sees open files; this sees everything). Fastest path = Bash CLI:',
+    'Parsed index of the whole repo. For structural questions — who calls X, what a',
+    'change breaks, every use of a symbol — one call replaces rounds of Grep + Read:',
     '',
     table,
     '',
-    'Not on PATH? A plugin-only install keeps its own copy — same commands, run',
-    '`~/.cache/code-graph/bin/code-graph-mcp` (or `npm i -g @sdsrs/code-graph` once).',
-    '',
+    'Unresolved calls (dynamic dispatch, reflection, unresolved imports) leave no edge, so',
+    'an empty answer is not proof: confirm with grep before deleting or renaming.',
     "Still use Grep for literal strings/regex in non-code files; still Read files you'll edit.",
     'Full command + MCP-tool table: `.claude/plugin_code_graph_mcp.md`',
   ].join('\n');
@@ -491,6 +482,17 @@ function readAdoptedProjects(home) {
   return readAdoptedResult(home).list;
 }
 
+// A8 (2026-09-29 usage evaluation): the registry only ever grew — 7 of 16
+// entries on the evaluation machine named deleted temp dirs. A directory that
+// no longer exists holds no managed block, so each write drops those; an entry
+// whose check fails any other way (EACCES, a stale mount) stays, since its
+// block may still be there.
+function withoutGoneDirs(list) {
+  return list.filter((p) => {
+    try { fs.statSync(p); return true; } catch (err) { return !(err && err.code === 'ENOENT'); }
+  });
+}
+
 /** @returns {boolean} true when the project is recorded (or already was). */
 function recordAdopted(projectDir, home) {
   const res = readAdoptedResult(home);
@@ -498,9 +500,11 @@ function recordAdopted(projectDir, home) {
   try {
     const file = adoptedRegistryFile(home);
     const abs = path.resolve(projectDir);
-    if (res.list.includes(abs)) return true;
+    const kept = withoutGoneDirs(res.list);
+    const next = kept.includes(abs) ? kept : [...kept, abs];
+    if (next.length === res.list.length && next.every((p, i) => p === res.list[i])) return true;
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    writeFileAtomic(file, JSON.stringify([...res.list, abs], null, 2) + '\n');
+    writeFileAtomic(file, JSON.stringify(next, null, 2) + '\n');
     return true;
   } catch { return false; }        // best-effort: registry loss only degrades guidance
 }
@@ -511,7 +515,7 @@ function removeAdopted(projectDir, home) {
   if (res.unusable) return false;
   try {
     const abs = path.resolve(projectDir);
-    const next = res.list.filter((p) => p !== abs);
+    const next = withoutGoneDirs(res.list).filter((p) => p !== abs);
     if (next.length === res.list.length) return true;
     writeFileAtomic(adoptedRegistryFile(home), JSON.stringify(next, null, 2) + '\n');
     return true;
@@ -736,19 +740,27 @@ function maybeAutoAdopt({ cwd, home, env, scriptPath } = {}) {
   if (!isPluginModeInstall(scriptPath || __dirname)) {
     return { attempted: false, reason: 'not-plugin-mode', migrated: noMigration };
   }
-  // Clean legacy memory-dir artifacts before installing the new CLAUDE.md scheme.
+  // Clean up this plugin's own legacy memory-dir artifacts.
   const migrated = migrateLegacyMemoryDir({ cwd, home });
+  // Never writes CLAUDE.md or .claude/ (decision D4, 2026-09-28 usage
+  // evaluation). Creating them on the first session made Claude stop to
+  // explain the unexpected changes in 12 of 15 coding runs (0 of 15 without
+  // the plugin), and the MCP instructions already carry 10 of the block's 11
+  // guidance points. An adopted project keeps its block as it is; one that has
+  // drifted from the shipped template is reported as `stale`, so SessionStart
+  // can tell the user how to refresh (`adopt`) or remove (`unadopt`) it. The
+  // name is kept: SessionStart, tests and the uninstall paths all call it.
   if (isAdopted({ cwd })) {
-    // shipped template / 管理块 漂移时重跑 adopt 对齐。
-    // opt-out: CODE_GRAPH_NO_TEMPLATE_REFRESH=1（锁定手动编辑）。
     if (env.CODE_GRAPH_NO_TEMPLATE_REFRESH !== '1' && needsRefresh({ cwd })) {
-      const result = adopt({ cwd, home });
-      return { attempted: true, reason: 'refreshed', result, migrated };
+      return { attempted: false, reason: 'stale', migrated };
     }
     return { attempted: false, reason: 'already-adopted', migrated };
   }
-  const result = adopt({ cwd, home });
-  return { attempted: true, reason: 'adopted', result, migrated };
+  return { attempted: false, reason: 'not-adopted', migrated };
+}
+
+function adoptCommand() {
+  return `node ${shellQuote(__filename)} adopt`;
 }
 
 function unadopt({ cwd, home } = {}) {
@@ -978,7 +990,7 @@ if (require.main === module) {
 module.exports = {
   adopt, unadopt, memoryDir, formatResult, unadoptCommand, shellQuote, stripSentinelBlock,
   readAdoptedProjects, readAdoptedResult, recordAdopted, removeAdopted, adoptedRegistryFile,
-  isAdopted, isPluginModeInstall, maybeAutoAdopt, needsRefresh, isProjectRoot,
+  isAdopted, isPluginModeInstall, maybeAutoAdopt, needsRefresh, isProjectRoot, adoptCommand,
   detectProjectType, buildBlock, buildTriggerRows, migrateLegacyMemoryDir,
   claudeMdPath, detailDir, detailPath,
   extractCargoRuntimeDeps, extractPyRuntimeDeps, extractGoDirectRequires,

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

@@ -545,6 +545,13 @@ function runCallgraphAnswer(opts = {}) {
         !(out.includes('← called by') || out.includes('→ calls'))) {
       return { status: 'no-hits' };
     }
+    // `callgraph` promotes a unique fuzzy match when the name has no edges of
+    // its own (`task` → `run_startup_tasks`) and says so only on stderr, which
+    // this run discards. A tree rooted at another symbol is not an answer about
+    // the grepped one: real sessions got up to 27 of 98 injections this way.
+    if (out.split('\n', 1)[0].split(' ', 1)[0] !== symbol) {
+      return { status: 'no-hits' };
+    }
     const { text, truncated } = truncateAtLine(out, maxBytes);
     return { status: 'hits', text, truncated };
   } catch {

package/claude-plugin/scripts/covering-tests.js

@@ -56,8 +56,7 @@ function formatCoveringTests(testCallers, editedFile) {
   }
 
   // High fan-out: editing a widely-tested symbol. A long targeted command is noise
-  // — point at the suite instead (mirrors the blast-size scaling in
-  // session-init.js formatRecentImpact).
+  // — point at the suite instead.
   let out = `  Covering tests: ${n} — editing a widely-tested symbol\n`;
   const suite = suiteCommand(runner);
   if (suite) out += `  → Run the suite after editing: ${suite}\n`;

package/claude-plugin/scripts/doctor.js

@@ -7,7 +7,7 @@ const os = require('os');
 const { readBinaryVersion, isDevMode, getNewestMtime } = require('./version-utils');
 const {
   getPluginVersion, readJson, readJsonResult, healthCheck, scanForBrokenPaths,
-  settingsPath, surveyHookCoverage,
+  settingsPath, surveyHookCoverage, hooksFromPluginManifest,
   installedGlobalPkgs, GLOBAL_INSTALL_MARKER, SHELL_PKG,
 } = require('./lifecycle');
 const { UPDATE_STATE_FILE, uninstallTombstoneActive } = require('./cache-paths');
@@ -537,6 +537,25 @@ function runDiagnostics({ checkOnly = false } = {}) {
         status: 'warn',
         detail: 'not determinable — settings.json could not be read or parsed',
       });
+    } else if (hooksFromPluginManifest(settings)) {
+      // Decision D2: the installed plugin's hooks.json carries every hook, so an
+      // empty settings.json is the healthy state and our entries in it — left
+      // by a pre-0.164 install — fire each hook a second time.
+      if (cov.present.length === 0) {
+        results.push({
+          name: 'Hook coverage',
+          status: 'ok',
+          detail: "hooks come from the plugin's hooks.json; settings.json holds none of ours",
+        });
+      } else {
+        results.push({
+          name: 'Hook coverage',
+          status: 'warn',
+          detail: `${cov.present.length} code-graph hook entr${cov.present.length === 1 ? 'y' : 'ies'} in settings.json ` +
+            `run next to the plugin's hooks.json, so each fires twice: ${cov.present.join(', ')}`,
+          fixId: 'legacy-hooks-in-settings',
+        });
+      }
     } else if (cov.missing.length === 0 && cov.stale.length === 0) {
       results.push({
         name: 'Hook coverage',
@@ -1247,6 +1266,26 @@ function runRepairs(results, {
         break;
       }
 
+      case 'legacy-hooks-in-settings': {
+        console.log("\n  Removing code-graph hooks from settings.json (the plugin's hooks.json carries them)...");
+        if (relicRepairGuard()) break;
+        if (teardownRepairGuard()) break;
+        const { install } = require('./lifecycle');
+        const r = install({ clearTombstone: true });
+        if (r.settingsUnwritable) {
+          console.log('  \u274c settings.json is not writable \u2014 entries NOT removed');
+          console.log('     Fix the permissions on it (or on ~/.claude) and re-run; see the error above.');
+        } else if (r.settingsUnreadable) {
+          console.log('  \u274c settings.json could not be read or parsed \u2014 entries NOT removed');
+        } else if (r.hooksRegistered) {
+          console.log('  \u2705 settings.json updated — restart Claude Code to apply');
+          fixed++;
+        } else {
+          console.log('  \u2796 install reported no change');
+        }
+        break;
+      }
+
       case 'missing-hooks-in-settings': {
         console.log('\n  Registering code-graph hooks in settings.json...');
         if (relicRepairGuard()) break;

package/claude-plugin/scripts/incremental-index.js

@@ -60,8 +60,11 @@ function runMain() {
   const budget = childBudgetMs();
   if (budget === null) return; // exhausted — the index waits for the next edit
 
+  // --no-embed: structure is what the next query needs, and the vector
+  // backfill made every edit wait out the whole budget (8,048 ms per edit,
+  // hook audit 2026-09-28). Vectors are filled in by the MCP server.
   try {
-    execFileSync(bin, ['incremental-index', '--quiet'], hidden({
+    execFileSync(bin, ['incremental-index', '--quiet', '--no-embed'], hidden({
       timeout: budget,
       stdio: ['pipe', 'pipe', 'pipe']
     }));

package/claude-plugin/scripts/lifecycle.js

@@ -348,7 +348,7 @@ function tryWriteSettings(settings) {
   } catch (err) {
     console.error(
       `[code-graph] cannot write ${settingsPath()} (${err.code || err.name}: ${err.message}). ` +
-      `Nothing was changed. The plugin stays inactive until the file is writable.`
+      `Nothing was changed; run \`code-graph-mcp doctor\` once the file is writable.`
     );
     return err;
   }
@@ -1019,7 +1019,7 @@ function buildSettingsHookEntries() {
 
   return {
     PreToolUse: [
-      { description: SETTINGS_HOOK_DESC.preToolUse, matcher: 'Edit', hooks: [scriptCmd('pre-edit-guide.js')] },
+      { description: SETTINGS_HOOK_DESC.preToolUse, matcher: 'Edit|Write', hooks: [scriptCmd('pre-edit-guide.js')] },
       { description: SETTINGS_HOOK_DESC.preToolUse, matcher: 'Bash', hooks: [scriptCmd('pre-grep-guide.js')] },
       { description: SETTINGS_HOOK_DESC.preToolUse, matcher: 'Read', hooks: [scriptCmd('pre-read-guide.js')] },
     ],
@@ -1101,6 +1101,42 @@ function registerHooksToSettings(settings) {
   return before !== JSON.stringify(settings.hooks);
 }
 
+// --- Where the hooks live (decision D2, 2026-09-28 usage evaluation) ---
+//
+// A plugin install declares its hooks in the plugin's own hooks/hooks.json, and
+// current Claude Code loads that file for every event — verified on 2.1.284:
+// PreToolUse / PostToolUse / UserPromptSubmit / Stop entries in a plugin's
+// hooks.json all fired, and the marketplace-installed claude-mem-lite runs every
+// hook it has that way. The 2026-05-24 observation behind the v0.32.0 re-route
+// (only SessionStart loaded from there) no longer holds, and writing into the
+// user-global settings.json cost a doctor that re-added hooks after uninstall,
+// version-pinned paths and the ping-pong between delivery surfaces.
+//
+// settings.json registration stays for the one surface hooks.json does not
+// reach: an npm-global or dev CLI with no plugin installed. It never runs next
+// to an installed, enabled plugin — both copies would fire every hook twice.
+function hooksFromPluginManifest(settings = readJson(settingsPath()) || {}, { pluginRoot = PLUGIN_ROOT, env = process.env } = {}) {
+  // Claude Code is running this copy as a plugin right now: SessionStart comes
+  // from its hooks.json with CLAUDE_PLUGIN_ROOT set to its root. Compared, not
+  // merely present — the variable can carry another plugin's root.
+  if (env.CLAUDE_PLUGIN_ROOT && path.resolve(env.CLAUDE_PLUGIN_ROOT) === path.resolve(pluginRoot)) return true;
+  // A marketplace install's copy, reached outside a session (doctor, auto-update).
+  const rel = path.relative(pluginsCacheDir(), path.resolve(pluginRoot));
+  if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) return true;
+  // Another surface (npm global, dev checkout) while the plugin is installed and
+  // enabled: the plugin's hooks.json already covers every session.
+  return hasInstalledPluginRecord() && !isPluginExplicitlyDisabled(settings);
+}
+
+// Put settings.json in the state the surface needs: our entries registered when
+// nothing else carries the hooks, removed when the plugin's hooks.json does.
+// Returns whether `settings` changed.
+function syncSettingsHooks(settings, opts = {}) {
+  return hooksFromPluginManifest(settings, opts)
+    ? removeHooksFromSettings(settings)
+    : registerHooksToSettings(settings);
+}
+
 // Extract the .js script path a hook command invokes — bare (`node "…"`) or
 // existence-guarded (`if [ -f "…" ]; then node "…"; fi`).
 // Is the composite command currently in the statusLine slot one we should
@@ -1251,6 +1287,7 @@ function hookFirePayload(matcher, event = '') {
     case 'Read':
       return { tool_name: 'Read', tool_input: { file_path: 'src/example.rs' } };
     case 'Edit':
+    case 'Edit|Write':
     case 'Write|Edit':
       return { tool_name: 'Edit', tool_input: { file_path: 'src/example.rs', old_string: 'a', new_string: 'b' } };
     case '': // UserPromptSubmit
@@ -1269,9 +1306,9 @@ function hookFirePayload(matcher, event = '') {
   }
 }
 
-// The hooks CC actually loads from settings.json (PreToolUse/PostToolUse/
-// UserPromptSubmit). SessionStart (hooks.json) runs every session → its own
-// liveness proof → excluded here.
+// Every hook besides SessionStart, from the one list both registration surfaces
+// use (hooks.json for a plugin, settings.json otherwise). SessionStart runs
+// every session → its own liveness proof → excluded here.
 function defaultHookFireProbes() {
   const probes = [];
   for (const [event, entries] of Object.entries(buildSettingsHookEntries())) {
@@ -1485,11 +1522,9 @@ function install({ reclaimStatusline = false, clearTombstone = false } = {}) {
   // Register code-graph provider
   registerStatuslineProvider('code-graph', codeGraphStatuslineCommand(), false);
 
-  // 2. Hooks — v0.32.0: actively write PreToolUse/PostToolUse/UserPromptSubmit
-  //    to settings.json. Plugin-cache hooks.json is silently ignored by current
-  //    Claude Code for these events (SessionStart still loads from cache).
-  //    registerHooksToSettings is idempotent: strips priors then appends fresh.
-  const hooksRegistered = registerHooksToSettings(settings);
+  // 2. Hooks — registered in settings.json only where the plugin's hooks.json
+  //    does not reach; removed from it where it does (syncSettingsHooks).
+  const hooksRegistered = syncSettingsHooks(settings);
   if (hooksRegistered) settingsChanged = true;
 
   // NOTE: enabledPlugins is managed by Claude Code's plugin system, not by lifecycle.
@@ -1765,9 +1800,9 @@ function update() {
   // 2. Update code-graph provider in registry
   registerStatuslineProvider('code-graph', codeGraphStatuslineCommand(), false);
 
-  // 3. Hooks — v0.32.0: register PreToolUse/PostToolUse/UserPromptSubmit in
-  //    settings.json (idempotent; absolute paths re-anchor on every update).
-  const hooksRegistered = registerHooksToSettings(settings);
+  // 3. Hooks — as in install(): settings.json carries them only where the
+  //    plugin's hooks.json does not (idempotent; paths re-anchor on update).
+  const hooksRegistered = syncSettingsHooks(settings);
   if (hooksRegistered) settingsChanged = true;
 
   // NOTE: enabledPlugins is managed by Claude Code's plugin system, not by lifecycle.
@@ -2192,6 +2227,7 @@ module.exports = {
   cacheDirVersion,                                                     // exported for the separator-agnostic test
 
   verifyHooksFire, defaultHookFireProbes,                              // v0.67.0 — firing self-test
+  hooksFromPluginManifest, syncSettingsHooks,                          // D2 — where the hooks live
   activeInstallPath, isStaleRelicContext,                              // v0.49.1 — stale-relic downgrade guard
   SETTINGS_HOOK_DESC, OUR_HOOK_SCRIPTS, OUR_DESCRIPTIONS,              // v0.32.0 — for tests
   PLUGIN_ROOT,                                                         // v0.32.1 — for tests / consumers