@event4u/agent-config 14.17.0 → 14.19.0

package/src/scripts/hooks/permission_gate.ts

@@ -0,0 +1,117 @@
+/**
+ * permission_gate — whether a `pre_tool_use` call gets an explicit
+ * `permissionDecision`, and which one.
+ *
+ * Four independent conditions, each able to withhold an allow on its own: the
+ * host offers the field on `pre_tool_use` only; the dispatcher's reduced
+ * severity must already be `allow`; no concern may have voted `ask` or `deny`;
+ * and the call itself must be category A. An allow is emitted only when all
+ * four hold, so widening any one of them is a visible edit rather than an
+ * emergent effect.
+ *
+ * Separate from `dispatch_hook` because that file is against the per-file
+ * source-size budget, and because the seam is real: the dispatcher runs
+ * concerns and reduces exit codes, this module reads the result and decides
+ * what the host is told about permission.
+ */
+import { isCategoryA, type ToolInput } from "./category_a.js";
+import {
+  composePermissionDecision,
+  type PermissionDecision,
+  type PermissionEmission,
+} from "./host_semantics.js";
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function _isObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Mirrors `dispatch_hook.EXIT_ALLOW` / `EXIT_BLOCK`; imported would be a cycle. */
+const EXIT_ALLOW = 0;
+const EXIT_BLOCK = 1;
+
+/** The host's `tool_name`, or `""` when the event carries none. */
+export function _payload_tool_name(envelope: JsonObject): string {
+  const payload = envelope["payload"];
+  if (!_isObject(payload)) return "";
+  const raw = payload["tool_name"];
+  return typeof raw === "string" ? raw : "";
+}
+
+/** The host's `tool_input` object, or `{}` when the event carries none. */
+export function _payload_tool_input(envelope: JsonObject): ToolInput {
+  const payload = envelope["payload"];
+  if (!_isObject(payload)) return {};
+  const raw = payload["tool_input"];
+  return _isObject(raw) ? (raw as ToolInput) : {};
+}
+
+/**
+ * The root every category-A path argument must resolve inside.
+ *
+ * The host's own `cwd` wins over `workspace_root` because the latter is the
+ * dispatcher's process cwd, which in a worktree is the parent checkout rather
+ * than the tree the user is working in — confining against it would admit a
+ * path outside the tree the call actually runs in.
+ */
+export function _working_tree_root(envelope: JsonObject): string {
+  const payload = envelope["payload"];
+  if (_isObject(payload) && typeof payload["cwd"] === "string" && payload["cwd"].trim()) {
+    return payload["cwd"];
+  }
+  const workspace = envelope["workspace_root"];
+  return typeof workspace === "string" ? workspace : "";
+}
+
+/**
+ * One concern's permission verdict.
+ *
+ * A block is a deny. A concern may also say `{"decision":"ask"}` on stdout —
+ * the field has been recorded in the feedback file since v1 and read by
+ * nothing, so an advisory concern that wanted a confirmation got silence.
+ * `ask` is honoured regardless of the exit code: an advisory concern cannot
+ * block and must not have to in order to be heard. Everything else abstains,
+ * which composes as `allow`.
+ */
+export function _concern_permission_verdict(
+  rc: number,
+  reply: JsonObject,
+): PermissionDecision {
+  if (rc === EXIT_BLOCK) return "deny";
+  const stated = String(reply["decision"] ?? "").trim().toLowerCase();
+  if (stated === "ask") return "ask";
+  if (stated === "deny") return "deny";
+  return "allow";
+}
+
+/**
+ * The permission field to hand the host, or `null` to keep the legacy envelope.
+ *
+ * Four independent conditions, each able to withhold the allow on its own:
+ * the host offers the field on `pre_tool_use` only; the reduced severity must
+ * already be `allow`; no concern may have voted `ask` or `deny`; and the call
+ * itself must be category A. An allow is emitted only when all four hold, so
+ * widening any one of them is a visible edit rather than an emergent effect.
+ */
+export function _permission_for(
+  event: string,
+  envelope: JsonObject,
+  final_rc: number,
+  verdicts: readonly PermissionDecision[],
+): PermissionEmission | null {
+  if (event !== "pre_tool_use") return null;
+  if (final_rc !== EXIT_ALLOW) return null;
+  if (composePermissionDecision(verdicts) !== "allow") return null;
+  const tool_name = _payload_tool_name(envelope);
+  if (!isCategoryA(tool_name, _payload_tool_input(envelope), _working_tree_root(envelope))) {
+    return null;
+  }
+  return {
+    decision: "allow",
+    reason:
+      `agent-config: category-A ${tool_name} inside the working tree — ` +
+      `no concern gates it and none asked to.`,
+  };
+}

package/src/scripts/hooks/push_settle_hook.ts

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse push-settle reminder — the second half of "a push closes its own
+ * loop", and the half no gate could reach before.
+ *
+ * WHY THIS EXISTS — measured, not hypothetical.
+ *
+ * The pre-push hook answers "is this push safe to make". Nothing answered "is
+ * this push finished", and the difference is what reaches the user. Over the 30
+ * sessions and 50 PRs preceding 2026-09-04:
+ *
+ *   · 22 of 30 sessions ran `gh run view --log-failed` — i.e. a red CI job was
+ *     routine, not exceptional.
+ *   · 17 of the 36 PRs whose workflow runs were still readable carried at least
+ *     one FAILED run (56 failed runs in total).
+ *   · 20 of 50 PRs carried a follow-up `fix(ci|gates|budget)…` commit — 41 of
+ *     them — every one a repair made after a push that had looked done.
+ *
+ * The push itself always succeeded. What failed was the ending: the agent
+ * pushed, reported the work as delivered, and the red arrived afterwards, where
+ * the user found it. `verify-before-complete` already forbids that, and it is
+ * model-carried at exactly the moment a turn feels finished — which is the
+ * moment a behavior rule is least likely to fire.
+ *
+ * So this hook fires where the fact is deterministic: right after a shell
+ * command that ACTUALLY ADVANCED A REMOTE REF. It reads git's own push report
+ * rather than the exit code or the command text — a wrapper that pushes
+ * (`task push-ready`, a deploy script, a `git` alias) advances a ref without
+ * the words `git push` appearing anywhere, and those are the pushes furthest
+ * from a human's eye. So:
+ *
+ *   · `Everything up-to-date`  → nothing was pushed, nothing to settle, silent.
+ *   · `! [rejected]`           → the push did not happen; the agent already has
+ *                                a visible failure and does not need a second.
+ *   · `--delete`              → no ref advanced; silent.
+ *   · `--dry-run`             → prints the same report as a real push, so this
+ *                                one is caught on the COMMAND, not the output.
+ *
+ * It resolves the PR number for the pushed branch itself (one `gh` call, best
+ * effort) so the reminder carries the literal next command rather than a flag —
+ * per `active-remediation` § "The ask carries fixes, not a flag". With no `gh`,
+ * no auth, or no open PR, it names the branch and the two-step instead, and
+ * never claims a PR number it did not read.
+ *
+ * Warn only, never blocks (fail_closed: false). A push that is genuinely WIP is
+ * a legitimate thing to leave unsettled; what is not legitimate is ENDING THE
+ * TURN on one silently.
+ *
+ * Exit codes (dispatcher contract): 0 allow · 2 warn (+ `{decision,reason,
+ * additional_context}` JSON on stdout).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { readHookStdin } from "./hook_stdin.js";
+
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+// Tool names across platforms whose command field carries a shell command
+// (kept in lock-step with pr_url_reminder_hook.COMMAND_TOOLS).
+const COMMAND_TOOLS: ReadonlySet<string> = new Set([
+  "launch-process",
+  "launch_process",
+  "Bash",
+  "BashTool",
+  "run-process",
+  "runProcess",
+  "shell",
+  "execute_shell",
+  "RunShellCommand",
+]);
+
+/**
+ * A push git was told NOT to actually make. `git push --dry-run` prints the SAME
+ * ref-advance report as a real push, so the command is where the two are told
+ * apart — and it is the ONLY thing the command is consulted for.
+ *
+ * Deliberately not the other way round. The first version required the command
+ * to match `git push`, and its own near-miss test exposed the cost: a wrapper
+ * that pushes — `task push-ready`, a deploy script, a `git` alias — advances a
+ * remote ref without the words `git push` appearing anywhere, and the hook
+ * would have been silent on exactly the pushes furthest from a human's eye.
+ * A false negative here is the failure this whole change exists to remove, so
+ * the authoritative condition is git's OWN report and the command only subtracts.
+ */
+const DRY_RUN = /(?:^|\s)(?:--dry-run|-n)(?:\s|$)/;
+
+/**
+ * Git's own report that a ref MOVED. Both shapes it prints:
+ *   `   b75d7f7..a1b2c3d  feat/x -> feat/x`      (fast-forward / forced)
+ *   ` * [new branch]      feat/x -> feat/x`      (first push)
+ * The `->` is the load-bearing token: `Everything up-to-date` has none, and a
+ * `! [rejected]` line carries one but is excluded before this runs.
+ */
+const REF_ADVANCED = /(?:\[new branch\]|\[new tag\]|[0-9a-f]{7,}\.\.[0-9a-f]{7,})\s+(\S+)\s+->\s+(\S+)/;
+
+/** A push git refused. Its `->` must never be read as an advance. */
+const REJECTED = /^\s*!\s*\[(?:rejected|remote rejected)\]/m;
+
+function isObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Unwrap the dispatcher envelope `{event, platform, payload: <native>}`.
+ * Reading `tool_name` off the top level is the defect that left
+ * `pr-url-reminder` silently never firing in production (measured 2026-08-06).
+ */
+function unwrap(envelope: JsonObject): JsonObject {
+  const inner = envelope["payload"];
+  return isObject(inner) ? inner : envelope;
+}
+
+function extractCommand(payload: JsonObject): string | null {
+  const toolRaw = payload["tool_name"] ?? payload["toolName"] ?? payload["tool"];
+  const tool = typeof toolRaw === "string" ? toolRaw : null;
+  if (tool === null || !COMMAND_TOOLS.has(tool)) return null;
+  const ti = payload["tool_input"];
+  if (isObject(ti)) {
+    for (const key of ["command", "cmd", "shell_command"]) {
+      const v = ti[key];
+      if (typeof v === "string" && v) return v;
+    }
+  }
+  for (const key of ["command", "cmd"]) {
+    const v = payload[key];
+    if (typeof v === "string" && v) return v;
+  }
+  return null;
+}
+
+function toolOutput(payload: JsonObject): string {
+  for (const key of ["tool_response", "tool_result", "toolResponse", "output", "result", "stdout"]) {
+    const v = payload[key];
+    if (typeof v === "string") return v;
+    if (isObject(v) || Array.isArray(v)) return JSON.stringify(v);
+  }
+  return JSON.stringify(payload);
+}
+
+/**
+ * The pushed branch, taken from the REMOTE side of git's `local -> remote`
+ * report and stripped of any `refs/heads/` prefix. The remote side is the one
+ * that names the branch CI will run against; on a `HEAD:feat/x` push the local
+ * side says `HEAD` and would resolve to nothing.
+ */
+export function pushedBranch(output: string): string | null {
+  if (REJECTED.test(output)) return null;
+  const m = REF_ADVANCED.exec(output);
+  if (m === null) return null;
+  const remote = m[2];
+  if (remote === undefined) return null;
+  return remote.replace(/^refs\/heads\//, "") || null;
+}
+
+/** Best-effort PR number for a branch. Never throws, never guesses. */
+export function resolvePr(
+  branch: string,
+  run: (cmd: string, args: string[]) => string = (cmd, args) =>
+    execFileSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 15_000 }),
+): number | null {
+  try {
+    const out = run("gh", ["pr", "view", branch, "--json", "number", "-q", ".number"]).trim();
+    const n = Number.parseInt(out, 10);
+    return Number.isInteger(n) && n > 0 ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The reminder text. Split out so the test can read it without a `gh` on PATH. */
+export function buildReminder(branch: string, pr: number | null): { reason: string; additional_context: string } {
+  const settle =
+    pr === null
+      ? `gh pr view ${branch} --json number -q .number   # then:\n` +
+        `./scripts-run src/scripts/ci_settle <that number>`
+      : `./scripts-run src/scripts/ci_settle ${pr}`;
+  const subject = pr === null ? `branch ${branch}` : `PR #${pr} (${branch})`;
+  const reason =
+    `Pushed ${subject} — the turn is not finished until its CI has settled green ` +
+    `(verify-before-complete). Run ci_settle before you report this as done.`;
+  const additional_context =
+    `You just advanced a remote ref: ${subject}.\n\n` +
+    `A push is not a delivery. Per verify-before-complete, a completion claim needs ` +
+    `fresh evidence, and the evidence for a push is the CI verdict — not the push's ` +
+    `own exit code.\n\n` +
+    `Before this turn ends:\n` +
+    `  1. Settle it:\n     ${settle}\n` +
+    `     Exit 0 = settled green · 1 = settled, something failed · 2 = NOT a verdict ` +
+    `(timed out or unreadable — never report 2 as green).\n` +
+    `  2. Red? Read only the failing part:\n` +
+    `     gh run view --job <id> --log-failed | grep -E '×|FAIL|Error'\n` +
+    `     then fix it and push again (fix-what-you-see: the author is irrelevant).\n` +
+    `  3. Still red after 3 attempts on the same target, or blocked on something ` +
+    `only the user can decide — stop and say so, with the three attempts named ` +
+    `(autonomous-execution N=3).\n\n` +
+    `Handing the user a red PR with its cause named and unfixed is not a delivery ` +
+    `either. If you are deliberately leaving this WIP, say that in the reply — ` +
+    `silence is what this hook exists to stop.`;
+  return { reason, additional_context };
+}
+
+export function main(): number {
+  let envelope: JsonValue;
+  try {
+    const raw = readHookStdin();
+    envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+  } catch {
+    return EXIT_ALLOW; // never block on a malformed envelope
+  }
+  if (!isObject(envelope)) return EXIT_ALLOW;
+
+  const inner = unwrap(envelope);
+  // A shell tool is still required: the report below is git's own text, and a
+  // structured forge tool does not produce it.
+  const command = extractCommand(inner);
+  if (command === null) return EXIT_ALLOW;
+  if (DRY_RUN.test(command)) return EXIT_ALLOW;
+
+  const branch = pushedBranch(toolOutput(inner));
+  if (branch === null) return EXIT_ALLOW; // up-to-date, rejected, delete — nothing advanced
+
+  const { reason, additional_context } = buildReminder(branch, resolvePr(branch));
+  process.stdout.write(`${JSON.stringify({ decision: "warn", reason, additional_context })}\n`);
+  return EXIT_WARN;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function isCliEntry(): boolean {
+  if (typeof __AGENT_CONFIG_BUNDLE__ !== "undefined" && __AGENT_CONFIG_BUNDLE__) return false;
+  if (process.argv[1] === undefined) return false;
+  const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+  if (import.meta.url === argvUrl) return true;
+  try {
+    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+if (isCliEntry()) {
+  process.exit(main());
+}

package/src/scripts/hooks/ship_diff_volume_hook.ts

@@ -91,7 +91,7 @@ export function correctedVolume(numstat: string): { volume: number; excluded: nu
 }
 
 /**
- * Tools that carry a shell command. Mirrors `block_unauthorized_git`'s set.
+ * Tools that carry a shell command. Mirrors `git_command_classifier`'s set.
  *
  * `SHIP_PATTERNS` are unanchored, so without this gate a `grep` for the string
  * `git push` spawns two `git` subprocesses on a blocking slot. ALLOW-list: a

package/src/scripts/hooks_status.ts

@@ -45,7 +45,9 @@ const MANIFEST_PATH = path.join(
   "hook_manifest.yaml",
 );
 
-// (label, project-relative bridge path, install hint).
+// (project-relative bridge path, one-line note shown when the bridge is not
+// live). The note is printed verbatim, so a note that is not a command must
+// not read as one.
 // Path may be a directory (cline) — existence => any file inside.
 //
 // Cowork has no project-scope bridge path: the Claude desktop app's
@@ -58,17 +60,17 @@ const MANIFEST_PATH = path.join(
 // Once upstream lands the fix and a stable settings location is
 // documented, swap the empty path here for that location.
 export const PLATFORM_BRIDGES: Record<string, [string, string]> = {
-  augment: [".augment/settings.json", "src/scripts/install.py"],
-  claude: [".claude/settings.json", "src/scripts/install.py"],
+  augment: [".augment/settings.json", "run `agent-config install`"],
+  claude: [".claude/settings.json", "run `agent-config install`"],
   cowork: [
     "",
     "upstream-blocked: anthropics/claude-code#40495 + #27398 (settings.json ignored in Cowork sandbox)",
   ],
-  cursor: [".cursor/hooks.json", "src/scripts/install.py"],
-  cline: [".clinerules/hooks", "src/scripts/install.py"],
-  windsurf: [".windsurf/hooks.json", "src/scripts/install.py"],
-  gemini: [".gemini/settings.json", "src/scripts/install.py"],
-  copilot: ["", "rule-only fallback (no hook surface)"],
+  cursor: [".cursor/hooks.json", "run `agent-config install`"],
+  cline: [".clinerules/hooks", "run `agent-config install`"],
+  windsurf: [".windsurf/hooks.json", "run `agent-config install`"],
+  gemini: [".gemini/settings.json", "run `agent-config install`"],
+  copilot: ["", "rule-only fallback — this package binds no hook here"],
 };
 
 export interface PlatformRow {
@@ -180,11 +182,11 @@ export function _render_table(matrix: StatusMatrix): string {
       lines.push(`    ${event.padEnd(22)} → ${concerns}`);
     }
     if (row.hint) {
-      lines.push(`    hint: run ${row.hint}`);
+      lines.push(`    hint: ${row.hint}`);
     }
   }
   lines.push("");
-  lines.push("Source of truth: scripts/hook_manifest.yaml");
+  lines.push("Source of truth: src/scripts/hook_manifest.yaml");
   lines.push("Contract: docs/contracts/hook-architecture-v1.md");
   return lines.join("\n");
 }

package/src/scripts/install-hooks.sh

@@ -12,7 +12,25 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 # (where $PROJECT_ROOT/.git is a file, not a dir, and a literal .git/hooks path
 # would break under `set -e`). --git-common-dir points at the main .git even from
 # a worktree; fall back to the literal path only outside a git repo.
-if COMMON_GIT_DIR="$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)"; then
+#
+# AGENT_CONFIG_HOOKS_DIR overrides the destination. It exists so that
+# `check_installed_hooks_fresh` can render what this installer WOULD write into
+# a scratch directory and byte-compare it against what is installed — the only
+# way to answer "is the installed copy stale?" without re-parsing these
+# heredocs, which carry an appended block (post-merge / post-checkout) that no
+# heredoc slice can reproduce. It is a test/inspection seam; a normal install
+# never sets it.
+if [ -n "${AGENT_CONFIG_HOOKS_DIR+set}" ]; then
+    # SET-BUT-EMPTY is refused rather than ignored. A caller that meant to
+    # redirect an inspection run and passed an empty value would otherwise fall
+    # through to the real .git/hooks and INSTALL over it — including over a
+    # pre-push that is running the inspection, which truncates it silently.
+    if [ -z "$AGENT_CONFIG_HOOKS_DIR" ]; then
+        echo "❌  AGENT_CONFIG_HOOKS_DIR is set but empty — refusing to fall back to the real .git/hooks." >&2
+        exit 2
+    fi
+    HOOKS_DIR="$AGENT_CONFIG_HOOKS_DIR"
+elif COMMON_GIT_DIR="$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)"; then
     case "$COMMON_GIT_DIR" in /*) : ;; *) COMMON_GIT_DIR="$PROJECT_ROOT/$COMMON_GIT_DIR" ;; esac
     HOOKS_DIR="$COMMON_GIT_DIR/hooks"
 else
@@ -20,6 +38,12 @@ else
 fi
 
 mkdir -p "$HOOKS_DIR"
+# Name the destination. AGENT_CONFIG_HOOKS_DIR is a global override, and a
+# stray non-empty value would otherwise redirect a real `task install-hooks`
+# while it printed six "hook installed" lines that name no path at all — the
+# freshness check would then report every hook missing with nothing pointing at
+# the cause.
+echo "→  installing git hooks into $HOOKS_DIR" >&2
 
 cat > "$HOOKS_DIR/pre-push" << 'EOF'
 #!/usr/bin/env bash
@@ -85,6 +109,96 @@ fi
 
 fail=0
 
+# BASE FRESHNESS — first, and it EXITS rather than setting fail=1.
+#
+# The header above has promised "when this hook refuses for staleness" since the
+# hook was written, and nothing below ever asked. Measured over the 50 PRs
+# preceding 2026-09-04: 25 of them carried at least one `Merge branch 'main'
+# into <branch>` commit (52 such commits in total), and 17 of the 36 PRs whose
+# workflow runs were still readable had at least one FAILED run — the three
+# workflows that failed most (Tests 18, Consistency 16, Rule Backstops 13) are
+# exactly the base-relative ones: ratchets, budgets and generated counts that
+# were green against the base the branch forked from and red against the base it
+# merges into. A branch pushed behind its base buys a CONFLICTING PR, a red run,
+# or both, and the contributor pays for it after the work looks finished.
+#
+# It runs FIRST because everything after it is invalidated by the merge that has
+# to happen anyway: `task consistency` regenerates derived files against the
+# stale base, the merge then re-dirties them, and the ~10s is spent twice. And
+# it EXITS instead of accumulating into `fail`, for the same reason — there is
+# no useful second finding to collect from a tree that is about to move.
+#
+# It never merges. `check_branch_freshness` asks the REMOTE (one `ls-remote`,
+# measured 4.5s) and returns 1 only on a VERIFIED behind state; offline, in CI,
+# on a detached HEAD, or standing on the base itself it returns 0 and says so.
+# So an unreachable network cannot block a push, and a stale local tracking ref
+# cannot fake a green.
+echo "🔍 Base freshness — is this branch behind the base it will merge into?"
+if [ "${AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS:-}" = "1" ]; then
+    echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS=1"
+elif [ ! -x ./scripts-run ]; then
+    echo "⚠️  ./scripts-run not found — skipping the freshness check for this push."
+elif ! ./scripts-run src/scripts/check_branch_freshness --quiet; then
+    echo ""
+    echo "   Push blocked — the branch is behind its base, and the gates you just"
+    echo "   passed were answered against a base that no longer exists."
+    echo ""
+    echo "     task push-ready         # fetch → integrate the base SET → regenerate"
+    echo "                             # → verify → re-check freshness, then push"
+    echo "     task push-ready DRY=1   # the same steps, read-only"
+    echo ""
+    echo "   This hook refuses; it never merges. Bypass a genuine WIP push with"
+    echo "   AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS=1."
+    exit 1
+fi
+
+# INSTALLED-HOOK FRESHNESS — ADVISORY, and deliberately AFTER base freshness.
+#
+# What it answers: are the hooks in .git/hooks still what THIS checkout's
+# install-hooks.sh would write? Measured 2026-09-05: the installed pre-push here
+# was 146 lines against a 189-line source body, missing the entire base-freshness
+# gate above, merged five days earlier. It read as live in the source, in CI and
+# in the skill documenting it, and did not run here.
+#
+# WHY IT DOES NOT REFUSE. The predicate is "installed == what this checkout
+# renders", and .git/hooks is SHARED by every linked worktree through the common
+# dir. With two worktrees whose installer bodies differ, at most one can satisfy
+# it at a time and each re-install flips which — so a refusal would fire on
+# ordinary parallel work, and the documented skip variable would become routine,
+# which retires the gate rather than enforcing it. An AI council (claude-sonnet-4-5
+# + codex-default, 2026-09-05, 2 of 2 seats) chose advisory unanimously after an
+# independent review raised exactly that. Blocking returns only with a
+# single-referent predicate — per-worktree hook isolation via core.hooksPath, or a
+# branch-independent dispatcher installed once in the common dir.
+#
+# WHY AFTER BASE FRESHNESS. Being behind a base that moved the installer is the
+# most common cause of a mismatch, and the repair for THAT is to merge, not to
+# re-install: re-installing from a behind-base checkout writes the OLDER hook set
+# over the shared directory. Base freshness exits first, so that contributor is
+# told the correct thing and never reaches this notice.
+echo "🔍 Installed-hook freshness — do .git/hooks still match this checkout?"
+if [ "${AGENT_CONFIG_SKIP_PREPUSH_HOOKFRESH:-}" = "1" ]; then
+    echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_HOOKFRESH=1"
+elif [ ! -x ./scripts-run ] || [ ! -d node_modules ] \
+    || [ ! -f src/scripts/check_installed_hooks_fresh.ts ]; then
+    # Three guards, and each has been a real miss. `-d node_modules`: without
+    # dependencies ./scripts-run cannot start tsx and the non-zero exit would
+    # read as staleness. `-f`: .git/hooks is shared, so this file also runs in a
+    # worktree standing on a branch that predates the gate, and calling a script
+    # that is not on that checkout would report the wrong thing.
+    echo "⏭️  check_installed_hooks_fresh not runnable on this checkout — skipping."
+else
+    ./scripts-run src/scripts/check_installed_hooks_fresh --quiet
+    hookfresh_rc=$?
+    # The gate's three exit codes mean three different things, and collapsing
+    # them reports a false cause: 0 = match or nothing installed, 1 = mismatch,
+    # 2 = it could not render (installer failed, unwritable TMPDIR, usage error).
+    if [ "$hookfresh_rc" = "2" ]; then
+        echo "⚠️  could not compare the installed hooks (see above) — not a staleness verdict."
+    fi
+    # Advisory in both cases: nothing here sets fail=1 or exits.
+fi
+
 if ! command -v task >/dev/null 2>&1; then
     echo "⚠️  'task' (go-task) not found — cannot run the consistency gate locally."
     echo "    Install it (https://taskfile.dev) so pre-push can mirror the CI check;"
@@ -381,6 +495,25 @@ if [ -n "\$prev" ] && [ -n "\$new" ] && [ "\$prev" != "\$new" ]; then
         if command -v npm >/dev/null 2>&1 && [ -d node_modules ]; then
             npm run build:cli >/dev/null 2>&1 || true
         fi
+        # Installed-hook staleness — REPORT it here, never repair it here.
+        #
+        # This is the event that CAUSES the staleness, so it is where the news
+        # belongs. It is NOT where the repair belongs: linked worktrees SHARE
+        # .git/hooks through the common dir, so re-running the installer from a
+        # checkout would let one worktree silently redefine the gates every
+        # other worktree runs, and an older branch would reinstall older hooks
+        # over newer ones. An AI council (claude-sonnet-4-5 + codex-default,
+        # 2026-09-05, 2 of 2 seats) refused that mutation unanimously.
+        #
+        # Output goes to stderr and is NOT swallowed: the rest of this block is
+        # "|| true" so a pull is never blocked, and a repair notice nobody can
+        # see is the same silence this check exists to remove.
+        # The -f guard is not belt-and-braces: this hook is shared across
+        # linked worktrees, so it also runs on checkouts that predate the gate.
+        if [ -x ./scripts-run ] && [ -d node_modules ] \
+            && [ -f src/scripts/check_installed_hooks_fresh.ts ]; then
+            ./scripts-run src/scripts/check_installed_hooks_fresh --quiet >&2 || true
+        fi
     fi
 fi
 EOF