@event4u/agent-config 16.1.0 → 16.2.0

package/src/scripts/hooks/interruption_ledger_hook.ts

@@ -60,8 +60,7 @@ import { derive_session_tag } from '../chat_history.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { HANDBACK, finalParagraph, readTranscriptTail } from './turn_end_gate_hook.js';
-
-const EXIT_OK = 0;
+import { EXIT_ALLOW as EXIT_OK } from './exit_codes.js';
 
 /** Same cap the turn-end gate reads its tail under. */
 const TRANSCRIPT_READ_MAX_BYTES = 2 * 1024 * 1024;

package/src/scripts/hooks/journal_record_hook.ts

@@ -102,8 +102,7 @@ import {
 } from '../_lib/runtime_journal.js';
 import { readHookStdin } from './hook_stdin.js';
 import { is_replay_mode } from './state_io.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 /** The `.agent-settings.yml` section under `hooks:` that arms this concern. */
 export const SETTINGS_SECTION = 'runtime_journal';

package/src/scripts/hooks/memory_recall_hook.ts

@@ -68,13 +68,12 @@ import { COMMAND_TOOLS } from '../before_complete_hook.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { atomic_write_json } from './state_io.js';
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
 /**
  * Severity comes from the exit code, not from the `decision` field. See the
  * header: this never blocks, and never returns 1 on any path.
  */
-const EXIT_WARN = 2;
 
 /** Hard ceiling on `reason` + `additional_context`, matching the registered row. */
 export const CAP_BYTES = 768;

package/src/scripts/hooks/obligation_settle_hook.ts

@@ -41,13 +41,19 @@
 import path from 'node:path';
 import process from 'node:process';
 
+import { readHookStdin } from './hook_stdin.js';
+// The WRITER's own root resolver, imported rather than re-derived. A second
+// spelling of "which tree is this" is how a reader comes to address a ledger
+// the writer never wrote — which is the defect this whole file is repairing,
+// one field over.
+import { workspaceRoot as writerWorkspaceRoot } from './rule_inject_hook.js';
+
 import { may_refuse_on } from '../_lib/obligation_frequency.js';
 import { appendShadow, readDelivered, readDischarged, stamp } from '../_lib/obligations.js';
 import { loadRouter, matchTierRules } from '../_lib/rule_injection.js';
 import { gitNumstatRows, isDocPath, untrackedNonDocFiles } from './end_review_nudge_hook.js';
 import { openRecordStats } from './subagent_ledger_hook.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 /**
  * Every non-doc path this turn wrote, tracked or not.
@@ -142,9 +148,144 @@ export function shouldContinue(attempt: number): boolean {
     return attempt <= 1;
 }
 
-export function main(): number {
-    const root = process.cwd();
-    const session = (process.env['CLAUDE_CODE_SESSION_ID'] ?? '').trim();
+/**
+ * The session and root this reading is about, resolved the way the WRITER does.
+ *
+ * THE DEFECT THIS EXISTS TO CLOSE. This hook used to read
+ * `CLAUDE_CODE_SESSION_ID` out of the process environment and return allow when
+ * it was empty. The dispatcher sets no such variable — it hands each concern
+ * the envelope on stdin and `AGENT_CONFIG_PACKAGE_ROOT` in the environment,
+ * nothing else — so on every dispatched stop event the reader looked for a
+ * ledger under a key the writer never used. Measured 2026-09-29 on this
+ * machine's own ledgers: 187 delivered rows, 0 shadow rows, across 8 sessions.
+ *
+ * WHY THE ORDER IS ENVELOPE-THEN-ENVIRONMENT AND NOT THE REVERSE. The envelope
+ * id is the key `rule_inject_hook.ts` wrote the delivered rows under, so it is
+ * not merely the better source — it is the ONLY one that can find them. The
+ * environment fallback survives for a raw invocation that carries no envelope
+ * at all (a maintainer piping nothing, a host shim that skips the dispatcher),
+ * which is a case where guessing wrong costs a missing reading rather than a
+ * wrong one.
+ *
+ * THE ROOT IS PART OF THE SAME JOIN, not a second change riding along. A ledger
+ * is addressed by root AND session; reading the session from the envelope while
+ * taking the root from `process.cwd()` would leave the pair half-joined, and the
+ * two disagree exactly on the hosts whose shim does not chdir. `cwd` stays the
+ * fallback because that is what the dispatcher sets it to.
+ *
+ * Both spellings of each key are accepted because the injector accepts both.
+ */
+export function resolveSettleContext(
+    envelope: Record<string, unknown>,
+    payload: Record<string, unknown>,
+    env: Record<string, string | undefined>,
+): { root: string; session: string } {
+    const str = (...values: unknown[]): string => {
+        for (const v of values) {
+            if (typeof v === 'string' && v.trim() !== '') return v.trim();
+        }
+        return '';
+    };
+    return {
+        // `workspaceRoot` is the INJECTOR's function, not a copy of it. It reads
+        // `workspace` / `cwd` / `project_dir`; this file used to read
+        // `workspace_root` / `workspace` / `cwd`, so the two key sets overlapped
+        // without matching and the pair was joined on the session only. It
+        // happened to agree on both real envelope shapes — the dispatcher sets
+        // `workspace_root` and chdirs concerns to it, a native wiring passes
+        // `cwd` — which made the asymmetry a property of today's envelopes
+        // rather than of the code. `workspace_root` is appended ahead of the
+        // shared resolver because the dispatcher is the only producer that sets
+        // it and nothing else reads it.
+        root:
+            str(envelope['workspace_root'])
+            || writerWorkspaceRoot(envelope as Parameters<typeof writerWorkspaceRoot>[0]),
+        session: str(
+            envelope['session_id'],
+            envelope['sessionId'],
+            payload['session_id'],
+            payload['sessionId'],
+            // The one pre-existing source, kept as the last resort and NOT
+            // joined by siblings: adding a name the writer never keys on
+            // would address a ledger that cannot exist.
+            env['CLAUDE_CODE_SESSION_ID'],
+        ),
+    };
+}
+
+/**
+ * The session id the WRITER would have used, for the ledger nobody reads.
+ *
+ * `rule_inject_hook.ts` defaults an unnamed session to the literal `unknown`
+ * and writes delivered rows there; this reader used to return `''` and allow, so
+ * that population was invisible to every reading of the bar. Reported rather
+ * than silently joined: a shared `unknown` bucket aggregates unrelated sessions,
+ * so reading it as one session's turn would be worse than not reading it. The
+ * constant is exported so a future census can count what is sitting there.
+ */
+export const WRITER_UNNAMED_SESSION = 'unknown';
+
+/** The envelope on stdin, or an empty object when there is none to read. */
+function readEnvelope(): { envelope: Record<string, unknown>; payload: Record<string, unknown> } {
+    let envelope: Record<string, unknown> = {};
+    try {
+        const raw = readHookStdin();
+        const parsed: unknown = raw.trim() === '' ? {} : JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            envelope = parsed as Record<string, unknown>;
+        }
+    } catch {
+        // A malformed envelope is not a reason to refuse, and this concern
+        // refuses nothing anyway. It is a reason to read nothing from it.
+    }
+    const nested = envelope['payload'];
+    const payload =
+        typeof nested === 'object' && nested !== null && !Array.isArray(nested)
+            ? (nested as Record<string, unknown>)
+            : envelope;
+    return { envelope, payload };
+}
+
+/**
+ * The resolver as it stood BEFORE the join fix, kept reachable for one test.
+ *
+ * A reproduction that cannot run the old code is not a reproduction — it is an
+ * assertion about the new function's behavior on inputs nobody sends, and
+ * `tests/hooks/obligation_settle.test.ts` carried exactly that until an
+ * independent review named it. This function is dead on every production path
+ * (nothing but the fixture calls it) and exists so the defect stays executable:
+ * environment-only resolution, allow when empty, root from the cwd.
+ */
+export function resolveSettleContextPreFix(
+    _envelope: Record<string, unknown>,
+    _payload: Record<string, unknown>,
+    env: Record<string, string | undefined>,
+): { root: string; session: string } {
+    // Same arity as the live resolver ON PURPOSE. A narrower signature would let
+    // the fixture pass the envelope in as `env`, where the lookup misses for the
+    // wrong reason and the test goes green without exercising the defect.
+    return { root: process.cwd(), session: (env['CLAUDE_CODE_SESSION_ID'] ?? '').trim() };
+}
+
+/**
+ * Which context resolver this reading uses — the seam the pre-fix fixture needs.
+ *
+ * It is NOT a parameter of `main()`, and that is a contract rather than a
+ * preference: `concern_main_signature` requires every concern's `main()` to take
+ * argv first or nothing, because the dispatcher calls `main(argv)` — so a
+ * resolver in first position would receive an argv array at runtime and resolve
+ * a session from it. Caught by that test, which is the reason this indirection
+ * exists instead of the obvious default parameter.
+ */
+export type SettleResolver = (
+    envelope: Record<string, unknown>,
+    payload: Record<string, unknown>,
+    env: Record<string, string | undefined>,
+) => { root: string; session: string };
+
+export function runSettle(resolve: SettleResolver = resolveSettleContext): number {
+    const { envelope, payload } = readEnvelope();
+    const { root, session } = resolve(envelope, payload, process.env);
     if (session === '') return EXIT_ALLOW;
 
     let verdict: SettleVerdict;
@@ -176,6 +317,11 @@ export function main(): number {
     return EXIT_ALLOW;
 }
 
+/** The dispatcher entry point. Argv-shaped, per `concern_main_signature`. */
+export function main(_argv: readonly string[] = process.argv.slice(2)): number {
+    return runSettle();
+}
+
 // Bundle-safety: never auto-run when inlined into an esbuild bundle.
 if (process.argv[1] !== undefined && path.basename(process.argv[1]).startsWith('obligation_settle')) {
     process.exit(main());

package/src/scripts/hooks/one_question_per_ask_hook.ts

@@ -16,10 +16,31 @@
  *
  * WHAT IT SEES, honestly. `_lib/structured_ask.ts` carries no observed
  * per-host tool, so this guard matches on a name SHAPE and is filtered by the
- * manifest's per-concern `tools:` key to the same candidate names. On every
- * host measured today it therefore fires on nothing — the concern exists so
- * that the first host to ship a picker meets the rule already in force, not
- * because a violation has been observed.
+ * manifest's per-concern `tools:` key to the same candidate names. No host's
+ * delivered surface has been OBSERVED in this tree carrying a question-picker
+ * tool, which is why `STRUCTURED_ASK_SHAPES` is empty and no per-host shape row
+ * exists — the same sentence `_lib/structured_ask.ts` already uses about itself.
+ *
+ * That is NARROWER than the claim this header used to make. The earlier
+ * sentence asserted that on every host measured today the concern therefore
+ * matches nothing at all, and the two are different claims with only the first
+ * supported. The old wording is described here rather than quoted, because
+ * 1.1's drift check is a grep and a grep cannot tell a refuted quotation from
+ * a live assertion. The measurement base is ONE row:
+ * `_lib/host_capability.ts`'s registry records `structured_ask: false` for
+ * `claude` alone, observed-absent on Claude Code 2.1.263 on 2026-09-07, and the
+ * other eight hosts in `docs/enforcement-by-host.md` have no row at all — never
+ * looked, not measured. "Every host measured" read against that table therefore
+ * describes one host, and a present-tense claim about what the concern matches
+ * turns one dated single-version reading into a standing property, which the registry's own
+ * comment refuses in the same breath: the observation "is not a claim that the
+ * vendor ships no such tool anywhere, and a later session observing one writes
+ * the `true` row over it".
+ *
+ * So the honest statement is about what has been looked at, not about what
+ * fires. The concern exists so the first host whose delivered surface carries a
+ * picker meets the rule already in force, not because a violation has been
+ * observed.
  *
  * ENFORCEMENT REACH, also honestly. `fail_closed: false` and the exit-1 deny
  * are only a deny where the host both binds `pre_tool_use` AND honours the

package/src/scripts/hooks/orchestration_record_hook.ts

@@ -72,8 +72,7 @@ import { buildOrchestrationLine, type RecordInput } from '../_lib/orchestration_
 import { DEFAULT_DIR } from '../orchestration_record.js';
 import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };

package/src/scripts/hooks/permission_gate.ts

@@ -20,6 +20,7 @@ import {
   type PermissionDecision,
   type PermissionEmission,
 } from "./host_semantics.js";
+import { EXIT_ALLOW, EXIT_BLOCK } from './exit_codes.js';
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };
@@ -29,8 +30,6 @@ function _isObject(v: unknown): v is JsonObject {
 }
 
 /** Mirrors `dispatch_hook.EXIT_ALLOW` / `EXIT_BLOCK`; imported would be a cycle. */
-const EXIT_ALLOW = 0;
-const EXIT_BLOCK = 1;
 
 /** The host's `tool_name`, or `""` when the event carries none. */
 export function _payload_tool_name(envelope: JsonObject): string {

package/src/scripts/hooks/push_settle_hook.ts

@@ -54,9 +54,7 @@ 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;
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };

package/src/scripts/hooks/replay_hook.ts

@@ -36,6 +36,7 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { EXIT_USAGE } from './exit_codes.js';
 
 // src/scripts/hooks/replay_hook.ts → parents[3] is the repo root.
 const REPO_ROOT = path.resolve(
@@ -175,7 +176,7 @@ function _parse_args(argv: string[]): ReplayArgs {
     process.stderr.write(
       `replay_hook: the following arguments are required: ${missing.join(", ")}\n`,
     );
-    process.exit(2);
+    process.exit(EXIT_USAGE);
   }
   return args;
 }

package/src/scripts/hooks/reread_guard_hook.ts

@@ -69,12 +69,11 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { atomic_write_json } from './state_io.js';
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
 // Severity is taken from the EXIT CODE, not from the `decision` field — see
 // the file header for why this never blocks on `claude`. This concern never
 // returns exit 1 on any path.
-const EXIT_WARN = 2;
 
 /**
  * Committed exemption list — deliberately duplicated from

package/src/scripts/hooks/review_baseline_hook.ts

@@ -49,8 +49,7 @@ import { deriveSessionKey, totalNonDocMutatedLinesWithMeasure } from './end_revi
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { atomic_write_json } from './state_io.js';
-
-const EXIT_OK = 0;
+import { EXIT_ALLOW as EXIT_OK } from './exit_codes.js';
 
 export function buildBaseline(workspaceRoot: string, now: Date = new Date()): ReviewBaseline {
     const measured = totalNonDocMutatedLinesWithMeasure(workspaceRoot);

package/src/scripts/hooks/rtk_wrap_hook.ts

@@ -63,10 +63,9 @@ import {
 } from "./block_no_verify.js";
 import { readHookStdin } from "./hook_stdin.js";
 import { detectRtkCached } from "../../install/rtkDetection.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 };

package/src/scripts/hooks/rule_inject_hook.ts

@@ -102,7 +102,12 @@ import {
     resolveLeanProjectionHosts,
 } from '../_lib/lean_projection_mode.js';
 import { enforcement_class_from_frontmatter } from '../_lib/obligation_frequency.js';
-import { appendDelivered, stamp, type DeliveredRow } from '../_lib/obligations.js';
+import {
+    appendDelivered,
+    stamp,
+    type DeliveredRow,
+    type WriterInput,
+} from '../_lib/obligations.js';
 import {
     loadRuleBody,
     loadRouter,
@@ -110,9 +115,7 @@ import {
     selectForInjection,
 } from '../_lib/rule_injection.js';
 import { readHookStdin } from './hook_stdin.js';
-
-const EXIT_ALLOW = 0;
-const EXIT_WARN = 2;
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
 /**
  * Per-prompt injection ceiling, in UTF-8 BYTES.
@@ -268,7 +271,7 @@ export interface Injection {
 export function recordDelivered(root: string, session: string, ruleIds: string[]): number {
     try {
         const now = stamp();
-        const rows: DeliveredRow[] = ruleIds.map((id) => {
+        const rows: WriterInput<DeliveredRow>[] = ruleIds.map((id) => {
             const body = loadRuleBody(root, id);
             return {
                 rule: id,

package/src/scripts/hooks/run_continuation_hook.ts

@@ -152,10 +152,9 @@ import {
     sessionRefusalFile,
 } from '../_lib/turn_end_refusals.js';
 import { phaseLines } from '../_lib/roadmap_checkboxes.js';
+import { commandBearing, renderVerifyLine, type VerifyClause } from '../_lib/verify_clause.js';
 
-const EXIT_ALLOW = 0;
 /** Dispatcher-internal block code; the dispatcher maps stop-slot 1 → host 2. */
-const EXIT_BLOCK = 1;
 
 /**
  * The gate's cap, IMPORTED rather than restated — the two must agree by
@@ -194,6 +193,7 @@ import {
     WALL_CLOCK_CAP_MS,
     type LadderAction,
 } from '../_lib/continuation_ladder.js';
+import { EXIT_ALLOW, EXIT_BLOCK } from './exit_codes.js';
 
 /**
  * DECLARED in `_lib/continuation_ladder.ts`, re-exported here: one declaration,
@@ -375,8 +375,8 @@ export function isDuplicateFire(
 export interface NextStep {
     /** The step's own line, checkbox stripped, truncated for the message. */
     text: string;
-    /** The step's `verify:` command, when its line carries one. */
-    verify: string | null;
+    /** The step's `verify:` clause — command plus optional expectation. */
+    verify: VerifyClause | null;
 }
 
 export interface ScanResult {
@@ -481,15 +481,15 @@ export function scanOpenSteps(text: string): ScanResult {
  * The comment form wins when both are present: it is the machine-readable one,
  * and a step carrying both has a human-facing line and a tooling-facing line
  * rather than two commands.
+ *
+ * The hook's narrowing only — a prose clause is not a command, and the
+ * continuation message renders commands. It parses nothing itself: a second
+ * copy of the arrow grammar is how this hook and `closure_scan` would drift,
+ * and a drifted grammar stops reading expectations without failing anything.
+ * `_lib/verify_clause.ts` owns the grammar and the sweep that keeps it single.
  */
-export function extractVerify(stepText: string): string | null {
-    const html = /<!--\s*verify:\s*(.*?)\s*-->/.exec(stepText);
-    if (html !== null) return (html[1] as string).trim() || null;
-    // `verify:` then the command, both backticked. The label's own backticks
-    // are optional because the tree carries `verify:` and `` `verify:` ``.
-    const backticked = /`?verify:`?\s*`([^`]+)`/.exec(stepText);
-    if (backticked !== null) return (backticked[1] as string).trim() || null;
-    return null;
+export function extractVerify(stepText: string): VerifyClause | null {
+    return commandBearing(stepText);
 }
 
 /**
@@ -1259,7 +1259,6 @@ export function main(): number {
         return EXIT_ALLOW;
     }
 
-
     // The two-tree provenance, carried on every event this run emits. See
     // `provenance()` for the six fields and why none of them is a boolean.
     //
@@ -1487,8 +1486,7 @@ export function main(): number {
 
 function _continuationText(slug: string, scan: ScanResult, iteration: number): string {
     const stepLine = scan.next
-        ? `Next step: ${scan.next.text}` +
-          (scan.next.verify ? `\n  verify: ${scan.next.verify}` : '')
+        ? `Next step: ${scan.next.text}${renderVerifyLine(scan.next.verify)}`
         : 'Next step: (first open checkbox in the roadmap)';
     return (
         `run-continuation: the contracted roadmap \`${slug}\` has ${scan.open} open ` +

package/src/scripts/hooks/skill_route_hook.ts

@@ -143,10 +143,9 @@ import { isSyntheticPrompt } from "../_lib/prompt_shape.js";
 import { OBSERVATION_LOG, readObservationLog, resolveSkillCatalogueRoots } from "../_lib/skill_catalogue.js";
 import { knownBareNames } from "../_lib/skill_catalogue_series.js";
 import { _tokenize, rank, type RankRow } from "../skill_tools/score_skill_relevance.js";
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
 /** See the header: reduced to a real exit of 0 by `emitFor`'s warn branch. */
-const EXIT_WARN = 2;
 
 /**
  * Minimum top-1 ranker score before this concern speaks.

package/src/scripts/hooks/source_first_gate_hook.ts

@@ -95,8 +95,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
 import { resolveConsumerRoot } from './subagent_ledger_hook.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 /** Would-warns per session before the valve goes silent — `MAX_NUDGES` shape. */
 export const MAX_SHADOW_WARNS = 2;

package/src/scripts/hooks/spawn_guard_shadow_hook.ts

@@ -55,8 +55,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { appendLedgerLine, openRecordStats, resolveConsumerRoot } from './subagent_ledger_hook.js';
 import { readHookStdin } from './hook_stdin.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };

package/src/scripts/hooks/subagent_ledger_hook.ts

@@ -115,8 +115,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { countContractFields, validateResponse } from '../_lib/subagent_response.js';
 import { atomic_write_json, is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };

package/src/scripts/hooks/suggestion_capture_hook.ts

@@ -51,8 +51,8 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { unwrap } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { humanTypedThisTurn } from '../_lib/machine_wake.js';
+import { EXIT_ALLOW } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
 const SETTINGS_FILE = '.agent-settings.yml';
 const SINK_REL = path.join('agents', 'runtime', 'state', 'audit', 'suggestion-capture.jsonl');
 const LATCH_REL = path.join('agents', 'runtime', 'state', 'suggestion-latch.json');

package/src/scripts/hooks/table_fingerprint.ts

@@ -0,0 +1,49 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * table_fingerprint — the content fingerprint a compiled plumbing table is
+ * validated against.
+ *
+ * Extracted from `dispatch_hook._manifest_fingerprint` so a SECOND table
+ * (`host_lowering.yaml`) can use the same helper without importing the
+ * dispatcher: `dispatch_hook` → `host_semantics` → `host_lowering` is a live
+ * import chain, so the reverse edge would be a cycle.
+ *
+ * DELIBERATELY CONTENT-DERIVED, NOT MTIME. The first version of the manifest
+ * fast path compared mtimes and that was a measured defect, not a theoretical
+ * one: on a fresh `actions/checkout` both files carry the checkout timestamp in
+ * whatever order git wrote them, so whether the optimisation applied at all was
+ * a coin flip — it won on a PR run (p95 129 ms) and lost on the trunk
+ * (p95 186 ms) for the same commit. A fingerprint is deterministic wherever the
+ * tree came from.
+ *
+ * SHA-256 over the UTF-8 bytes, plus the length. This replaced an FNV-1a loop
+ * in step 3.1 of `road-to-a-kernel-that-guards-its-plumbing`, and the reason
+ * the old one existed no longer holds. Its header said a cryptographic hash was
+ * refused because `require('node:crypto')` costs 8 ms of process start, which
+ * is most of what the precompiled table saves. Both halves were re-measured
+ * against the tree as it now stands, and both had gone stale:
+ *
+ * - The module is ALREADY LOADED. `dist/hooks/dispatch.js` carries 23
+ *   top-level `import … from "node:crypto"` statements from other parts of the
+ *   graph, so the 8 ms is paid on every dispatch whether this function uses it
+ *   or not. There is no startup cost left to avoid.
+ * - SHA-256 is FASTER here, not slower: 0.106 ms against 0.113 ms over the
+ *   99,792-byte manifest, because Node's digest is native and the FNV-1a loop
+ *   was 99,792 interpreted `charCodeAt` calls.
+ *
+ * The change is therefore free, and it buys the property the old comment had to
+ * disclaim: this now guards against a CRAFTED sibling as well as a stale one,
+ * which is what a file called a fingerprint should mean when the roadmap around
+ * it is about integrity.
+ *
+ * Producer and both consumers import THIS function — `compile_hook_manifest`
+ * writes the value, `dispatch_hook` and `host_lowering` check it — so the
+ * algorithm can never drift between the two sides. A mismatch is not a failure
+ * either way: the reader falls through to parsing the YAML source, which is
+ * correct and merely slower.
+ */
+export function tableFingerprint(text: string): string {
+    const digest = createHash('sha256').update(text, 'utf-8').digest('hex');
+    return `${digest}:${String(text.length)}`;
+}

package/src/scripts/hooks/telemetry_flush_hook.ts

@@ -45,8 +45,7 @@ import {
 import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
 import { _resolveRoot, readSettingsFor } from './telemetry_usage_hook.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 /**
  * Where `flush_sender.mjs` lives, relative to this module.

package/src/scripts/hooks/telemetry_usage_hook.ts

@@ -57,8 +57,7 @@ import {
 } from '../../agent-src/templates/scripts/telemetry/transport.js';
 import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 /** The tool name Phase 0 spike 1 confirmed for a skill invocation. */
 export const SKILL_TOOL_NAME = 'Skill';