@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/hooks/block_plumbing_writes.ts

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse guard: refuse a hand edit to a hook BUILD OUTPUT.
+ *
+ * road-to-a-kernel-that-guards-its-plumbing 1.2 — the other half of a
+ * deliberate split, and the split is the whole design:
+ *
+ *   · plumbing SOURCES (`hook_manifest.yaml`, `host_lowering.yaml`, the
+ *     `*-dispatcher.sh` trampolines, both hook budget files) are edited
+ *     legitimately all the time. They carry a RECORD — the ADR-268 § 4
+ *     ratification gate, path set extended by step 1.1 — not a deny.
+ *   · plumbing BUILD OUTPUTS have no legitimate hand edit at all. They carry a
+ *     DENY, which is this file.
+ *
+ * One mechanism per file class. A record for a file whose every hand edit is a
+ * mistake would be a record of a mistake; a deny on a file people edit on
+ * purpose would be a wedge.
+ *
+ * WHAT IS REFUSED.
+ *
+ * - `dist/hooks/dispatch.js` — the esbuild bundle (`npm run build:hooks`).
+ *   Every concern the dispatcher runs is inlined here. A hand edit survives
+ *   until the next build, reaches every dispatch in the meantime, and is
+ *   invisible in a source review.
+ * - `hooks/hooks.json` — the host binding file, written by `condense.ts` via
+ *   `task sync`. A hand edit here silently unbinds a guard.
+ * - `src/scripts/hook_manifest.json` and `src/scripts/hooks/host_lowering.json`
+ *   — the compiled plumbing tables, written by `compile_hook_manifest`
+ *   (road-to-blocking-severities 2.2). These are the ones the RUNTIME actually
+ *   reads: `dispatch_hook._load_yaml` and `host_lowering.resolveTable` serve
+ *   the compiled body in preference to the YAML whenever its fingerprint
+ *   matches, so an edited table is what every host is told about which concern
+ *   runs and which slot can refuse, while the reviewed YAML beside it still
+ *   says something else.
+ *
+ * All four are matched under any parent directory, because a consumer install
+ * carries them under its own project root rather than under this repository's.
+ *
+ * WHAT STILL PASSES, and why that is not a hole.
+ *
+ * `npm run build:hooks` and `task sync` are the legitimate writers, and both
+ * reach these files through a build tool rather than through a shell write
+ * shape: the command string carries no redirect into the path, no in-place
+ * `sed`, no `tee`/`mv`/`cp` naming it. `shellWriteTarget` matches shapes, not
+ * effects, so the builds pass and a hand edit does not. Stated here because it
+ * is the property that makes this guard safe to bind `fail_closed`.
+ *
+ * KNOWN OPEN, stated rather than implied.
+ *
+ * A write whose target never appears as a path-shaped token — built inside an
+ * interpreter's own argument, as in `python3 -c "open('hooks/hooks.json','w')…"`
+ * — carries none of the recognised shapes and is NOT detected. This is the same
+ * residual `block_kernel_rule_writes.ts` declares for itself and the same
+ * boundary: a guard, not write mediation. The honest claim is that the cheap
+ * and the accidental paths are closed, not that the determined one is.
+ *
+ * "Through an interpreter" does not by itself mean undetected, and the tests
+ * pin both directions: `sh -c 'printf x > hooks/hooks.json'` IS refused,
+ * because the redirect survives the tokenizer inside the quoted argument.
+ *
+ * MANIFEST DECLARATION.
+ *
+ * `fail_closed: true`, `severity: blocking`. The fail-closed guarantee is
+ * about a DETECTED write: a malformed envelope with no target at all allows,
+ * exactly as the kernel guard does, because a guard that blocks what it cannot
+ * read turns a shape defect into a wedged session.
+ *
+ * No agent-accessible kill switch — deliberately, and it is also what
+ * `lint_deny_text` (step 1.3) requires of every blocking concern's deny text.
+ * The legitimate change is to rebuild the file from its source.
+ *
+ * Exit codes (docs/contracts/hook-architecture-v1.md):
+ *   0 — allow
+ *   1 — block
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { shellWriteTarget } from '../_lib/shell_write_shapes.js';
+import { EDIT_TOOLS } from '../minimal_safe_diff_hook.js';
+import { COMMAND_TOOLS } from '../before_complete_hook.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function _isObject(v: JsonValue | undefined): v is JsonObject {
+    return v !== null && v !== undefined && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * The generated plumbing artifacts, as trailing path segments.
+ *
+ * A trailing match rather than a repo-relative one because the same two files
+ * exist under every consumer project root and under this repository's, and a
+ * guard anchored to one tree would be silent in the other.
+ */
+export const PLUMBING_BUILD_OUTPUTS: readonly string[] = [
+    'dist/hooks/dispatch.js',
+    'hooks/hooks.json',
+    'src/scripts/hook_manifest.json',
+    'src/scripts/hooks/host_lowering.json',
+];
+
+/**
+ * Where each output comes from, printed in the deny so the reader is told what
+ * to run instead of only what not to do.
+ *
+ * road-to-blocking-severities 2.2 added the two compiled tables. They are the
+ * same KIND of file as the first two — written by a build, never by hand — and
+ * until this step they were refused by nothing, which mattered more here than
+ * it would have for an ordinary generated artifact: `dispatch_hook._load_yaml`
+ * and `host_lowering.resolveTable` both serve the compiled body IN PREFERENCE
+ * to the YAML whenever its fingerprint matches, so an edited JSON is what every
+ * host is told about which concern runs and which slot can refuse.
+ *
+ * Their YAML sources stay OUT of this set and keep carrying a ratification
+ * record instead — a hand edit there is legitimate and is exactly how the
+ * plumbing is maintained. The split is the one the guard's header already
+ * draws: a deny for files with no legitimate hand edit, a record for files
+ * whose hand edits are the point.
+ */
+const REGENERATED_BY: Readonly<Record<string, string>> = {
+    'dist/hooks/dispatch.js': 'npm run build:hooks',
+    'hooks/hooks.json': 'task sync',
+    'src/scripts/hook_manifest.json':
+        './scripts-run src/scripts/compile_hook_manifest --table manifest',
+    'src/scripts/hooks/host_lowering.json':
+        './scripts-run src/scripts/compile_hook_manifest --table host-lowering',
+};
+
+// Keys across platforms that carry the tool's target file path.
+const _PATH_KEYS: readonly string[] = [
+    'file_path',
+    'path',
+    'target_file',
+    'filename',
+    'filePath',
+    'notebook_path',
+];
+
+/** Normalize separators; strip a leading "./" run so segment checks are robust. */
+function _normalize(p: string): string {
+    return p.replace(/\\/g, '/').replace(/^(\.\/)+/, '');
+}
+
+/**
+ * The build output `filePath` names, or `null`.
+ *
+ * Two matching rules, because the guard has two kinds of input and only one of
+ * them carries enough information to be exact:
+ *
+ *   · a RELATIVE path is matched EXACTLY, after a leading `./` or `../` run is
+ *     stripped. `dist/hooks/dispatch.js` and `./hooks/hooks.json` are the
+ *     governed files; `docs/hooks/hooks.json` is a different file that happens
+ *     to end the same way, and refusing it would be an over-block on a file
+ *     nothing generates.
+ *   · an ABSOLUTE path is matched on its trailing segments, because the guard
+ *     does not know where the project root is and a host that sends absolute
+ *     paths — Claude Code sends every `file_path` absolute — would otherwise
+ *     escape it entirely. A fail-open on the main path is the worse of the two
+ *     errors.
+ *
+ * The residual is named rather than hidden: an absolute path ending in
+ * `…/hooks/hooks.json` under an unrelated parent is refused too. That is the
+ * conservative direction for a two-file guard, and the fix if it ever bites is
+ * to relativise against the envelope's `workspace_root`.
+ *
+ * A bare basename (`dispatch.js`) never matches under either rule — it is not
+ * evidence that the governed file is the target.
+ */
+export function targets_plumbing_output(filePath: string): string | null {
+    if (!filePath) {
+        return null;
+    }
+    const normalized = _normalize(filePath);
+    const absolute = normalized.startsWith('/') || /^[A-Za-z]:\//.test(normalized);
+    const segments = normalized.split('/').filter((s) => s.length > 0 && s !== '.');
+    const relevant = absolute ? segments : segments.filter((s) => s !== '..');
+
+    for (const output of PLUMBING_BUILD_OUTPUTS) {
+        const want = output.split('/');
+        if (absolute) {
+            if (relevant.length < want.length) {
+                continue;
+            }
+            const tail = relevant.slice(relevant.length - want.length);
+            if (tail.every((s, i) => s === want[i])) {
+                return output;
+            }
+            continue;
+        }
+        if (relevant.length === want.length && relevant.every((s, i) => s === want[i])) {
+            return output;
+        }
+    }
+    return null;
+}
+
+/** Best-effort (toolName, candidate target paths) read off a PreToolUse envelope. */
+function _extract(envelope: JsonObject): { tool: string; paths: string[] } {
+    const payload = _isObject(envelope['payload']) ? envelope['payload'] : envelope;
+    const nameVal =
+        payload['tool_name'] ??
+        payload['toolName'] ??
+        payload['tool'] ??
+        envelope['tool_name'] ??
+        envelope['tool'];
+    const tool = typeof nameVal === 'string' ? nameVal : '';
+
+    const ti = _isObject(payload['tool_input'])
+        ? payload['tool_input']
+        : _isObject(envelope['tool_input'])
+          ? envelope['tool_input']
+          : null;
+
+    const paths: string[] = [];
+    if (ti !== null) {
+        for (const key of _PATH_KEYS) {
+            const v = ti[key];
+            if (typeof v === 'string' && v) {
+                paths.push(v);
+            }
+        }
+    }
+    return { tool, paths };
+}
+
+/** Best-effort read of a shell command off a PreToolUse envelope. */
+function _extract_command(envelope: JsonObject): string | null {
+    const payload = _isObject(envelope['payload']) ? envelope['payload'] : envelope;
+    const ti = _isObject(payload['tool_input'])
+        ? payload['tool_input']
+        : _isObject(envelope['tool_input'])
+          ? envelope['tool_input']
+          : null;
+    for (const src of [ti, payload]) {
+        if (src === null) {
+            continue;
+        }
+        const v = src['command'];
+        if (typeof v === 'string' && v) {
+            return v;
+        }
+    }
+    return null;
+}
+
+/** Return (blocked, reason) for one PreToolUse envelope. Pure — no I/O. */
+export function check_envelope(envelope: JsonObject): [boolean, string] {
+    const { tool, paths } = _extract(envelope);
+    if (!tool) {
+        return [false, ''];
+    }
+    const deny = (output: string): [boolean, string] => [
+        true,
+        `${output} is a build output, not a source — regenerate it with ` +
+            `\`${REGENERATED_BY[output] ?? 'the build that writes it'}\`. ` +
+            'See docs/contracts/hook-architecture-v1.md § Plumbing.',
+    ];
+    if (EDIT_TOOLS.has(tool)) {
+        for (const p of paths) {
+            const output = targets_plumbing_output(p);
+            if (output !== null) {
+                return deny(output);
+            }
+        }
+        return [false, ''];
+    }
+    if (COMMAND_TOOLS.has(tool)) {
+        const cmd = _extract_command(envelope);
+        if (cmd !== null) {
+            const output = shellWriteTarget(cmd, targets_plumbing_output);
+            if (output !== null) {
+                return deny(output);
+            }
+        }
+    }
+    return [false, ''];
+}
+
+function _asObject(v: JsonValue | undefined): JsonObject | null {
+    return _isObject(v) ? v : null;
+}
+
+export function main(): number {
+    const raw = readHookStdin();
+    let envelope: JsonObject = {};
+    if (raw.trim()) {
+        try {
+            const obj = JSON.parse(raw) as JsonValue;
+            envelope = _asObject(obj) ?? {};
+        } catch {
+            // Malformed envelope — no target to decide about; allow. The
+            // fail-closed guarantee applies to a DETECTED write.
+            return 0;
+        }
+    }
+
+    const [blocked, reason] = check_envelope(envelope);
+    if (blocked) {
+        process.stderr.write(
+            `block-plumbing-writes: BLOCKED — ${reason}\n` +
+                '  This file is generated. Edit the source it is built from, then rebuild.\n' +
+                '  Contract: docs/contracts/hook-architecture-v1.md\n',
+        );
+        return 1; // EXIT_BLOCK
+    }
+
+    return 0; // EXIT_ALLOW
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url`.
+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() || (typeof __AGENT_CONFIG_BUNDLE__ === 'undefined' && process.argv[1] === _HERE)) {
+    process.exitCode = main();
+}

package/src/scripts/hooks/bundle_integrity.ts

@@ -0,0 +1,291 @@
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { fix_hint, log_dispatch_issue } from './dispatch_issues.js';
+import { EXIT_BLOCK } from './exit_codes.js';
+import { emitFor } from './host_semantics.js';
+
+/**
+ * bundle_integrity — does the dispatcher's own bundle still match what the
+ * build produced?
+ *
+ * Step 3.1 of `road-to-a-kernel-that-guards-its-plumbing`. `dist/hooks/
+ * dispatch.js` is a generated file with no legitimate hand edit, and until
+ * this landed an edit to it survived until the next build, reached every
+ * dispatch meanwhile, and was invisible in a source review.
+ * `check_hook_bundle_content` catches that in CI and `block_plumbing_writes`
+ * refuses the edit at tool-call time; neither of them is looking at the bundle
+ * the process is EXECUTING at the moment it runs a blocking guard.
+ *
+ * Three verdicts, and the gap between two of them is the whole design:
+ *
+ * - `ok` — the bundle hashes to the sidecar.
+ * - `mismatch` — it does not. The caller refuses on a slot carrying a blocking
+ *   concern and warns otherwise.
+ * - `unverifiable` — there is no sidecar, or it cannot be read or parsed.
+ *
+ * `unverifiable` NEVER refuses, and that is a decision rather than an
+ * oversight. A consumer install from a package built before the sidecar
+ * existed has no sidecar; so does any tree where `dist/` was produced by
+ * something other than `npm run build:hooks`. Refusing there would convert a
+ * missing optional artifact into a total outage of the agent's tooling, which
+ * is the failure `hook-architecture-v1.md` already rules on one level up when
+ * it fixes a MISSING dispatcher as a silent allow even for a `fail_closed`
+ * concern. An absent control is not a tripped control.
+ *
+ * This is not a signature. Anyone who can rewrite the bundle can rewrite the
+ * sidecar beside it, and saying otherwise would be the coverage inflation this
+ * roadmap exists to remove. What it catches is the hand edit and the partial
+ * write — the cases where somebody changed one file and not the other.
+ */
+
+/** What a verification produced. */
+export type IntegrityVerdict =
+    | { state: 'ok'; sha: string }
+    | { state: 'mismatch'; expected: string; actual: string }
+    | { state: 'unverifiable'; reason: string };
+
+/**
+ * The cheap identity of a file — what a later dispatch compares instead of
+ * re-hashing 1.5 MB.
+ *
+ * Size AND mtime, never mtime alone: a rebuild that produces a byte-identical
+ * bundle bumps mtime and would force a needless re-hash (harmless), while a
+ * same-size edit at the same mtime is the one pair this cannot see. That pair
+ * needs a deliberate timestamp forge, which is a strictly harder act than the
+ * hand edit this defends against, and the honest statement is that the cache
+ * trades that case for 0.0101 ms per dispatch against 0.470 ms.
+ *
+ * 0.0101 ms is the WHOLE cached path measured — reading the stamp back plus
+ * the stat — not the stat alone, which is 0.0010 ms. The first version of this
+ * comment quoted the stat, which described one of the two syscalls the
+ * dispatcher actually pays.
+ */
+export interface BundleStamp {
+    sha: string;
+    size: number;
+    mtimeMs: number;
+}
+
+/** Read the expected digest out of a `shasum -a 256` style sidecar. */
+export function parseSidecar(text: string): string | null {
+    // `<64 hex>  <filename>` — the two-space form `shasum` emits. Tolerant of
+    // any run of whitespace and of a trailing newline, because an operator who
+    // regenerates the file by hand should not be punished for one space.
+    const m = /^([0-9a-f]{64})\s/u.exec(text.trim());
+    return m === null ? null : (m[1] as string);
+}
+
+/** Where the sidecar for a given bundle lives. */
+export function sidecarPathFor(bundlePath: string): string {
+    return bundlePath.replace(/\.js$/u, '') + '.sha256';
+}
+
+/** SHA-256 of a file's bytes, or null when it cannot be read. */
+export function hashFile(p: string): string | null {
+    try {
+        return createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Compare a bundle against its sidecar.
+ *
+ * Pure apart from the two reads, so the caller's caching and the verdict logic
+ * can be tested without a dispatch.
+ */
+export function verifyBundle(bundlePath: string): IntegrityVerdict {
+    const sidecar = sidecarPathFor(bundlePath);
+    let expected: string | null;
+    try {
+        expected = parseSidecar(fs.readFileSync(sidecar, 'utf-8'));
+    } catch {
+        return { state: 'unverifiable', reason: `no sidecar at ${path.basename(sidecar)}` };
+    }
+    if (expected === null) {
+        return { state: 'unverifiable', reason: `sidecar at ${path.basename(sidecar)} is malformed` };
+    }
+    const actual = hashFile(bundlePath);
+    if (actual === null) {
+        return { state: 'unverifiable', reason: `bundle at ${path.basename(bundlePath)} is unreadable` };
+    }
+    return actual === expected ? { state: 'ok', sha: actual } : { state: 'mismatch', expected, actual };
+}
+
+/** The cheap identity of the bundle right now, or null when it is not there. */
+export function stampOf(bundlePath: string, sha: string): BundleStamp | null {
+    try {
+        const st = fs.statSync(bundlePath);
+        return { sha, size: st.size, mtimeMs: Math.floor(st.mtimeMs) };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Is a cached stamp still describing the file on disk?
+ *
+ * Returns false whenever the answer is not a confident yes — an unreadable
+ * file re-verifies rather than reusing a stamp that may describe something
+ * else.
+ */
+export function stampMatches(bundlePath: string, cached: BundleStamp | null | undefined): boolean {
+    if (cached === null || cached === undefined) return false;
+    try {
+        const st = fs.statSync(bundlePath);
+        return st.size === cached.size && Math.floor(st.mtimeMs) === cached.mtimeMs;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Where the once-per-bundle stamp is cached.
+ *
+ * The step wrote "caches `{sha, size, mtime}` in session state"; this uses the
+ * OS temp dir instead, and the deviation is deliberate. Session state under
+ * `agents/runtime/state/` is not written in replay mode — which is the mode
+ * `bench_hook_latency` runs in — so a session-state cache would be skipped in
+ * exactly the harness that has to measure the cached path, and the step's own
+ * verify line asks for `bench_hook_latency --gate` green with a per-dispatch
+ * cost of a stat call. It also means a host that never emits `session_start`
+ * would get no cache and no check at all.
+ *
+ * A temp-dir cache is content-addressed by the bundle's own path, so it needs
+ * no session identity, self-heals on the first dispatch of any session, works
+ * in a consumer install, and degrades to "verify every time" when the temp dir
+ * is unwritable — slower, never wrong.
+ */
+export function stampCachePath(bundlePath: string, tmpDir: string): string {
+    const key = createHash('sha256').update(bundlePath).digest('hex').slice(0, 16);
+    return path.join(tmpDir, `agent-config-bundle-integrity-${key}.json`);
+}
+
+/** Read a cached stamp, or null when there is not a usable one. */
+export function readStamp(cachePath: string): BundleStamp | null {
+    try {
+        const raw = JSON.parse(fs.readFileSync(cachePath, 'utf-8')) as Partial<BundleStamp>;
+        if (
+            typeof raw.sha === 'string' &&
+            typeof raw.size === 'number' &&
+            typeof raw.mtimeMs === 'number'
+        ) {
+            return { sha: raw.sha, size: raw.size, mtimeMs: raw.mtimeMs };
+        }
+    } catch {
+        // Absent, unreadable or malformed — all three mean "no cache", which
+        // costs a re-verification and never a wrong answer.
+    }
+    return null;
+}
+
+/** Persist a stamp. Failure is silent: a cache that cannot be written is a cache miss. */
+export function writeStamp(cachePath: string, stamp: BundleStamp): void {
+    try {
+        fs.writeFileSync(cachePath, JSON.stringify(stamp), 'utf-8');
+    } catch {
+        /* a cache is an optimisation, never a control */
+    }
+}
+
+/**
+ * The whole check, cache included — hash once per bundle identity, stat after.
+ *
+ * Returns the verdict plus whether this call had to do the expensive part, so
+ * a caller (and a test) can assert the cache actually caches rather than
+ * trusting that it does.
+ */
+export function verifyBundleCached(
+    bundlePath: string,
+    tmpDir: string,
+): { verdict: IntegrityVerdict; hashed: boolean } {
+    const cachePath = stampCachePath(bundlePath, tmpDir);
+    const cached = readStamp(cachePath);
+    if (stampMatches(bundlePath, cached) && cached !== null) {
+        return { verdict: { state: 'ok', sha: cached.sha }, hashed: false };
+    }
+    const verdict = verifyBundle(bundlePath);
+    if (verdict.state === 'ok') {
+        const stamp = stampOf(bundlePath, verdict.sha);
+        if (stamp !== null) writeStamp(cachePath, stamp);
+    }
+    // A `mismatch` is deliberately NOT cached. Caching it would be caching a
+    // refusal, and the next legitimate rebuild has to be able to clear it
+    // without anyone knowing a cache existed.
+    return { verdict, hashed: true };
+}
+
+/** What the dispatcher should do about the verdict it just got. */
+export type IntegrityAction =
+    | { action: 'allow' }
+    | { action: 'warn'; detail: string }
+    | { action: 'block'; detail: string };
+
+/**
+ * Turn a verdict into a dispatch decision.
+ *
+ * Separated from the dispatcher so the SEVERITY half of the rule is testable
+ * without a dispatch — and because `dispatch_hook.ts` sits against the
+ * 1,500-line source budget, which refused the inline version.
+ *
+ * `hasBlockingConcern` is the discriminator rather than the slot name: a slot
+ * carrying only advisory concerns could not have refused anything anyway, so
+ * blocking there would let a stale digest wedge a chain with no authority to
+ * begin with.
+ */
+export function integrityAction(
+    verdict: IntegrityVerdict,
+    hasBlockingConcern: boolean,
+): IntegrityAction {
+    if (verdict.state !== 'mismatch') {
+        // `ok` and `unverifiable` are both allow, and they are both SILENT.
+        // See the header for why an absent sidecar is not a tripped control.
+        return { action: 'allow' };
+    }
+    const detail =
+        `dist/hooks/dispatch.js does not match its build digest ` +
+        `(expected ${verdict.expected.slice(0, 12)}…, got ${verdict.actual.slice(0, 12)}…). ` +
+        `The bundle is generated by \`npm run build:hooks\` and has no legitimate ` +
+        `hand edit; rebuild to clear this.`;
+    return hasBlockingConcern ? { action: 'block', detail } : { action: 'warn', detail };
+}
+
+/**
+ * The whole gate, side effects included — verify, log, and decide the exit.
+ *
+ * Returns an exit code when the dispatch must stop, `null` when it continues.
+ * It lives here rather than inline in `dispatch_hook.ts` for two reasons, and
+ * the second is the load-bearing one: that file sits against the 1,500-line
+ * source budget and `check_source_size_budget` refused the inline version, and
+ * a gate whose logging and emission are inside the dispatcher can only be
+ * tested by running a dispatch.
+ */
+export function runBundleIntegrityGate(
+    bundlePath: string,
+    platform: string,
+    event: string,
+    hasBlockingConcern: boolean,
+    tmpDir: string = os.tmpdir(),
+): number | null {
+    const { verdict } = verifyBundleCached(bundlePath, tmpDir);
+    const act = integrityAction(verdict, hasBlockingConcern);
+    if (act.action === 'allow') return null;
+    const line = `plumbing-integrity: ${act.detail}`;
+    try {
+        log_dispatch_issue(process.cwd(), 'dispatcher', 'execution_failed', line, fix_hint());
+    } catch {
+        /* observability never breaks the hook */
+    }
+    if (act.action === 'warn') {
+        process.stderr.write(`dispatch_hook: ${line}\n`);
+        return null;
+    }
+    const em = emitFor(platform, event, 'block', [line], EXIT_BLOCK);
+    if (em.stdout) process.stdout.write(em.stdout);
+    if (em.stderr) process.stderr.write(em.stderr);
+    return em.exit;
+}

package/src/scripts/hooks/chain_nudge_hook.ts

@@ -84,10 +84,9 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { readHookStdin } from './hook_stdin.js';
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
 const SETTINGS_FILE = '.agent-settings.yml';
-const EXIT_ALLOW = 0;
-const EXIT_WARN = 2;
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };