@event4u/agent-config 13.0.0 → 14.1.0

package/src/scripts/git_authorization_hook.ts

@@ -43,8 +43,102 @@ import { readHookStdin } from "./hooks/hook_stdin.js";
 
 const EXIT_ALLOW = 0;
 
+/**
+ * Legacy single-file ledger path — one file for the whole project root.
+ *
+ * Kept for direct invocations and for reading a ledger written by an older
+ * build, NOT as the write target when a session id is known. See
+ * `ledgerFileFor` for why one shared file was the defect.
+ */
 export const STATE_FILE = path.join("agents", "state", "git-authorization.json");
 
+/** Per-session ledger directory. */
+export const STATE_DIR = path.join("agents", "state", "git-authorization");
+
+/** Per-session pending-refusal directory. */
+export const PENDING_DIR = path.join("agents", "state", "git-authorization-pending");
+
+/**
+ * A session id reduced to a safe path component.
+ *
+ * The id reaches this from the host's envelope, so it is untrusted input on a
+ * path — `..` or a separator in it would place the ledger outside the state
+ * directory. Anything outside the allowed set collapses to `_`.
+ */
+export function sessionSlug(session_id: string): string {
+    return session_id.replace(/[^A-Za-z0-9._-]/gu, "_").slice(0, 80);
+}
+
+/**
+ * Where THIS session's ledger lives.
+ *
+ * MEASURED DEFECT (2026-08-18, during the 14.0.0 release): the ledger was a
+ * single file per project root, so every prompt from every concurrent session
+ * in the repo overwrote it. A second session typed an 11-character prompt
+ * between the user's `merge den pr` and the guard's read; the guard found a
+ * foreign session id, discarded the ledger as another conversation's consent,
+ * and refused. The refusal then said "no authorization in this turn's prompt",
+ * which was false and unfalsifiable from the message alone — the authorization
+ * had existed and been clobbered. Three consecutive refusals, and the user
+ * re-authorized each time.
+ *
+ * This repo runs dozens of worktrees against one root, so the race is not an
+ * edge case there; it is the normal condition. Scoping the file by session is
+ * what makes "this turn's prompt" mean this conversation's turn.
+ */
+export function ledgerFileFor(session_id: string): string {
+    if (!session_id) {
+        return STATE_FILE;
+    }
+    return path.join(STATE_DIR, `${sessionSlug(session_id)}.json`);
+}
+
+/** Where THIS session's refused-operation record lives. */
+export function pendingFileFor(session_id: string): string {
+    if (!session_id) {
+        return PENDING_FILE;
+    }
+    return path.join(PENDING_DIR, `${sessionSlug(session_id)}.json`);
+}
+
+/**
+ * One refused irreversible operation, waiting for the answer to the question
+ * the guard just told the agent to ask.
+ *
+ * WHY THIS FILE EXISTS — the measured deadlock (2026-08-18, 14.0.0 release):
+ * `user-interaction` requires a decision to be handed to the user as a
+ * NUMBERED-OPTIONS block, and the answer to one is a bare `1`. The classifier
+ * below reads the prompt in isolation, and `1` carries no operation, so the
+ * user's consent was real, visible, and unrecordable. The release deadlocked
+ * for three turns: the guard refused, the agent asked as instructed, the user
+ * answered, and the next attempt refused identically. Two mechanisms this repo
+ * mandates were structurally incompatible on exactly the irreversible subset.
+ *
+ * The fix is deliberately the narrowest thing that resolves it. Widening the
+ * prose list with bare affirmatives was rejected: `ja` would then authorize
+ * `npm publish` on any turn, which is reach, not severity. Instead the guard
+ * records WHICH op it refused, and only that one op can be confirmed, once, by
+ * the immediately following prompt. Everything the user is consenting to has
+ * already been named to them in the refusal they just read.
+ */
+export const PENDING_FILE = path.join("agents", "state", "git-authorization-pending.json");
+
+/** A refused operation carried to exactly one following prompt. */
+export interface PendingRefusal {
+    op: GitOp;
+    session_id: string;
+    refused_at: string;
+}
+
+/**
+ * The window in which a refusal is still the thing the user is answering.
+ *
+ * Short on purpose: this is "the user read the refusal and replied", not "the
+ * user said yes to something at some point today". A stale record expires into
+ * the same not-authorized state the guard starts from.
+ */
+export const PENDING_MAX_AGE_MS = 10 * 60 * 1000;
+
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };
 
@@ -142,6 +236,36 @@ export function isInterrogative(prose: string): boolean {
   );
 }
 
+/**
+ * Is this prompt an ANSWER to the refusal the user was just shown?
+ *
+ * Accepts the two shapes a numbered-options block actually produces — a bare
+ * selection (`1`, `1.`, `Option 2`) and a bare affirmative (`ja`, `ok`, `mach`,
+ * `go`, `do it`) — and nothing else. The bar is that the prompt says yes and
+ * says NOTHING ELSE: a turn that also carries new instructions is a new turn,
+ * not an answer, and must name its operation like any other.
+ *
+ * That last clause is the whole safety argument, so it is enforced by length
+ * rather than by good intentions. `release und fixe auch den schess bug` reads
+ * as consent to a human and is correctly NOT an affirmative here — it opens new
+ * work, and the op it authorizes is the one it names.
+ */
+export function isAffirmative(prose: string): boolean {
+    const t = prose.trim().replace(/[.!]+$/u, "");
+    if (!t || t.length > 24) {
+        return false;
+    }
+    if (isInterrogative(t)) {
+        return false;
+    }
+    return (
+        /^(?:option\s*)?\d{1,2}[.)]?$/iu.test(t) ||
+        /^(ja|jo|jep|yes|yep|yeah|ok|okay|okey|klar|passt|gut|los|go|go ahead|mach|mach das|mach es|leg los|do it|proceed|bitte)$/iu.test(
+            t,
+        )
+    );
+}
+
 /** Executable commands a user may paste, mapped to the op they authorize. */
 const PASTED_COMMANDS: ReadonlyArray<{ op: GitOp; re: RegExp }> = [
   { op: "publish", re: /\bnpm\s+publish\b/i },
@@ -242,6 +366,55 @@ export function classifyAuthorization(prompt: string): {
   return { authorized: [...authorized], evidence };
 }
 
+/**
+ * Read the refused operation, and consume it in the same breath.
+ *
+ * Consuming unconditionally is the single-use guarantee: the record survives
+ * exactly one following prompt whether or not that prompt confirmed it, so a
+ * `ja` three turns later cannot reach back to a refusal the user has long
+ * stopped thinking about.
+ */
+export function takePending(
+    consumer_root: string,
+    session_id: string,
+    now: number,
+): PendingRefusal | null {
+    const file = path.join(consumer_root, pendingFileFor(session_id));
+    let raw: string;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    } catch {
+        return null;
+    }
+    try {
+        fs.rmSync(file, { force: true });
+    } catch {
+        /* consumed in memory either way — a stale file expires by age below */
+    }
+    try {
+        const decoded = JSON.parse(raw) as unknown;
+        if (!_isObject(decoded)) {
+            return null;
+        }
+        const op = decoded["op"];
+        if (typeof op !== "string" || !(ALL_OPS as readonly string[]).includes(op)) {
+            return null;
+        }
+        const recorded = typeof decoded["session_id"] === "string" ? decoded["session_id"] : "";
+        // A refusal from another conversation is another conversation's question.
+        if (session_id && recorded && recorded !== session_id) {
+            return null;
+        }
+        const at = Date.parse(String(decoded["refused_at"] ?? ""));
+        if (!Number.isFinite(at) || now - at > PENDING_MAX_AGE_MS) {
+            return null;
+        }
+        return { op: op as GitOp, session_id: recorded, refused_at: String(decoded["refused_at"]) };
+    } catch {
+        return null;
+    }
+}
+
 export function run(stdin_text: string, options: { consumer_root: string }): number {
   let envelope: JsonObject = {};
   if (stdin_text.trim()) {
@@ -269,6 +442,18 @@ export function run(stdin_text: string, options: { consumer_root: string }): num
   }
 
   const { authorized, evidence } = classifyAuthorization(prompt);
+
+  // The answer to the guard's own question. Read (and consume) on EVERY prompt,
+  // so the record cannot outlive the turn it was raised in.
+  const session = typeof envelope["session_id"] === "string" ? envelope["session_id"] : "";
+  const pending = takePending(options.consumer_root, session, Date.now());
+  if (pending && !authorized.includes(pending.op) && isAffirmative(prompt)) {
+    authorized.push(pending.op);
+    evidence[pending.op] =
+      `confirmation of the refused \`${pending.op}\` (refused ${pending.refused_at}): ` +
+      `"${prompt.trim().slice(0, 40)}"`;
+  }
+
   const ledger: Ledger = {
     session_id: typeof envelope["session_id"] === "string" ? envelope["session_id"] : "",
     detected_at: new Date().toISOString(),
@@ -278,7 +463,7 @@ export function run(stdin_text: string, options: { consumer_root: string }): num
   };
 
   try {
-    atomic_write_json(path.join(options.consumer_root, STATE_FILE), ledger);
+    atomic_write_json(path.join(options.consumer_root, ledgerFileFor(session)), ledger);
   } catch {
     // Observability only — a failed write degrades the gate to "no ledger",
     // which the pre_tool_use concern treats as "not authorized" for the

package/src/scripts/hook_manifest.yaml

@@ -74,6 +74,21 @@ concerns:
   # Phase 5 — Tier-1 hook for the minimal-safe-diff rule. Counts unique
   # files touched per turn into agents/runtime/state/minimal-safe-diff.json and
   # flips warning=true past hooks.minimal_safe_diff.threshold.
+  # road-to-metric-loop-and-review-integrity Phase 4 — shipping-intent gate on
+  # diff VOLUME, complementary to `minimal-safe-diff` rather than a duplicate:
+  # that concern counts unique files touched PER TURN, this one counts changed
+  # lines on the branch AT A SHIP VERB. Threshold 1695 is the corrected p90 of
+  # this repository's own last 40 merged PRs, and the exclusion set (review-input
+  # snapshots, generated indexes, projection trees) is part of the metric's
+  # definition, not a tuning knob — the replay measured the naive metric
+  # double-counting the diff it was measuring. Warn-level first; escalation waits
+  # for one release of recorded firings. Evidence:
+  # agents/evidence/eval-findings/metric-loop-s04.md
+  ship-diff-volume:
+    script: src/scripts/hooks/ship_diff_volume_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
   minimal-safe-diff:
     script: src/scripts/minimal_safe_diff_hook.ts
     args: []
@@ -474,6 +489,16 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+    # road-to-stop-gate-honesty step 3.1 — skipped on a refusal RETRY.
+    # ARGUMENT, per concern as that step requires: the F2 fire gate is a
+    # once-per-session marker, and this concern's own header records that a
+    # second run "reads the marker and returns silently, without re-running the
+    # transcript scan". The retry therefore cannot change its artefact — the
+    # telemetry line was already written, or already suppressed, on the first
+    # Stop. Idempotence is the concern's own construction, not our assumption
+    # about it. The saving is the module load rather than a large read, which is
+    # the smaller of the two flags below it and is stated as such.
+    skip_on_refusal_retry: true
   # road-to-conformance-round5 Phase 3 — the FIRST concern that can refuse a
   # turn-END. Round 5 measured the reason: both blocking carriers reached zero
   # violations, neither advisory carrier did, and 19 language violations
@@ -557,6 +582,43 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+  # road-to-user-out-of-the-loop Phase 0 Step 1 — the interruption ledger.
+  # Every Stop, classifies whether the turn that just ended put a synchronous
+  # contact to the user and appends one `{run_id, turn, kind, class, roadmap}`
+  # line to gitignored runtime state (agents/runtime/state/interruptions.jsonl,
+  # file shape after gate-metrics.jsonl). Three classes, not two: a hand-back
+  # ("das entscheidest Du", "your call") ends the turn and waits for the user
+  # exactly as a question does, so counting only `?` would report this
+  # package's own preferred shape as zero contacts.
+  #
+  # CAPTURE ONLY, and that is the point rather than caution: Phase 0's two
+  # pre-registered claims are baselines, and a baseline can only be read off a
+  # window no mechanism reacted to. It emits nothing, never warns, and always
+  # returns 0 — so it carries no src/config/hook-token-budget.json row, the
+  # same as subagent-ledger and orchestration-record.
+  #
+  # Reply-shape detection is IMPORTED from turn-end-gate (readTranscriptTail,
+  # finalParagraph, HANDBACK) rather than copied — a second copy would drift
+  # from the measured corpus's detector and the drift would land silently in
+  # the baseline. Dedupe on the turn ordinal, the same identity that hook
+  # derives, because a host may fire Stop twice for one turn. fail_closed: false.
+  interruption-ledger:
+    script: src/scripts/hooks/interruption_ledger_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
+    # road-to-stop-gate-honesty step 3.1 — skipped on a refusal RETRY, and this
+    # is the flag with the real saving.
+    # ARGUMENT, per concern: `alreadyRecorded(ledgerPath, run_id, turn)` dedupes
+    # on the TURN ORDINAL, and a refusal retry is the same turn by construction
+    # — the gate's layer-2 marker is keyed on that same ordinal. So the ledger
+    # already writes nothing on the retry and the artefact is provably identical.
+    # What it does NOT already avoid is the cost: `main()` calls
+    # `readTranscriptTail` (up to 8 MB, walking the whole file) BEFORE reaching
+    # `alreadyRecorded`, so today every refused Stop pays a full transcript walk
+    # and then discards the result. That is the "pure duplicate cost" § D-3
+    # names, measured in the source rather than assumed.
+    skip_on_refusal_retry: true
   # road-to-subagent-lifecycle-integrity Phase 1 (Steps 2+3) — the subagent
   # lifecycle ledger. Binds ONLY the two new events; on every other slot it is
   # not listed at all. Appends `subagent_start` / `subagent_stop` lines to
@@ -665,22 +727,27 @@ roles:
     # is on it: a worker was handed a bounded slice by an orchestrator that
     # already chose the approach, so a routing pointer there advises nobody who
     # can act on it and costs the dispatch anyway.
-    drop: [delegation-nudge, skill-route, end-review-nudge, council-availability, team-review-gate, self-repair, session-eol]
+    # `interruption-ledger` joins it on the first clause verbatim — "a worker
+    # never talks to the user". Its whole measurement is synchronous user
+    # contacts, so a worker turn that ends in a question to its orchestrator
+    # would be recorded as a contact that never reached a human, inflating the
+    # exact baseline Phase 0 pre-registers.
+    drop: [delegation-nudge, skill-route, end-review-nudge, council-availability, team-review-gate, self-repair, session-eol, interruption-ledger]
 
 platforms:
   augment:
     session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:      [chat-history, memory-learn, session-register]
     stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register]
-    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard]
+    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, ship-diff-volume, reread-guard]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
 
   claude:
     session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:      [chat-history, memory-learn, session-register]
-    stop:             [chat-history, hot-context, verify-before-complete, team-review-gate, end-review-nudge, turn-end-gate, self-repair, session-register, session-eol]
+    stop:             [chat-history, hot-context, verify-before-complete, team-review-gate, end-review-nudge, turn-end-gate, self-repair, session-register, session-eol, interruption-ledger]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, delegation-nudge, skill-route, git-authorization, session-canary, self-repair, session-register]
-    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard, spawn-guard-shadow]
+    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, ship-diff-volume, reread-guard, spawn-guard-shadow]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape, language-mirror]
     # `language-mirror` — round-5 § 6.1. `pre_compact` sets a pin-lost marker;
     # the `post_tool_use` entry above re-emits the pin exactly once while that
@@ -734,7 +801,7 @@ platforms:
     # still costs the dispatch, and its entire output is thrown away.
     stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard, spawn-guard-shadow]
+    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, ship-diff-volume, reread-guard, spawn-guard-shadow]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
     # subagent-ledger IS bound here, unlike the two nudges above, and the
     # difference is the delivery channel rather than the platform: the nudges

package/src/scripts/hooks/block_unauthorized_git.ts

@@ -61,7 +61,13 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { readHookStdin } from "./hook_stdin.js";
-import { STATE_FILE, type GitOp } from "../git_authorization_hook.js";
+import { atomic_write_json } from "./state_io.js";
+import {
+  ledgerFileFor,
+  pendingFileFor,
+  STATE_FILE,
+  type GitOp,
+} from "../git_authorization_hook.js";
 
 const EXIT_ALLOW = 0;
 // MUST equal dispatch_hook.EXIT_BLOCK. The dispatcher's internal ladder is
@@ -497,18 +503,45 @@ function _loadLedger(
   session_id: string,
   now: number,
 ): { authorized: Set<GitOp>; present: boolean } {
+  // 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;
+    }
+  }
+  return { authorized: new Set<GitOp>(), present: false };
+}
+
+/**
+ * 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(path.join(consumer_root, STATE_FILE), "utf8");
+    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 { authorized: new Set<GitOp>(), present: false };
+        return null;
       }
       const at = Date.parse(String(decoded["detected_at"] ?? ""));
       if (Number.isFinite(at) && now - at > LEDGER_MAX_AGE_MS) {
-        return { authorized: new Set<GitOp>(), present: false };
+        return null;
       }
       return {
         authorized: new Set((decoded["authorized"] as string[]).filter(Boolean) as GitOp[]),
@@ -518,13 +551,21 @@ function _loadLedger(
   } catch {
     /* fall through */
   }
-  return { authorized: new Set<GitOp>(), present: false };
+  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;
 }
 
 export function decide(
@@ -547,7 +588,7 @@ export function decide(
       `This operation is irreversible and non-destructive-by-default already declares it ` +
       `never-autonomous. Command: ${shown}. ` +
       `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` };
+    return { exit: EXIT_BLOCK, stdout: "", stderr: `${reason}\n`, blockedOp: op };
   }
 
   if (WARN_OPS.has(op)) {
@@ -582,6 +623,21 @@ export function run(stdin_text: string, options: { consumer_root: string }): num
     extractCommand(envelope),
     _loadLedger(options.consumer_root, session_id, Date.now()),
   );
+  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);
   }

package/src/scripts/hooks/concern_registry.ts

@@ -32,6 +32,7 @@ import { main as onboardingGateMain } from '../onboarding_gate_hook.js';
 import { main as contextHygieneMain } from '../context_hygiene_hook.js';
 import { main as verifyBeforeCompleteMain } from '../before_complete_hook.js';
 import { main as minimalSafeDiffMain } from '../minimal_safe_diff_hook.js';
+import { main as shipDiffVolumeMain } from './ship_diff_volume_hook.js';
 import { main as injectionScanMain } from '../injection_scan_hook.js';
 import { main as memoryLearnMain } from '../memory_learn_hook.js';
 import { main as firstRunGateMain } from '../first_run_gate_hook.js';
@@ -66,6 +67,7 @@ import { main as sessionEolMain } from './session_eol_hook.js';
 import { main as subagentLedgerMain } from './subagent_ledger_hook.js';
 import { main as toolResultBytesMain } from './tool_result_bytes_hook.js';
 import { main as spawnGuardShadowMain } from './spawn_guard_shadow_hook.js';
+import { main as interruptionLedgerMain } from './interruption_ledger_hook.js';
 
 /** A concern `main` — argv-taking or not; both shapes exist. */
 export type ConcernMain = (argv?: string[]) => number | undefined | void;
@@ -80,6 +82,7 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/context_hygiene_hook.ts': contextHygieneMain as ConcernMain,
     'src/scripts/before_complete_hook.ts': verifyBeforeCompleteMain as ConcernMain,
     'src/scripts/minimal_safe_diff_hook.ts': minimalSafeDiffMain as ConcernMain,
+    'src/scripts/hooks/ship_diff_volume_hook.ts': shipDiffVolumeMain as ConcernMain,
     'src/scripts/injection_scan_hook.ts': injectionScanMain as ConcernMain,
     'src/scripts/memory_learn_hook.ts': memoryLearnMain as ConcernMain,
     'src/scripts/first_run_gate_hook.ts': firstRunGateMain as ConcernMain,
@@ -114,4 +117,5 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/subagent_ledger_hook.ts': subagentLedgerMain as ConcernMain,
     'src/scripts/hooks/tool_result_bytes_hook.ts': toolResultBytesMain as ConcernMain,
     'src/scripts/hooks/spawn_guard_shadow_hook.ts': spawnGuardShadowMain as ConcernMain,
+    'src/scripts/hooks/interruption_ledger_hook.ts': interruptionLedgerMain as ConcernMain,
 };

package/src/scripts/hooks/dispatch_hook.ts

@@ -342,16 +342,51 @@ export function _role_drop_set(
   return new Set(drop.filter((d): d is string => typeof d === "string"));
 }
 
+/**
+ * True when this `stop` is the RETRY of a turn a stop-hook already refused.
+ *
+ * The host sets `stop_hook_active` on exactly that Stop; `turn_end_gate_hook`
+ * reads the same field as its layer-1 re-entrancy guard, so this is the host's
+ * own answer rather than an inference of ours. Anything unparseable is `false`,
+ * which is the full chain — the safe direction, since the cost of running a
+ * concern twice is duplicate work and the cost of skipping one wrongly is a lost
+ * write.
+ */
+export function _is_refusal_retry(event: string, payload_text: string): boolean {
+  if (event !== "stop") return false;
+  try {
+    const parsed: unknown = JSON.parse(payload_text);
+    if (!_isObject(parsed)) return false;
+    const payload = parsed["payload"];
+    const source = _isObject(payload) ? payload : parsed;
+    return source["stop_hook_active"] === true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Return the ordered concern definitions for (platform, event) under the
  * given session role (default `orchestrator` — byte-identical to the
  * pre-role-axis behaviour).
+ *
+ * `opts.refusal_retry` drops concerns that opted in with
+ * `skip_on_refusal_retry: true` — `road-to-stop-gate-honesty` step 3.1. Stop is
+ * the heaviest slot on claude and **every refused Stop runs the whole slot again
+ * on the retry** (§ D-3), so the concerns whose second run provably produces the
+ * identical artefact are pure duplicate cost.
+ *
+ * Opt-in per concern, default off, never a blanket skip: Risk 3 of that roadmap
+ * is that a concern skipped on the retry might have been the one that needed the
+ * second pass, and the loss would be silent. The manifest carries the per-concern
+ * argument beside each flag.
  */
 export function _resolve_concerns(
   manifest: JsonObject,
   platform: string,
   event: string,
   role: SessionRole = "orchestrator",
+  opts: { refusal_retry?: boolean } = {},
 ): ConcernDef[] {
   const platformsRaw = manifest["platforms"];
   const platforms = _isObject(platformsRaw) ? platformsRaw : {};
@@ -381,6 +416,9 @@ export function _resolve_concerns(
       );
       continue;
     }
+    if (opts.refusal_retry && spec["skip_on_refusal_retry"] === true) {
+      continue;
+    }
     out.push({ name: String(name), ...spec });
   }
   return out;
@@ -1081,13 +1119,17 @@ export function main(argv?: string[]): number {
   const payload_text = process.stdin.isTTY ? "" : _readStdin();
   _maybe_capture_payload(args, payload_text);
   const session_role = resolveSessionRole(process.env);
-  const concerns = _resolve_concerns(manifest, args.platform, args.event, session_role);
+  const refusal_retry = _is_refusal_retry(args.event, payload_text);
+  const concerns = _resolve_concerns(manifest, args.platform, args.event, session_role, {
+    refusal_retry,
+  });
 
   if (args.dry_run) {
     const plan = {
       platform: args.platform,
       event: args.event,
       role: session_role,
+      refusal_retry,
       concerns: concerns.map((c) => c["name"]),
     };
     process.stdout.write(_py_json_dumps(plan, 2) + "\n");