@event4u/agent-config 14.14.1 → 14.16.0

package/src/scripts/hooks/block_unauthorized_git.ts

@@ -61,12 +61,17 @@ 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;
@@ -95,6 +100,31 @@ export const BLOCK_OPS: ReadonlySet<GitOp> = new Set<GitOp>([
   // Enabling auto-merge commits the outcome to a condition the agent does not
   // control, so it is blocked on the same terms as the merge it schedules.
   "pr-merge-auto",
+
+  // ── Added 2026-09-03. Every one is already never-autonomous in the
+  // `non-destructive-by-default` prose; the measurement that drove it is in the
+  // `GitOp` union's own note — 17 of 25 borderline operations classified as
+  // NOTHING, including three worse than anything the guard already caught.
+  /** The undo that is more destructive than the act: lockfiles break. */
+  "unpublish",
+  /** Metadata only, and every install on earth starts warning. */
+  "deprecate",
+  /** Replaces bytes consumers already hold a checksum for. */
+  "release-asset",
+  /** Deletes the guard rather than the data — everything after is unguarded. */
+  "protection",
+  /** No data lost; the gate that protects everything downstream is off. */
+  "workflow-toggle",
+  /** Reach outside the repository, and mostly one-way. */
+  "repo-lifecycle",
+  /** No code moves, and an armed auto-merge is released. */
+  "review-approve",
+  /** Discards commits that landed after the last fetch, on a shared ref. */
+  "force-push",
+  /** Destroys uncommitted work belonging to a session this one cannot see. */
+  "worktree-remove",
+  /** `-x` is the flag that takes `.env` and local certificates. */
+  "clean-ignored",
 ]);
 
 /** Recoverable operations — warned without a this-turn authorization. */
@@ -103,6 +133,22 @@ export const WARN_OPS: ReadonlySet<GitOp> = new Set<GitOp>([
   "push",
   "pr-create",
   "branch",
+
+  // ── Added 2026-09-03, deliberately at warn rather than block.
+  //
+  // Each is destructive in some reading, and each is also routine enough that
+  // blocking it would be the friction that gets the whole guard routed around —
+  // the failure mode this estate has already recorded twice. `reset-hard` is the
+  // sharpest case and stays here for a decidable reason: the Hard Floor's
+  // qualifier is "past unpushed work", and the command text cannot say whether
+  // the work was pushed.
+  "tag-force",
+  "rebase",
+  "reset-hard",
+  "clean",
+  "stash-drop",
+  "branch-delete",
+  "close",
 ]);
 
 /**
@@ -191,6 +237,74 @@ const COMMAND_OPS: ReadonlyArray<{ op: GitOp; re: RegExp }> = [
     op: "pr-create",
     re: new RegExp(`${P}gh\\s+pr\\s+create\\b|${ghApiWrite("\\/pulls\\b").source}`, "i"),
   },
+  // ── Added 2026-09-03. Placement inside this table is as load-bearing as the
+  // patterns: the loop takes the MOST SEVERE match per segment, but within one
+  // op the first pattern wins, so anything more specific than a plain `git push`
+  // has to sit above it.
+
+  // `npm unpublish` is NOT reached by the publish pattern — `\bpublish\b` needs
+  // a word boundary that `unpublish` does not provide between `n` and `p`. That
+  // is why it classified as nothing for as long as it did.
+  { op: "unpublish", re: new RegExp(`${P}(npm|pnpm|yarn)\\s+${G}unpublish\\b`, "i") },
+  { op: "deprecate", re: new RegExp(`${P}(npm|pnpm|yarn)\\s+${G}deprecate\\b`, "i") },
+  {
+    op: "release-asset",
+    re: new RegExp(`${P}gh\\s+release\\s+(upload|edit|delete)\\b`, "i"),
+  },
+  {
+    op: "protection",
+    re: new RegExp(
+      `${P}gh\\s+api\\b(?=[^\\n]*(?:protection|rulesets?)\\b)(?=[^\\n]*(?:-X|--method)\\s+(?:DELETE|PUT|PATCH|POST)\\b)|${P}gh\\s+ruleset\\s+delete\\b`,
+      "i",
+    ),
+  },
+  {
+    op: "workflow-toggle",
+    re: new RegExp(`${P}gh\\s+workflow\\s+(disable|enable)\\b`, "i"),
+  },
+  {
+    op: "repo-lifecycle",
+    re: new RegExp(
+      `${P}gh\\s+repo\\s+(archive|delete|unarchive)\\b|${P}gh\\s+repo\\s+edit\\b(?=[^\\n]*--visibility\\b)`,
+      "i",
+    ),
+  },
+  {
+    op: "review-approve",
+    re: new RegExp(`${P}gh\\s+pr\\s+review\\b(?=[^\\n]*--approve\\b)`, "i"),
+  },
+  // Above `push`, and both spellings: `--force` and `--force-with-lease`. The
+  // "safe force" is in the same class here because what it is safe against is a
+  // stale local view, not a collaborator who pushed after your fetch.
+  {
+    op: "force-push",
+    re: new RegExp(`${P}git\\s+${G}push\\b[^\\n;|&]*(--force\\b|--force-with-lease\\b|\\s-f\\b)`, "i"),
+  },
+  {
+    op: "worktree-remove",
+    re: new RegExp(`${P}git\\s+worktree\\s+remove\\b[^\\n;|&]*(--force\\b|\\s-f\\b)`, "i"),
+  },
+  // `-x` (or `-X`) anywhere in the flag cluster is what reaches ignored files.
+  {
+    op: "clean-ignored",
+    re: new RegExp(`${P}git\\s+clean\\b[^\\n;|&]*-[A-Za-z]*x`, "i"),
+  },
+  { op: "tag-force", re: new RegExp(`${P}git\\s+tag\\b[^\\n;|&]*(-f\\b|--force\\b)`, "i") },
+  { op: "rebase", re: new RegExp(`${P}git\\s+${G}rebase\\b`, "i") },
+  { op: "reset-hard", re: new RegExp(`${P}git\\s+${G}reset\\b[^\\n;|&]*--hard\\b`, "i") },
+  { op: "clean", re: new RegExp(`${P}git\\s+clean\\b`, "i") },
+  { op: "stash-drop", re: new RegExp(`${P}git\\s+stash\\s+(drop|clear)\\b`, "i") },
+  // Remote deletion and the local `-D` are one op: both remove a ref, and the
+  // remote form additionally closes any open PR pointing at it.
+  {
+    op: "branch-delete",
+    re: new RegExp(
+      `${P}git\\s+branch\\b[^\\n;|&]*(-D\\b|--delete\\b)|${P}git\\s+${G}push\\b[^\\n;|&]*(--delete\\b|\\s:\\S)`,
+      "i",
+    ),
+  },
+  { op: "close", re: new RegExp(`${P}gh\\s+(pr|issue)\\s+close\\b`, "i") },
+
   { op: "push", re: new RegExp(`${P}git\\s+${G}push\\b`, "i") },
   { op: "commit", re: new RegExp(`${P}git\\s+${G}commit\\b`, "i") },
   { op: "branch", re: new RegExp(`${P}git\\s+${G}(checkout\\s+-b|switch\\s+-c)\\b`, "i") },
@@ -503,6 +617,66 @@ export function commandOp(command: string): GitOp | null {
   return found;
 }
 
+/**
+ * The pull request a merge command acts on, or `null` when the command does not
+ * say.
+ *
+ * `gh pr merge` with no number merges whatever the current branch's PR is — the
+ * command text identifies no object, so no grant can match it and the
+ * clock-bound path applies unchanged. That is the fail-closed direction: an
+ * unnamed target never consumes a grant minted for a named one.
+ */
+export function mergeTargetOf(command: string): number | null {
+  // Ten digits lexically, `PR_NUMBER_MAX` numerically — the API contract's own
+  // bound, imported from the mint site so the two cannot drift. The old
+  // `\d{1,7}` put the `\b` after digit seven, so an eight-digit target did not
+  // resolve to an out-of-range value: it resolved to NOTHING, and the gate fell
+  // back to the clock-bound path with no diagnostic.
+  const gh = /\bgh\s+pr\s+merge\s+(?:-{1,2}\S+\s+)*?(\d{1,10})\b/i.exec(command);
+  if (gh) {
+    return _boundedTarget(gh[1] as string);
+  }
+  // The same operation by its REST spelling. `commandOp` already classifies
+  // `gh api -X PUT repos/o/r/pulls/1499/merge` as `pr-merge`, so a reader that
+  // missed it here would silently fall back to the clock.
+  const api = /\/pulls\/(\d{1,10})\/merge\b/i.exec(command);
+  return api ? _boundedTarget(api[1] as string) : null;
+}
+
+/** A target only counts inside the API's own range; anything else is no target. */
+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.
  *
@@ -558,7 +732,15 @@ function _loadLedger(
   consumer_root: string,
   session_id: string,
   now: number,
-): { authorized: Set<GitOp>; present: boolean } {
+): { 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
@@ -570,10 +752,10 @@ function _loadLedger(
   for (const rel of candidates) {
     const found = _readLedgerFile(path.join(consumer_root, rel), session_id, now);
     if (found !== null) {
-      return found;
+      return { ...found, grants };
     }
   }
-  return { authorized: new Set<GitOp>(), present: false };
+  return { authorized: new Set<GitOp>(), present: false, grants };
 }
 
 /**
@@ -622,11 +804,21 @@ export interface Decision {
    * `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 },
+  ledger: { authorized: Set<GitOp>; present: boolean; grants?: MergeGrant[] },
+  impact?: string,
 ): Decision {
   if (command === null) {
     return { exit: EXIT_ALLOW, stdout: "", stderr: "" };
@@ -636,13 +828,30 @@ export function decide(
     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}. ` +
+      `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 };
   }
@@ -675,10 +884,42 @@ export function run(stdin_text: string, options: { consumer_root: string }): num
     }
   }
   const session_id = typeof envelope["session_id"] === "string" ? envelope["session_id"] : "";
-  const decision = decide(
-    extractCommand(envelope),
-    _loadLedger(options.consumer_root, session_id, Date.now()),
-  );
+  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.

package/src/scripts/hooks/merge_impact.ts

@@ -0,0 +1,275 @@
+/**
+ * Stage-2 impact analysis for a merge the guard is about to refuse.
+ *
+ * STAGE 1 asks "is this operation in the blocked set?" — a question about the
+ * command's shape, answered by `commandOp`. STAGE 2 asks "what would it
+ * actually do?" — a question about the diff, answered here.
+ *
+ * WHAT THIS DOES NOT DO, stated first because the opposite is the tempting
+ * reading: it never downgrades a refusal into an allow. Both council seats
+ * (2026-09-03, anthropic + codex-default, deep) rejected exactly that, and the
+ * argument is not about diff parsing being imperfect — it is that a purely
+ * additive diff can still fire a production deploy, close issues, hit outbound
+ * webhooks, and land against a base that moved since the review. Diff content
+ * is one axis; the destination is the other, and nothing readable from a patch
+ * tells you what merging into that branch triggers.
+ *
+ * So the verdict enriches the REFUSAL. A block that says "this PR adds two
+ * files and touches no migration, no exported symbol and no version — say
+ * `merge #1499` to authorize" is a question the user can answer in four words,
+ * including out loud. A block that says "refused" makes them go read the diff
+ * themselves. Same gate, and the difference is entirely in whether the human
+ * can act on it.
+ *
+ * THREE-VALUED ON PURPOSE. `undecidable` is a real answer and the most common
+ * one offline: no ref, no network, an unparsable patch. Collapsing it into
+ * `additive` would be the failure this module exists to avoid, so every unknown
+ * resolves toward "ask".
+ */
+import { execFileSync } from "node:child_process";
+
+export type ImpactVerdict = "additive" | "destructive" | "undecidable";
+
+export interface MergeImpact {
+  verdict: ImpactVerdict;
+  /** Human-readable markers behind a `destructive` verdict, in diff order. */
+  markers: string[];
+  /** Why the analysis could not run, when the verdict is `undecidable`. */
+  reason?: string;
+  /** Files the diff touches, for the one-line summary in a refusal. */
+  filesChanged?: number;
+}
+
+/**
+ * Destructive markers, each decidable from the patch text alone.
+ *
+ * DELIBERATELY A PROXY SET, NOT A BREAKING-CHANGE ORACLE. "Does this break a
+ * consumer" is undecidable in general; these are the shapes that are cheap to
+ * see and expensive to miss. A marker firing means "a human should look", never
+ * "this is certainly breaking" — and the absence of every marker means "nothing
+ * cheap to see fired", never "this is certainly safe". That asymmetry is why an
+ * `additive` verdict still refuses.
+ */
+const DESTRUCTIVE_MARKERS: ReadonlyArray<{ label: string; re: RegExp }> = [
+  // Schema removal. Matched on ADDED lines only — a migration that *removes* a
+  // dropColumn call is the opposite of destructive, and matching the raw patch
+  // would score it the same way.
+  { label: "migration drops a column or table", re: /^\+.*\b(dropColumn|dropTable|dropIfExists|removeColumn|drop_column|drop_table)\b/im },
+  { label: "raw DROP or TRUNCATE in a migration", re: /^\+.*\b(DROP\s+(TABLE|COLUMN|INDEX|CONSTRAINT)|TRUNCATE\s+TABLE)\b/im },
+  // The author said so themselves. Conventional Commits marks a breaking change
+  // with a `!` before the colon or a body trailer.
+  { label: "author marked a BREAKING CHANGE", re: /^\+.*BREAKING[ -]CHANGE/m },
+  // A removed export is the shape most likely to break an importer.
+  { label: "an exported symbol was removed", re: /^-\s*export\s+(default\s+|const\s+|function\s+|class\s+|interface\s+|type\s+|async\s+)/m },
+  { label: "a public PHP or Python symbol was removed", re: /^-\s*(public\s+function|def\s+[a-z_]+\s*\()/m },
+  // Route removal breaks callers that never imported anything.
+  { label: "a route or endpoint was removed", re: /^-.*\b(Route::(get|post|put|patch|delete)|@(Get|Post|Put|Patch|Delete)Mapping|app\.(get|post|put|patch|delete)\s*\()/m },
+  { label: "a whole file was deleted", re: /^deleted file mode /m },
+];
+
+/**
+ * Schema-removal patterns, ADDED-side anchor stripped, for use inside a rename.
+ *
+ * Kept as its own list rather than derived by rewriting the table above,
+ * because a regex rewritten at runtime is a second source of truth that no
+ * test reads.
+ */
+const SCHEMA_REMOVAL_BODY =
+  /\b(dropColumn|dropTable|dropIfExists|removeColumn|drop_column|drop_table|DROP\s+(TABLE|COLUMN|INDEX|CONSTRAINT)|TRUNCATE\s+TABLE)\b/i;
+
+/** Git's own rename metadata for one file block. */
+const RENAME_METADATA = /^rename (?:from|to) /m;
+
+/**
+ * Per-file blocks of a unified diff, split on git's own file header.
+ *
+ * The first element of the split is whatever precedes the first `diff --git`
+ * (usually empty, sometimes a commit header) and is dropped.
+ */
+function fileBlocks(patch: string): string[] {
+  return patch
+    .split(/^(?=diff --git )/m)
+    .filter((b) => b.startsWith('diff --git '));
+}
+
+/**
+ * Does a RENAMED file drop schema on the side the added-line anchors cannot see?
+ *
+ * MEASURED at 022c0d240. A rename with `similarity index 88%` whose hunk reads
+ *
+ *     -Schema::dropTable("users");
+ *     +Schema::create("users");
+ *
+ * classified `additive`, markers `[]`. Both schema markers in the table above
+ * are anchored to `^\+` for a good reason — a migration that REMOVES a
+ * `dropColumn` call is the opposite of destructive, and that counter-case is
+ * pinned by its own test. But the reason stops holding inside a rename: the
+ * content did not stay put, so a removal on the old path is not "the drop was
+ * taken out", it is "the drop moved and the file it lived in is gone".
+ *
+ * So the widened scan is CONDITIONAL on git's rename metadata, per the risk
+ * this roadmap recorded against exactly this step — it is not applied to every
+ * deleted line, which would score the pinned counter-case destructive.
+ *
+ * NOT COVERED, and stated rather than implied: a `similarity index 100%` rename
+ * carries no content lines at all, so nothing here fires on it and it stays
+ * `additive`. That is the honest reading — a pure move drops nothing — but it
+ * does mean a moved migration is invisible to this scan. Recorded as a residual
+ * rather than closed by guessing at a path-shape heuristic.
+ */
+function renamedSchemaRemoval(patch: string): boolean {
+  for (const block of fileBlocks(patch)) {
+    if (!RENAME_METADATA.test(block)) {
+      continue;
+    }
+    for (const line of block.split('\n')) {
+      if (line.startsWith('-') && !line.startsWith('---') && SCHEMA_REMOVAL_BODY.test(line)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/** A major-version bump in a manifest, which is the author declaring a break. */
+const MAJOR_BUMP =
+  /^-\s*"version"\s*:\s*"(\d+)\.[^"]*"[\s\S]{0,200}?^\+\s*"version"\s*:\s*"(\d+)\./m;
+
+/**
+ * Classify a unified diff.
+ *
+ * Pure — the caller supplies the patch, so this is testable without a network,
+ * a repository, or a fixture PR.
+ */
+export function classifyDiff(patch: string): MergeImpact {
+  if (patch.trim() === "") {
+    return { verdict: "undecidable", markers: [], reason: "empty diff" };
+  }
+
+  const markers: string[] = [];
+  for (const { label, re } of DESTRUCTIVE_MARKERS) {
+    if (re.test(patch)) {
+      markers.push(label);
+    }
+  }
+
+  if (renamedSchemaRemoval(patch)) {
+    markers.push("a renamed file drops a column or table");
+  }
+
+  const bump = MAJOR_BUMP.exec(patch);
+  if (bump && bump[1] !== bump[2]) {
+    markers.push(`major version bump ${bump[1]}.x to ${bump[2]}.x`);
+  }
+
+  const filesChanged = (patch.match(/^diff --git /gm) ?? []).length;
+
+  if (markers.length > 0) {
+    return { verdict: "destructive", markers, filesChanged };
+  }
+  return { verdict: "additive", markers: [], filesChanged };
+}
+
+/** How the patch was obtained, so a refusal can say which source answered. */
+export type PatchSource = "local" | "gh" | "none";
+
+export interface PatchResult {
+  patch: string;
+  source: PatchSource;
+  reason?: string;
+}
+
+/**
+ * Fetch the diff for a pull request, local first.
+ *
+ * The ordering is not a preference, it is a cost decision. A local
+ * `git diff` against the merge base costs milliseconds and works offline; a
+ * `gh pr diff` costs a network round trip on a `pre_tool_use` hook, which is in
+ * the user's critical path. Local answers whenever the ref happens to be
+ * fetched, which in a drain run is almost always, because the run just synced
+ * the branch it is about to merge.
+ *
+ * Every failure returns `none` rather than throwing. The caller turns that into
+ * `undecidable`, which asks the user — a hook that crashed would be worse than
+ * a hook that admitted it did not know.
+ */
+export function fetchPatch(
+  pr: number,
+  opts: { cwd?: string; allowNetwork?: boolean; exec?: typeof execFileSync } = {},
+): PatchResult {
+  const run = opts.exec ?? execFileSync;
+  const cwd = opts.cwd ?? process.cwd();
+  const capture = (file: string, args: string[]): string =>
+    run(file, args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 15_000 }) as unknown as string;
+
+  // A fetched PR ref is what a synced drain run leaves behind.
+  for (const ref of [`refs/pull/${pr}/head`, `pull/${pr}/head`]) {
+    try {
+      const base = capture("git", ["merge-base", "HEAD", ref]).trim();
+      if (base) {
+        const patch = capture("git", ["diff", `${base}...${ref}`]);
+        if (patch.trim() !== "") {
+          return { patch, source: "local" };
+        }
+      }
+    } catch {
+      /* try the next spelling, then the network */
+    }
+  }
+
+  if (opts.allowNetwork === false) {
+    return { patch: "", source: "none", reason: "no local ref and network reads disabled" };
+  }
+
+  try {
+    const patch = capture("gh", ["pr", "diff", String(pr), "--patch"]);
+    if (patch.trim() !== "") {
+      return { patch, source: "gh" };
+    }
+    return { patch: "", source: "none", reason: "gh returned an empty diff" };
+  } catch {
+    return { patch: "", source: "none", reason: "no local ref, and gh pr diff failed" };
+  }
+}
+
+/** Analyse a pull request end to end. `undecidable` whenever the patch is not readable. */
+export function analyseMergeImpact(
+  pr: number,
+  opts: Parameters<typeof fetchPatch>[1] = {},
+): MergeImpact {
+  const got = fetchPatch(pr, opts);
+  if (got.source === "none") {
+    return { verdict: "undecidable", markers: [], ...(got.reason ? { reason: got.reason } : {}) };
+  }
+  return classifyDiff(got.patch);
+}
+
+/**
+ * One line for a refusal message.
+ *
+ * Phrased so the user can answer it out loud, which is the point of the whole
+ * stage: the shortest reply that unblocks the operation is quoted back to them.
+ */
+export function describeImpact(pr: number, impact: MergeImpact): string {
+  const say = `Say "merge #${pr}" to authorize it.`;
+  switch (impact.verdict) {
+    case "additive":
+      return (
+        `Impact scan: PR #${pr} touches ${impact.filesChanged ?? 0} file(s) and trips no ` +
+        `destructive marker — no schema drop, no removed export or route, no major bump, ` +
+        `no BREAKING CHANGE. Additive as far as the diff can show, which is not the same ` +
+        `as safe to merge: the base has moved since review and merging may trigger a ` +
+        `deploy. ${say}`
+      );
+    case "destructive":
+      return (
+        `Impact scan: PR #${pr} is NOT additive — ${impact.markers.join("; ")}. ` +
+        `Read the diff before authorizing. ${say}`
+      );
+    default:
+      return (
+        `Impact scan: could not read the diff for PR #${pr} (${impact.reason ?? "unknown"}), ` +
+        `so nothing is known about what it changes. ${say}`
+      );
+  }
+}