@mmerterden/multi-agent-pipeline 20.28.0 → 20.29.0

package/pipeline/scripts/agent-guard.py

@@ -2,15 +2,18 @@
 """Decision core for agent-guard.sh (see that file for the hook contract).
 
 Reads the PreToolUse payload JSON on stdin and prints exactly one decision:
-  BLOCK_ATTRIB | BLOCK_FORCE | BLOCK_UNATTENDED<TAB>reason | BLOCK_PARSE | OK
+  BLOCK_ATTRIB | BLOCK_FORCE | BLOCK_NOVERIFY<TAB>reason | BLOCK_READONLY<TAB>reason |
+  BLOCK_UNATTENDED<TAB>reason | BLOCK_PARSE | ASK<TAB>hook-json |
+  DENY<TAB>reason | OK
 
 Never executes the command. shlex.split only tokenizes shell-like text; a
 `$(...)` in the command is a literal token, never a subshell. The processes it
 does start are read-only `git rev-parse` / `git diff --name-only` calls on a
 path, with argv and no shell.
 
-Attended (MULTI_AGENT_UNATTENDED unset): the attribution and force-push rules
-only, and any error prints OK (fail-open) so a guard bug cannot break a
+Attended (MULTI_AGENT_UNATTENDED unset): the attribution (argv and -F
+message files), force-push and hook-skipping rules, plus the confirmations in
+_guard_rules.ask_reason, and any error prints OK (fail-open) so a guard bug cannot break a
 legitimate tool call. Unattended: unattended_policy.py is consulted as well,
 and an error prints BLOCK_PARSE (fail-closed).
 """
@@ -22,6 +25,9 @@ import signal
 import sys
 import unicodedata
 
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import _guard_rules  # noqa: E402
+
 # An internal deadline well under the hook timeout: if the guard cannot decide
 # in this long, it prints the blocking verdict when unattended (fail-closed) and
 # the allow verdict when attended (a guard bug must not break legitimate work).
@@ -43,6 +49,7 @@ PROTECTED = {"main", "master", "develop"}
 REMOTES = {"origin", "upstream"}
 ATTRIBUTION = re.compile(
     r"co-authored-by:\s*(claude|anthropic|opus|sonnet|haiku|fable)"
+    r"|co-authored-by:[^\n]*\bcopilot\b"
     r"|noreply@anthropic\.com"
     r"|generated with\s+.*claude"
     r"|\U0001F916\s*generated"
@@ -276,16 +283,62 @@ def _nested_payload(toks: list):
     return None
 
 
+def _attributed(text: str) -> bool:
+    return bool(ATTRIBUTION.search(text) or ATTRIBUTION.search(normalize_for_match(text)))
+
+
+# The directory the hook payload names as the session's cwd; message files a
+# command names relative to it are read from there.
+PAYLOAD_CWD = {"dir": None}
+
+
+def _command_rules(cmd: str) -> str:
+    """Rules 1b, 3, 4 and 5, judged on the line's simple commands with heredoc
+    bodies removed and only where the program is the command word
+    (_guard_rules.command_segments / command_word). A `cd` moves later
+    segments into another directory."""
+    pending_ask = None
+    cwd = None
+    for seg, toks in _guard_rules.command_segments(cmd):
+        if toks and toks[0] in ("{", "}"):
+            toks = toks[1:]
+        if toks and toks[0] in ("cd", "pushd"):
+            cwd = _cd_target(toks, cwd)
+            continue
+        here = cwd or PAYLOAD_CWD["dir"]
+        # Rule 1b: the commit message given as a file (-F / --file).
+        for path in _guard_rules.message_files(toks):
+            if _attributed(_guard_rules.read_bounded(path, here)):
+                return "BLOCK_ATTRIB"
+        # Rule 5: history writes in a repository listed as read-only.
+        reason = _guard_rules.read_only_git_reason(toks, here)
+        if reason:
+            return "BLOCK_READONLY\t" + reason
+        # Rule 3: skipping the repository's git hooks.
+        reason = _guard_rules.no_verify(toks)
+        if reason:
+            return "BLOCK_NOVERIFY\t" + reason
+        # Rule 4: writes a person confirms (issue closure, Jira transition).
+        ask = _guard_rules.ask_reason(toks, seg, here)
+        if ask and not pending_ask:
+            pending_ask = "ASK\t" + ask
+    return pending_ask or "OK"
+
+
 def decide(cmd: str, depth: int = 0) -> str:
     low = cmd.lower()
     segs = segments(flatten(cmd))
 
-    # Rule 1: AI attribution inside a git commit.
+    # Rule 1: AI attribution inside a git commit, read from what the commit
+    # records (_guard_rules.commit_text), never from a neighbouring command.
     commits = re.search(r"git\s+commit", low) or any(
         git_subcommand(toks) == "commit" for _, toks in segs
     )
-    if commits and (ATTRIBUTION.search(cmd) or ATTRIBUTION.search(normalize_for_match(cmd))):
+    if commits and _attributed(_guard_rules.commit_text(cmd, PAYLOAD_CWD["dir"])):
         return "BLOCK_ATTRIB"
+    if commits and _guard_rules.ai_generated(cmd, PAYLOAD_CWD["dir"]):
+        return "BLOCK_ATTRIB"
+    pending_ask = None
 
     # Rule 2: force-push to a protected branch. Evaluate each push segment on its
     # own so a neighbouring command's flags cannot implicate it. A `cd` earlier
@@ -301,7 +354,9 @@ def decide(cmd: str, depth: int = 0) -> str:
         payload = _nested_payload(toks)
         if payload and depth < MAX_DEPTH:
             verdict = decide(payload, depth + 1)
-            if verdict != "OK":
+            if verdict.startswith("ASK"):
+                pending_ask = pending_ask or verdict
+            elif verdict != "OK":
                 return verdict
             continue
         if git_subcommand(toks) != "push" and not re.search(r"git\s+push", seg.lower()):
@@ -310,7 +365,12 @@ def decide(cmd: str, depth: int = 0) -> str:
         if verdict != "OK":
             return verdict
 
-    return "OK"
+    verdict = _command_rules(cmd)
+    if verdict.startswith("ASK"):
+        return pending_ask or verdict
+    if verdict != "OK":
+        return verdict
+    return pending_ask or "OK"
 
 
 def _cd_target(toks: list, cwd):
@@ -530,6 +590,46 @@ def fallback_verdict(text: str) -> str:
     return "OK"
 
 
+FILE_TOOLS = {"Edit", "Write", "NotebookEdit", "MultiEdit"}
+
+
+# Permission modes in which a hook's "ask" has no documented prompt to raise.
+# The hooks reference documents "ask" as forcing a prompt (and states it for
+# auto mode); it says nothing for bypassPermissions or dontAsk, where the
+# permission prompt is switched off. There the guard denies with the reason
+# and names the channel the user's answer travels through: the model asks,
+# confirm-command.mjs records a yes for that exact command (sha256, ten
+# minutes, one use), and the rerun finds it. Attended only: unattended, the
+# record is never read.
+NO_PROMPT_MODES = {"bypassPermissions", "dontAsk"}
+
+
+def ask_verdict(reason: str, data: dict, strict: bool) -> str:
+    """ASK<TAB>json for a prompt, DENY<TAB>reason where no prompt can be
+    raised, BLOCK_UNATTENDED<TAB>reason when nobody is there to answer."""
+    if strict:
+        return "BLOCK_UNATTENDED\t" + reason
+    if data.get("permission_mode") in NO_PROMPT_MODES:
+        # With prompts switched off the native ask cannot be raised, so the
+        # recorded confirmation stands in for it. In every other mode the
+        # prompt is the confirmation and a record must not skip it.
+        if _guard_rules.confirmed((data.get("tool_input") or {}).get("command", "")):
+            return "OK"
+        return (
+            "DENY\t" + reason + " (permission prompts are off in this mode: ask the user with AskUserQuestion; on yes, "
+            "record it with node \"$HOME/.claude/scripts/confirm-command.mjs\" --command '<the exact command>' "
+            "and run the command again, unchanged, within 10 minutes)"
+        )
+    out = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "ask",
+            "permissionDecisionReason": "agent-guard: " + reason,
+        }
+    }
+    return "ASK\t" + json.dumps(out)
+
+
 def unattended() -> bool:
     """MULTI_AGENT_UNATTENDED=1 in the hook's own environment - the launcher's,
     never anything the run wrote (lib/unattended.sh ma_unattended)."""
@@ -687,9 +787,20 @@ def main() -> None:
     try:
         data = json.loads(seen["text"])
         cmd = (data.get("tool_input") or {}).get("command", "")
+        if isinstance(data.get("cwd"), str) and data.get("cwd"):
+            PAYLOAD_CWD["dir"] = data["cwd"]
         if isinstance(cmd, str):
             seen["text"], seen["raw"] = cmd, False
         verdict = decide(cmd) if isinstance(cmd, str) and cmd else "OK"
+        if verdict == "OK" and data.get("tool_name") in FILE_TOOLS:
+            ti = data.get("tool_input") or {}
+            reason = _guard_rules.read_only_file_reason(
+                ti.get("file_path") or ti.get("notebook_path") or "", PAYLOAD_CWD["dir"]
+            )
+            if reason:
+                verdict = "BLOCK_READONLY\t" + reason
+        if verdict.startswith("ASK"):
+            verdict = ask_verdict(verdict.split("\t", 1)[1], data, strict)
         if verdict == "OK" and strict:
             sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
             import unattended_policy

package/pipeline/scripts/agent-guard.sh

@@ -2,10 +2,20 @@
 # agent-guard.sh  -  PreToolUse guard for the multi-agent pipeline.
 #
 # Turns prompt-level rules into deterministic, OS-enforced gates:
-#   1. No AI/assistant attribution in git commit messages (Co-Authored-By: Claude,
-#      "Generated with Claude Code", robot emoji, Anthropic no-reply address).
+#   1. No AI/assistant attribution in git commit messages (Co-Authored-By: Claude
+#      or Copilot, "Generated with Claude Code", "Generated by AI", robot emoji,
+#      Anthropic no-reply address), on the command line or in a `-F` file.
 #   2. No force-push to a protected branch (main / master / develop), whichever
 #      remote, push options or `git -C` directory the push names.
+#   2b. No skipping the repository's git hooks (commit / push / merge with
+#      --no-verify, commit -n, -c core.hooksPath=...).
+#   2c. No literal credential on a Bash command line (argv-secret-scan.mjs).
+#   2e. No Edit / Write, git commit or git push inside a repository listed in
+#      prefs.global.readOnlyRepos (a reference checkout).
+#   2d. A person confirms (permissionDecision "ask") closing a GitHub issue, a
+#      PR body with Closes/Fixes/Resolves #N and a Jira transition POST. Where
+#      the permission mode raises no prompt (bypassPermissions, dontAsk) the
+#      call is denied with the reason instead; unattended it is blocked.
 #   3. With MULTI_AGENT_UNATTENDED=1 in the hook's environment only: no outward
 #      writes (push, PR, issue, tracker publishers, mutating API calls), no
 #      Keychain reads, no fetch outside the network allowlist, no package
@@ -15,7 +25,7 @@
 # Contract (Claude Code PreToolUse hook, matcher Bash and Edit|Write|NotebookEdit):
 #   - Reads the tool-call JSON on stdin: {"tool_name":..., "tool_input":{...}, "cwd":...}.
 #   - Exit 2  -> BLOCK the tool call (reason on stderr, shown to the model).
-#   - Exit 0  -> allow.
+#   - Exit 0  -> allow, or, with hook JSON on stdout, ask the user to confirm.
 #
 # Safety design:
 #   - The command string is ONLY parsed/pattern-matched, NEVER executed or eval'd
@@ -52,6 +62,27 @@ CUR_BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
 
 DECISION="$(printf '%s' "$PAYLOAD" | CUR_BRANCH="$CUR_BRANCH" python3 "$HELPER" 2>/dev/null || true)"
 
+# A literal credential on a Bash command line is refused before anything else
+# is said about the call (argv-secret-scan.mjs, the outbound gate's credential
+# shapes). Only rule names are printed, never the value.
+case "$DECISION" in
+  OK|ASK*|DENY*)
+    case "$PAYLOAD" in
+      *'"tool_name":"Bash"'*|*'"tool_name": "Bash"'*)
+        if command -v node >/dev/null 2>&1 && [ -f "$HERE/argv-secret-scan.mjs" ]; then
+          RULES="$(printf '%s' "$PAYLOAD" | node "$HERE/argv-secret-scan.mjs" 2>/dev/null)"
+          if [ "$?" = "7" ]; then
+            echo "BLOCKED by agent-guard: the command line carries a literal credential ($RULES)." >&2
+            echo "Read it from the credential store or an environment variable instead; a value typed" >&2
+            echo "into argv lands in the transcript, the process table and every log that echoes it." >&2
+            exit 2
+          fi
+        elif [ "$STRICT" = "1" ]; then
+          refuse_unjudged "node or argv-secret-scan.mjs is unavailable for the credential scan"
+        fi ;;
+    esac ;;
+esac
+
 case "$DECISION" in
   BLOCK_ATTRIB)
     echo "BLOCKED by agent-guard: the commit message carries AI/assistant attribution." >&2
@@ -62,6 +93,22 @@ case "$DECISION" in
     echo "BLOCKED by agent-guard: force-push to a protected branch (main/master/develop) is not allowed." >&2
     echo "Rewriting shared history is a data-loss risk. Push a normal commit, or force-push a feature branch." >&2
     exit 2 ;;
+  BLOCK_READONLY*)
+    echo "BLOCKED by agent-guard: ${DECISION#BLOCK_READONLY?}." >&2
+    echo "Read it, cite it and port the change to the repository you are working in." >&2
+    exit 2 ;;
+  BLOCK_NOVERIFY*)
+    echo "BLOCKED by agent-guard: ${DECISION#BLOCK_NOVERIFY?}." >&2
+    echo "The repository's own hooks (lint, tests, secret checks) are part of the commit contract." >&2
+    echo "Fix what they report and commit without skipping them." >&2
+    exit 2 ;;
+  ASK*)
+    # The hook JSON the host reads: permissionDecision "ask" forces a prompt.
+    printf '%s\n' "${DECISION#ASK?}"
+    exit 0 ;;
+  DENY*)
+    echo "BLOCKED by agent-guard: ${DECISION#DENY?}." >&2
+    exit 2 ;;
   BLOCK_UNATTENDED*)
     echo "BLOCKED by agent-guard (unattended policy): ${DECISION#BLOCK_UNATTENDED?}." >&2
     echo "This run has nobody watching it. Outward writes go through pr-request.json and the runner;" >&2

package/pipeline/scripts/argv-secret-scan.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * argv-secret-scan.mjs  -  a Bash command line that carries a literal
+ * credential is refused before it runs.
+ *
+ * agent-guard.sh pipes the PreToolUse payload here for every Bash call. A
+ * credential typed into a command line lands in the transcript, the shell
+ * history of whatever runs it, the process table and any log that echoes
+ * argv; the outbound gate (lib/outbound-gate.mjs) already knows the shapes, so
+ * its `certain` rules are applied to the command text.
+ *
+ * Three adjustments keep it to credentials that can leak:
+ *   - A credential URL to a local host (localhost, 127.x, ::1, *.local) or with
+ *     a placeholder pair (`postgres:postgres`, `user:pass`) is a dev DSN, not a
+ *     secret, and is removed before the scan (withoutLocalCredentials).
+ *   - Shell variable references (`$TOKEN`, `${TOKEN}`) and command
+ *     substitutions (`$(...)`) are removed before the scan. A command that
+ *     reads its secret from the environment or the credential store is the
+ *     correct way to do it, and a clone URL whose password part is
+ *     `${TOKEN}` must not read as a URL with credentials.
+ *   - Rules that match a marker rather than a value
+ *     (`service-account-json`, `private-key-block`) are skipped: grepping for
+ *     the marker is how an audit finds the leak.
+ *
+ * Output never contains the matched value, only rule names.
+ *
+ * Exit: 0 clean (or not a Bash payload), 7 a literal credential found,
+ * 2 the payload could not be read.
+ *
+ * @module pipeline/scripts/argv-secret-scan
+ */
+
+import { readFileSync } from "node:fs";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { scan } from "../lib/outbound-gate.mjs";
+
+const MARKER_RULES = new Set(["service-account-json", "private-key-block"]);
+
+/** The command with variable references and substitutions removed. */
+export function withoutReferences(cmd) {
+  let out = String(cmd);
+  // Innermost substitutions first, until none are left.
+  for (let i = 0; i < 8 && /\$\([^()]*\)/.test(out); i++) out = out.replace(/\$\([^()]*\)/g, "");
+  out = out.replace(/`[^`]*`/g, "");
+  out = out.replace(/\$\{[^}]*\}/g, "");
+  out = out.replace(/\$[A-Za-z_][A-Za-z0-9_]*/g, "");
+  return out;
+}
+
+const URL_CREDS = /\b([a-z][a-z0-9+.-]*:\/\/)([^\s/:@]+):([^\s/@]+)@(\[[^\]\s]+\]|[^\s/:?#'"]+)/gi;
+const LOCAL_HOST =
+  /^(?:localhost|127(?:\.\d{1,3}){3}|0\.0\.0\.0|\[::1\]|::1|[\w.-]+\.(?:local|localhost|test|example|invalid))$/i;
+const PLACEHOLDERS = new Set([
+  "user",
+  "username",
+  "pass",
+  "password",
+  "secret",
+  "postgres",
+  "root",
+  "admin",
+  "test",
+  "example",
+  "changeme",
+  "default",
+]);
+
+/**
+ * The command with credentials removed from URLs that cannot leak anything:
+ * a local host (a dev database DSN), or a placeholder pair (`user:pass`,
+ * `postgres:postgres`). A credential URL to any other host is left for the
+ * scan.
+ */
+export function withoutLocalCredentials(cmd) {
+  return String(cmd).replace(URL_CREDS, (all, scheme, user, pass, host) => {
+    const placeholder =
+      user === pass ||
+      (PLACEHOLDERS.has(user.toLowerCase()) && PLACEHOLDERS.has(pass.toLowerCase()));
+    return LOCAL_HOST.test(host) || placeholder ? `${scheme}${host}` : all;
+  });
+}
+
+/**
+ * Names of the credential rules a command line matches.
+ *
+ * @param {string} cmd
+ * @returns {string[]}
+ */
+export function literalSecrets(cmd) {
+  if (typeof cmd !== "string" || !cmd) return [];
+  const found = scan(withoutLocalCredentials(withoutReferences(cmd))).filter(
+    (f) => f.certain && !MARKER_RULES.has(f.rule),
+  );
+  return [...new Set(found.map((f) => f.rule))];
+}
+
+function main() {
+  let payload;
+  try {
+    payload = JSON.parse(readFileSync(0, "utf8"));
+  } catch {
+    process.exitCode = 2;
+    return;
+  }
+  if (payload?.tool_name !== "Bash") return;
+  const rules = literalSecrets(payload?.tool_input?.command);
+  if (rules.length) {
+    process.stdout.write(`${rules.join(", ")}\n`);
+    process.exitCode = 7;
+  }
+}
+
+if (invokedDirectly(import.meta.url)) main();

package/pipeline/scripts/autopilot-runner.mjs

@@ -82,6 +82,7 @@ import { runMain } from "../lib/fatal.mjs";
 import { LIVE_STATUSES, resolveClaudeBin } from "../lib/claude-sessions.mjs";
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
 import { readRegularJson } from "../lib/regular-file.mjs";
+import { completionGaps } from "../lib/run-completion.mjs";
 import { messages, outputLanguage } from "../lib/user-facing.mjs";
 import {
   ARTIFACTS_SUBDIR,
@@ -1152,7 +1153,10 @@ export function prFromState(state) {
  *
  * "finished with no PR" is deliberately not "failed": a run can stop
  * legitimately without opening one, and calling that a failure would put a
- * healthy item into the retry path.
+ * healthy item into the retry path. It is only that when the state earns it
+ * (lib/run-completion.mjs): a `complete` written below the mode's last phase,
+ * without Phase 4 evidence or without a plan-coverage verdict is
+ * `stopped-incomplete`, which is retried, not filed as finished.
  */
 export function outcomeFor(supervised, state, prUrl) {
   if (prUrl) return OUTCOME.PR_OPENED;
@@ -1166,7 +1170,9 @@ export function outcomeFor(supervised, state, prUrl) {
   if (rateLimited({ row: supervised.lastRow, state })) return OUTCOME.RATE_LIMITED;
   if (state && state.verificationFailed) return OUTCOME.VERIFICATION_FAILED;
   const status = state && state.status;
-  if (status === "complete" || status === "completed") return OUTCOME.COMPLETED_NO_PR;
+  if (status === "complete" || status === "completed") {
+    return completionGaps(state).length ? OUTCOME.STOPPED_INCOMPLETE : OUTCOME.COMPLETED_NO_PR;
+  }
   if (status === "failed") return OUTCOME.FAILED;
   return state ? `stopped-${status || "unknown"}` : OUTCOME.NO_STATE;
 }

package/pipeline/scripts/confirm-command.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * confirm-command.mjs  -  carry the user's yes for one command to agent-guard.
+ *
+ * agent-guard asks before a write a person must confirm (closing an issue, a
+ * PR body that closes one, a Jira transition POST). In bypassPermissions and
+ * dontAsk no permission prompt is raised, so the guard denies and says to ask
+ * the user with AskUserQuestion. On a yes, this records it: a file named by the
+ * sha256 of the exact command under <log root>/confirmations/. The next time
+ * agent-guard sees that exact command it consumes the record and lets it run;
+ * a record older than ten minutes, or for any other command, does nothing.
+ *
+ * Attended only. Under MULTI_AGENT_UNATTENDED=1 nobody gave an answer, so the
+ * script refuses (exit 2) and agent-guard never reads a record there.
+ *
+ * Usage:  confirm-command.mjs --command '<the exact command>'
+ * Exit:   0 recorded, 2 usage or unattended, 3 could not write
+ *
+ * @module pipeline/scripts/confirm-command
+ */
+
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { isUnattended } from "../lib/unattended.mjs";
+
+/** Where records live; agent-guard's _guard_rules.confirmations_dir agrees. */
+export function confirmationsDir(env = process.env) {
+  const root = env.LOGS_ROOT || join(homedir(), ".claude", "logs", "multi-agent");
+  return join(root, "confirmations");
+}
+
+/** The record path for one command. */
+export function recordPath(command, env = process.env) {
+  const digest = createHash("sha256").update(command, "utf8").digest("hex");
+  return join(confirmationsDir(env), `${digest}.json`);
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const i = argv.indexOf("--command");
+  const command = i === -1 ? undefined : argv[i + 1];
+  if (typeof command !== "string" || !command) {
+    process.stderr.write("usage: confirm-command.mjs --command '<the exact command>'\n");
+    process.exitCode = 2;
+    return;
+  }
+  if (isUnattended()) {
+    process.stderr.write("confirm-command: refused, nobody can confirm in an unattended run\n");
+    process.exitCode = 2;
+    return;
+  }
+  try {
+    mkdirSync(confirmationsDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(recordPath(command), `${JSON.stringify({ at: new Date().toISOString() })}\n`, {
+      mode: 0o600,
+    });
+  } catch (err) {
+    process.stderr.write(`confirm-command: ${err.message}\n`);
+    process.exitCode = 3;
+    return;
+  }
+  process.stdout.write("confirm-command: recorded for 10 minutes, one use\n");
+}
+
+if (invokedDirectly(import.meta.url)) runMain("confirm-command", main, { code: 3 });

package/pipeline/scripts/doctor.mjs

@@ -61,6 +61,7 @@ import {
 } from "../lib/unattended-settings-location.mjs";
 import { prefsHosts, profileGaps } from "../lib/unattended-profile-check.mjs";
 import { xcodeSkillsStatus } from "../lib/xcode-plugin.mjs";
+import { hookReport } from "../lib/hook-registration.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const HOME = homedir();
@@ -94,6 +95,7 @@ const CHECK_IDS = [
   "prefs-valid",
   "identity",
   "hook-coverage",
+  "hook-reachability",
   "credential-mapping",
   "credential-liveness",
   "store-reference",
@@ -515,6 +517,57 @@ function checkHookCoverage() {
   ok("hook-coverage");
 }
 
+// hook-coverage asks whether each template command appears in settings.json
+// at all. This asks what Claude Code will actually run: per event, a matcher
+// that covers the template's tool names, the script present under
+// ~/.claude/scripts, no disableAllHooks; and which preferences do nothing
+// because their hook is missing (lib/hook-registration.mjs).
+function checkHookReachability() {
+  const tpl = join(CLAUDE, "templates", "claude-hooks.json");
+  if (!existsSync(tpl)) {
+    skip("hook-reachability", "no hooks template installed to compare against");
+    return;
+  }
+  const r = hookReport({ templatePath: tpl, home: HOME });
+  if (r.error) {
+    skip("hook-reachability", r.error);
+    return;
+  }
+  if (r.ok) {
+    ok("hook-reachability");
+    return;
+  }
+  const parts = [];
+  if (r.disabled) parts.push(r.disabled);
+  else if (r.missing.length) {
+    const names = [
+      ...new Set(
+        r.missing.map(
+          (m) => `${m.script || m.command} on ${m.event}${m.matcher ? ` ${m.matcher}` : ""}`,
+        ),
+      ),
+    ];
+    parts.push(
+      `${r.missing.length} template hook(s) Claude Code will not run: ${names.slice(0, 4).join(", ")}${names.length > 4 ? ` and ${names.length - 4} more` : ""}`,
+    );
+  }
+  if (r.inert.length) {
+    parts.push(
+      `inert preference(s): ${r.inert.map((i) => `${i.pref} (needs ${i.script})`).join(", ")}`,
+    );
+  }
+  report(
+    "hook-reachability",
+    "WARN",
+    parts.join("; "),
+    `merge ${tpl} into ${join(CLAUDE, "settings.json")} (or run ${hostCommand("setup", HERE)})`,
+    [
+      ...r.missing.map((m) => `${m.event} ${m.matcher || "-"} ${m.command}: ${m.why}`),
+      ...r.inert.map((i) => `prefs.global.${i.pref} -> ${i.script}`),
+    ],
+  );
+}
+
 function credentialInventory() {
   const inv = join(CLAUDE, "lib", "credential-inventory.sh");
   if (!existsSync(inv)) return null;
@@ -1403,6 +1456,7 @@ function main() {
   checkPrefsValid();
   checkIdentity();
   checkHookCoverage();
+  checkHookReachability();
   checkCredentials(credentialInventory());
   checkStoreReference();
   checkEmbeddedCredentials();

package/pipeline/scripts/evidence-gate.mjs

@@ -75,7 +75,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
-import { gateContext } from "./gate-ledger.mjs";
+import { ATTENDED_RECORDED, gateContext } from "./gate-ledger.mjs";
 
 const LEDGER = fileURLToPath(new URL("./gate-ledger.mjs", import.meta.url));
 
@@ -203,15 +203,19 @@ function parseArgs(argv) {
 // the bytes are gone. The verdict is short today; the verdict is also the only
 // thing a caller reads, so losing half of it is the one failure that matters.
 let verdictExtra = {};
-// Only while the quality gates are active (lib/unattended.mjs, gatesActive):
-// one synchronous append, so the verdict and its ledger entry
+// While the quality gates are active (lib/unattended.mjs, gatesActive), and
+// for the build and test claims of an attended run: one synchronous append, so the verdict and its ledger entry
 // cannot come apart. A ledger problem is reported and never changes the verdict.
 let ledgerClaim = null;
 let ledgerState = null;
 function ledger(verdict, reason, extra) {
   if (!ledgerClaim) return;
   const ctx = gateContext({ statePath: ledgerState });
-  if (!ctx.active) return;
+  // Attended, only the build and test claims are recorded (marked attended):
+  // the attended commit check reads them. Without a run state there is
+  // nothing to record into.
+  if (!ctx.active && !(ctx.statePath && ATTENDED_RECORDED.has(`evidence-gate/${ledgerClaim}`)))
+    return;
   const detail = { reason, ...(extra.summary ? { summary: extra.summary } : {}) };
   if (verdictExtra.stack) detail.stack = verdictExtra.stack;
   const argv = [LEDGER, "append", "--gate", `evidence-gate/${ledgerClaim}`, "--verdict", verdict];