continuous-improvement 3.9.2 → 3.12.3

package/hooks/gateguard.mjs

@@ -9,8 +9,10 @@
  * Three-stage gate per skills/gateguard.md:
  * - DENY  : first mutating tool call per file, with fact-list reason
  * - FORCE : agent presents facts (model-side; out of band)
- * - ALLOW : retry once `_gateguard_facts_presented: true` is set or the
- *           per-file marker is recorded in session state
+ * - ALLOW : retry once the per-file marker is recorded in session state
+ *           (harness-portable, written out of band via Bash), or
+ *           `_gateguard_facts_presented: true` is set where the harness
+ *           forwards unknown tool params
  *
  * Read-only and exploratory tools (Read, Grep, Glob, routine Bash) bypass
  * unconditionally. Destructive Bash gates EVERY call, not just first.
@@ -18,12 +20,16 @@
  * V1 honest limitations (see src/lib/gateguard-state.mts header):
  *   honor-system flag, state-file deletion, parallel-hook race.
  *
- * MultiEdit handling (V1): gates on edits[0].file_path only. Per-file
- * batching is not implemented — TODO: extend to gate every entry in
- * edits[]. Tracked in issue #106 acceptance criteria item 5.
+ * MultiEdit handling gates every edited file individually. The hook blocks
+ * unless all edited paths are already cleared, or the agent presents facts
+ * for the call and the hook records clearance for each edited path.
+ * Block reasons now name the whole batch instead of just the first uncleared
+ * path.
  */
 import { readFileSync } from "node:fs";
-import { isCapReached, loadState, markFileCleared, resolveSessionDir, saveState, } from "../lib/gateguard-state.mjs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { MAX_CLEARED_FILES, canonicalizeFileKey, isCapReached, isFileCleared, loadState, markFileCleared, resolveSessionDir, saveState, } from "../lib/gateguard-state.mjs";
 const TOOL_ROUTE = {
     Read: "allow",
     Grep: "allow",
@@ -71,30 +77,65 @@ function classifyTool(toolName, toolInput) {
     }
     return "allow";
 }
-function extractFilePath(toolInput) {
+function extractFilePaths(toolInput) {
     if (typeof toolInput.file_path === "string")
-        return toolInput.file_path;
-    // MultiEdit V1: first edit's file_path is the canonical key.
+        return [toolInput.file_path];
     if (Array.isArray(toolInput.edits) && toolInput.edits.length > 0) {
-        const first = toolInput.edits[0];
-        if (first && typeof first.file_path === "string")
-            return first.file_path;
+        return toolInput.edits
+            .map((edit) => (edit && typeof edit.file_path === "string" ? edit.file_path : ""))
+            .filter((filePath) => filePath !== "");
     }
     if (typeof toolInput.command === "string")
-        return toolInput.command;
-    return "";
+        return [toolInput.command];
+    return [];
 }
-function buildMutatingFileReason(toolName, filePath) {
+// The call site only reads this inside the block branch, where at least one
+// path is uncleared; an all-cleared batch returns "" and is never consumed.
+function firstUnclearedFilePath(toolInput, state) {
+    return extractFilePaths(toolInput).find((path) => !isFileCleared(state, path)) ?? "";
+}
+function countDistinctNewFilePaths(filePaths, state) {
+    return new Set(filePaths.filter((path) => !isFileCleared(state, path)).map((path) => canonicalizeFileKey(path))).size;
+}
+function formatFileTarget(filePaths) {
+    const nonEmpty = filePaths.filter((path) => path !== "");
+    if (nonEmpty.length === 0)
+        return "<unknown>";
+    if (nonEmpty.length === 1)
+        return nonEmpty[0];
+    return `${nonEmpty.length} files (${nonEmpty.join(", ")})`;
+}
+// Resolved from the hook's own location at load time. The block reason must
+// print a command the agent can run in its OWN shell, where ${CLAUDE_PLUGIN_ROOT}
+// is empty — that variable is only populated while this hook itself executes.
+// bin/ is a sibling of hooks/ in both the repo layout and the plugin-bundle
+// mirror, so this resolves correctly from either.
+const CLEAR_CLI_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "gateguard-clear.mjs");
+// Quote a path for the printed clearance command. Forward slashes (node accepts
+// them on every platform and they survive a Bash double-quote without escaping)
+// inside JSON quotes — JSON.stringify still escapes any embedded quote, so a
+// path like a"b.ts stays safe rather than collapsing into a bare-quoted token.
+function quotePath(p) {
+    return JSON.stringify(p.replace(/\\/g, "/"));
+}
+function buildMutatingFileReason(toolName, filePaths, stateFilePath) {
+    const target = formatFileTarget(filePaths);
+    const pathList = filePaths.filter((p) => p !== "");
+    const quoted = (pathList.length > 0 ? pathList : [target]).map((p) => quotePath(p));
     return [
-        `Before ${toolName === "Write" ? "creating" : "editing"} ${filePath || "<unknown>"}, present these facts:`,
+        `Before ${toolName === "Write" ? "creating" : "editing"} ${target}, present these facts:`,
         "",
         "  1. List ALL files that import/require this file (use Grep)",
         "  2. List the public functions/classes affected by this change",
         "  3. If this file reads/writes data files, show field names, structure, and date format",
         "  4. Quote the user's current instruction verbatim",
         "",
-        "After presenting the facts, retry with `_gateguard_facts_presented: true` in tool_input,",
-        "or with the same file_path after a previous clearance has been recorded for this session.",
+        "Then clear the gate and retry the same call. Either route works:",
+        `  A. Bash (always works — run verbatim): node ${quotePath(CLEAR_CLI_PATH)} --state ${quotePath(stateFilePath)} ${quoted.join(" ")}`,
+        `  B. MCP tool (when the continuous-improvement server is connected): ci_gateguard_clear  {file_paths: [${quoted.join(", ")}]}`,
+        "  Both canonicalize paths — drive-letter case and separators don't matter.",
+        "  (Harnesses that forward unknown tool params may instead retry the call with",
+        "  `_gateguard_facts_presented: true`; Claude Code's strict schema rejects that, so use A or B.)",
     ].join("\n");
 }
 function buildDestructiveBashReason(command) {
@@ -110,7 +151,7 @@ function buildDestructiveBashReason(command) {
 }
 function buildCapReachedReason() {
     return [
-        "Gateguard session clearance cap reached (50 distinct files).",
+        `Gateguard session clearance cap reached (${MAX_CLEARED_FILES} distinct files).`,
         "Start a new Claude Code session to reset the gate. The cap exists to bound",
         "stuck-loop or rogue-agent clearance from compounding within a single session.",
     ].join("\n");
@@ -150,22 +191,28 @@ function main() {
     }
     // mutating-file
     const sessionDir = resolveSessionDir();
+    const stateFilePath = join(sessionDir, "gateguard-session.json");
     const state = loadState(sessionDir);
-    const filePath = extractFilePath(toolInput);
+    const filePaths = extractFilePaths(toolInput);
+    const filePath = firstUnclearedFilePath(toolInput, state);
     const factsFlagged = toolInput._gateguard_facts_presented === true;
-    const alreadyCleared = filePath !== "" && filePath in state.cleared_files;
+    const alreadyCleared = filePaths.length > 0 && filePaths.every((path) => isFileCleared(state, path));
+    const newFileCount = countDistinctNewFilePaths(filePaths, state);
     if (!factsFlagged && !alreadyCleared) {
-        emit({ decision: "block", reason: buildMutatingFileReason(toolName, filePath) });
+        emit({ decision: "block", reason: buildMutatingFileReason(toolName, filePaths.length > 0 ? filePaths : [filePath], stateFilePath) });
         return;
     }
     if (factsFlagged && !alreadyCleared) {
-        if (isCapReached(state)) {
+        if (isCapReached(state) || Object.keys(state.cleared_files).length + newFileCount > MAX_CLEARED_FILES) {
             emit({ decision: "block", reason: buildCapReachedReason() });
             return;
         }
-        if (filePath !== "") {
-            saveState(sessionDir, markFileCleared(state, filePath));
+        let nextState = state;
+        for (const path of filePaths) {
+            nextState = markFileCleared(nextState, path);
         }
+        if (filePaths.length > 0)
+            saveState(sessionDir, nextState);
     }
     emit({ decision: "allow" });
 }

package/hooks/goal-drift-stop.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// goal-drift-stop.mts — Stop hook that scores the turn's activity against the
+// stated goal (task_plan.md ## Goal) and, when the session has DRIFTed on a
+// substantive wrap-up, warns or (opt-in) blocks the close. This is the runtime
+// arm of goal-monitor: it auto-fires the drift check at the Stop phase boundary
+// instead of waiting for someone to run /goal-check.
+//
+// Mode via CLAUDE_GOAL_DRIFT_GATE: "warn" (default) | "block" | "off".
+//   - warn  : print a one-line drift notice to stderr; never blocks.
+//   - block : emit {"decision":"block","reason":...} to re-prompt.
+//   - off   : no-op.
+// The drift status is persisted to
+// ~/.claude/instincts/<project-hash>/goal-drift-state.json every turn.
+//
+// Project-hash resolution is byte-identical to bin/observe.mts so this hook
+// reads the SAME observations.jsonl the observer writes. Fail-open by
+// 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 { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
+function readStdinSync() {
+    try {
+        return readFileSync(0, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveMode() {
+    const raw = (process.env.CLAUDE_GOAL_DRIFT_GATE ?? "warn").trim().toLowerCase();
+    return raw === "block" || raw === "off" ? raw : "warn";
+}
+// Mirrors bin/observe.mts:resolveProjectRoot — the same basis the observer uses
+// to bucket observations.jsonl, so the hash here resolves to the same file.
+function resolveProjectRoot() {
+    const fromEnv = process.env.CLAUDE_PROJECT_DIR;
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (root)
+            return root;
+    }
+    catch {
+        // not a git repo
+    }
+    return "global";
+}
+function projectHash(root) {
+    return createHash("sha256").update(root).digest("hex").slice(0, 12);
+}
+function readGoalMarkdown(projectRoot, instinctsProjectDir) {
+    const candidates = [join(projectRoot, "task_plan.md"), join(instinctsProjectDir, "goal.md")];
+    for (const file of candidates) {
+        try {
+            if (existsSync(file))
+                return readFileSync(file, "utf8");
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return "";
+}
+function readObservations(instinctsProjectDir) {
+    const file = join(instinctsProjectDir, "observations.jsonl");
+    try {
+        if (!existsSync(file))
+            return [];
+        const lines = readFileSync(file, "utf8")
+            .split("\n")
+            .filter((line) => line.trim().length > 0);
+        const out = [];
+        for (const line of lines.slice(-100)) {
+            const row = safeJsonParse(line);
+            if (!row)
+                continue;
+            out.push({
+                ts: typeof row.ts === "string" ? row.ts : "",
+                tool: typeof row.tool === "string" ? row.tool : "",
+                input_summary: typeof row.input_summary === "string" ? row.input_summary : "",
+                output_summary: typeof row.output_summary === "string" ? row.output_summary : "",
+            });
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+function lastAssistantTextLength(transcriptPath) {
+    try {
+        const lines = readFileSync(transcriptPath, "utf8").split(/\r?\n/);
+        for (let i = lines.length - 1; i >= 0; i -= 1) {
+            const line = lines[i].trim();
+            if (!line)
+                continue;
+            const obj = safeJsonParse(line);
+            if (!obj || obj.type !== "assistant")
+                continue;
+            const blocks = obj.message?.content;
+            if (!Array.isArray(blocks))
+                continue;
+            const text = blocks
+                .filter((b) => b &&
+                typeof b === "object" &&
+                b.type === "text" &&
+                typeof b.text === "string")
+                .map((b) => b.text)
+                .join("\n");
+            if (text.length === 0)
+                continue;
+            return text.length;
+        }
+    }
+    catch {
+        // fall through to 0
+    }
+    return 0;
+}
+function persistState(instinctsProjectDir, state) {
+    try {
+        mkdirSync(instinctsProjectDir, { recursive: true });
+        writeFileSync(join(instinctsProjectDir, "goal-drift-state.json"), JSON.stringify({ ts: new Date().toISOString(), ...state }) + "\n", "utf8");
+    }
+    catch {
+        // state persistence is best-effort; never throw
+    }
+}
+function main() {
+    const mode = resolveMode();
+    if (mode === "off")
+        return;
+    const stdin = readStdinSync();
+    if (!stdin)
+        return;
+    const payload = safeJsonParse(stdin);
+    if (!payload)
+        return;
+    const home = resolveHomeDir();
+    if (!home)
+        return;
+    const projectRoot = resolveProjectRoot();
+    const instinctsProjectDir = join(home, ".claude", "instincts", projectHash(projectRoot));
+    const goalMarkdown = readGoalMarkdown(projectRoot, instinctsProjectDir);
+    const observations = readObservations(instinctsProjectDir);
+    const textLength = payload.transcript_path && existsSync(payload.transcript_path)
+        ? lastAssistantTextLength(payload.transcript_path)
+        : 0;
+    const decision = evaluateGoalDrift({ goalMarkdown, observations, textLength, mode });
+    persistState(instinctsProjectDir, {
+        status: decision.status,
+        score: decision.score,
+        action: decision.action,
+    });
+    if (decision.action === "block") {
+        process.stdout.write(JSON.stringify({ decision: "block", reason: decision.reason }) + "\n");
+    }
+    else if (decision.action === "warn") {
+        process.stderr.write(`[continuous-improvement] goal-drift: ${decision.reason}\n`);
+    }
+}
+try {
+    main();
+}
+catch {
+    // fail open — never block the session due to a hook bug
+}

package/hooks/observe.sh

@@ -101,6 +101,20 @@ fi
 # ---------------------------------------------------------------------------
 # Compute project hash and name
 # ---------------------------------------------------------------------------
+# Canonicalize MSYS-mounted Windows paths (/d/Path) to native form (D:/Path)
+# so the bash fallback hashes to the same project bucket as the Node observer.
+# Without this, Git Bash on Windows produces /d/Ai/repo from `git rev-parse`
+# while Node's child_process produces D:/Ai/repo for the same physical path,
+# splitting telemetry between two SHA-256 buckets per project.
+# Pattern matches /<single-letter>/... only — Linux/macOS paths like /usr,
+# /home, /Users are unaffected.
+case "$PROJECT_ROOT" in
+  /[a-zA-Z]/*)
+    drive_letter="$(printf '%s' "$PROJECT_ROOT" | cut -c2 | tr '[:lower:]' '[:upper:]')"
+    PROJECT_ROOT="${drive_letter}:$(printf '%s' "$PROJECT_ROOT" | cut -c3-)"
+    ;;
+esac
+
 PROJECT_HASH="$(printf '%s' "$PROJECT_ROOT" | sha256sum | cut -c1-12)"
 PROJECT_NAME="$(basename "${PROJECT_ROOT%.git}")"
 
@@ -119,7 +133,7 @@ if [[ -f "$OBS_FILE" ]]; then
   LINE_COUNT="$(wc -l < "$OBS_FILE")"
   if (( LINE_COUNT >= 10000 )); then
     mv "$OBS_FILE" "${PROJECT_DIR}/observations.$(date -u +"%Y-%m-%d-%H%M%S").jsonl"
-    
+
     # Clean up old archives - keep only 10 most recent
     ls -t "${PROJECT_DIR}"/observations.*.jsonl 2>/dev/null | tail -n +11 | xargs -r rm -f
   fi

package/hooks/recall-briefing.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * Runtime UserPromptSubmit recall-briefing hook (opt-in amplifier).
+ *
+ * On the first substantive prompt of a session, searches this project's past
+ * observations (BM25, via recall-index.mts) and injects a one-time
+ * `<system-reminder>` listing the most relevant prior activity — so the agent
+ * reuses a past fix instead of re-deriving it. This makes episodic memory
+ * proactive instead of opt-in-per-query (the ci_recall MCP tool stays available
+ * for explicit, deeper searches).
+ *
+ * Opt-in: runs only when CLAUDE_RECALL_BRIEFING is 1/on/true. Default off, so it
+ * never changes the prompt path for users who have not enabled it.
+ *
+ * Stdin  : JSON { prompt, session_id?, cwd? }
+ * Stdout : JSON { hookSpecificOutput: { hookEventName: "UserPromptSubmit",
+ *                                       additionalContext: string } }
+ *          OR empty when it should not brief.
+ * Exit   : 0 always — this is an amplifier, never a gate; it cannot block a prompt.
+ *
+ * Fail-open: any error (no env flag, bad stdin, missing/short observations log,
+ * unreadable state) emits nothing and exits 0. State at
+ * ~/.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";
+const ENABLED_VALUES = new Set(["1", "on", "true", "yes"]);
+const MAX_BRIEFED_KEYS = 1000;
+function isEnabled() {
+    const flag = (process.env.CLAUDE_RECALL_BRIEFING ?? "").trim().toLowerCase();
+    return ENABLED_VALUES.has(flag);
+}
+function readStdin() {
+    try {
+        return readFileSync(0, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function resolveHome() {
+    return process.env.HOME ?? process.env.USERPROFILE ?? homedir();
+}
+function resolveProjectRoot() {
+    const fromEnv = process.env.CLAUDE_PROJECT_DIR;
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (root)
+            return root;
+    }
+    catch {
+        // not in a git repo
+    }
+    return "global";
+}
+function instinctsDir(home) {
+    const hash = createHash("sha256").update(resolveProjectRoot()).digest("hex").slice(0, 12);
+    return join(home, ".claude", "instincts", hash);
+}
+function readObservations(dir) {
+    const path = join(dir, "observations.jsonl");
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const rows = [];
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            rows.push(JSON.parse(trimmed));
+        }
+        catch {
+            // skip a malformed line; never let one bad row sink the briefing
+        }
+    }
+    return rows;
+}
+function readState(dir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, "recall-briefing-session.json"), "utf8"));
+        if (parsed && typeof parsed.briefed === "object" && parsed.briefed !== null)
+            return parsed;
+    }
+    catch {
+        // missing or malformed → fresh state
+    }
+    return { briefed: {} };
+}
+function writeState(dir, state, sessionKey) {
+    try {
+        const keys = Object.keys(state.briefed);
+        // Bound growth: if the map is huge, keep only the most recent run plus this one.
+        const briefed = keys.length >= MAX_BRIEFED_KEYS ? {} : state.briefed;
+        briefed[sessionKey] = new Date().toISOString();
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "recall-briefing-session.json"), `${JSON.stringify({ briefed }, null, 2)}\n`);
+    }
+    catch {
+        // fail-open: a missed state write at worst briefs twice; it never blocks
+    }
+}
+function emit(additionalContext) {
+    if (additionalContext !== null) {
+        process.stdout.write(`${JSON.stringify({
+            hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext },
+        })}\n`);
+    }
+    process.exit(0);
+}
+function main() {
+    if (!isEnabled()) {
+        emit(null);
+        return;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(readStdin());
+    }
+    catch {
+        emit(null);
+        return;
+    }
+    const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
+    if (prompt.length === 0) {
+        emit(null);
+        return;
+    }
+    const sessionKey = typeof payload.session_id === "string" && payload.session_id ? payload.session_id : "no-session";
+    const home = resolveHome();
+    const dir = instinctsDir(home);
+    const state = readState(dir);
+    const alreadyBriefed = Object.prototype.hasOwnProperty.call(state.briefed, sessionKey);
+    const observations = readObservations(dir);
+    const index = buildIndex(observations);
+    const hits = query(index, prompt, { k: DEFAULT_MAX_HITS });
+    const decision = decideBriefing({ enabled: true, alreadyBriefed, prompt, hits });
+    if (!decision.shouldBrief || decision.reminder === null) {
+        emit(null);
+        return;
+    }
+    writeState(dir, state, sessionKey);
+    emit(decision.reminder);
+}
+try {
+    main();
+}
+catch {
+    // Absolute fail-open backstop: never let a hook bug block a prompt.
+    process.exit(0);
+}