@sdsrs/code-graph 0.31.0 → 0.32.2

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

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

package/claude-plugin/hooks/hooks.json

@@ -1,6 +1,6 @@
 {
-  "description": "code-graph-mcp hooks — loaded directly by Claude Code from the plugin cache.",
-  "_note": "Authoritative source. settings.json is no longer used for hook registration as of v0.8.3 — session-init.js actively removes any legacy code-graph entries it finds there. Paths use ${CLAUDE_PLUGIN_ROOT} so they follow version directory updates automatically.",
+  "description": "code-graph-mcp hooks — only SessionStart is loaded by Claude Code from plugin-cache. All other event types are registered by lifecycle.js into ~/.claude/settings.json (v0.32.0+).",
+  "_note": "Empirical 2026-05-24: current Claude Code only loads SessionStart entries from plugin-cache hooks.json. PreToolUse / PostToolUse / UserPromptSubmit / Stop / SessionEnd entries here are SILENTLY IGNORED. lifecycle.js install/update writes those to ~/.claude/settings.json instead (pattern from claude-mem-lite). Re-adding non-SessionStart entries here would NOT make them fire — they would just be dead config. See feedback_pretooluse_dark_under_green_health.md for the jsonl evidence chain.",
   "hooks": {
     "SessionStart": [
       {
@@ -13,62 +13,6 @@
           }
         ]
       }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "tool == \"Edit\"",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-edit-guide.js\"",
-            "timeout": 4
-          }
-        ]
-      },
-      {
-        "matcher": "tool == \"Bash\"",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-grep-guide.js\"",
-            "timeout": 3
-          }
-        ]
-      },
-      {
-        "matcher": "tool == \"Read\"",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-read-guide.js\"",
-            "timeout": 3
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "tool == \"Write\" || tool == \"Edit\"",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/incremental-index.js\"",
-            "timeout": 10
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/user-prompt-context.js\"",
-            "timeout": 5
-          }
-        ]
-      }
     ]
   }
 }

package/claude-plugin/scripts/auto-update.js

@@ -8,6 +8,7 @@ const os = require('os');
 const { CACHE_DIR, PLUGIN_ID, MARKETPLACE_NAME, readManifest, readJson, writeJsonAtomic, installedPluginsPath, pluginsCacheDir } = require('./lifecycle');
 const { clearCache: clearBinaryCache } = require('./find-binary');
 const { readBinaryVersion, isDevMode } = require('./version-utils');
+const { cgTmpDir } = require('./tmp-dir');
 
 // ── Environment Checks ────────────────────────────────────
 
@@ -251,7 +252,7 @@ async function downloadAndInstall(latest) {
     return { pluginUpdated: false, binaryUpdated: false };
   }
 
-  const tmpDir = path.join(os.tmpdir(), `code-graph-update-${Date.now()}`);
+  const tmpDir = path.join(cgTmpDir(), `update-${Date.now()}`);
   let pluginUpdated = false;
   let binaryUpdated = false;
 

package/claude-plugin/scripts/doctor.js

@@ -7,8 +7,7 @@ const os = require('os');
 const { readBinaryVersion, isDevMode, getNewestMtime } = require('./version-utils');
 const {
   getPluginVersion, readJson, healthCheck, CACHE_DIR,
-  removeHooksFromSettings, isOurHookEntry, writeJsonAtomic,
-  settingsPath,
+  isOurHookEntry, settingsPath, buildSettingsHookEntries,
 } = require('./lifecycle');
 const { findBinary, clearCache: clearBinaryCache } = require('./find-binary');
 
@@ -173,34 +172,52 @@ function runDiagnostics() {
   }
 
   // 6. Hook paths validity
+  // healthCheck() auto-attempts install() when broken paths are detected and
+  // re-scans to verify; repaired:true is now contingent on the re-scan
+  // returning clean. If repaired:false despite install() running, the
+  // re-scan still found broken paths — surfacing 'remaining' makes that
+  // honest instead of telling the user we fixed nothing.
   const hookResult = healthCheck();
   if (hookResult.healthy) {
     results.push({ name: 'Hooks', status: 'ok', detail: 'all paths valid' });
+  } else if (hookResult.repaired) {
+    results.push({
+      name: 'Hooks',
+      status: 'ok',
+      detail: `${hookResult.issues.length} issue(s) auto-repaired`,
+    });
   } else {
+    const remainingCount = Array.isArray(hookResult.remaining)
+      ? hookResult.remaining.length
+      : hookResult.issues.length;
     results.push({
       name: 'Hooks',
-      status: hookResult.repaired ? 'ok' : 'warn',
-      detail: hookResult.repaired
-        ? `${hookResult.issues.length} issue(s) auto-repaired`
-        : `${hookResult.issues.length} invalid path(s)`,
-      fixId: hookResult.repaired ? undefined : 'hooks-invalid',
+      status: 'warn',
+      detail: `${remainingCount} invalid path(s) — auto-repair did not resolve`,
+      fixId: 'hooks-invalid',
     });
   }
 
-  // 7. Legacy hooks in settings.json — v0.8.2 and earlier wrote hooks there;
-  //    cache/<ver>/hooks/hooks.json is now authoritative. Duplicates cause
-  //    every hook to fire twice until settings.json is cleaned.
+  // 7. settings.json hook coverage — v0.32.0 inversion. Current Claude Code
+  //    silently ignores plugin-cache hooks.json for PreToolUse/PostToolUse/
+  //    UserPromptSubmit. lifecycle.js install/update is responsible for
+  //    registering them in settings.json. "Missing" is the bug (previously
+  //    "present" was treated as legacy debris — that was wrong).
   try {
     const settings = readJson(settingsPath()) || {};
-    const legacyCount = countLegacyHookEntries(settings);
-    if (legacyCount === 0) {
-      results.push({ name: 'Legacy hooks', status: 'ok', detail: 'settings.json is clean' });
+    const cov = surveyHookCoverage(settings);
+    if (cov.missing.length === 0) {
+      results.push({
+        name: 'Hook coverage',
+        status: 'ok',
+        detail: `settings.json has all ${cov.expected.length} expected entries`,
+      });
     } else {
       results.push({
-        name: 'Legacy hooks',
+        name: 'Hook coverage',
         status: 'warn',
-        detail: `${legacyCount} entries in settings.json (fire twice per event)`,
-        fixId: 'legacy-hooks-in-settings',
+        detail: `missing ${cov.missing.length}/${cov.expected.length} settings.json entries: ${cov.missing.join(', ')}`,
+        fixId: 'missing-hooks-in-settings',
       });
     }
   } catch { /* probe failed — skip */ }
@@ -208,16 +225,31 @@ function runDiagnostics() {
   return results;
 }
 
-function countLegacyHookEntries(settings) {
-  if (!settings || !settings.hooks) return 0;
-  let count = 0;
-  for (const entries of Object.values(settings.hooks)) {
-    if (!Array.isArray(entries)) continue;
-    for (const entry of entries) {
-      if (isOurHookEntry(entry)) count++;
+// Inventory of (event, matcher) tuples we expect to find in settings.json after
+// install. Used by doctor to detect missing entries.
+function surveyHookCoverage(settings) {
+  const desired = buildSettingsHookEntries();
+  const expected = [];
+  for (const [event, entries] of Object.entries(desired)) {
+    for (const e of entries) {
+      expected.push(`${event}:${e.matcher || '*'}`);
+    }
+  }
+
+  const present = new Set();
+  if (settings && settings.hooks) {
+    for (const [event, entries] of Object.entries(settings.hooks)) {
+      if (!Array.isArray(entries)) continue;
+      for (const entry of entries) {
+        if (isOurHookEntry(entry)) {
+          present.add(`${event}:${entry.matcher || '*'}`);
+        }
+      }
     }
   }
-  return count;
+
+  const missing = expected.filter(k => !present.has(k));
+  return { expected, present: [...present], missing };
 }
 
 // ── Report Formatting ─────────────────────────────────────
@@ -370,21 +402,20 @@ function runRepairs(results) {
         console.log('\n  Repairing hooks...');
         const { install } = require('./lifecycle');
         install();
-        console.log('  \u2705 Hooks repaired');
+        console.log('  \u2705 Hooks repaired \u2014 restart Claude Code to apply');
         fixed++;
         break;
       }
 
-      case 'legacy-hooks-in-settings': {
-        console.log('\n  Removing legacy code-graph hooks from settings.json...');
-        const settingsFile = settingsPath();
-        const settings = readJson(settingsFile) || {};
-        if (removeHooksFromSettings(settings)) {
-          writeJsonAtomic(settingsFile, settings);
-          console.log('  \u2705 settings.json cleaned — restart Claude Code to apply');
+      case 'missing-hooks-in-settings': {
+        console.log('\n  Registering code-graph hooks in settings.json...');
+        const { install } = require('./lifecycle');
+        const r = install();
+        if (r.hooksRegistered) {
+          console.log('  \u2705 settings.json updated — restart Claude Code to apply');
           fixed++;
         } else {
-          console.log('  \u2796 No legacy entries found');
+          console.log('  \u2796 install reported no change (settings already had entries)');
         }
         break;
       }

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

@@ -0,0 +1,151 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+// Regression gate for v0.31.1: hooks.json matchers must be Claude Code's
+// literal/regex form, NOT the expression DSL `tool == "X"`. The earlier
+// matchers parsed as regex against tool names, never matched anything,
+// and left every PreToolUse hook silently inert from v0.25.0 through
+// v0.31.0. The bug was invisible to the existing unit tests because they
+// spawn the hook scripts directly via stdin, bypassing Claude Code's
+// matcher dispatch.
+
+const HOOKS_JSON = path.resolve(__dirname, '..', 'hooks', 'hooks.json');
+
+function loadHooks() {
+  const raw = fs.readFileSync(HOOKS_JSON, 'utf8');
+  return JSON.parse(raw);
+}
+
+function* iterMatchers(hooksByEvent) {
+  for (const [event, entries] of Object.entries(hooksByEvent || {})) {
+    if (!Array.isArray(entries)) continue;
+    for (let i = 0; i < entries.length; i++) {
+      const e = entries[i];
+      yield { event, idx: i, matcher: e && e.matcher };
+    }
+  }
+}
+
+test('hooks.json: file parses as JSON', () => {
+  assert.doesNotThrow(loadHooks);
+});
+
+test('hooks.json: every entry has a string matcher', () => {
+  const cfg = loadHooks();
+  let count = 0;
+  for (const { event, idx, matcher } of iterMatchers(cfg.hooks)) {
+    assert.equal(typeof matcher, 'string',
+      `hooks.${event}[${idx}].matcher should be a string, got ${typeof matcher}`);
+    count++;
+  }
+  assert.ok(count > 0, 'expected at least one matcher in hooks.json');
+});
+
+// The actual regression gate. Each banned token reflects a specific
+// failure mode we hit and want to keep out forever.
+const BANNED_TOKENS = [
+  // The original v0.25.0 → v0.31.0 bug: expression-style matcher treated
+  // as regex against tool name → never matched.
+  { token: '==', why: 'expression DSL (e.g. `tool == "Edit"`) is not supported; use literal tool name' },
+  // `tool ==` or `tool name == "X"` — same family, different spelling.
+  { token: 'tool ', why: 'expression DSL with `tool` variable is not supported' },
+  // Boolean ORs as expression operators (regex uses `|`, not `||`).
+  { token: '||', why: 'use `|` for pipe-list (e.g. `Write|Edit`), not `||`' },
+  // Boolean AND has no meaning in tool-name matching.
+  { token: '&&', why: '`&&` has no meaning in matchers' },
+  // Double-quotes inside the matcher are a strong hint of expression DSL
+  // (the broken syntax was `"tool == \"Edit\""`).
+  { token: '"', why: 'literal double-quote in matcher is almost always a copy-paste of expression DSL' },
+];
+
+test('hooks.json: matchers avoid banned expression-DSL tokens', () => {
+  const cfg = loadHooks();
+  const offenders = [];
+  for (const { event, idx, matcher } of iterMatchers(cfg.hooks)) {
+    for (const { token, why } of BANNED_TOKENS) {
+      if (matcher.includes(token)) {
+        offenders.push(`hooks.${event}[${idx}].matcher = ${JSON.stringify(matcher)} — contains banned ${JSON.stringify(token)} (${why})`);
+      }
+    }
+  }
+  assert.deepEqual(offenders, [],
+    'hooks.json matcher syntax regression — see v0.31.1 CHANGELOG:\n  ' + offenders.join('\n  '));
+});
+
+// v0.32.0 architecture: plugin-cache hooks.json ONLY carries SessionStart.
+// PreToolUse / PostToolUse / UserPromptSubmit are registered into
+// ~/.claude/settings.json by lifecycle.js (current Claude Code silently
+// ignores plugin-cache hooks.json entries for those events — confirmed
+// 2026-05-24 via session jsonl, see feedback_pretooluse_dark_under_green_health.md).
+test('hooks.json: contains SessionStart only (v0.32.0)', () => {
+  const cfg = loadHooks();
+  assert.deepEqual(Object.keys(cfg.hooks || {}), ['SessionStart'],
+    'plugin-cache hooks.json must contain only SessionStart; other events go via settings.json. ' +
+    'Adding entries here for PreToolUse/PostToolUse/UserPromptSubmit would be dead config — CC does not load them.');
+});
+
+test('hooks.json: SessionStart wires session-init.js', () => {
+  const cfg = loadHooks();
+  const entries = (cfg.hooks && cfg.hooks.SessionStart) || [];
+  assert.ok(entries.length > 0, 'SessionStart entry missing');
+  const cmd = entries[0].hooks && entries[0].hooks[0] && entries[0].hooks[0].command;
+  assert.match(cmd || '', /session-init\.js/);
+});
+
+// Cross-validate that lifecycle.js's buildSettingsHookEntries covers the
+// matchers we removed from hooks.json — keeps the migration whole. If a
+// future refactor accidentally drops a matcher in one place, this fails.
+test('lifecycle.buildSettingsHookEntries covers PreToolUse Edit/Bash/Read', () => {
+  const { buildSettingsHookEntries } = require('./lifecycle');
+  const desired = buildSettingsHookEntries();
+  const ptu = (desired.PreToolUse || []).map(e => e.matcher);
+  for (const tool of ['Edit', 'Bash', 'Read']) {
+    assert.ok(ptu.includes(tool), `lifecycle.js PreToolUse missing matcher: ${tool}; got ${JSON.stringify(ptu)}`);
+  }
+});
+
+test('lifecycle.buildSettingsHookEntries covers PostToolUse Write|Edit + UserPromptSubmit', () => {
+  const { buildSettingsHookEntries } = require('./lifecycle');
+  const desired = buildSettingsHookEntries();
+  const postMatchers = (desired.PostToolUse || []).map(e => e.matcher);
+  assert.ok(postMatchers.some(m => m === 'Write|Edit'),
+    `PostToolUse must have 'Write|Edit' matcher; got ${JSON.stringify(postMatchers)}`);
+  const upsMatchers = (desired.UserPromptSubmit || []).map(e => e.matcher);
+  assert.ok(upsMatchers.length > 0, 'UserPromptSubmit must have at least one matcher');
+});
+
+test('lifecycle.buildSettingsHookEntries: every entry carries description marker', () => {
+  // Description marker is the primary cleanup discriminator (immune to
+  // path/env pollution per feedback_plugin_env_isolation.md). If an entry
+  // lacks a description, isOurHookEntry falls back to path-fragment match
+  // which is less reliable. Force every entry to have one.
+  const { buildSettingsHookEntries } = require('./lifecycle');
+  const desired = buildSettingsHookEntries();
+  for (const [event, entries] of Object.entries(desired)) {
+    for (let i = 0; i < entries.length; i++) {
+      assert.ok(entries[i].description && entries[i].description.includes('[code-graph-mcp'),
+        `${event}[${i}] missing or malformed description marker`);
+    }
+  }
+});
+
+test('lifecycle.buildSettingsHookEntries: hook commands use absolute paths (no env vars)', () => {
+  // settings.json hook commands run with env pollution risk
+  // (feedback_plugin_env_isolation.md). Paths MUST be absolute, derived
+  // from __dirname, never from ${CLAUDE_PLUGIN_ROOT}.
+  const { buildSettingsHookEntries } = require('./lifecycle');
+  const desired = buildSettingsHookEntries();
+  for (const entries of Object.values(desired)) {
+    for (const e of entries) {
+      for (const h of e.hooks) {
+        assert.ok(!h.command.includes('${CLAUDE_PLUGIN_ROOT}'),
+          `command must not use \${CLAUDE_PLUGIN_ROOT}: ${h.command}`);
+        assert.ok(h.command.startsWith('node "/') || h.command.match(/node "[A-Z]:\\/),
+          `command path must be absolute: ${h.command}`);
+      }
+    }
+  }
+});

package/claude-plugin/scripts/lifecycle.js

@@ -245,28 +245,63 @@ function migrateOldPluginIds(settings) {
 }
 
 // --- Hook identity ---
-// Claude Code loads hooks from cache/<mp>/<plugin>/<ver>/hooks/hooks.json —
-// that file is the authoritative source. Any entries matching our hooks
-// inside settings.json are legacy migration debris (v0.8.2 and earlier wrote
-// there) and must be stripped on every install/update/session-init so events
-// don't fire twice.
+//
+// v0.32.0 ARCHITECTURE CORRECTION (see project_hooks_settings.md / feedback_pretooluse_dark_under_green_health.md):
+//
+// Empirical finding 2026-05-24: current Claude Code only loads SessionStart
+// hooks from cache/<mp>/<plugin>/<ver>/hooks/hooks.json. PreToolUse, PostToolUse,
+// UserPromptSubmit, Stop, SessionEnd entries in plugin-cache hooks.json are
+// SILENTLY IGNORED. Only ~/.claude/settings.json entries reach CC for those events.
+//
+// Therefore lifecycle.js now ACTIVELY WRITES non-SessionStart hook entries to
+// settings.json (with description markers for cleanup), and the shipped
+// claude-plugin/hooks/hooks.json carries only SessionStart. SessionStart entries
+// in claude-plugin/hooks/hooks.json continue to be CC-loaded as before.
+//
+// Pattern mirrors claude-mem-lite's install.mjs (cache hooks.json cleared
+// to prevent duplicate registration).
+
+const OUR_HOOK_SCRIPTS = [
+  'session-init.js',
+  'incremental-index.js',
+  'user-prompt-context.js',
+  'pre-edit-guide.js',
+  'pre-grep-guide.js',   // v0.32.0 — was in plugin-cache only, never fired
+  'pre-read-guide.js',   // v0.32.0 — was in plugin-cache only, never fired
+];
+
+// Description markers — primary cleanup discriminator (immune to env/path
+// pollution per feedback_plugin_env_isolation.md). New v0.32.0 markers carry
+// the version so older lifecycle.js still recognizes them as ours.
+const SETTINGS_HOOK_DESC = {
+  preToolUse:       '[code-graph-mcp v0.32+] PreToolUse re-routed via settings.json (cache hooks.json silently ignored for this event by current CC)',
+  postToolUseEdit:  '[code-graph-mcp v0.32+] PostToolUse Write|Edit incremental-index update',
+  userPromptSubmit: '[code-graph-mcp v0.32+] UserPromptSubmit context push',
+};
 
-const OUR_HOOK_SCRIPTS = ['session-init.js', 'incremental-index.js', 'user-prompt-context.js', 'pre-edit-guide.js'];
 const OUR_DESCRIPTIONS = [
+  // Legacy v0.7.x / 0.8.x descriptions — kept so very-old installs still get cleaned up.
   'StatusLine self-heal, lifecycle sync, project map injection',
   'Auto-inject impact analysis when editing functions with 2+ callers',
   'Auto-update code graph index after file edits',
   'Inject code-graph structural context based on user intent',
+  // v0.32.0 — new re-route markers
+  SETTINGS_HOOK_DESC.preToolUse,
+  SETTINGS_HOOK_DESC.postToolUseEdit,
+  SETTINGS_HOOK_DESC.userPromptSubmit,
 ];
 
 function isOurHookEntry(entry) {
   if (!entry || !entry.hooks) return false;
-  // Primary: match by description (legacy v0.7.x/0.8.x registrations).
+  // Primary: match by description (immune to path pollution).
   if (entry.description && OUR_DESCRIPTIONS.includes(entry.description)) return true;
-  // Fallback: match by script name + 'code-graph' in path.
+  // Fallback: script name + MARKETPLACE_NAME in path. v0.32.1: tightened from
+  // bare 'code-graph' (which would claim a user's own ~/code-graph/foo.js) to
+  // the actual marketplace dir name 'code-graph-mcp' — Requirement 3 says
+  // foreign-entry strip is unacceptable, so be conservative.
   return entry.hooks.some(h =>
     h.command && OUR_HOOK_SCRIPTS.some(s => h.command.includes(s)) &&
-    h.command.includes('code-graph')
+    h.command.includes(MARKETPLACE_NAME)
   );
 }
 
@@ -286,6 +321,62 @@ function removeHooksFromSettings(settings) {
   return changed;
 }
 
+// --- v0.32.0: settings.json hook registration ---
+
+// PLUGIN_ROOT (module-level, line 18) is the canonical __dirname-derived
+// absolute path — never CLAUDE_PLUGIN_ROOT env (env leaks across plugins
+// in settings.json hook execution context per feedback_plugin_env_isolation.md).
+
+function buildSettingsHookEntries() {
+  const root = PLUGIN_ROOT;
+  const scriptCmd = (name, timeout) => ({
+    type: 'command',
+    command: `node "${path.join(root, 'scripts', name)}"`,
+    timeout,
+  });
+
+  return {
+    PreToolUse: [
+      { description: SETTINGS_HOOK_DESC.preToolUse, matcher: 'Edit', hooks: [scriptCmd('pre-edit-guide.js', 4)] },
+      { description: SETTINGS_HOOK_DESC.preToolUse, matcher: 'Bash', hooks: [scriptCmd('pre-grep-guide.js', 3)] },
+      { description: SETTINGS_HOOK_DESC.preToolUse, matcher: 'Read', hooks: [scriptCmd('pre-read-guide.js', 3)] },
+    ],
+    PostToolUse: [
+      { description: SETTINGS_HOOK_DESC.postToolUseEdit, matcher: 'Write|Edit', hooks: [scriptCmd('incremental-index.js', 10)] },
+    ],
+    UserPromptSubmit: [
+      { description: SETTINGS_HOOK_DESC.userPromptSubmit, matcher: '', hooks: [scriptCmd('user-prompt-context.js', 5)] },
+    ],
+  };
+}
+
+// Idempotent two-pass: (1) evict ALL our entries (legacy v0.7+/0.8+ markers
+// AND v0.32+ markers) across EVERY event — catches legacy SessionStart/
+// PostToolUse entries in settings.json pointing to stale plugin-cache paths;
+// (2) write fresh v0.32+ entries for the events we own. SessionStart stays
+// in plugin-cache hooks.json (it's still loaded from there), so we don't
+// re-write it to settings.json.
+function registerHooksToSettings(settings) {
+  settings.hooks = settings.hooks || {};
+  const before = JSON.stringify(settings.hooks);
+
+  // Pass 1: evict our entries across every event.
+  for (const event of Object.keys(settings.hooks)) {
+    if (!Array.isArray(settings.hooks[event])) continue;
+    settings.hooks[event] = settings.hooks[event].filter(e => !isOurHookEntry(e));
+    if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  }
+
+  // Pass 2: write fresh entries for our desired events.
+  const desired = buildSettingsHookEntries();
+  for (const [event, desiredEntries] of Object.entries(desired)) {
+    const existing = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    settings.hooks[event] = [...existing, ...desiredEntries];
+  }
+
+  return before !== JSON.stringify(settings.hooks);
+}
+
 // --- Install (idempotent) ---
 
 function install() {
@@ -324,11 +415,12 @@ function install() {
   // Register code-graph provider
   registerStatuslineProvider('code-graph', codeGraphStatuslineCommand(), false);
 
-  // 2. Hooks — cache/<ver>/hooks/hooks.json is authoritative. Strip any legacy
-  //    entries from settings.json that v0.8.2 or earlier registered, so events
-  //    don't fire twice.
-  const legacyHooksRemoved = removeHooksFromSettings(settings);
-  if (legacyHooksRemoved) settingsChanged = true;
+  // 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);
+  if (hooksRegistered) settingsChanged = true;
 
   // NOTE: enabledPlugins is managed by Claude Code's plugin system, not by lifecycle.
   // Do NOT add enabledPlugins entries here — it causes phantom plugin entries
@@ -345,7 +437,7 @@ function install() {
   manifest.updatedAt = new Date().toISOString();
   writeManifest(manifest);
 
-  return { version, settingsChanged, statusLineClaimed: manifest.config.statusLine, legacyHooksRemoved };
+  return { version, settingsChanged, statusLineClaimed: manifest.config.statusLine, hooksRegistered };
 }
 
 // --- Uninstall (clean all config) ---
@@ -437,10 +529,10 @@ function update() {
   // 2. Update code-graph provider in registry
   registerStatuslineProvider('code-graph', codeGraphStatuslineCommand(), false);
 
-  // 3. Hooks — strip any legacy entries from settings.json. cache hooks.json
-  //    is the new authoritative source and always has the up-to-date paths.
-  const legacyHooksRemoved = removeHooksFromSettings(settings);
-  if (legacyHooksRemoved) settingsChanged = true;
+  // 3. Hooks — v0.32.0: register PreToolUse/PostToolUse/UserPromptSubmit in
+  //    settings.json (idempotent; absolute paths re-anchor on every update).
+  const hooksRegistered = registerHooksToSettings(settings);
+  if (hooksRegistered) settingsChanged = true;
 
   // NOTE: enabledPlugins is managed by Claude Code's plugin system, not by lifecycle.
 
@@ -463,7 +555,7 @@ function update() {
   //    cache dirs are inert disk clutter, not correctness risks.
   cleanupOldCacheVersions(3);
 
-  return { oldVersion, version, settingsChanged, legacyHooksRemoved };
+  return { oldVersion, version, settingsChanged, hooksRegistered };
 }
 
 /**
@@ -503,9 +595,15 @@ function cleanupOldCacheVersions(keep = 3) {
 
 // --- Health Check ---
 // Validates all registered paths in settings.json point to existing scripts.
-// Returns { healthy, issues, repaired }.
-
-function healthCheck() {
+// Returns { healthy, issues, repaired, remaining }.
+//   issues:    pre-repair detection list (what was wrong on entry)
+//   repaired:  true only after a post-repair re-scan returned zero issues
+//              (was previously set blindly to true whenever install() ran,
+//              which would lie if install() couldn't actually fix something)
+//   remaining: post-repair detection list — present iff install() was invoked;
+//              empty array means repair succeeded
+
+function scanForBrokenPaths() {
   const settings = readJson(settingsPath()) || {};
   const issues = [];
 
@@ -543,23 +641,40 @@ function healthCheck() {
     }
   }
 
-  // Auto-repair if issues found
-  let repaired = false;
-  if (issues.length > 0) {
-    install();
-    repaired = true;
+  return issues;
+}
+
+function healthCheck() {
+  const issues = scanForBrokenPaths();
+
+  if (issues.length === 0) {
+    return { healthy: true, issues, repaired: false };
   }
 
-  return { healthy: issues.length === 0, issues, repaired };
+  // Attempt auto-repair, then re-scan to confirm the issues actually went
+  // away. install() may legitimately fail to resolve a problem (binary path
+  // permanently gone, registry corrupted, etc.) and the previous code lied
+  // by always returning repaired:true.
+  install();
+  const remaining = scanForBrokenPaths();
+  return {
+    healthy: false,
+    issues,
+    repaired: remaining.length === 0,
+    remaining,
+  };
 }
 
 module.exports = {
-  install, uninstall, update, healthCheck, checkScopeConflict,
+  install, uninstall, update, healthCheck, scanForBrokenPaths, checkScopeConflict,
   isPluginExplicitlyDisabled, isPluginInactive, cleanupDisabledStatusline,
   readManifest, readJson, writeJsonAtomic,
   readRegistry, writeRegistry,
   getPluginVersion, cleanupOldCacheVersions,
   removeHooksFromSettings, isOurHookEntry,
+  registerHooksToSettings, buildSettingsHookEntries,                  // v0.32.0
+  SETTINGS_HOOK_DESC, OUR_HOOK_SCRIPTS, OUR_DESCRIPTIONS,              // v0.32.0 — for tests
+  PLUGIN_ROOT,                                                         // v0.32.1 — for tests / consumers
   registerStatuslineProvider, unregisterStatuslineProvider,
   PLUGIN_ID, OLD_PLUGIN_IDS, MARKETPLACE_NAME, CACHE_DIR, REGISTRY_FILE,
   settingsPath, installedPluginsPath, providersBackupFile, pluginsCacheDir,