@compr/opscontext-mcp 2.8.3 → 2.9.0

package/dist/cli.js

@@ -651,7 +651,8 @@ import { listLearnings, parseSince, learningsToChunks, learningsStats, formatLea
 import { saveSession, loadSession, listSessions, deleteSession, formatSession, formatSessionList, } from "./sessions.js";
 import { activate, deactivate, getActivationStatus, gateCheck, } from "./activation.js";
 import { syncTierA, syncTierB, loadCommunityStore, communityRulesToChunks, mergeWithDedup, STORE_PATH as COMMUNITY_STORE_PATH, } from "./community-sync.js";
-import { readAuditLog, verifyChain, filterByRange, toCsv, rotateAuditLog, planRotation, listSegments, acknowledgeRedaction, } from "./audit.js";
+import { readAuditLog, verifyChain, filterByRange, toCsv, rotateAuditLog, planRotation, listSegments, acknowledgeRedaction, restoreSegment, scrubAuditLog, } from "./audit.js";
+import { redactPayload } from "./secret-shapes.js";
 import { loadRepoPolicy, parsePolicy, formatPolicySummary, formatValidationErrors, repoPolicyPath, } from "./policy.js";
 import { buildCostReport } from "./cost-report.js";
 import { getStagedFiles, runSecretScan, runDocCoverage, runCommitMessageRequired, runRuleParity, formatSecretViolations, formatDocCoverageViolations, formatSecretViolationsJson, formatDocCoverageViolationsJson, formatCommitMessageViolations, formatCommitMessageViolationsJson, formatRuleParityViolations, formatRuleParityViolationsJson, } from "./hooks.js";
@@ -1996,6 +1997,68 @@ function cliAuditRotate(args) {
         process.exit(2);
     }
 }
+/** Remove credentials from records already written. [LOCK] [SCRUB-IS-ACKNOWLEDGED-REDACTION] */
+function cliAuditScrub(args) {
+    const reasonAt = args.indexOf("--reason");
+    const reason = reasonAt >= 0 ? args[reasonAt + 1] ?? "" : "";
+    const apply = args.includes("--apply");
+    const r = scrubAuditLog({ apply, reason, redact: redactPayload, actor: "cli" });
+    if (r.refusedReason) {
+        console.error(`\nNot scrubbed: ${r.refusedReason}\n`);
+        process.exit(1);
+    }
+    const hit = r.files.filter((f) => f.redacted > 0);
+    console.log(`\nAudit scrub${apply ? "" : ", DRY RUN, nothing written"}\n`);
+    console.log(`  records to redact  ${r.redactedRecords}${apply ? " (redacted)" : ""}, in ${hit.length} of ${r.files.length} file(s)`);
+    for (const [id, n] of Object.entries(r.counts).sort((a, b) => b[1] - a[1])) {
+        console.log(`    ${id.padEnd(24)} ${n}`);
+    }
+    if (!apply) {
+        if (r.redactedRecords > 0)
+            console.log(`\n  Run again with --apply --reason "<why>" to rewrite them and acknowledge it on the chain.\n`);
+        return;
+    }
+    console.log(`  acknowledged by    ${r.acknowledgements.length} audit.redact record(s)`);
+    const after = verifyChain();
+    console.log(`\n  audit-verify now: ${after.ok ? "OK" : "FAILED"}, ${after.total} record(s), ` +
+        `${(after.redactedIndices ?? []).length} redacted and acknowledged, ${(after.tamperedIndices ?? []).length} altered.\n`);
+    if (!after.ok)
+        process.exit(2);
+}
+/** Put a lost block of audit records back from a backup. [LOCK] [RESTORE-ONLY-CLOSES-A-PROVEN-GAP] */
+function cliAuditRestore(args) {
+    const reasonAt = args.indexOf("--reason");
+    const reason = reasonAt >= 0 ? args[reasonAt + 1] ?? "" : "";
+    const apply = args.includes("--apply");
+    const file = args.find((a, i) => !a.startsWith("--") && !(reasonAt >= 0 && i === reasonAt + 1));
+    if (!file) {
+        console.error(`usage: contextengine audit-restore <file.jsonl> [--apply --reason "<where the records came from and why>"]`);
+        console.error(`   Without --apply it only checks the file and says what it would do.`);
+        process.exit(1);
+    }
+    const r = restoreSegment(resolve(file), { apply, reason, actor: "cli" });
+    if (r.refusedReason) {
+        console.error(`\nNot restored: ${r.refusedReason}\n`);
+        process.exit(1);
+    }
+    console.log(`\nAudit restore${apply ? "" : ", DRY RUN, nothing written"}\n`);
+    console.log(`  block             ${r.records} record(s), ${r.firstTs} to ${r.lastTs}`);
+    console.log(`  every record      matches its own hash`);
+    console.log(`  fits between      ${r.after} and ${r.before}`);
+    console.log(`  closes            the orphan at index ${r.orphanIndex}`);
+    if (!apply) {
+        console.log(`  would write       audit-archive/${r.segmentFile}`);
+        console.log(`\n  Run again with --apply --reason "<where the records came from and why>" to write it.\n`);
+        return;
+    }
+    console.log(`  wrote             audit-archive/${r.segmentFile}`);
+    console.log(`  recorded as       audit.restore, hash ${r.record.hash.slice(0, 16)}...`);
+    const after = verifyChain();
+    console.log(`\n  audit-verify now: ${after.ok ? "OK" : "FAILED"}, ${after.total} record(s), ` +
+        `${(after.orphanIndices ?? []).length} orphan(s), ${(after.tamperedIndices ?? []).length} altered.\n`);
+    if (!after.ok)
+        process.exit(2);
+}
 /** Acknowledge deliberately redacted audit records on the chain. [LOCK] [REDACTION-IS-A-CHAINED-RECORD] */
 function cliAuditRedactAck(args) {
     const idxAt = args.indexOf("--index");
@@ -2058,6 +2121,8 @@ async function cliAuditVerify() {
         console.error(`\n   Orphaned records (parent hash absent from the log):`);
         console.error(`     ${o.slice(0, 10).join(", ")}${o.length > 10 ? `, … (+${o.length - 10} more)` : ""}`);
         console.error(`   This means earlier records were deleted or the log was truncated.`);
+        console.error(`   If a backup holds the missing records, 'contextengine audit-restore <file>' checks`);
+        console.error(`   that they fill this gap exactly, and puts them back with --apply.`);
     }
     if (forks.length > 0) {
         console.error(`\n   (Also ${forks.length} concurrent-append fork(s) — benign, see docs.)`);
@@ -2552,6 +2617,14 @@ Usage:
                                        the size ceiling (default 50000 live records),
                                        whichever is more. The chain stays linear: segments
                                        are part of the verified history, never deleted.
+  contextengine audit-restore <file> [--apply --reason "..."]
+                                       Put a lost block of records back from a backup. Only
+                                       fills a gap audit-verify reports, at a segment boundary,
+                                       after checking every record's hash. Dry run by default.
+  contextengine audit-scrub [--apply --reason "..."]
+                                       Remove credentials (keys, tokens, passwords in commands
+                                       and URLs) from captured records already written, and
+                                       acknowledge each rewrite on the chain. Dry run by default.
   contextengine cost [--session ID] [--project NAME] [--run wf_ID] [--days N] [--top N] [--json]
                                        Multi-agent spend from Claude Code transcripts. Always prints
                                        VOLUME (tokens), VALUED COST (API list prices — notional on a
@@ -2757,6 +2830,12 @@ else if (command === "audit-redact-ack") {
 else if (command === "audit-rotate") {
     cliAuditRotate(process.argv.slice(3));
 }
+else if (command === "audit-restore") {
+    cliAuditRestore(process.argv.slice(3));
+}
+else if (command === "audit-scrub") {
+    cliAuditScrub(process.argv.slice(3));
+}
 else if (command === "servers") {
     const fleet = listServers();
     const health = computeFleetHealth({ version: readPackageVersion(), report: fleet });

package/dist/detector.js

@@ -79,7 +79,9 @@ function stableStringify(v) {
 }
 function getText(r) {
     const p = r.payload || {};
-    return String(p.text ?? p.preview ?? p.args_preview ?? "");
+    // A prompt kept as a fingerprint only ([PROMPT-TEXT-IS-NOT-KEPT]) compares as one token: equal
+    // for an exact repeat, different otherwise.
+    return String(p.text ?? p.text_fingerprint ?? p.preview ?? p.args_preview ?? "");
 }
 function sessionKey(r) {
     const p = r.payload || {};
@@ -120,7 +122,7 @@ function detectLoop(events) {
             }
         }
         if (dupes >= 2) {
-            const snippet = getText(prompts[i]).slice(0, 80);
+            const snippet = typeof prompts[i].payload?.text === "string" ? getText(prompts[i]).slice(0, 80) : "(prompt text not kept)";
             return mk("loop", "warn", `Same prompt sent ${dupes + 1}× in 5 min`, matches, { repetitions: dupes + 1, snippet });
         }
     }
@@ -188,7 +190,9 @@ function detectFabrication(events, cwd) {
 function detectDrift(events) {
     // Per-session: if the last 3 prompts are jointly far (low overlap) from
     // the session's FIRST prompt, the conversation has drifted off-topic.
-    const bySession = groupBy(events.filter((e) => e.event === "browser.prompt" || e.event === "vscode.prompt_submit"), sessionKey);
+    // Word overlap needs words: prompts kept as a fingerprint only are left out, or every session
+    // would read as drifted. [LOCK] [PROMPT-TEXT-IS-NOT-KEPT]
+    const bySession = groupBy(events.filter((e) => (e.event === "browser.prompt" || e.event === "vscode.prompt_submit") && typeof e.payload?.text === "string"), sessionKey);
     for (const [sid, prompts] of bySession) {
         if (prompts.length < 4)
             continue;

package/dist/fleet-health.d.ts

@@ -23,7 +23,16 @@ export interface FleetHealth {
         /** Above this many writes per hour a warning is raised. */
         threshold: number;
     };
+    /** Claude Code hook registrations per event, read from ~/.claude/settings.json the way the
+     *  installer counts them (paths expanded). null: no readable settings.json. A correct install
+     *  has 1 for every event; the 2026-09-06 doubling would have shown 2 here within a minute. */
+    claudeHooks: Record<string, number> | null;
     today: {
+        /** Claude Code hook events (vscode.*) since local midnight. */
+        hookEvents: number;
+        /** Of those, records identical in event and payload to the previous hook event within
+         *  DOUBLED_WINDOW_MS: what a hook registered twice produces. */
+        doubledHookEvents: number;
         /** Pre-commit blocks (hook.block) since local midnight. */
         blocks: number;
         /** Store refusals (unreadable, shrink refused, growth refused) since local midnight. */
@@ -42,6 +51,11 @@ export interface FleetHealth {
     warnings: string[];
 }
 export declare const REINDEX_PER_HOUR_WARN = 30;
+/** Doubled hook events above this share of the day's hook events raise a warning, once the day
+ *  has at least DOUBLED_MIN_EVENTS of them (a single repeated call is not a doubled hook). */
+export declare const DOUBLED_HOOK_EVENTS_WARN_PCT = 5;
+export declare const DOUBLED_MIN_EVENTS = 10;
+export declare const DOUBLED_WINDOW_MS = 2000;
 export declare function fleetHealthPath(): string;
 /** The highest version with a verify-release marker; version order, not file time (ties). */
 export declare function lastVerifiedRelease(dir?: string): string | null;
@@ -50,6 +64,7 @@ export declare function computeFleetHealth(opts?: {
     version?: string;
     auditPath?: string;
     report?: ServerReport;
+    settingsPath?: string;
 }): FleetHealth;
 /** Temp file + rename: a reader never sees half a file. */
 export declare function writeFleetHealth(h: FleetHealth): string;

package/dist/fleet-health.js

@@ -13,7 +13,13 @@ import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readSync, readdi
 import { join } from "path";
 import { homedir } from "os";
 import { listServers } from "./server-registry.js";
+import { claudeHookRegistrations } from "./install-claude-hook.js";
 export const REINDEX_PER_HOUR_WARN = 30;
+/** Doubled hook events above this share of the day's hook events raise a warning, once the day
+ *  has at least DOUBLED_MIN_EVENTS of them (a single repeated call is not a doubled hook). */
+export const DOUBLED_HOOK_EVENTS_WARN_PCT = 5;
+export const DOUBLED_MIN_EVENTS = 10;
+export const DOUBLED_WINDOW_MS = 2000;
 const TAIL_BYTES = 8 * 1024 * 1024;
 function ceHome() {
     return process.env.CONTEXTENGINE_HOME || join(homedir(), ".contextengine");
@@ -100,12 +106,20 @@ export function computeFleetHealth(opts = {}) {
     const midnight = localMidnight(now).getTime();
     const hourAgo = now.getTime() - 3_600_000;
     const perCorpus = {};
-    let lastHourWrites = 0, blocks = 0, refusals = 0, learningsSaved = 0;
+    let lastHourWrites = 0, blocks = 0, refusals = 0, learningsSaved = 0, hookEvents = 0, doubledHookEvents = 0;
     const lastBlocks = [];
+    let prevHook = null;
     for (const r of records) {
         const t = Date.parse(r.ts);
         if (Number.isNaN(t))
             continue;
+        if (r.event.startsWith("vscode.") && t >= midnight) {
+            hookEvents++;
+            const payload = JSON.stringify(r.payload ?? {});
+            if (prevHook && prevHook.event === r.event && prevHook.payload === payload && t - prevHook.t <= DOUBLED_WINDOW_MS)
+                doubledHookEvents++;
+            prevHook = { t, event: r.event, payload };
+        }
         if (r.event === "index.write" && t >= hourAgo) {
             lastHourWrites++;
             const c = String(r.payload?.corpus ?? "?");
@@ -127,9 +141,22 @@ export function computeFleetHealth(opts = {}) {
     const stale = report.servers.filter((s) => s.staleBuild).map((s) => ({ pid: s.pid, version: s.version, build: s.build, cwd: s.cwd }));
     const diskBuild = report.servers.find((s) => s.currentBuild)?.currentBuild ?? null;
     const indexers = report.servers.filter((s) => s.role !== "reader").length;
+    const claudeHooks = claudeHookRegistrations(opts.settingsPath);
     const warnings = [];
     if (stale.length > 0)
         warnings.push(`${stale.length} server(s) on an old build (pid ${stale.map((s) => s.pid).join(", ")}): reload their windows`);
+    if (claudeHooks) {
+        const doubled = Object.entries(claudeHooks).filter(([, n]) => n > 1);
+        if (doubled.length > 0)
+            warnings.push(`Claude Code runs an OpsContext hook more than once (${doubled.map(([ev, n]) => `${ev}=${n}`).join(", ")}): every event reaches the audit log that many times, run install-claude-hook`);
+        const core = ["UserPromptSubmit", "PostToolUse", "SessionStart", "Stop"];
+        const present = core.filter((ev) => (claudeHooks[ev] ?? 0) >= 1);
+        if (present.length > 0 && present.length < core.length)
+            warnings.push(`OpsContext hooks installed for ${present.join(", ")} but not ${core.filter((ev) => !present.includes(ev)).join(", ")}: run install-claude-hook`);
+    }
+    if (hookEvents >= DOUBLED_MIN_EVENTS && doubledHookEvents * 100 > hookEvents * DOUBLED_HOOK_EVENTS_WARN_PCT) {
+        warnings.push(`${doubledHookEvents} of ${hookEvents} Claude Code hook events today arrived twice within ${DOUBLED_WINDOW_MS / 1000} s: a hook is registered twice somewhere, run install-claude-hook`);
+    }
     if (lastHourWrites > REINDEX_PER_HOUR_WARN)
         warnings.push(`${lastHourWrites} shared-index writes in the last hour (ceiling ${REINDEX_PER_HOUR_WARN}): something saves in a loop`);
     if (refusals > 0)
@@ -143,7 +170,8 @@ export function computeFleetHealth(opts = {}) {
         writerPid: process.pid,
         servers: { total: report.servers.length, indexers, readers: report.servers.length - indexers, stale, diskBuild },
         reindex: { lastHourWrites, perCorpus, threshold: REINDEX_PER_HOUR_WARN },
-        today: { blocks, refusals, learningsSaved, lastBlocks: lastBlocks.slice(-3) },
+        claudeHooks,
+        today: { hookEvents, doubledHookEvents, blocks, refusals, learningsSaved, lastBlocks: lastBlocks.slice(-3) },
         lastVerifiedRelease: lastVerifiedRelease(),
         warnings,
     };
@@ -163,6 +191,7 @@ export function formatFleetHealth(h) {
     lines.push(`  servers ${h.servers.total}: ${h.servers.indexers} indexing, ${h.servers.readers} reading, ${h.servers.stale.length} on an old build`);
     lines.push(`  shared-index writes last hour: ${h.reindex.lastHourWrites} (ceiling ${h.reindex.threshold})`);
     lines.push(`  today: ${h.today.blocks} block(s) prevented, ${h.today.refusals} store refusal(s), ${h.today.learningsSaved} learning(s) saved`);
+    lines.push(`  claude code: ${h.today.hookEvents} hook event(s) today, ${h.today.doubledHookEvents} doubled; registrations ${h.claudeHooks ? Object.entries(h.claudeHooks).map(([ev, n]) => `${ev}=${n}`).join(" ") : "no settings.json"}`);
     for (const b of h.today.lastBlocks)
         lines.push(`    ${b.ts.slice(11, 19)}Z ${b.kind}: ${b.detail}`);
     for (const w of h.warnings)

package/dist/http-server.d.ts

@@ -10,6 +10,12 @@ declare function loadSecret(): string | null;
 declare function constantTimeEqual(a: string, b: string): boolean;
 /** Validate an event has the minimum shape we'll write to audit. */
 declare function validateEvent(e: IncomingEvent, idx: number): string | null;
+/**
+ * The payload as it will be written: every string redacted, and the per-shape counts recorded
+ * under `redacted_at_ingest` when anything was removed. The only path from the network to the
+ * log. [LOCK] [CAPTURE-IS-REDACTED-AT-THE-DOOR] (src/secret-shapes.ts)
+ */
+export declare function prepareCapturedPayload(payload: Record<string, unknown>, event?: string): Record<string, unknown>;
 /**
  * Boot the local event-ingest HTTP server. Returns the listening port or null
  * if the port was already in use (caller may decide whether to retry on
@@ -20,6 +26,7 @@ declare function validateEvent(e: IncomingEvent, idx: number): string | null;
 export declare function startEventIngestServer(): Promise<number | null>;
 export declare function stopEventIngestServer(): Promise<void>;
 export declare const _internal: {
+    prepareCapturedPayload: typeof prepareCapturedPayload;
     loadSecret: typeof loadSecret;
     constantTimeEqual: typeof constantTimeEqual;
     validateEvent: typeof validateEvent;

package/dist/http-server.js

@@ -23,6 +23,7 @@ import { join } from "path";
 import { homedir } from "os";
 import { timingSafeEqual } from "crypto";
 import { safeAppend } from "./audit.js";
+import { redactPayload, textFingerprint } from "./secret-shapes.js";
 const PORT = parseInt(process.env.OPSCONTEXT_EVENT_PORT || "7842", 10);
 const HOST = "127.0.0.1";
 const SECRET_FILE = join(homedir(), ".contextengine", "extension-secret");
@@ -73,6 +74,40 @@ function validateEvent(e, idx) {
     }
     return null;
 }
+/**
+ * The payload as it will be written: every string redacted, and the per-shape counts recorded
+ * under `redacted_at_ingest` when anything was removed. The only path from the network to the
+ * log. [LOCK] [CAPTURE-IS-REDACTED-AT-THE-DOOR] (src/secret-shapes.ts)
+ */
+export function prepareCapturedPayload(payload, event) {
+    const { value, counts, changed } = redactPayload(dropPromptText(payload, event));
+    return changed ? { ...value, redacted_at_ingest: counts } : value;
+}
+/**
+ * [LOCKED] [PROMPT-TEXT-IS-NOT-KEPT] - 2026-09-25
+ * [NEVER] write the text of a prompt or an AI response to the audit log by default.
+ * WHY: the owner's decision, 2026-09-25. The text fed one feature, the loop and drift alarm, which
+ *      fired 0 times in three months of real use; meanwhile it held the owner's typed passwords
+ *      and logins. A record of "prompt sent at 10:02, 340 characters" keeps the evidence of
+ *      activity without keeping what was said.
+ * FIX: prompts (vscode.prompt_submit, browser.prompt) and responses (browser.response) keep their
+ *      length and a keyed fingerprint (textFingerprint), so an exact repeat is still detectable.
+ *      Commands and tool input stay, redacted: they are the record of what an agent did.
+ *      OPSCONTEXT_KEEP_PROMPT_TEXT=1 keeps the (redacted) text, for someone who wants it.
+ */
+const PROMPT_TEXT_EVENTS = new Set(["vscode.prompt_submit", "browser.prompt", "browser.response"]);
+function dropPromptText(payload, event) {
+    if (!event || !PROMPT_TEXT_EVENTS.has(event) || process.env.OPSCONTEXT_KEEP_PROMPT_TEXT === "1")
+        return payload;
+    if (typeof payload.text !== "string")
+        return payload;
+    const { text, ...rest } = payload;
+    return {
+        ...rest,
+        char_count: typeof rest.char_count === "number" ? rest.char_count : text.length,
+        text_fingerprint: textFingerprint(text),
+    };
+}
 function sendJson(res, status, body) {
     const json = JSON.stringify(body);
     res.writeHead(status, {
@@ -143,7 +178,8 @@ function handleEvents(req, res) {
         for (const ev of batch.events) {
             const actor = typeof ev.actor === "string" ? ev.actor : "browser-ext";
             // event/payload were validated above — cast is safe.
-            safeAppend(ev.event, ev.payload, actor);
+            // [LOCK] [CAPTURE-IS-REDACTED-AT-THE-DOOR]: redact before the append, never after.
+            safeAppend(ev.event, prepareCapturedPayload(ev.payload, ev.event), actor);
             written++;
         }
         sendJson(res, 200, { ok: true, written });
@@ -233,6 +269,7 @@ export function stopEventIngestServer() {
 // Test helpers (not exported in dist surface in production use — but the
 // module is small enough that tests can import them directly).
 export const _internal = {
+    prepareCapturedPayload,
     loadSecret,
     constantTimeEqual,
     validateEvent,

package/dist/index.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir } from "./config.js";
 import { ingestSources } from "./ingest.js";
+import { redactSecrets } from "./secret-shapes.js";
 import { summarizeSource } from "./source-summary.js";
 import { searchChunks } from "./search.js";
 import { initEmbeddings, embedChunks, embedKeyOf, vectorSearch, isEmbeddingsReady, } from "./embeddings.js";
@@ -152,6 +153,8 @@ async function buildIndex(opts) {
         console.error(`[ContextEngine] 🌐 Injected ${added} community rule chunks ` +
             `(${skipped} dedup'd vs local; ${store.rules.length} total in cache)`);
     }
+    // [LOCK] [INDEX-NEVER-SERVES-A-CREDENTIAL]: before the adapters, whose block can return early.
+    chunks = chunks.map(redactChunk);
     // Collect from plugin adapters
     if (config.adapters && config.adapters.length > 0) {
         if (opts.loadAdapters) {
@@ -161,11 +164,27 @@ async function buildIndex(opts) {
         }
         const adapterChunks = await collectFromAdapters(config.adapters);
         if (adapterChunks.length > 0) {
-            chunks.push(...adapterChunks);
+            chunks.push(...adapterChunks.map(redactChunk));
             console.error(`[ContextEngine] 🔌 Adapters contributed ${adapterChunks.length} chunks`);
         }
     }
 }
+/**
+ * [LOCKED] [INDEX-NEVER-SERVES-A-CREDENTIAL] - 2026-09-25
+ * [NEVER] let a chunk into the index, the shared index file or a search result without passing
+ *         its text through redactSecrets().
+ * WHY: on 2026-09-25 the shared index held database URLs with their passwords (read from dotenv
+ *      files, whose masking skipped the password inside a URL), sshpass and mysql passwords from
+ *      runbooks and memory notes, and Google API keys: 55 sources in all. search_context hands
+ *      chunks to every AI agent that asks, and the index file rides the weekly backup.
+ * FIX: every chunk, whatever collected it (docs, code, ops collectors, learnings, community rules,
+ *      adapters), is redacted with the capture shapes (src/secret-shapes.ts) as the index is built.
+ *      The source files are not touched: cleaning those is the owner's call, file by file.
+ */
+function redactChunk(c) {
+    const r = redactSecrets(c.content);
+    return Object.keys(r.counts).length > 0 ? { ...c, content: r.text } : c;
+}
 /** Load the model once; every caller shares the same promise. */
 function ensureModel() {
     if (!modelInit)

package/dist/install-claude-hook.d.ts

@@ -21,6 +21,11 @@ export declare function dropDuplicateHooks(entries: HookEntry[], ourScripts: str
 };
 /** How many times each event runs `script`. A correct install has exactly 1 everywhere. */
 export declare function countOurHooks(settings: Settings, events: readonly string[], script: string, home?: string): Record<string, number>;
+/** How many times Claude Code runs each OpsContext hook, read from settings.json: the three
+ *  emit events, the Stop gate, and the optional simplicity gate as "PostToolUse(simplicity)".
+ *  null when there is no readable settings.json. Shared by the install verification
+ *  ([INSTALL-VERIFIES-BY-COUNT]) and fleet health, so both count the same way. */
+export declare function claudeHookRegistrations(settingsPath?: string, home?: string): Record<string, number> | null;
 export declare function cliInstallClaudeHook(args: string[]): Promise<void>;
 export declare function cliUninstallClaudeHook(args: string[]): Promise<void>;
 //# sourceMappingURL=install-claude-hook.d.ts.map

package/dist/install-claude-hook.js

@@ -31,6 +31,12 @@ const HOOK_SCRIPT = join(HOOKS_DIR, "opscontext-emit.sh");
 /** The Stop gate: a wrapper that runs `session-gate` with the node and CLI that installed it.
  *  [LOCK] [SESSION-SAVE-IS-A-GATE] (src/session-gate.ts) */
 const GATE_SCRIPT = join(HOOKS_DIR, "opscontext-session-gate.sh");
+/** The simplicity gate: a PostToolUse hook on Edit/Write that reports complexity the edit just
+ *  introduced in a Python file, compared with git HEAD. Optional: `--simplicity`.
+ *  [LOCK] [SIMPLICITY-GATE-SILENT-WHEN-BLIND] (defaults/simplicity-gate.py) */
+const SIMPLICITY_SCRIPT = join(HOOKS_DIR, "opscontext-simplicity-gate.py");
+const SIMPLICITY_MATCHER = "Edit|Write|MultiEdit";
+const OUR_SCRIPTS = [HOOK_SCRIPT, GATE_SCRIPT, SIMPLICITY_SCRIPT];
 const EVENT_KINDS = ["UserPromptSubmit", "PostToolUse", "SessionStart"];
 function readSettings() {
     if (!existsSync(SETTINGS_FILE))
@@ -104,22 +110,59 @@ export function countOurHooks(settings, events, script, home = homedir()) {
     const count = (ev) => (settings.hooks?.[ev] ?? []).flatMap((e) => e.hooks ?? []).filter((h) => hookScriptPath(h.command, home) === script).length;
     return Object.fromEntries(events.map((ev) => [ev, count(ev)]));
 }
-/** Path to the reference hook script bundled with this package. */
-function bundledHookSource() {
-    // dist/install-claude-hook.js → ../defaults/claude-code-hook.sh in dev tree,
-    // or .../node_modules/@compr/opscontext-mcp/defaults/claude-code-hook.sh
+/** How many times Claude Code runs each OpsContext hook, read from settings.json: the three
+ *  emit events, the Stop gate, and the optional simplicity gate as "PostToolUse(simplicity)".
+ *  null when there is no readable settings.json. Shared by the install verification
+ *  ([INSTALL-VERIFIES-BY-COUNT]) and fleet health, so both count the same way. */
+export function claudeHookRegistrations(settingsPath = SETTINGS_FILE, home = homedir()) {
+    let settings;
+    try {
+        if (!existsSync(settingsPath))
+            return null;
+        settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+    const hooksDir = join(home, ".claude", "hooks");
+    const emit = join(hooksDir, "opscontext-emit.sh");
+    return {
+        ...countOurHooks(settings, EVENT_KINDS, emit, home),
+        ...countOurHooks(settings, ["Stop"], join(hooksDir, "opscontext-session-gate.sh"), home),
+        "PostToolUse(simplicity)": countOurHooks(settings, ["PostToolUse"], join(hooksDir, "opscontext-simplicity-gate.py"), home).PostToolUse,
+    };
+}
+/** Path to a file bundled under defaults/ with this package. */
+function bundledFile(name) {
+    // dist/install-claude-hook.js → ../defaults/<name> in dev tree,
+    // or .../node_modules/@compr/opscontext-mcp/defaults/<name>
     // when globally / locally installed via npm. Both follow the same relative
     // shape because npm copies defaults/ via the `files` whitelist.
-    const candidates = [
-        join(__dirname_esm, "..", "defaults", "claude-code-hook.sh"),
-        join(__dirname_esm, "defaults", "claude-code-hook.sh"),
-    ];
+    const candidates = [join(__dirname_esm, "..", "defaults", name), join(__dirname_esm, "defaults", name)];
     for (const c of candidates) {
         if (existsSync(c))
             return c;
     }
     return null;
 }
+/** Where the simplicity gate will find ruff: PATH, then the usual install dirs (the same
+ *  order as the script itself). null when it is nowhere, so the install can say so. */
+function findRuff() {
+    try {
+        const onPath = execSync("command -v ruff 2>/dev/null", { encoding: "utf-8" }).trim();
+        if (onPath)
+            return onPath;
+    }
+    catch {
+        /* not on PATH */
+    }
+    const home = homedir();
+    for (const c of ["/opt/homebrew/bin/ruff", "/usr/local/bin/ruff", join(home, ".local", "bin", "ruff"), join(home, ".cargo", "bin", "ruff")]) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
 /** dist/cli.js of a global install, when there is one (same preference as install-autostart). */
 function globalCliPath() {
     try {
@@ -134,7 +177,7 @@ function globalCliPath() {
 export async function cliInstallClaudeHook(args) {
     const help = args.includes("-h") || args.includes("--help");
     if (help) {
-        console.log(`Usage: opscontext install-claude-hook
+        console.log(`Usage: opscontext install-claude-hook [--simplicity]
 
 Wires OpsContext into Claude Code's hook system so every terminal Claude
 Code session sends prompts + tool calls to the OpsContext audit log.
@@ -145,12 +188,19 @@ Events emitted (all go through the local HTTP endpoint, never the network):
   • SessionStart     → vscode.session_start
   • Stop             → the session gate: a turn cannot end while the repo's CE session
                        is older than the last commit (contextengine session-gate --help)
+  • PostToolUse on Edit|Write|MultiEdit, with --simplicity → the simplicity gate: after an
+                       edit to a Python file, ruff's complexity rules run on the file and on
+                       its git HEAD version; functions the edit made new offenders or worse
+                       are reported back to Claude (exit 2). Pre-existing complexity, files
+                       outside git and a missing ruff are silent. Needs ruff (brew install ruff).
 
 The installer:
   1. Copies the bundled hook script to ~/.claude/hooks/opscontext-emit.sh
-     and writes ~/.claude/hooks/opscontext-session-gate.sh (node + this CLI, absolute paths)
-  2. Splices four entries into ~/.claude/settings.json under "hooks"
-  3. Preserves every existing hook entry (idempotent, safe to re-run)
+     and writes ~/.claude/hooks/opscontext-session-gate.sh (node + this CLI, absolute paths);
+     with --simplicity also ~/.claude/hooks/opscontext-simplicity-gate.py
+  2. Splices four entries (five with --simplicity) into ~/.claude/settings.json under "hooks"
+  3. Preserves every existing hook entry (idempotent, safe to re-run; a re-run without
+     --simplicity keeps an installed simplicity gate and refreshes its script)
 
 A timestamped backup is written next to settings.json before any change.
 
@@ -160,9 +210,10 @@ Run: opscontext install-autostart
 `);
         return;
     }
+    const simplicityAsked = args.includes("--simplicity");
     // Step 1: Install / verify the hook script
     mkdirSync(HOOKS_DIR, { recursive: true });
-    const src = bundledHookSource();
+    const src = bundledFile("claude-code-hook.sh");
     if (!src) {
         console.error(`❌ Could not find bundled hook script defaults/claude-code-hook.sh.`);
         console.error(`   This means the install is incomplete. Reinstall opscontext:`);
@@ -185,7 +236,7 @@ Run: opscontext install-autostart
         const entries = settings.hooks[kind];
         if (!entries)
             continue;
-        const r = dropDuplicateHooks(entries, [HOOK_SCRIPT, GATE_SCRIPT]);
+        const r = dropDuplicateHooks(entries, OUR_SCRIPTS);
         settings.hooks[kind] = r.entries;
         deduped += r.removed;
     }
@@ -227,6 +278,35 @@ Run: opscontext install-autostart
         added++;
     }
     console.log(`✅ Installed session gate: ${GATE_SCRIPT}`);
+    // Step 4: the simplicity gate, when asked for or already there (a plain re-run keeps it and
+    // refreshes its script, so an upgrade reaches it too).
+    const simplicityWired = hookAlreadyWired(settings.hooks.PostToolUse, SIMPLICITY_SCRIPT);
+    const wantSimplicity = simplicityAsked || simplicityWired;
+    if (wantSimplicity) {
+        const gateSrc = bundledFile("simplicity-gate.py");
+        if (!gateSrc) {
+            console.error(`❌ Could not find bundled defaults/simplicity-gate.py. Reinstall opscontext.`);
+            process.exit(1);
+        }
+        copyFileSync(gateSrc, SIMPLICITY_SCRIPT);
+        chmodSync(SIMPLICITY_SCRIPT, 0o755);
+        if (simplicityWired) {
+            skipped++;
+        }
+        else {
+            settings.hooks.PostToolUse.push({
+                matcher: SIMPLICITY_MATCHER,
+                hooks: [{ type: "command", command: SIMPLICITY_SCRIPT, timeout: 30 }],
+            });
+            added++;
+        }
+        console.log(`✅ Installed simplicity gate: ${SIMPLICITY_SCRIPT} (PostToolUse ${SIMPLICITY_MATCHER})`);
+        const ruff = findRuff();
+        if (ruff)
+            console.log(`   ruff: ${ruff}`);
+        else
+            console.log(`⚠️  ruff not found (PATH, /opt/homebrew/bin, /usr/local/bin, ~/.local/bin, ~/.cargo/bin): the gate stays silent until it is installed (brew install ruff, or pipx install ruff).`);
+    }
     writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
     const removedNote = deduped ? `, ${deduped} duplicate registrations removed` : "";
     console.log(`✅ ${added} hook entries added, ${skipped} already present${removedNote}.`);
@@ -236,18 +316,19 @@ Run: opscontext install-autostart
     //      the session that ran it recorded "they were not there"; the doubled audit events then
     //      went unseen for nine days.
     // FIX: re-read settings.json from disk and require exactly one registration per event.
-    const written = readSettings();
-    const counts = {
-        ...countOurHooks(written, EVENT_KINDS, HOOK_SCRIPT),
-        ...countOurHooks(written, ["Stop"], GATE_SCRIPT),
-    };
-    const wrong = Object.entries(counts).filter(([, n]) => n !== 1);
+    const counts = claudeHookRegistrations() ?? {};
+    // Every event exactly once; the optional gate exactly once when wanted, never otherwise (a
+    // dedup pass alone never adds it).
+    const expected = Object.fromEntries(Object.keys(counts).map((ev) => [ev, 1]));
+    expected["PostToolUse(simplicity)"] = wantSimplicity ? 1 : 0;
+    const wrong = Object.entries(counts).filter(([ev, n]) => n !== expected[ev]);
     if (wrong.length > 0) {
         const detail = wrong.map(([ev, n]) => `${ev}=${n}`).join(", ");
         console.error(`❌ settings.json must hold exactly one OpsContext hook per event, found ${detail}. Backup: ${backup || "none"}`);
         process.exit(1);
     }
-    console.log(`✅ Verified in settings.json: exactly one registration for ${Object.keys(counts).join(", ")}.`);
+    const once = Object.keys(expected).filter((ev) => expected[ev] === 1);
+    console.log(`✅ Verified in settings.json: exactly one registration for ${once.join(", ")}.`);
     console.log(``);
     console.log(`Test live:`);
     console.log(`  1. Open a NEW VS Code terminal (settings.json is read at session start).`);
@@ -259,13 +340,17 @@ Run: opscontext install-autostart
 }
 export async function cliUninstallClaudeHook(args) {
     if (args.includes("-h") || args.includes("--help")) {
-        console.log(`Usage: opscontext uninstall-claude-hook
+        console.log(`Usage: opscontext uninstall-claude-hook [--simplicity]
 
-Removes OpsContext hook entries from ~/.claude/settings.json. The hook
-script file (~/.claude/hooks/opscontext-emit.sh) is left in place — delete
-manually if you want it gone. The audit log is NOT touched.`);
+Removes OpsContext hook entries from ~/.claude/settings.json. With --simplicity
+only the simplicity gate entry is removed; the emit hooks and the Stop gate stay.
+The hook script files under ~/.claude/hooks/ are left in place — delete
+manually if you want them gone. The audit log is NOT touched.`);
         return;
     }
+    const ourNames = args.includes("--simplicity")
+        ? ["opscontext-simplicity-gate.py"]
+        : ["opscontext-emit.sh", "opscontext-session-gate.sh", "opscontext-simplicity-gate.py"];
     const settings = readSettings();
     if (!settings.hooks) {
         console.log(`   (no hooks block in settings.json — nothing to remove)`);
@@ -279,7 +364,7 @@ manually if you want it gone. The audit log is NOT touched.`);
         const entries = settings.hooks[kind];
         if (!entries)
             continue;
-        const filtered = entries.filter((e) => !e.hooks?.some((h) => h.command?.includes("opscontext-emit.sh") || h.command?.includes("opscontext-session-gate.sh")));
+        const filtered = entries.filter((e) => !e.hooks?.some((h) => ourNames.some((n) => h.command?.includes(n))));
         removed += entries.length - filtered.length;
         if (filtered.length === 0) {
             delete settings.hooks[kind];

package/dist/rubric.js

@@ -9,7 +9,7 @@
  * WHAT THIS IS NOT: hidden behaviour. This file contains numbers and nothing else — no network
  * calls, no file access, no data collection. Every code path in this package ships readable,
  * including the two (and only two) network calls the tool ever makes: licence activation and the
- * daily heartbeat, both in activation.js. Full source: https://github.com/FASTPROD/ContextEngine
+ * daily heartbeat, both in activation.js. Full source: https://github.com/FASTPROD/opscontext-mcp
  *
  * Your project data never leaves your machine. See the Privacy section of the README, and verify
  * it in the source rather than taking our word for it.