continuous-improvement 3.22.1 → 3.24.0

package/plugins/continuous-improvement/hooks/gateguard.mjs

@@ -35,6 +35,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { classifyDestructiveBash } from "../lib/destructive-bash.mjs";
 import { MAX_CLEARED_FILES, canonicalizeFileKey, canonicalizeProjectRoot, isCapReached, isFileCleared, loadState, markFileCleared, resolveProjectRoot, resolveSessionDir, saveState, } from "../lib/gateguard-state.mjs";
 const TOOL_ROUTE = {
     Read: "allow",
@@ -48,42 +49,14 @@ const TOOL_ROUTE = {
     NotebookEdit: "mutating-file",
     Bash: "allow",
 };
-const DESTRUCTIVE_PATTERNS = [
-    "rm -rf",
-    "rm -fr",
-    "git reset --hard",
-    "git push --force",
-    "git push -f",
-    "--force-with-lease",
-    "git branch -D",
-    "drop table",
-    "drop database",
-    "drop schema",
-    "truncate ",
-    "mkfs",
-    "dd if=",
-    "format ",
-    "rmdir /s",
-    "del /f /q",
-    "del /q /f",
-    "Remove-Item -Recurse",
-    "Remove-Item -Force",
-];
-// Flags whose VALUE is human prose (a commit message, a PR body) or a filename —
-// never a command to execute. Their contents must not trip the destructive scan:
-// `git commit -m "drop the stale format helper"` and `gh pr create --body "…"`
-// were stranding finished work on their own wording. `-c` is deliberately
-// EXCLUDED — `bash -c "rm -rf /"` carries a real command and must still gate.
-const MESSAGE_FLAG_RE = /(^|\s)(-m|--message|-F|--file|--body|--body-file|--title|--notes|-C|--reuse-message)(=|\s+)('[^']*'|"[^"]*"|\S+)/g;
-// Blank the value of every message/body flag so only executable command syntax
-// remains for the destructive-pattern scan. The flag itself is preserved so a
-// flag like `-F` never accidentally merges with its neighbours.
-function stripMessageArgs(command) {
-    return command.replace(MESSAGE_FLAG_RE, (_match, lead, flag) => `${lead}${flag} `);
-}
+// The destructive-Bash classifier lives in lib/destructive-bash.mjs: structured
+// rules (flag order and spelling do not matter: `rm -r -f`, `git clean -fdx`,
+// `git checkout -- .`, `git restore .`, `find -delete`, `git push +ref`,
+// `git stash drop`) plus the original substring list as the fallback. The
+// message-flag carve-out (`git commit -m "…"`) lives there too. Each rule has
+// a stable id the deny reason prints, so a block is explainable.
 function isDestructiveBash(command) {
-    const lower = stripMessageArgs(command).toLowerCase();
-    return DESTRUCTIVE_PATTERNS.some((p) => lower.includes(p.toLowerCase()));
+    return classifyDestructiveBash(command).destructive;
 }
 function classifyTool(toolName, toolInput) {
     const route = TOOL_ROUTE[toolName] ?? "allow";
@@ -119,12 +92,34 @@ const EXCLUDE_FRAGMENTS = String(process.env.CI_GATEGUARD_EXCLUDE ?? "")
     .split(",")
     .map((fragment) => fragment.trim().replace(/\\/g, "/").toLowerCase())
     .filter((fragment) => fragment !== "");
-function isExcludedPath(filePath) {
+function matchedExcludeFragment(filePath) {
     if (EXCLUDE_FRAGMENTS.length === 0 || typeof filePath !== "string" || filePath === "") {
-        return false;
+        return null;
     }
     const normalized = filePath.replace(/\\/g, "/").toLowerCase();
-    return EXCLUDE_FRAGMENTS.some((fragment) => normalized.includes(fragment));
+    return EXCLUDE_FRAGMENTS.find((fragment) => normalized.includes(fragment)) ?? null;
+}
+function isExcludedPath(filePath) {
+    return matchedExcludeFragment(filePath) !== null;
+}
+// A fragment every path contains ("/", ".", any single character) is not an
+// exclusion, it is an off switch for the whole file gate. It is still honoured —
+// the operator set it — but silently honouring it is how a host ends up with the
+// headline feature off and nobody noticing (this repo's own author's shell had
+// CI_GATEGUARD_EXCLUDE="/,." for weeks). So every exclusion prints one stderr
+// line, and a catch-all says plainly that the gate is off. stderr never changes
+// the decision: allow stays empty stdout + exit 0.
+function isCatchAllFragment(fragment) {
+    return fragment.length <= 1 || fragment === "./" || fragment === "..";
+}
+function buildExcludeNotice(paths, fragment) {
+    const shown = paths.map((p) => p.replace(/\\/g, "/")).join(", ");
+    if (isCatchAllFragment(fragment)) {
+        return (`[continuous-improvement] gateguard: CI_GATEGUARD_EXCLUDE fragment "${fragment}" matches every path, ` +
+            `so the file gate is off for this session (skipped ${shown}). ` +
+            "Narrow it to a directory, e.g. CI_GATEGUARD_EXCLUDE=docs/wiki, to get the gate back.");
+    }
+    return `[continuous-improvement] gateguard: skipped by CI_GATEGUARD_EXCLUDE (fragment "${fragment}" matched ${shown}).`;
 }
 // --- Target lock (opt-in) --------------------------------------------------
 // A fact-list can't catch a wrong-repo / wrong-worktree write — you can present
@@ -271,6 +266,7 @@ function buildBraceRefReason(hit) {
     ].join("\n");
 }
 function buildDestructiveBashReason(command) {
+    const rule = classifyDestructiveBash(command).rule ?? "unknown";
     return [
         `Destructive command requested: ${command}`,
         "",
@@ -278,6 +274,7 @@ function buildDestructiveBashReason(command) {
         "  2. Write a one-line rollback procedure",
         "  3. Quote the user's current instruction verbatim",
         "",
+        `Matched rule: ${rule}`,
         "Destructive Bash gates EVERY call — clearance is not cached.",
     ].join("\n");
 }
@@ -354,7 +351,10 @@ function main() {
     const allTargetPaths = extractFilePaths(toolInput);
     const filePaths = allTargetPaths.filter((path) => !isExcludedPath(path));
     if (allTargetPaths.length > 0 && filePaths.length === 0) {
-        emitAllow(); // every target is under a CI_GATEGUARD_EXCLUDE path; skip the gate
+        // Every target is under a CI_GATEGUARD_EXCLUDE path; skip the gate, but say so.
+        const fragment = matchedExcludeFragment(allTargetPaths[0]) ?? EXCLUDE_FRAGMENTS[0];
+        process.stderr.write(`${buildExcludeNotice(allTargetPaths, fragment)}\n`);
+        emitAllow();
         return;
     }
     // Target lock runs before the fact gate and independent of clearance: a

package/plugins/continuous-improvement/hooks/goal-drift-stop.mjs

@@ -17,10 +17,10 @@
 // construction: any error / missing goal / unreadable observations exits 0 and
 // never blocks. No network. 5s hook budget.
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { evaluateGoalDrift } from "../lib/goal-drift-gate.mjs";
+import { hashProjectRoot } from "../lib/gateguard-state.mjs";
 import { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
 function readStdinSync() {
     try {
@@ -62,7 +62,7 @@ function resolveProjectRoot() {
     return "global";
 }
 function projectHash(root) {
-    return createHash("sha256").update(root).digest("hex").slice(0, 12);
+    return hashProjectRoot(root);
 }
 function readGoalMarkdown(projectRoot, instinctsProjectDir) {
     const candidates = [join(projectRoot, "task_plan.md"), join(instinctsProjectDir, "goal.md")];

package/plugins/continuous-improvement/hooks/hooks.json

@@ -24,6 +24,16 @@
             "timeout": 30
           }
         ]
+      },
+      {
+        "matcher": "Bash|Edit|MultiEdit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/config-guard.mjs\"",
+            "timeout": 30
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/plugins/continuous-improvement/hooks/query-cost-nudge.mjs

@@ -16,7 +16,7 @@
  * the DB files stay dirty. Never blocks; fail-open on any error.
  */
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { hashProjectRoot } from "../lib/gateguard-state.mjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -71,7 +71,7 @@ function markerKey(sessionId) {
     return sanitized || `day-${new Date().toISOString().slice(0, 10)}`;
 }
 function markerPath(home, projectRoot, sessionId) {
-    const hash = createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);
+    const hash = hashProjectRoot(projectRoot);
     return join(home, ".claude", "instincts", hash, "query-cost-nudge", `${markerKey(sessionId)}.nudged`);
 }
 function main() {

package/plugins/continuous-improvement/hooks/recall-briefing.mjs

@@ -23,13 +23,13 @@
  * ~/.claude/instincts/<project-hash>/recall-briefing-session.json records which
  * session_ids have been briefed so each session is briefed at most once.
  */
-import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
 import { buildIndex, query } from "../lib/recall-index.mjs";
 import { DEFAULT_MAX_HITS, decideBriefing } from "../lib/recall-briefing.mjs";
+import { hashProjectRoot } from "../lib/gateguard-state.mjs";
 const ENABLED_VALUES = new Set(["1", "on", "true", "yes"]);
 const MAX_BRIEFED_KEYS = 1000;
 function isEnabled() {
@@ -65,7 +65,7 @@ function resolveProjectRoot() {
     return "global";
 }
 function instinctsDir(home) {
-    const hash = createHash("sha256").update(resolveProjectRoot()).digest("hex").slice(0, 12);
+    const hash = hashProjectRoot(resolveProjectRoot());
     return join(home, ".claude", "instincts", hash);
 }
 function readObservations(dir) {

package/plugins/continuous-improvement/hooks/route-prompt.mjs

@@ -30,12 +30,12 @@
  *   }
  * Rows are evaluated in order; first match wins.
  */
-import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { hashProjectRoot } from "../lib/gateguard-state.mjs";
 function readStdin() {
     try {
         return readFileSync(0, "utf8");
@@ -65,10 +65,7 @@ function resolveProjectRoot() {
     return "global";
 }
 function telemetryPath(home) {
-    const hash = createHash("sha256")
-        .update(resolveProjectRoot())
-        .digest("hex")
-        .slice(0, 12);
+    const hash = hashProjectRoot(resolveProjectRoot());
     return join(home, ".claude", "instincts", hash, "route-prompt.jsonl");
 }
 function writeTelemetry(home, event) {

package/plugins/continuous-improvement/hooks/session.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
 import { readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
+import { hashProjectRoot } from "../lib/gateguard-state.mjs";
 import { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
 function read(path) {
     try {
@@ -62,7 +62,7 @@ function main() {
     if (!home)
         return;
     const instinctsRoot = join(home, ".claude", "instincts");
-    const hash = createHash("sha256").update(projectRoot()).digest("hex").slice(0, 12);
+    const hash = hashProjectRoot(projectRoot());
     const projectDir = join(instinctsRoot, hash);
     const files = [...yamlFiles(projectDir), ...yamlFiles(join(instinctsRoot, "global"))];
     const observations = read(join(projectDir, "observations.jsonl")).split(/\r?\n/).filter(Boolean).length;

package/plugins/continuous-improvement/hooks/workflow-distill.mjs

@@ -24,9 +24,9 @@
 // name + verify command, so a run is nudged at most once. Fail-open by
 // construction: any error exits 0 and never blocks. No network. 5s hook budget.
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { hashProjectRoot } from "../lib/gateguard-state.mjs";
 import { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
 import { workflowRunFromObservations } from "../lib/skill-distill.mjs";
 function safeJsonParse(text) {
@@ -60,7 +60,7 @@ function resolveProjectRoot() {
     return "global";
 }
 function projectHash(root) {
-    return createHash("sha256").update(root).digest("hex").slice(0, 12);
+    return hashProjectRoot(root);
 }
 function readObservations(instinctsProjectDir) {
     const file = join(instinctsProjectDir, "observations.jsonl");

package/plugins/continuous-improvement/lib/config-guard-gate.mjs

@@ -0,0 +1,243 @@
+// config-guard-gate.mts — Pure decision core for the config-guard PreToolUse hook.
+//
+// The guardrails this plugin ships are wired by a handful of files: the
+// Claude Code settings files, the MCP config, hooks.json, the user hooks
+// directory, the installed-plugins cache, and plugin manifests. Nothing stopped
+// an agent from editing those files and switching every gate off, and
+// hooks/gateguard.mjs is designed to be cleared per file, not to hard-deny. This
+// module decides whether a tool call would mutate one of them. No I/O: the hook
+// (src/hooks/config-guard.mts) wires stdin and the mode env var around it, so a
+// table test covers every branch without spawning anything. Lives in lib/ so
+// tests can import it (the test-imports-only invariant forbids hooks/).
+//
+// Idea ported from karanb192/claude-code-hooks `config-guard` (MIT); the code
+// and the pattern list are ours. Fail-open by construction: an unrecognized mode
+// resolves to warn, and a call that names no protected path is always allowed.
+/**
+ * Path patterns, matched case-insensitively on the forward-slash form.
+ * A trailing "/" means a directory component anywhere in the path; otherwise
+ * the pattern must be the whole path or a trailing path segment, so
+ * `hooks.json.md` and `config/settings.json` are not matched.
+ */
+export const PROTECTED_PATTERNS = [
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".mcp.json",
+    "hooks.json",
+    ".claude/hooks/",
+    ".claude/plugins/",
+    ".claude-plugin/",
+];
+const ALLOW = { action: "allow", reason: "" };
+export function parseMode(raw) {
+    const v = (raw ?? "warn").trim().toLowerCase();
+    return v === "block" || v === "off" ? v : "warn";
+}
+function normalizePath(p) {
+    return p.replace(/\\/g, "/").toLowerCase();
+}
+export function matchProtectedPath(filePath) {
+    if (typeof filePath !== "string" || filePath === "")
+        return null;
+    const n = normalizePath(filePath);
+    for (const pattern of PROTECTED_PATTERNS) {
+        const lp = pattern.toLowerCase();
+        if (lp.endsWith("/")) {
+            if (n.includes(lp))
+                return pattern;
+            continue;
+        }
+        if (n === lp || n.endsWith(`/${lp}`))
+            return pattern;
+    }
+    return null;
+}
+// --- file tools ------------------------------------------------------------
+function fileToolPaths(toolInput) {
+    const paths = [];
+    if (typeof toolInput.file_path === "string")
+        paths.push(toolInput.file_path);
+    if (typeof toolInput.notebook_path === "string")
+        paths.push(toolInput.notebook_path);
+    if (Array.isArray(toolInput.edits)) {
+        for (const edit of toolInput.edits) {
+            if (edit && typeof edit === "object" && typeof edit.file_path === "string") {
+                paths.push(edit.file_path);
+            }
+        }
+    }
+    return paths;
+}
+const FILE_MUTATING_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+// --- Bash --------------------------------------------------------------------
+// Split at shell separators that sit outside single or double quotes.
+function splitSimpleCommands(command) {
+    const segments = [];
+    let current = "";
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            current += ch;
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === "\n" || ch === ";") {
+            segments.push(current);
+            current = "";
+            continue;
+        }
+        if (ch === "|" || ch === "&") {
+            if (command[i + 1] === ch)
+                i++;
+            segments.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    segments.push(current);
+    return segments.map((s) => s.trim()).filter((s) => s !== "");
+}
+function tokenize(segment) {
+    return segment.split(/\s+/).filter((t) => t !== "");
+}
+function stripQuotes(token) {
+    return token.replace(/^['"]+|['"]+$/g, "");
+}
+function commandWord(tokens) {
+    let i = 0;
+    while (i < tokens.length) {
+        const t = tokens[i];
+        if (t === "sudo" || t === "env" || t === "command" || /^[A-Za-z_][A-Za-z0-9_]*=/.test(t)) {
+            i++;
+            continue;
+        }
+        break;
+    }
+    return { cmd: (tokens[i] ?? "").toLowerCase(), rest: tokens.slice(i + 1) };
+}
+const COPY_MOVE = new Set(["cp", "mv", "copy-item", "move-item"]);
+const OPERAND_WRITERS = new Set([
+    "rm",
+    "tee",
+    "truncate",
+    "remove-item",
+    "del",
+    "set-content",
+    "out-file",
+    "add-content",
+    "clear-content",
+]);
+// Mutation indicators for the generic scan (a protected path mentioned inside
+// a scripting one-liner such as `node -e "writeFileSync('.claude/settings.json')"`).
+const GENERIC_WRITE_RE = /writefilesync|writefile\(|appendfile|unlink|rename\(|copyfile|rmsync|truncate|set-content|out-file|add-content|remove-item|\bdel\b|\bsed\s+-i\b|\btee\b|>{1,2}/i;
+const CLAUDE_CLI_MUTATIONS = {
+    plugin: new Set(["install", "uninstall", "enable", "disable", "update", "marketplace"]),
+    mcp: new Set(["add", "remove", "add-json", "add-from-claude-desktop", "reset-project-choices"]),
+    config: new Set(["set", "add", "remove", "reset", "rm"]),
+};
+function classifyBashSegment(segment) {
+    const tokens = tokenize(segment);
+    if (tokens.length === 0)
+        return null;
+    const { cmd, rest } = commandWord(tokens);
+    // `claude plugin|mcp|config <mutating-verb>`: the CLI edits the same files.
+    if (cmd === "claude") {
+        const area = (rest[0] ?? "").toLowerCase();
+        const verb = (rest[1] ?? "").toLowerCase();
+        const verbs = CLAUDE_CLI_MUTATIONS[area];
+        if (verbs && verbs.has(verb)) {
+            return { target: `claude ${area} ${verb}`, pattern: "claude-cli", via: "claude-cli" };
+        }
+        return null;
+    }
+    // cp / mv: only the destination (last operand) can be a protected write.
+    if (COPY_MOVE.has(cmd)) {
+        const operands = rest.filter((t) => !t.startsWith("-"));
+        const dest = operands[operands.length - 1];
+        const pattern = dest ? matchProtectedPath(stripQuotes(dest)) : null;
+        return pattern && dest ? { target: stripQuotes(dest), pattern, via: "bash" } : null;
+    }
+    // Redirects: `> path`, `>> path`, `2>path`, `>path`.
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        const m = /^(\d?>{1,2})(.*)$/.exec(t);
+        if (!m)
+            continue;
+        const target = m[2] !== "" ? m[2] : (tokens[i + 1] ?? "");
+        const pattern = matchProtectedPath(stripQuotes(target));
+        if (pattern)
+            return { target: stripQuotes(target), pattern, via: "bash" };
+    }
+    // Operand writers: any operand that is a protected path.
+    const sedInPlace = cmd === "sed" && rest.some((t) => /^-[a-zA-Z]*i/.test(t) || t === "--in-place");
+    if (OPERAND_WRITERS.has(cmd) || sedInPlace) {
+        for (const t of rest) {
+            if (t.startsWith("-"))
+                continue;
+            const clean = stripQuotes(t);
+            const pattern = matchProtectedPath(clean);
+            if (pattern)
+                return { target: clean, pattern, via: "bash" };
+        }
+        return null;
+    }
+    // Generic scan: a protected path quoted inside a scripting one-liner, next
+    // to a write indicator. Reads (`cat`, `grep`) carry no indicator and pass.
+    if (GENERIC_WRITE_RE.test(segment)) {
+        const candidates = [];
+        const quoted = /'([^']+)'|"([^"]+)"/g;
+        let q;
+        while ((q = quoted.exec(segment)) !== null)
+            candidates.push((q[1] ?? q[2]));
+        for (const t of tokens)
+            candidates.push(stripQuotes(t));
+        for (const c of candidates) {
+            const inner = /['"]([^'"]*?)['"]/.exec(c);
+            for (const candidate of [c, inner?.[1] ?? ""]) {
+                const pattern = matchProtectedPath(candidate);
+                if (pattern)
+                    return { target: candidate, pattern, via: "bash" };
+            }
+            // A path embedded in a longer expression, e.g. writeFileSync('.claude/settings.json','{}')
+            const embedded = /(?:^|[('"\s=,])([~A-Za-z0-9_./\\:-]*(?:\.claude\/|\.claude-plugin\/|\.mcp\.json|hooks\.json)[A-Za-z0-9_./\\-]*)/i.exec(c);
+            if (embedded) {
+                const pattern = matchProtectedPath(embedded[1]);
+                if (pattern)
+                    return { target: embedded[1], pattern, via: "bash" };
+            }
+        }
+    }
+    return null;
+}
+/** Decide whether a tool call would mutate a guardrail-wiring file. Pure. */
+export function classifyMutation(toolName, toolInput) {
+    if (FILE_MUTATING_TOOLS.has(toolName)) {
+        for (const p of fileToolPaths(toolInput)) {
+            const pattern = matchProtectedPath(p);
+            if (pattern)
+                return { target: p, pattern, via: "file" };
+        }
+        return null;
+    }
+    if (toolName === "Bash" && typeof toolInput.command === "string" && toolInput.command.trim() !== "") {
+        for (const segment of splitSimpleCommands(toolInput.command)) {
+            const hit = classifyBashSegment(segment);
+            if (hit)
+                return hit;
+        }
+    }
+    return null;
+}
+export function decide(mode, gated, reason) {
+    if (!gated || mode === "off")
+        return ALLOW;
+    return { action: mode === "block" ? "block" : "warn", reason };
+}