code-auditor-mcp 5.0.1 → 5.2.0

package/examples/node-api.auditrc.json

@@ -1,7 +1,4 @@
 {
-  "projectRoot": ".",
-  "reportTitle": "Node.js API Audit",
-  
   "includePaths": [
     "src/**/*.{ts,js}",
     "lib/**/*.{ts,js}",
@@ -11,7 +8,7 @@
     "services/**/*.{ts,js}",
     "models/**/*.{ts,js}"
   ],
-  
+
   "excludePaths": [
     "**/node_modules/**",
     "**/dist/**",
@@ -21,55 +18,18 @@
     "**/__tests__/**",
     "**/coverage/**"
   ],
-  
-  "analyzerConfig": {
-    "security": {
-      "authPatterns": ["authenticate", "authorize", "requireAuth", "passport"],
-      "rateLimitPatterns": ["rateLimit", "throttle", "limiter"],
-      "securityHeaders": [
-        "helmet",
-        "cors",
-        "Content-Security-Policy"
-      ]
-    },
-    "data-access": {
-      "databasePatterns": {
-        "postgres": ["pg", "postgres"],
-        "mysql": ["mysql", "mysql2"],
-        "mongodb": ["mongodb", "mongoose"]
-      },
-      "securityPatterns": {
-        "parameterized": ["?", "$1", ":id"],
-        "sanitized": ["sanitize", "escape", "validator"]
-      },
-      "performanceThresholds": {
-        "maxJoins": 4,
-        "warnOnSelectStar": true
-      }
-    },
+
+  "analyzerConfigs": {
     "solid": {
       "maxMethodsPerClass": 12,
       "maxLinesPerMethod": 60,
       "maxParametersPerMethod": 5
     }
   },
-  
-  "outputFormats": ["json", "html"],
-  "outputDirectory": "./audit-reports",
-  
+
   "minSeverity": "severe",
-  "failOnCritical": true,
-  
+
   "thresholds": {
-    "maxCritical": 0,
-    "maxWarnings": 10,
     "minHealthScore": 90
-  },
-  
-  "integrations": {
-    "ci": {
-      "provider": "github",
-      "failOnThreshold": true
-    }
   }
-}
+}

package/examples/react.auditrc.json

@@ -1,11 +1,8 @@
 {
-  "projectRoot": ".",
-  "reportTitle": "React Project Audit",
-  
   "includePaths": [
     "src/**/*.{ts,tsx,js,jsx}"
   ],
-  
+
   "excludePaths": [
     "**/node_modules/**",
     "**/build/**",
@@ -16,18 +13,10 @@
     "**/coverage/**",
     "**/*.stories.{ts,tsx,js,jsx}"
   ],
-  
-  "analyzerConfig": {
-    "component": {
-      "checkErrorBoundaries": true,
-      "checkPropTypes": true,
-      "maxComplexity": 12,
-      "frameworkPatterns": {
-        "react": {
-          "hooks": ["use*"],
-          "context": ["*Context", "*Provider"]
-        }
-      }
+
+  "analyzerConfigs": {
+    "react": {
+      "maxComponentComplexity": 12
     },
     "solid": {
       "maxMethodsPerClass": 8,
@@ -38,16 +27,10 @@
       "checkImports": true
     }
   },
-  
-  "outputFormats": ["html", "json"],
-  "outputDirectory": "./audit-reports",
-  
+
   "minSeverity": "severe",
-  "showProgress": true,
-  
+
   "thresholds": {
-    "maxCritical": 0,
-    "maxWarnings": 30,
     "minHealthScore": 75
   }
-}
+}

package/examples/tolerant-solid.auditrc.json

@@ -1,11 +1,8 @@
 {
-  "projectRoot": ".",
-  "reportTitle": "Project Audit with Relaxed SOLID Tolerances",
-  
   "includePaths": [
     "src/**/*.{ts,tsx,js,jsx}"
   ],
-  
+
   "excludePaths": [
     "**/node_modules/**",
     "**/build/**",
@@ -13,53 +10,24 @@
     "**/*.test.{ts,tsx,js,jsx}",
     "**/*.spec.{ts,tsx,js,jsx}"
   ],
-  
+
   "analyzerConfigs": {
     "solid": {
-      "componentResponsibilityThresholds": {
-        "default": 2,
-        "layout": 2,      
-        "dashboard": 4,   
-        "table": 3,      
-        "form": 3        
-      },
-      
-      "classResponsibilityThresholds": {
-        "default": 2,
-        "repository": 2,  
-        "service": 3,     
-        "controller": 3,  
-        "model": 3        
-      },
-      
-      "ifElseChainThreshold": 5,         
-      "switchCaseThreshold": 7,          
-      "classMethodThreshold": 12,        
-      "interfaceMemberThreshold": 20,    
-      "dependencyInjectionLimit": 6      
+      "classMethodsThreshold": 40,
+      "maxInterfaceMembers": 50,
+      "maxMethodComplexity": 100
     },
-    
+
     "dry": {
-      "minLineThreshold": 15,            
-      "similarityThreshold": 0.85,       
-      "checkImports": true,
-      "unusedImportsConfig": {
-        "checkLevel": "function",
-        "includeTypeOnlyImports": false,
-        "ignorePatterns": ["React", "^_", "test.*"]
-      }
+      "minLineThreshold": 15,
+      "similarityThreshold": 0.85,
+      "checkImports": true
     }
   },
-  
-  "outputFormats": ["html", "json"],
-  "outputDirectory": "./audit-reports",
-  
+
   "minSeverity": "severe",
-  "showProgress": true,
-  
+
   "thresholds": {
-    "maxCritical": 5,
-    "maxWarnings": 50,
     "minHealthScore": 70
   }
-}
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "code-auditor-mcp",
-  "version": "5.0.1",
-  "description": "Architectural invariants and code quality analysis, enforced inside your AI agent's edit loop. MCP server + CLI + Claude Code plugin. TypeScript, JavaScript, Go.",
+  "version": "5.2.0",
+  "description": "Enforces architectural invariants and code quality rules inside your AI agent's edit loop.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -12,9 +12,9 @@
     "code-auditor-daemon": "dist/daemon/main.js"
   },
   "scripts": {
-    "build": "pnpm run build:version && tsc && pnpm run build:grammars && pnpm run download:natives && pnpm run build:skills && pnpm run build:manifest",
+    "build": "pnpm run build:version && pnpm run build:hooklog && tsc && pnpm run build:grammars && pnpm run build:skills && pnpm run build:manifest",
     "build:version": "node scripts/write-version.mjs",
-    "download:natives": "bash scripts/download-natives.sh",
+    "build:hooklog": "node scripts/write-hook-log-path.mjs",
     "build:grammars": "mkdir -p dist/grammars && cp node_modules/tree-sitter-typescript/tree-sitter-typescript.wasm node_modules/tree-sitter-typescript/tree-sitter-tsx.wasm node_modules/tree-sitter-go/tree-sitter-go.wasm node_modules/tree-sitter-css/tree-sitter-css.wasm grammars/tree-sitter-scss.wasm dist/grammars/",
     "build:skills": "node scripts/build-skills.mjs",
     "build:manifest": "node scripts/build-manifest.mjs",
@@ -36,6 +36,8 @@
     "verify:disk-space": "node scripts/verify-disk-space.mjs",
     "verify:types": "tsc --noEmit",
     "verify:dist-fresh": "node scripts/verify-dist-fresh.mjs",
+    "verify:hook-log-path": "node scripts/verify-hook-log-path.mjs",
+    "verify:version-fresh": "node scripts/verify-version-fresh.mjs",
     "verify:clean-install": "bash scripts/verify-clean-install.sh",
     "verify:dist": "npm pack --silent && bash scripts/verify-dist.sh && rm -f code-auditor-mcp-*.tgz",
     "verify:self": "node scripts/verify-self.mjs && node scripts/verify-languages.mjs",
@@ -45,23 +47,26 @@
     "verify:gate-budget": "node scripts/verify-gate-budget.mjs",
     "verify:recall-value-drift": "tsx scripts/verify-recall-value-drift.ts",
     "verify:extraction-completeness": "tsx scripts/verify-extraction-completeness.ts",
-    "verify:oracle-shortfalls": "tsx scripts/verify-oracle-shortfalls.ts",
+    "verify:recall-cases": "tsx scripts/verify-recall-cases.ts",
     "verify:close": "node scripts/verify-close.mjs"
   },
   "keywords": [
     "mcp",
     "code-quality",
     "static-analysis",
+    "ai-agent",
     "ai-agents",
     "claude-code",
-    "invariants",
+    "cursor",
+    "codex",
     "sarif",
     "tree-sitter",
-    "linter",
     "solid",
+    "go",
     "typescript",
     "javascript",
-    "go"
+    "invariants",
+    "linter"
   ],
   "author": "benahammond",
   "license": "MIT",
@@ -119,7 +124,6 @@
   "files": [
     "dist/**/*",
     "dist/grammars/",
-    "dist/native/",
     "plugin/**/*",
     ".claude-plugin/**/*",
     "examples/**/*",

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

@@ -1,16 +1,17 @@
 {
-  "version": "5.0.1",
+  "version": "5.2.0",
   "files": {
-    ".claude-plugin/plugin.json": "3703d82b6985618b4d93577d72542790d36b38bf9ffd84a8a84c5f200ab5add9",
+    ".claude-plugin/plugin.json": "b492a180519f2991d0aa18211c3c9e45e6569c4715339e79d2032bbeec6ff44d",
     "README.md": "6e51516ead6c7d0b4e77629e071e139b899d30a47838e8721c0d534eb733ad45",
-    "hooks/hooks.json": "4480d9d4fe80dbeb8fc8dacb0a6c67a46f45bf4610b42718876ed4a01935e7b1",
-    "scripts/hook-audit.sh": "5286ee058a73ce9cf3a2fdbb325b8835ae70d85436365d691e95ad6c52bcb84c",
-    "scripts/hook-common.sh": "e6a7b8da6a5e5d528c297c9ab381c77a1d360a6813775ef85342ff200d07a020",
-    "scripts/hook-drift-check.sh": "6fcb897fc5fe6814e9a4cae3138532e6783bb44044c549f89fbfe8eb44580e44",
-    "scripts/hook-self-audit.sh": "4b218f754ca466052da16b0578e2889bdff1abf16d7cbc27a259f71e332af392",
-    "scripts/hook-warm.sh": "9923fe1434e5579abebae868772aba1e53d25d7392b4181ccd4a41dc3692dd55",
+    "hooks/hooks.json": "f9817f337d147bbd0e175741e57c6bd0718c64352ddbff15b5ba9357272b6725",
+    "scripts/hook-audit.sh": "3fa178a87c8ac4d4d49d0cac16df308a37ccc89d778a5eda614799fc69e3e6c8",
+    "scripts/hook-common.sh": "0f29ac77e94ca7ba3f6ffe23bc91f9ce0c77f1568d9f13e29288d0cf5eef6bd8",
+    "scripts/hook-drift-check.sh": "4e6ed8e4e33d0765a5ed6adfda6fb3ecec5750d836632aa4ee6d7a6acce69665",
+    "scripts/hook-log-path.sh": "4ac27ac22dcb29fd82cbd9a936b3da7115c5182386a0e3290ed5ac9e529bc132",
+    "scripts/hook-self-audit.sh": "593926cd4714c653269791ed53675b46fbc92310074bff9194772e25665b0257",
+    "scripts/hook-warm.sh": "22d750e8e36164920515c8370f02dd48f9f09f26bfe4a21e67de91f45b5ffef9",
     "skills/code-auditor/SKILL-RULE-KINDS.md": "be1bbe1b56b19dc112c2657c1f5984f6f704b2ac9c1c0f78a561a58b110d508a",
     "skills/code-auditor/SKILL-SEARCH.md": "95d2df4474995bc5b18e14cc55ac55fb828024541463f109239567e2aa5ab7b0",
-    "skills/code-auditor/SKILL.md": "f120c4b45fe38deeeb2f76ea74df763e87269a15defa6c0508413a41972447ec"
+    "skills/code-auditor/SKILL.md": "0f88508c4549f4b53fdfee431e43a27c7eba2ac99e0eaad64ba55492429be41b"
   }
 }

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

@@ -1,7 +1,7 @@
 {
   "name": "code-auditor",
   "description": "Diff-scoped code quality auditing on every edit. Indexes your codebase, enforces invariants, and feeds violations back to the agent so fixes happen inline.",
-  "version": "5.0.1",
+  "version": "5.2.0",
   "author": {
     "name": "Ben Hammond",
     "email": "ben@benhammond.tech"

package/plugin/hooks/hooks.json

@@ -6,11 +6,11 @@
         "hooks": [
           {
             "type": "command",
-            "command": "if [ -z \"${CLAUDE_PLUGIN_ROOT}\" ]; then exit 0; fi; \"${CLAUDE_PLUGIN_ROOT}\"/scripts/hook-warm.sh"
+            "command": "if [ -z \"${CLAUDE_PLUGIN_ROOT}\" ]; then dir=\"${XDG_CACHE_HOME:-$HOME/.cache}/code-auditor/logs\"; mkdir -p \"$dir\" 2>/dev/null || true; echo \"[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [code-auditor] HOOK NOT RUNNING: CLAUDE_PLUGIN_ROOT is unset — could not locate the plugin; the warm-up is not running.\" >> \"$dir/hook.log\" 2>/dev/null || true; exit 0; fi; \"${CLAUDE_PLUGIN_ROOT}\"/scripts/hook-warm.sh"
           },
           {
             "type": "command",
-            "command": "if [ -z \"${CLAUDE_PLUGIN_ROOT}\" ]; then exit 0; fi; \"${CLAUDE_PLUGIN_ROOT}\"/scripts/hook-drift-check.sh"
+            "command": "if [ -z \"${CLAUDE_PLUGIN_ROOT}\" ]; then dir=\"${XDG_CACHE_HOME:-$HOME/.cache}/code-auditor/logs\"; mkdir -p \"$dir\" 2>/dev/null || true; echo \"[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [code-auditor] HOOK NOT RUNNING: CLAUDE_PLUGIN_ROOT is unset — could not locate the plugin; the drift check is not running.\" >> \"$dir/hook.log\" 2>/dev/null || true; exit 0; fi; \"${CLAUDE_PLUGIN_ROOT}\"/scripts/hook-drift-check.sh"
           }
         ]
       }
@@ -21,11 +21,11 @@
         "hooks": [
           {
             "type": "command",
-            "command": "if [ -z \"${CLAUDE_PLUGIN_ROOT}\" ]; then exit 0; fi; \"${CLAUDE_PLUGIN_ROOT}\"/scripts/hook-audit.sh"
+            "command": "if [ -z \"${CLAUDE_PLUGIN_ROOT}\" ]; then dir=\"${XDG_CACHE_HOME:-$HOME/.cache}/code-auditor/logs\"; mkdir -p \"$dir\" 2>/dev/null || true; echo \"[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [code-auditor] HOOK NOT RUNNING: CLAUDE_PLUGIN_ROOT is unset — could not locate the plugin; the audit is not running.\" >> \"$dir/hook.log\" 2>/dev/null || true; exit 0; fi; \"${CLAUDE_PLUGIN_ROOT}\"/scripts/hook-audit.sh"
           },
           {
             "type": "command",
-            "command": "if [ -z \"${CLAUDE_PLUGIN_ROOT}\" ]; then exit 0; fi; \"${CLAUDE_PLUGIN_ROOT}\"/scripts/hook-self-audit.sh"
+            "command": "if [ -z \"${CLAUDE_PLUGIN_ROOT}\" ]; then dir=\"${XDG_CACHE_HOME:-$HOME/.cache}/code-auditor/logs\"; mkdir -p \"$dir\" 2>/dev/null || true; echo \"[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [code-auditor] HOOK NOT RUNNING: CLAUDE_PLUGIN_ROOT is unset — could not locate the plugin; the self-audit is not running.\" >> \"$dir/hook.log\" 2>/dev/null || true; exit 0; fi; \"${CLAUDE_PLUGIN_ROOT}\"/scripts/hook-self-audit.sh"
           }
         ]
       }

package/plugin/scripts/hook-audit.sh

@@ -16,8 +16,11 @@
 #   failure surfaces on the next explicit audit, never on the edit.
 set -euo pipefail
 
-# Shared resolver + compatibility pinning (see hook-common.sh).
-. "${CLAUDE_PLUGIN_ROOT}/scripts/hook-common.sh"
+# Shared resolver + compatibility pinning (see hook-common.sh). Source it from
+# this script's own directory — the plugin's scripts/ — never from a host
+# environment variable.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+. "${SCRIPT_DIR}/hook-common.sh"
 
 # Read event JSON from stdin
 event="$(cat)"
@@ -89,6 +92,15 @@ fi
 exit_code=$?
 set -e
 
+# A completed run — clean (0) or finding (2) — is the positive "the hook is
+# alive and enqueueing" signal. Write it so the explicit-audit reader
+# (src/hookLog.ts) can clear a prior HOOK NOT RUNNING condition: the reader
+# resolves a condition by newest-record order, and without this line a hook that
+# recovered would leave the stale condition live forever.
+if [ "${exit_code}" -eq 0 ] || [ "${exit_code}" -eq 2 ]; then
+  hook_log "[code-auditor] HOOK RAN"
+fi
+
 # Exit 2 = a finding read from the daemon cache; propagate so Claude Code feeds
 # stdout back.
 if [ ${exit_code} -eq 2 ]; then

package/plugin/scripts/hook-common.sh

@@ -1,9 +1,12 @@
 #!/usr/bin/env bash
 # Shared helpers for the code-auditor PostToolUse hooks.
 #
-# Sourced by hook-audit.sh and hook-self-audit.sh. CLAUDE_PLUGIN_ROOT is
-# guaranteed set before either hook runs (the hooks.json guard exits 1 when it
-# is unset).
+# Sourced by hook-audit.sh, hook-self-audit.sh, hook-warm.sh, and
+# hook-drift-check.sh. The plugin root is derived from where THIS file lives —
+# `<plugin>/scripts/hook-common.sh`, so the root is its grand-parent — never
+# from a host environment variable. `CLAUDE_PLUGIN_ROOT` is honored only as a
+# validated override (see plugin_root below), so an unset or wrong value can
+# never decide whether the tool runs.
 #
 # Two rules enforced here are the fix for "the hook died quietly" (three times:
 # unset CLAUDE_PLUGIN_ROOT, a stale global binary, a removed CLI flag):
@@ -30,6 +33,32 @@
 #
 # The sourcing hook runs with `set -euo pipefail`.
 
+# plugin_root — the plugin's install root.
+#
+# This file ships at `<plugin>/scripts/hook-common.sh`, so the plugin root is the
+# grand-parent of its own location. That fixed, known-at-build-time offset is the
+# single source of truth: every path a hook needs (the manifest, the bundled CLI
+# sibling) is derived from here, not read from a host variable that may be unset.
+# `CLAUDE_PLUGIN_ROOT` is honored only when it actually points at a plugin — it
+# must contain this same `scripts/hook-common.sh` — so a stale or wrong value
+# never shadows the real location, and an absent one is a non-event.
+plugin_root() {
+  local here root
+  here="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+  root="$(dirname "${here}")"
+  if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/scripts/hook-common.sh" ]; then
+    printf '%s' "${CLAUDE_PLUGIN_ROOT}"
+    return
+  fi
+  printf '%s' "${root}"
+}
+
+# The hook-log path tail + file name are single-sourced in hook-log-path.sh,
+# generated by scripts/write-hook-log-path.mjs from the same source as
+# src/hookLogPath.generated.ts (the reader's copy). Sourced here so the write
+# half and the read half (src/hookLog.ts) can never drift apart.
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)/hook-log-path.sh"
+
 # hook_log_dir / hook_log_file / hook_log — the hook's diagnostic log.
 #
 # The PostToolUse hook must never write stderr: the host may block on stderr
@@ -38,10 +67,10 @@
 # still exits 0. A broken install therefore surfaces on the next explicit audit
 # (and in this log), never on the edit itself.
 hook_log_dir() {
-  printf '%s' "${XDG_CACHE_HOME:-$HOME/.cache}/code-auditor/logs"
+  printf '%s' "${XDG_CACHE_HOME:-$HOME/.cache}/${HOOK_LOG_DIR_TAIL}"
 }
 hook_log_file() {
-  printf '%s' "$(hook_log_dir)/hook.log"
+  printf '%s' "$(hook_log_dir)/${HOOK_LOG_FILE}"
 }
 hook_log() {
   mkdir -p "$(hook_log_dir)" 2>/dev/null || return 0
@@ -55,7 +84,7 @@ hook_log() {
 # manifest version. A stale candidate is warned about and skipped, so a mismatched
 # binary no longer turns the hook into a hard failure.
 #
-# 1. The plugin's bundled CLI (`${CLAUDE_PLUGIN_ROOT}/../dist/cli.js` ships in the
+# 1. The plugin's bundled CLI (`$(plugin_root)/../dist/cli.js` ships in the
 #    same npm package, so it usually matches) — but a marketplace checkout has no
 #    npm-paired dist/, and a locally built one can be stale, so it is
 #    version-checked like everything else.
@@ -66,9 +95,10 @@ hook_log() {
 # 3. Project-local install (consumer project's own node_modules) — if compatible.
 # 4. Global install / PATH — if compatible.
 resolve_code_audit() {
-  local candidate
-  if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/../dist/cli.js" ]; then
-    candidate="${CLAUDE_PLUGIN_ROOT}/../dist/cli.js"
+  local candidate root
+  root="$(plugin_root)"
+  if [ -f "${root}/../dist/cli.js" ]; then
+    candidate="${root}/../dist/cli.js"
     if cli_is_compatible "${candidate}"; then
       echo "${candidate}"
       return
@@ -165,7 +195,7 @@ plugin_version() {
     return
   fi
   __CODE_AUDITOR_PLUGIN_VERSION="$(
-    node -e "const fs=require('fs');const p=process.env.CLAUDE_PLUGIN_ROOT;for(const f of [p+'/.claude-plugin/plugin.json', p+'/plugin.json']){try{const v=JSON.parse(fs.readFileSync(f,'utf8')).version;if(v){process.stdout.write(v);break}}catch(e){}}" 2>/dev/null
+    node -e 'const fs=require("fs");const p=process.argv[1];for(const f of [p+"/.claude-plugin/plugin.json", p+"/plugin.json"]){try{const v=JSON.parse(fs.readFileSync(f,"utf8")).version;if(v){process.stdout.write(v);break}}catch(e){}}' "$(plugin_root)" 2>/dev/null
   )"
   __CODE_AUDITOR_PLUGIN_VERSION_RESOLVED=1
   printf '%s' "${__CODE_AUDITOR_PLUGIN_VERSION}"
@@ -220,7 +250,7 @@ assert_compatible() {
   # bundled sibling, a project-local install, a global on PATH) are NOT
   # path-guaranteed — the resolver's `cli_is_compatible` already version-checked
   # them, and the full check below remains the loud backstop for any of them.
-  if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ "${bin}" = "$(pin_dir)/node_modules/.bin/code-audit" ]; then
+  if [ "${bin}" = "$(pin_dir)/node_modules/.bin/code-audit" ]; then
     return 0
   fi
   pv="$(plugin_version)"

package/plugin/scripts/hook-drift-check.sh

@@ -18,20 +18,30 @@
 # single source of truth; the fix is to reinstall (or restore the file).
 set -uo pipefail
 
-# The hooks.json command already guards an unset CLAUDE_PLUGIN_ROOT, but keep
-# this a no-op if it is somehow absent here.
-[ -n "${CLAUDE_PLUGIN_ROOT:-}" ] || exit 0
+# Source the shared resolver from this script's own directory — the plugin's
+# scripts/ — never from a host environment variable. plugin_root() self-locates
+# the plugin root, so an unset or wrong CLAUDE_PLUGIN_ROOT is a non-event.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+. "${SCRIPT_DIR}/hook-common.sh"
+
+ROOT="$(plugin_root)"
 
 # The manifest ships at .claude-plugin/manifest.json; a few installs flatten the
 # plugin.json to the plugin root, so check both locations (mirrors
 # hook-common.sh's plugin_version).
 manifest=""
-for f in "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/manifest.json" "${CLAUDE_PLUGIN_ROOT}/manifest.json"; do
+for f in "${ROOT}/.claude-plugin/manifest.json" "${ROOT}/manifest.json"; do
   if [ -f "$f" ]; then manifest="$f"; break; fi
 done
-[ -n "${manifest}" ] || exit 0
+if [ -z "${manifest}" ]; then
+  # No manifest to compare against is still a completed run — the drift check
+  # never exits non-zero, so write the success record that resolves a prior
+  # HOOK NOT RUNNING condition before the no-op exit.
+  hook_log "[code-auditor] HOOK RAN"
+  exit 0
+fi
 
-MANIFEST_PATH="${manifest}" PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}" node <<'NODE'
+MANIFEST_PATH="${manifest}" PLUGIN_ROOT="${ROOT}" node <<'NODE'
 const fs = require('fs');
 const crypto = require('crypto');
 const path = require('path');
@@ -69,4 +79,7 @@ if (problems.length > 0) {
 }
 NODE
 
+# A completed run (drift found or not) resolves a prior HOOK NOT RUNNING
+# condition — the drift check never exits non-zero.
+hook_log "[code-auditor] HOOK RAN"
 exit 0

package/plugin/scripts/hook-log-path.sh

@@ -0,0 +1,7 @@
+# @generated — do not edit. Written by `scripts/write-hook-log-path.mjs`.
+#
+# Single source of truth for the hook-log path, shared by the TS reader
+# (src/hookLog.ts) and the bash writer (plugin/scripts/hook-common.sh).
+# Regenerate with `npm run build:hooklog`.
+HOOK_LOG_DIR_TAIL='code-auditor/logs'
+HOOK_LOG_FILE='hook.log'

package/plugin/scripts/hook-self-audit.sh

@@ -20,8 +20,11 @@
 #   the log file, not stderr, and still exits 0 (Spec 68 §hook-contract).
 set -euo pipefail
 
-# Shared resolver + compatibility pinning (see hook-common.sh).
-. "${CLAUDE_PLUGIN_ROOT}/scripts/hook-common.sh"
+# Shared resolver + compatibility pinning (see hook-common.sh). Source it from
+# this script's own directory — the plugin's scripts/ — never from a host
+# environment variable.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+. "${SCRIPT_DIR}/hook-common.sh"
 
 # Read event JSON from stdin
 event="$(cat)"
@@ -89,6 +92,15 @@ fi
 exit_code=$?
 set -e
 
+# A completed run — clean (0) or finding (2) — is the positive "the hook is
+# alive" signal, mirroring hook-audit.sh. Write it so the reader (src/hookLog.ts)
+# can clear a prior HOOK NOT RUNNING condition: the reader resolves by
+# newest-record order, and without this line a recovered hook would leave the
+# stale condition live forever.
+if [ "${exit_code}" -eq 0 ] || [ "${exit_code}" -eq 2 ]; then
+  hook_log "[code-auditor] HOOK RAN"
+fi
+
 # Exit 2 = a blocking self-audit finding; propagate so Claude Code feeds it back.
 if [ ${exit_code} -eq 2 ]; then
   exit 2

package/plugin/scripts/hook-warm.sh

@@ -17,28 +17,33 @@
 # at all — a warm session must not re-check on every launch.
 set -uo pipefail
 
-# Belt-and-suspenders: the hooks.json command already guards an unset
-# CLAUDE_PLUGIN_ROOT, but keep the warm a no-op if it is somehow absent here.
-[ -n "${CLAUDE_PLUGIN_ROOT:-}" ] || exit 0
-
-# Shared version lookup (plugin_version / semver_of / pin_dir).
-. "${CLAUDE_PLUGIN_ROOT}/scripts/hook-common.sh"
+# Source the shared resolver from this script's own directory — the plugin's
+# scripts/ — never from a host environment variable. plugin_root() self-locates
+# the plugin root, so an unset or wrong CLAUDE_PLUGIN_ROOT is a non-event.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+. "${SCRIPT_DIR}/hook-common.sh"
 
 # Nothing safe to warm if the manifest version can't be read: warming @latest
 # could pin a different version than resolve_code_audit's fallback would fetch.
 pv="$(plugin_version)"
-[ -n "${pv}" ] || exit 0
 
-dir="$(pin_dir)"
-bin="${dir}/node_modules/.bin/code-audit"
+if [ -n "${pv}" ]; then
+  dir="$(pin_dir)"
+  bin="${dir}/node_modules/.bin/code-audit"
 
-# Already installed — nothing to warm. Re-running npm install here would re-check
-# the registry on every session, which is exactly the cost this hook exists to avoid.
-[ -x "${bin}" ] && exit 0
+  # Already installed — nothing to warm. Re-running npm install here would re-check
+  # the registry on every session, which is exactly the cost this hook exists to avoid.
+  if [ ! -x "${bin}" ]; then
+    # Background the exact install the hook's last-resort path runs. Output to
+    # /dev/null (silent), stdin from /dev/null (don't hold the hook's stdin open),
+    # nohup so the install survives this hook's exit.
+    nohup npm install --prefer-offline --prefix "${dir}" "code-auditor-mcp@${pv}" \
+      --no-audit --no-fund --ignore-scripts --silent >/dev/null 2>&1 </dev/null &
+  fi
+fi
 
-# Background the exact install the hook's last-resort path runs. Output to
-# /dev/null (silent), stdin from /dev/null (don't hold the hook's stdin open),
-# nohup so the install survives this hook's exit.
-nohup npm install --prefer-offline --prefix "${dir}" "code-auditor-mcp@${pv}" \
-  --no-audit --no-fund --ignore-scripts --silent >/dev/null 2>&1 </dev/null &
+# A completed run — the warm hook never exits non-zero, so every path through it
+# is a success — writes the positive record that resolves a prior HOOK NOT RUNNING
+# condition (CLAUDE_PLUGIN_ROOT unset) in the reader (src/hookLog.ts).
+hook_log "[code-auditor] HOOK RAN"
 exit 0