code-auditor-mcp 4.1.0 → 5.0.1

package/plugin/scripts/hook-audit.sh

@@ -5,10 +5,15 @@
 # and runs `code-audit changed --stdin --json` against it.
 #
 # Exit codes:
-#   0 — clean pass
-#   2 — a gating finding was introduced (Claude Code feeds stdout back)
-#   1 — the hook itself broke (binary missing, version mismatch, CLI error) —
-#       reported loudly, never a silent no-op.
+#   0 — clean pass, no fresh result yet (the daemon is seeding/indexing, or
+#       this edit hasn't been re-audited — feedback arrives one edit later), or
+#       a broken tool (the failure is written to the log file, not stderr)
+#   2 — a gating finding was read from the daemon's cache (Claude Code feeds
+#       stdout back)
+#   The hook never exits 1 and never writes stderr: a hook that can fail the
+#   edit is worse than one that reports nothing (Spec 68 §hook-contract). A
+#   broken tool is written to the log file, not stderr, and still exits 0 — a
+#   failure surfaces on the next explicit audit, never on the edit.
 set -euo pipefail
 
 # Shared resolver + compatibility pinning (see hook-common.sh).
@@ -48,31 +53,53 @@ if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -n "${file}" ]; then
   esac
 fi
 
+# Source-file extension scope (Spec 35 item 10). Skip the CLI entirely for an
+# edit to a non-source file (`.md`, `.txt`, `.yml`, …) so a prose edit never pays
+# the discovery + index-sync spin-up. The CLI already exits 0 quietly on a
+# no-auditable-files scope, so this is a fast no-op guard, not a correctness fix —
+# a mismatch in either direction is harmless (an extension listed here that the
+# CLI declines still audits to zero; one missing here just pays one wasted call).
+# The extension set mirrors `getSourceExtensions()` (the language-registry union
+# plus the raw and style-markup extensions the pipeline reads directly); a test in
+# `src/plugin-manifest.spec.ts` pins this list to that function so a newly
+# registered parser surfaces here instead of silently skipping its files.
+case "${file}" in
+  *.ts|*.tsx|*.mts|*.cts|*.js|*.jsx|*.mjs|*.cjs|*.go|*.json|*.css|*.scss|*.sql|*.toml|*.prisma|*.astro|*.vue|*.svelte|*.html) : ;;
+  *) exit 0 ;;
+esac
+
 CODE_AUDIT_BIN="$(resolve_code_audit)"
 
-# Pin the plugin to a compatible CLI version — fail loudly on mismatch.
-assert_compatible "${CODE_AUDIT_BIN}" || exit 1
+# Pin the plugin to a compatible CLI version. On mismatch the message goes to
+# the hook log (a real failure) but the hook still exits 0 — it must never block the edit.
+assert_compatible "${CODE_AUDIT_BIN}" || exit 0
 
-# Run diff-scoped audit on the changed file. stdout/stderr feed back to the agent.
+# Run the diff-scoped gate in hook mode. CODE_AUDITOR_HOOK=1 tells the CLI:
+# enqueue (start the daemon if absent), read a fresh result from the daemon's
+# cache when it has one, and never run an in-process audit — so a successful
+# edit produces zero bytes on stderr and returns in tens of milliseconds. Any
+# stderr the CLI still emits is routed to the hook log, never to the host.
+mkdir -p "$(hook_log_dir)" 2>/dev/null || true
 set +e
 if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
-  echo "${file}" | ${CODE_AUDIT_BIN} changed --stdin --json -p "${CLAUDE_PROJECT_DIR}"
+  echo "${file}" | CODE_AUDITOR_HOOK=1 ${CODE_AUDIT_BIN} changed --stdin --json -p "${CLAUDE_PROJECT_DIR}" 2>>"$(hook_log_file)"
 else
-  echo "${file}" | ${CODE_AUDIT_BIN} changed --stdin --json
+  echo "${file}" | CODE_AUDITOR_HOOK=1 ${CODE_AUDIT_BIN} changed --stdin --json 2>>"$(hook_log_file)"
 fi
 exit_code=$?
 set -e
 
-# Exit 2 = a finding blocked the edit; propagate so Claude Code feeds it back.
+# Exit 2 = a finding read from the daemon cache; propagate so Claude Code feeds
+# stdout back.
 if [ ${exit_code} -eq 2 ]; then
   exit 2
 fi
 
-# Any other non-zero exit is the hook breaking, not a clean pass. Report loudly
-# and fail — a silent no-op here is exactly the failure mode this guards.
+# Any other non-zero exit is a broken tool, not a clean pass. Report it to the
+# log file (a real failure) but exit 0 — failing the edit is worse than silence.
 if [ ${exit_code} -ne 0 ]; then
-  echo "[code-auditor] HOOK BROKEN: code-audit exited ${exit_code} (neither clean nor a finding). Fix the install — do not treat this as a clean pass." >&2
-  exit 1
+  hook_log "[code-auditor] HOOK BROKEN: code-audit exited ${exit_code} (neither clean nor a finding). Fix the install — do not treat this as a clean pass."
+  exit 0
 fi
 
 exit 0

package/plugin/scripts/hook-common.sh

@@ -30,6 +30,24 @@
 #
 # The sourcing hook runs with `set -euo pipefail`.
 
+# 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
+# content, so a single warning could block the edit. Every diagnostic — info,
+# warnings, and failures alike — goes to this log file instead, and the hook
+# 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"
+}
+hook_log_file() {
+  printf '%s' "$(hook_log_dir)/hook.log"
+}
+hook_log() {
+  mkdir -p "$(hook_log_dir)" 2>/dev/null || return 0
+  printf '%s\n' "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] $*" >> "$(hook_log_file)" 2>/dev/null || true
+}
+
 # resolve_code_audit — emit the CLI invocation to use.
 #
 # Resolution is version-aware: EVERY candidate — bundled sibling, pinned install,
@@ -133,8 +151,24 @@ resolve_pinned_bin() {
 #
 # The manifest lives at .claude-plugin/plugin.json (this plugin's convention),
 # but a few installs flatten it to plugin.json at the plugin root, so check both.
+#
+# Memoized: the value is read once per hook invocation and cached. Three call
+# sites (pin_dir, cli_is_compatible, assert_compatible) each re-read the same
+# manifest, and each re-read is a fresh `node` spawn (~55ms) on the per-edit hot
+# path. The memo collapses those into one spawn; the manifest cannot change
+# mid-hook, so the cache is exact, not a heuristic.
+__CODE_AUDITOR_PLUGIN_VERSION=""
+__CODE_AUDITOR_PLUGIN_VERSION_RESOLVED=0
 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
+  if [ "${__CODE_AUDITOR_PLUGIN_VERSION_RESOLVED}" = "1" ]; then
+    printf '%s' "${__CODE_AUDITOR_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
+  )"
+  __CODE_AUDITOR_PLUGIN_VERSION_RESOLVED=1
+  printf '%s' "${__CODE_AUDITOR_PLUGIN_VERSION}"
 }
 
 # semver_of <version-string> — the leading X.Y.Z (with optional -prerelease) in a
@@ -156,13 +190,13 @@ cli_is_compatible() {
   [ -n "${pv_sem}" ] && [ -n "${cv_sem}" ] && [ "${pv_sem}" = "${cv_sem}" ]
 }
 
-# warn_stale <cmd> — one stderr line naming a stale installed CLI, so the user
+# warn_stale <cmd> — one log line naming a stale installed CLI, so the user
 # knows why the hook is paying the pinned install and how to restore the fast path.
 warn_stale() {
   local cmd="$1" cv pv
   pv="$(semver_of "$(plugin_version)")"
   cv="$(semver_of "$($cmd --version 2>/dev/null || true)")"
-  echo "[code-auditor] warn: ${cmd} is ${cv:-unidentified} but this plugin needs ${pv:-its version} — using the pinned install instead; update the install to restore the fast path" >&2
+  hook_log "[code-auditor] warn: ${cmd} is ${cv:-unidentified} but this plugin needs ${pv:-its version} — using the pinned install instead; update the install to restore the fast path"
 }
 
 # assert_compatible <bin> — pin the plugin to a compatible CLI.
@@ -178,16 +212,27 @@ warn_stale() {
 # determined — an unidentified binary is never trusted.
 assert_compatible() {
   local bin="$1" pv cv pv_sem cv_sem
+  # The pinned install's version is guaranteed by its path: `pin_dir` encodes
+  # `plugin_version`, and `resolve_pinned_bin` installs exactly
+  # `code-auditor-mcp@<that version>` there. A `--version` round-trip on it is a
+  # full CLI process spawn (~165ms) that re-proves what the path already states,
+  # so it is skipped on the per-edit hot path. Non-pinned candidates (the
+  # 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
+    return 0
+  fi
   pv="$(plugin_version)"
   cv="$($bin --version 2>/dev/null || true)"
   pv_sem="$(semver_of "${pv}")"
   cv_sem="$(semver_of "${cv}")"
   if [ -z "${pv_sem}" ] || [ -z "${cv_sem}" ]; then
-    echo "[code-auditor] HOOK BROKEN: cannot verify CLI version (plugin='${pv}' cli='${cv}') — refusing to run an unidentified binary" >&2
+    hook_log "[code-auditor] HOOK BROKEN: cannot verify CLI version (plugin='${pv}' cli='${cv}') — refusing to run an unidentified binary"
     return 1
   fi
   if [ "${pv_sem}" != "${cv_sem}" ]; then
-    echo "[code-auditor] version mismatch: plugin ${pv_sem} vs CLI ${cv_sem} — pin the CLI to the plugin version" >&2
+    hook_log "[code-auditor] version mismatch: plugin ${pv_sem} vs CLI ${cv_sem} — pin the CLI to the plugin version"
     return 1
   fi
   return 0

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

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# code-auditor SessionStart hook — detect installed-plugin drift against the
+# shipped manifest.
+#
+# Board row 7: the installed plugin and the source tree drifted silently in both
+# directions (the installed hook-audit.sh gained a scoping block the source
+# lacked, while the installed plugin.json/SKILL.md sat a version behind). This
+# hook closes the detection gap: at session start it re-hashes every installed
+# plugin file and compares each against the `manifest.json` shipped in the same
+# package (generated by `scripts/build-manifest.mjs` from the source tree).
+#
+# Deliberately non-blocking and diagnostic, like hook-warm.sh:
+#   - it never fails the session — an install that drifted still works, it just
+#     needs a reinstall, and a startup warning must not block the agent;
+#   - every failure (missing manifest, unreadable file) is a quiet no-op or a
+#     named warning, never an exit-1.
+# A drift mismatch is the signal that the install is no longer the source tree's
+# 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
+
+# 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
+  if [ -f "$f" ]; then manifest="$f"; break; fi
+done
+[ -n "${manifest}" ] || exit 0
+
+MANIFEST_PATH="${manifest}" PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}" node <<'NODE'
+const fs = require('fs');
+const crypto = require('crypto');
+const path = require('path');
+const manifestPath = process.env.MANIFEST_PATH;
+const root = process.env.PLUGIN_ROOT;
+
+let manifest;
+try {
+  manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+} catch {
+  process.exit(0); // unreadable manifest — nothing to compare, stay quiet
+}
+
+const files = manifest.files || {};
+const problems = [];
+for (const [rel, expected] of Object.entries(files)) {
+  const abs = path.join(root, rel);
+  let actual;
+  try {
+    actual = crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
+  } catch {
+    problems.push(`${rel} (missing)`);
+    continue;
+  }
+  if (actual !== expected) problems.push(rel);
+}
+
+if (problems.length > 0) {
+  console.error(
+    `[code-auditor] installed plugin differs from shipped ${manifest.version || '?'} ` +
+    `in ${problems.length} file(s); reinstall the plugin to restore the source tree as ` +
+    `the single source of truth:`
+  );
+  for (const p of problems) console.error(`  - ${p}`);
+}
+NODE
+
+exit 0

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

@@ -13,10 +13,11 @@
 # diff-gate enforces invariant rules on every edit.
 #
 # Exit codes:
-#   0 — clean pass or out of scope
+#   0 — clean pass, out of scope, or a broken tool (the failure is written to
+#       the log file, not stderr)
 #   2 — a blocking self-audit finding (Claude Code feeds stdout back)
-#   1 — the hook itself broke (binary missing, version mismatch, CLI error) —
-#       reported loudly, never a silent no-op.
+#   The hook never exits 1 and never writes stderr: a broken tool is written to
+#   the log file, not stderr, and still exits 0 (Spec 68 §hook-contract).
 set -euo pipefail
 
 # Shared resolver + compatibility pinning (see hook-common.sh).
@@ -71,15 +72,19 @@ esac
 
 CODE_AUDIT_BIN="$(resolve_code_audit)"
 
-# Pin the plugin to a compatible CLI version — fail loudly on mismatch.
-assert_compatible "${CODE_AUDIT_BIN}" || exit 1
+# Pin the plugin to a compatible CLI version. On mismatch the message goes to
+# stderr (a real failure) but the hook still exits 0 — it must never block the edit.
+assert_compatible "${CODE_AUDIT_BIN}" || exit 0
 
-# Run the self-audit on the edited file. stdout/stderr feed back to the agent.
+# Run the self-audit on the edited file. CODE_AUDITOR_HOOK=1 silences info/debug
+# on stderr (they go to the log file), so a successful self-audit is quiet. Any
+# stderr the CLI still emits is routed to the hook log, never to the host.
+mkdir -p "$(hook_log_dir)" 2>/dev/null || true
 set +e
 if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
-  echo "${file_abs}" | ${CODE_AUDIT_BIN} self-audit --stdin --json -p "${CLAUDE_PROJECT_DIR}"
+  echo "${file_abs}" | CODE_AUDITOR_HOOK=1 ${CODE_AUDIT_BIN} self-audit --stdin --json -p "${CLAUDE_PROJECT_DIR}" 2>>"$(hook_log_file)"
 else
-  echo "${file_abs}" | ${CODE_AUDIT_BIN} self-audit --stdin --json
+  echo "${file_abs}" | CODE_AUDITOR_HOOK=1 ${CODE_AUDIT_BIN} self-audit --stdin --json 2>>"$(hook_log_file)"
 fi
 exit_code=$?
 set -e
@@ -89,11 +94,11 @@ if [ ${exit_code} -eq 2 ]; then
   exit 2
 fi
 
-# Any other non-zero exit is the hook breaking, not a clean pass. Report loudly
-# and fail — a silent no-op here is exactly the failure mode this guards.
+# Any other non-zero exit is a broken tool, not a clean pass. Report it to the
+# log file (a real failure) but exit 0 — failing the edit is worse than silence.
 if [ ${exit_code} -ne 0 ]; then
-  echo "[code-auditor] HOOK BROKEN: self-audit exited ${exit_code} (neither clean nor a finding). Fix the install — do not treat this as a clean pass." >&2
-  exit 1
+  hook_log "[code-auditor] HOOK BROKEN: self-audit exited ${exit_code} (neither clean nor a finding). Fix the install — do not treat this as a clean pass."
+  exit 0
 fi
 
 exit 0

package/plugin/skills/code-auditor/SKILL.md

@@ -5,7 +5,7 @@ description: Audit code quality, search the codebase semantically, enforce invar
 
 # Code Auditor Skill
 
-> **Version 4.1.0** • Run `code-audit --version` to check your installed version.
+> **Version 5.0.1** • Run `code-audit --version` to check your installed version.
 > If versions differ, the CLI is authoritative — use `code-audit <command> --help` to see what your install actually supports.
 
 You have the `code-audit` CLI available. It indexes every function, component, and struct in the codebase for semantic search and invariant enforcement. Use these commands instead of raw grep/find whenever possible.

package/server.json

@@ -6,13 +6,13 @@
     "url": "https://github.com/BenAHammond/code-auditor-mcp",
     "source": "github"
   },
-  "version": "4.1.0",
+  "version": "5.0.1",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "code-auditor-mcp",
-      "version": "4.1.0",
+      "version": "5.0.1",
       "transport": {
         "type": "stdio"
       }