@event4u/agent-config 14.17.0 → 14.18.0

package/src/scripts/hooks/{block_unauthorized_git.ts → git_command_classifier.ts}

@@ -1,11 +1,28 @@
-#!/usr/bin/env node
 /**
- * Unauthorized-git gate — `pre_tool_use` concern.
- *
- * Checks a git / GitHub / npm operation against the authorization ledger that
- * `git_authorization_hook.ts` writes on `user_prompt_submit`, so the question
- * "did the user authorize this THIS turn?" is answered from a recorded fact
- * rather than from the model's recollection.
+ * Git / GitHub / npm command classifier — a pure library, not a gate.
+ *
+ * WHAT THIS IS NOT, AND WHY. Until 2026-09-04 this file was the
+ * `block-unauthorized-git` `pre_tool_use` concern: it read the authorization
+ * ledger and REFUSED an operation the turn had not authorized. The owner
+ * removed that enforcement (ADR-254) after it was measured to refuse
+ * authorizations the owner had in fact given — a guardrail sentence inside an
+ * authorization ("never merge empty PRs") read as a withdrawal and erased the
+ * whole ledger, and an answer given as an option number ("1") matched no
+ * authorizing pattern at all.
+ *
+ * What survives is the half that never decided anything: the command parser and
+ * the operation vocabulary. Two callers depend on it and neither gates git —
+ * `block_no_verify.ts` needs `substitutionPayloads` so `git $(echo --no-verify)`
+ * cannot slip past the hook-bypass guard, and `conformance_scan.ts` needs
+ * `commandOp` / `BLOCK_OPS` to MEASURE how often an irreversible operation ran
+ * on an unauthorized turn. Measurement is all that is left here.
+ *
+ * `BLOCK_OPS` and `WARN_OPS` keep their names because they name the
+ * reversibility split `non-destructive-by-default` draws, and that split is
+ * still true. They no longer name an action this file takes.
+ *
+ * SEVERITY SPLIT — by reversibility, not by confidence. Retained below because
+ * it is what the two sets still mean.
  *
  * SEVERITY SPLIT — by reversibility, not by confidence.
  *
@@ -56,33 +73,7 @@
  * substitution in every position tried, `sh -c` and `eval` payloads, env
  * assignment prefixes, and quotes inside the command word.
  */
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-import { readHookStdin } from "./hook_stdin.js";
-import { analyseMergeImpact, describeImpact } from "./merge_impact.js";
-import { atomic_write_json } from "./state_io.js";
-import {
-  consumeGrantTarget,
-  ledgerFileFor,
-  pendingFileFor,
-  PR_NUMBER_MAX,
-  readGrants,
-  STATE_FILE,
-  type GitOp,
-  type MergeGrant,
-} from "../git_authorization_hook.js";
-
-const EXIT_ALLOW = 0;
-// MUST equal dispatch_hook.EXIT_BLOCK. The dispatcher's internal ladder is
-// 0 allow / 1 block / 2 warn — NOT the 2-means-block shape a PreToolUse guard
-// reads naturally from Claude's own native contract. This constant was 2 when
-// this gate first shipped, so the dispatcher reduced every refusal to a WARN
-// and the gate emitted advisory context while the operation went through.
-// Pinned against the dispatcher's export by
-// tests/hooks/concern_block_exit_parity.test.ts.
-const EXIT_BLOCK = 1;
+import { PR_NUMBER_MAX, type GitOp } from "../git_authorization_hook.js";
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };
@@ -648,338 +639,3 @@ function _boundedTarget(digits: string): number | null {
   const n = Number.parseInt(digits, 10);
   return Number.isSafeInteger(n) && n > 0 && n <= PR_NUMBER_MAX ? n : null;
 }
-
-/**
- * Does a standing grant cover this exact merge?
- *
- * Three conditions, all necessary: the grant is for this op, the command named
- * a target, and that target sits in the grant's frozen set unspent.
- *
- * No clock is consulted here, and that is the whole of ADR-252. `authorized`
- * answers "did the user name this operation recently"; a grant answers "did the
- * user name this operation AND this pull request". The second question does not
- * decay with time, because the object it names cannot drift into a different
- * object — a force-push changes the SHA, but the grant is spent on first use, so
- * a merge that already happened can never be replayed against a moved head.
- */
-export function grantCovers(
-  grants: MergeGrant[],
-  op: GitOp,
-  target: number | null,
-): MergeGrant | null {
-  if (op !== "pr-merge" || target === null) {
-    return null;
-  }
-  return (
-    grants.find(
-      (g) => g.op === "pr-merge" && g.targets.includes(target) && !g.consumed.includes(target),
-    ) ?? null
-  );
-}
-
-/**
- * A ledger older than this is not "this turn" under any reading.
- *
- * **Widening this constant for a long run is forbidden practice.** On
- * 2026-08-21 it was sed-patched to twelve times this value — six hours —
- * behind a marker promising a revert that never came, so an autonomous PR-drain could
- * merge past the 30-minute bound. The widening was committed to the trunk and
- * left there. It is a twelvefold expansion of the authorization lifetime on
- * the guard that gates `pr-merge`, which is a `BLOCK_OPS` member precisely
- * because it is irreversible.
- *
- * Neither the widened expression nor the marker text is written out here: the
- * obvious regression check for either is a grep, and a comment reciting the
- * literal makes that grep match the guard's own prose on a clean tree.
- *
- * The supported answer to "my run is longer than the window" is that the run
- * STOPS and REPORTS at expiry and the user re-authorizes — never that the
- * window grows. The agent never edits this constant, this file, or the built
- * bundle; `dist/hooks/dispatch.js` is what actually executes, and a source
- * edit without a rebuild is silently inert.
- *
- * **ADR-251 (2026-08-30) decided this question and KEPT the value.** An AI
- * council converged 2/2 on a different authorization SHAPE rather than a wider
- * window, against the measured pressure that 7 of the 10 most recent sessions
- * of this package outlive a 30-minute window (median span 3.1 h) and that the
- * constant has been hand-widened twice. `LEDGER_MAX_AGE_MS` is unchanged at 30
- * minutes and raising it remains forbidden — that transition is owner-reserved,
- * and this record did not take it.
- *
- * What the record DID change is the behaviour at expiry: the run PAUSES,
- * reports the remaining work, and ASKS for re-authorization, instead of ending.
- * The user's reply renews this ledger through the path that already exists —
- * `git_authorization_hook.ts` rewrites the session's ledger with a fresh
- * `detected_at` on every human-typed prompt (`:512-537`), so a mid-run reply
- * carrying an authorization phrase resets the age this constant is compared
- * against. No new machinery, and the signal stays agent-unforgeable.
- *
- * See `docs/decisions/ADR-251-authorization-window-shape-not-width.md`.
- */
-export const LEDGER_MAX_AGE_MS = 30 * 60 * 1000;
-
-/**
- * Load the ledger, and refuse one that does not belong to THIS session and
- * THIS turn.
- *
- * The header claims the gate answers "did the user authorize this THIS turn?".
- * Before this check it answered "did anyone, in any session, ever authorize
- * it?" — the file records `session_id` and `detected_at` and neither was read.
- * Two concurrent worktrees share one state root, so session A typing
- * `mach den release` authorized session B.
- */
-function _loadLedger(
-  consumer_root: string,
-  session_id: string,
-  now: number,
-): { authorized: Set<GitOp>; present: boolean; grants: MergeGrant[] } {
-  // Grants are read on their OWN path, and the separation is load-bearing.
-  // `_readLedgerFile` below discards the entire ledger once `detected_at` is
-  // older than `LEDGER_MAX_AGE_MS`, so folding grants into its return value
-  // would let the clock silently kill them too — the change would ship, look
-  // correct, and do nothing after thirty minutes, with no test going red.
-  // `readGrants` performs the session check and no age check, which is exactly
-  // the contract: object identity, not recency (ADR-252).
-  const grants = readGrants(consumer_root, session_id);
-  // This session's own ledger first; the flat legacy file only as a fallback,
-  // so a ledger written by an older build still counts. Reading the flat file
-  // FIRST was the defect: any concurrent session in the repo overwrites it, and
-  // the session check below then discarded a real authorization as foreign.
-  const candidates = [ledgerFileFor(session_id)];
-  if (!candidates.includes(STATE_FILE)) {
-    candidates.push(STATE_FILE);
-  }
-  for (const rel of candidates) {
-    const found = _readLedgerFile(path.join(consumer_root, rel), session_id, now);
-    if (found !== null) {
-      return { ...found, grants };
-    }
-  }
-  return { authorized: new Set<GitOp>(), present: false, grants };
-}
-
-/**
- * Read one ledger file. `null` means "this file does not answer the question" —
- * absent, malformed, foreign session, or expired — so the caller may try the
- * next candidate. A parsed, in-session, fresh ledger answers definitively.
- */
-function _readLedgerFile(
-  file: string,
-  session_id: string,
-  now: number,
-): { authorized: Set<GitOp>; present: boolean } | null {
-  try {
-    const raw = fs.readFileSync(file, "utf8");
-    const decoded = JSON.parse(raw) as unknown;
-    if (_isObject(decoded) && Array.isArray(decoded["authorized"])) {
-      const ledgerSession = typeof decoded["session_id"] === "string" ? decoded["session_id"] : "";
-      // A ledger from a different session is another conversation's consent.
-      if (session_id && ledgerSession && ledgerSession !== session_id) {
-        return null;
-      }
-      const at = Date.parse(String(decoded["detected_at"] ?? ""));
-      if (Number.isFinite(at) && now - at > LEDGER_MAX_AGE_MS) {
-        return null;
-      }
-      return {
-        authorized: new Set((decoded["authorized"] as string[]).filter(Boolean) as GitOp[]),
-        present: true,
-      };
-    }
-  } catch {
-    /* fall through */
-  }
-  return null;
-}
-
-export interface Decision {
-  exit: number;
-  stdout: string;
-  stderr: string;
-  /**
-   * The op this decision refused, when it refused one.
-   *
-   * `decide` stays pure; `run` turns this into the pending record that lets the
-   * user's answer to the refusal count as authorization for that one op. See
-   * `git_authorization_hook.PENDING_FILE` for why that record exists at all.
-   */
-  blockedOp?: GitOp;
-  /**
-   * The grant target this decision spent, when a standing grant is what allowed
-   * it.
-   *
-   * `decide` stays pure; `run` turns this into the ledger write that marks the
-   * target used. Single use is the property that keeps a grant from being a
-   * standing licence: the user authorized merging PR #1499, once.
-   */
-  consumedTarget?: number;
-}
-
-export function decide(
-  command: string | null,
-  ledger: { authorized: Set<GitOp>; present: boolean; grants?: MergeGrant[] },
-  impact?: string,
-): Decision {
-  if (command === null) {
-    return { exit: EXIT_ALLOW, stdout: "", stderr: "" };
-  }
-  const op = commandOp(command);
-  if (op === null || ledger.authorized.has(op)) {
-    return { exit: EXIT_ALLOW, stdout: "", stderr: "" };
-  }
-
-  // A standing grant is the SECOND way an operation can be authorized, and it
-  // is strictly narrower than the first rather than an escape from it. Only
-  // `pr-merge` can hold one, the command must name its pull request, and that
-  // number must sit unspent in a set the user's own sentence froze. An unnamed
-  // target matches nothing and a spent target matches nothing, so every path
-  // that is not exactly "the user named this PR and it has not been merged yet"
-  // falls through to the clock-bound decision below unchanged (ADR-252).
-  const target = mergeTargetOf(command);
-  if (grantCovers(ledger.grants ?? [], op, target) && target !== null) {
-    return { exit: EXIT_ALLOW, stdout: "", stderr: "", consumedTarget: target };
-  }
-
-  const shown = command.length > 120 ? `${command.slice(0, 117)}…` : command;
-
-  if (BLOCK_OPS.has(op)) {
-    // STAGE 2. The refusal stands either way — what the scan changes is whether
-    // the user has to go read the diff to answer it. `impact` is injected by
-    // `run`, never computed here, so `decide` stays pure and testable without a
-    // repository.
-    const scan = op === "pr-merge" && target !== null && impact ? ` ${impact}` : "";
-    const reason =
-      `Blocked: \`${op}\` with no authorization in this turn's prompt. ` +
-      `This operation is irreversible and non-destructive-by-default already declares it ` +
-      `never-autonomous. Command: ${shown}.${scan} ` +
-      `Ask the user, in one numbered-options block, and run it only after they answer this turn.`;
-    return { exit: EXIT_BLOCK, stdout: "", stderr: `${reason}\n`, blockedOp: op };
-  }
-
-  if (WARN_OPS.has(op)) {
-    const reason =
-      `No \`${op}\` authorization found in this turn's prompt (commit-policy: a one-shot ` +
-      `authorization is spent on the operation it named). If the user did authorize it this ` +
-      `turn, proceed; otherwise stop and ask. Command: ${shown}`;
-    return {
-      exit: EXIT_ALLOW,
-      stdout: `${JSON.stringify({ decision: "warn", reason })}\n`,
-      stderr: "",
-    };
-  }
-
-  return { exit: EXIT_ALLOW, stdout: "", stderr: "" };
-}
-
-export function run(stdin_text: string, options: { consumer_root: string }): number {
-  let envelope: JsonObject = {};
-  if (stdin_text.trim()) {
-    try {
-      const decoded = JSON.parse(stdin_text) as unknown;
-      if (_isObject(decoded)) {
-        envelope = decoded;
-      }
-    } catch {
-      return EXIT_ALLOW;
-    }
-  }
-  const session_id = typeof envelope["session_id"] === "string" ? envelope["session_id"] : "";
-  const command = extractCommand(envelope);
-  const ledger = _loadLedger(options.consumer_root, session_id, Date.now());
-
-  // STAGE 2 runs only on the path where it can change something: a merge that is
-  // ABOUT to be refused. Not on an allowed merge (nothing to tell the user), not
-  // on an op whose target the command does not name, and never on publish or
-  // release — a scan costs a diff read, and spending one where it cannot change
-  // the outcome is latency in the user's critical path for nothing.
-  let impact: string | undefined;
-  const stage1 = command === null ? null : commandOp(command);
-  const stage2Target = command === null ? null : mergeTargetOf(command);
-  if (
-    stage1 === "pr-merge" &&
-    stage2Target !== null &&
-    !ledger.authorized.has("pr-merge") &&
-    !grantCovers(ledger.grants ?? [], "pr-merge", stage2Target)
-  ) {
-    try {
-      impact = describeImpact(
-        stage2Target,
-        analyseMergeImpact(stage2Target, { cwd: options.consumer_root }),
-      );
-    } catch {
-      // The scan is an enrichment, never a gate. A refusal without it is the
-      // pre-stage-2 message, which is still correct.
-    }
-  }
-
-  const decision = decide(command, ledger, impact);
-  if (decision.consumedTarget !== undefined) {
-    // Spend the target at the moment the merge is actually let through, never
-    // when the grant was minted. A grant the run never reached stays whole, and
-    // a pull request that merged can never be replayed — which is what makes a
-    // force-push back to an already-merged head harmless here.
-    consumeGrantTarget(options.consumer_root, session_id, decision.consumedTarget);
-  }
-  if (decision.blockedOp) {
-    // Record WHAT was refused, so the user's answer to the question this
-    // refusal just told the agent to ask can authorize that one operation.
-    // Best-effort: a failed write degrades to the previous behaviour, where a
-    // numbered answer is unrecordable and the refusal simply repeats.
-    try {
-      atomic_write_json(path.join(options.consumer_root, pendingFileFor(session_id)), {
-        op: decision.blockedOp,
-        session_id,
-        refused_at: new Date().toISOString(),
-      });
-    } catch {
-      /* observability only — see above */
-    }
-  }
-  if (decision.stdout) {
-    process.stdout.write(decision.stdout);
-  }
-  if (decision.stderr) {
-    process.stderr.write(decision.stderr);
-  }
-  return decision.exit;
-}
-
-export function main(argv?: string[]): number {
-  const args = argv ?? process.argv.slice(2);
-  let consumer_root = process.cwd();
-  for (let i = 0; i < args.length; i += 1) {
-    const a = args[i];
-    if (a === "--project-dir" && args[i + 1] !== undefined) {
-      consumer_root = args[i + 1] as string;
-      i += 1;
-    } else if (a !== undefined && a.startsWith("--project-dir=")) {
-      consumer_root = a.slice("--project-dir=".length);
-    }
-  }
-  return run(readHookStdin(), { consumer_root });
-}
-
-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 {
-    const here = fs.realpathSync(fileURLToPath(import.meta.url));
-    const argv = fs.realpathSync(path.resolve(process.argv[1]));
-    return here === argv;
-  } catch {
-    return false;
-  }
-}
-
-if (_isCliEntry()) {
-  process.exit(main());
-}

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