@event4u/agent-config 16.1.0 → 16.2.0

package/src/scripts/hooks/concern_timings.ts

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+
+/**
+ * concern_timings — the per-concern latency sink the bench reads.
+ *
+ * Step 3.2 of `road-to-a-kernel-that-guards-its-plumbing`. The dispatcher has
+ * always timed each concern — `_run_concern` returns a duration and the
+ * feedback record carries it — but nothing could READ that distribution: the
+ * feedback dir keeps one file per concern and every dispatch OVERWRITES it, so
+ * the only survivor is the last run. A p95 needs every sample, and the bench
+ * harness that produces the samples runs with `AGENT_CONFIG_REPLAY=1`, where
+ * the feedback write returns before writing anything at all.
+ *
+ * So this sink is separate from the feedback dir on purpose, and deliberately
+ * not derived from it:
+ *
+ * - it APPENDS, so N runs leave N samples rather than one;
+ * - it is written in replay mode, because the measurement harness is the
+ *   caller that needs it;
+ * - it is off unless the variable is set, so the cost on a real dispatch is
+ *   one `process.env` lookup.
+ *
+ * It carries a concern name, an integer, an event and a platform. There is no
+ * field that can hold a payload, a path or a prompt — the same shape-level
+ * privacy floor `payload_stubs` keeps one row up.
+ *
+ * It lives in its own file rather than inside `dispatch_hook.ts` because that
+ * file sits against the 1,500-line source budget, and `check_source_size_budget`
+ * refused the inline version.
+ */
+
+/** Environment variable naming the JSONL sink. Registered in the kill-switch table. */
+export const TIMINGS_SINK_ENV = "AGENT_CONFIG_HOOK_TIMINGS";
+
+/**
+ * One measurement.
+ *
+ * MICROseconds, not milliseconds. The dispatcher's `duration_ms` is floored,
+ * and since the in-process fast path landed every registry concern finishes in
+ * well under a millisecond — so the floored field reads exactly `0` for all of
+ * them. That was invisible while nothing consumed the number and stops being
+ * invisible the moment a p95 is reported and a timeout derived from it.
+ */
+export interface ConcernTimingSample {
+  concern: string;
+  duration_us: number;
+}
+
+/**
+ * Append one JSONL row per concern, when the sink is armed.
+ *
+ * Never throws and never blocks the dispatch: a measurement sink that can fail
+ * a hook would be a new way for the plumbing to refuse, which is the opposite
+ * of what this roadmap is for.
+ */
+export function writeConcernTimings(
+  event: string,
+  platform: string,
+  samples: readonly ConcernTimingSample[],
+  sinkPath: string | undefined = process.env[TIMINGS_SINK_ENV],
+): void {
+  if (!sinkPath) {
+    return;
+  }
+  try {
+    const lines: string[] = [];
+    for (const sample of samples) {
+      // A concern the dispatcher never timed is OMITTED rather than recorded
+      // as 0. A zero here would read as "instantaneous" and would be
+      // indistinguishable from a real sub-millisecond run — the exact
+      // substitution the report's `not_measured` requirement forbids one layer
+      // up, reintroduced at the source instead of at the report.
+      if (!Number.isFinite(sample.duration_us)) {
+        continue;
+      }
+      lines.push(
+        JSON.stringify({
+          concern: sample.concern,
+          // Rounded HERE rather than at the call site: the caller holds a
+          // float millisecond reading and the sink is the one place that has
+          // to decide the recorded unit.
+          duration_us: Math.round(sample.duration_us),
+          event,
+          platform,
+        }),
+      );
+    }
+    if (lines.length > 0) {
+      fs.appendFileSync(sinkPath, lines.join("\n") + "\n", "utf-8");
+    }
+  } catch {
+    // Non-fatal by construction — see the header.
+  }
+}

package/src/scripts/hooks/delegation_nudge_hook.ts

@@ -102,15 +102,14 @@ import { classifyLadder, type LadderRung } from "../_lib/judgment_ladder.js";
 import { resolveSessionRole } from "../_lib/session_role.js";
 import { resolveSubagentRouting, type Tier } from "../_lib/subagent_routing.js";
 import { isSyntheticPrompt } from "../_lib/prompt_shape.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 in the
 // stdout payload — mirrors `language_mirror_hook.ts`'s own note (found the
 // same way: by tracing delivery, not by re-reading the unit tests). A warn
 // verdict is reported at exit 2 so `host_semantics.emitFor` reduces it to
 // severity `"warn"` and forwards `additional_context`; see the file header
 // for why this exit code never actually blocks the turn.
-const EXIT_WARN = 2;
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };

package/src/scripts/hooks/design_pass_hook.ts

@@ -57,12 +57,13 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { appendDischarge, stamp } from '../_lib/obligations.js';
+import { compareInputs } from '../_lib/probe_inputs.js';
+import { trigger_matches, type Trigger } from '../_lib/router_match.js';
 import { isUiPath, isUiTreePath } from '../_lib/ui_surface.js';
 import { loadDesignContext, scanFile } from '../lint_design_slop.js';
 import { readHookStdin } from './hook_stdin.js';
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
-const EXIT_WARN = 2;
 const SETTINGS_FILE = '.agent-settings.yml';
 const STATE_REL = path.join('agents', 'runtime', 'state', 'design-pass-hook.json');
 const AUDIT_REL = path.join('agents', 'runtime', 'state', 'ui-audit.json');
@@ -150,27 +151,94 @@ export interface ConformanceVerdict {
      * write is the noise that gets a carrier switched off — Risk 1 of the parent
      * roadmap. Absent is still reported honestly whenever the pass speaks for
      * another reason.
+     *
+     * The ONE exception is a turn that actually touched a provided design
+     * handover. There, the probe is the evidence the turn was supposed to
+     * produce, and its absence is the noteworthy kind.
      */
     noteworthy: boolean;
     line: string;
 }
 
-export function conformanceVerdict(root: string): ConformanceVerdict {
+export interface ConformanceOptions {
+    /**
+     * Whether a provided design handover was among the files this turn wrote.
+     * Decided by `handoverTouched` from the shipped routing triggers, never by a
+     * matcher invented here.
+     */
+    handoverDetected?: boolean;
+}
+
+/**
+ * The file-based half of `src/rules/design-fidelity.md`'s `triggers:` set — the
+ * shipped answer to "is this file a provided design handover?".
+ *
+ * COPIED AS A CONSTANT, MATCHED BY THE SHIPPED MATCHER. Reading and parsing the
+ * rule's frontmatter here would put a YAML load on `post_tool_use`, the hottest
+ * slot this concern binds, and would depend on a rule path that differs between
+ * this repository and an installed consumer. The drift that a constant invites
+ * is closed by a test instead: `design_pass.test.ts` asserts this list equals the
+ * rule's file-based triggers in BOTH directions, so a trigger added to the rule
+ * and not here fails CI.
+ *
+ * THE HONEST REACH. Only the two HTML patterns are reachable through this
+ * carrier. `.claude/design-system/` names JSON and token files, which
+ * `isUiSurface` does not admit, so `main` returns before the verdict is
+ * computed. Widening `isUiSurface` to admit them would change the UI-turn
+ * denominator that the consultation-rate measurement is defined against, which
+ * is a different decision than this one. The prefix stays for parity with the
+ * rule and is stated as unreachable rather than quietly dropped.
+ */
+export const HANDOVER_TRIGGERS: readonly Trigger[] = [
+    { file_pattern: '*design.html' },
+    { file_pattern: '*.dc.html' },
+    { path_prefix: '.claude/design-system/' },
+];
+
+/** True when any of the paths this turn wrote is a provided design handover. */
+export function handoverTouched(paths: readonly string[]): boolean {
+    if (!paths.length) return false;
+    return HANDOVER_TRIGGERS.some((t) => trigger_matches(t, '', paths, null));
+}
+
+export function conformanceVerdict(root: string, opts: ConformanceOptions = {}): ConformanceVerdict {
     let raw: string;
     try {
         raw = fs.readFileSync(path.join(root, CONFORMANCE_REL), 'utf-8');
     } catch {
-        return {
-            noteworthy: false,
-            line: 'ui-conformance: absent — no probe artefact for this change (run `ui_conformance_probe --target <file> --reference <file>`). Absent is not clean.',
-        };
+        const base =
+            'ui-conformance: absent — no probe artefact for this change (run `ui_conformance_probe --target <file> --reference <file>`). Absent is not clean.';
+        return opts.handoverDetected
+            ? {
+                  noteworthy: true,
+                  line: `${base} A provided design handover was touched this turn, so this is the absence worth naming.`,
+              }
+            : { noteworthy: false, line: base };
     }
     try {
         const a = JSON.parse(raw) as {
             structure_gate?: string;
+            inputs?: unknown;
             dimensions?: { dimension: string; status: string; findings: number | null; reason?: string }[];
-            findings?: unknown[];
+            findings?: { dimension?: string; probe_id?: string; expected?: string; observed?: string }[];
         };
+
+        // Before anything is counted. A finding count measured against inputs
+        // that have since moved is the misleading half of a stale artefact, so
+        // the count is withheld rather than printed beside a warning.
+        const inputs = compareInputs(a.inputs, (p) => (path.isAbsolute(p) ? p : path.join(root, p)));
+        if (inputs.verdict === 'moved') {
+            return {
+                noteworthy: true,
+                line: [
+                    `ui-conformance: stale — ${inputs.moved.join(', ')} changed since the probe ran, so its findings ` +
+                        'describe inputs that no longer exist. The count is withheld rather than reported against ' +
+                        'them; re-run `ui_conformance_probe --target <file> --reference <file>`.',
+                    '  (shadow verdict: reported, never enforced — this pass does not block on it)',
+                ].join('\n'),
+            };
+        }
+
         const rows = a.dimensions ?? [];
         const exercised = rows.filter((r) => r.status === 'exercised');
         const notApplicable = rows.filter((r) => r.status !== 'exercised');
@@ -188,6 +256,29 @@ export function conformanceVerdict(root: string): ConformanceVerdict {
         if (a.structure_gate === 'stopped') {
             parts.push('  · structure gate stopped on at least one node — style comparison was skipped for it');
         }
+        // The added-element half. This line already said "Absent is not clean"
+        // about a missing artefact; the probe's structure dimension could only
+        // ever show the omit half of "never omit or add an element", so this is
+        // the one number the verdict could not print. Derived from the findings
+        // the probe already writes — no new artefact field is read.
+        const addedElements = (a.findings ?? []).filter(
+            (f) => f.dimension === 'structure' && f.expected === 'absent' && f.observed === 'present',
+        );
+        if (addedElements.length) {
+            parts.push(
+                `  · ${addedElements.length} element(s) present in the target and absent from the reference: ` +
+                    `${addedElements.map((f) => f.probe_id ?? '?').join(', ')} — added, not ported`,
+            );
+        }
+        parts.push(
+            inputs.verdict === 'unchanged'
+                ? '  · inputs: unchanged since the probe ran'
+                : // Unknown is a version skew, not evidence of movement — and
+                  // equally not evidence of freshness. Saying so is the whole
+                  // point: an artefact from before the digests existed must read
+                  // neither stale nor fresh.
+                  `  · inputs: unknown — ${inputs.reason}`,
+        );
         parts.push('  (shadow verdict: reported, never enforced — this pass does not block on it)');
         return {
             noteworthy: (a.findings ?? []).length > 0 || a.structure_gate === 'stopped' || notApplicable.length > 0,
@@ -456,7 +547,7 @@ function main(): number {
     // be silent — a behavioural finding is exactly the thing no static scan can
     // see — but it cannot make it refuse. `result.blocked` above is computed
     // without it and the exit code below is unchanged.
-    const conformance = conformanceVerdict(root);
+    const conformance = conformanceVerdict(root, { handoverDetected: handoverTouched(targets) });
 
     if (
         !result.findings.length &&

package/src/scripts/hooks/design_slop_hook.ts

@@ -26,10 +26,9 @@ import { type DesignContext } from "../design_slop_rules.js";
 import { UI_EXT } from "../_lib/ui_surface.js";
 import { loadDesignContext, scanFile } from "../lint_design_slop.js";
 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;
 const DEGRADE_AFTER = 3; // surfaces of the same file::rule signature before going silent
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };

package/src/scripts/hooks/dispatch_hook.ts

@@ -34,6 +34,10 @@ import * as tty from "node:tty";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parse as parseYaml } from "yaml";
 
+import { runBundleIntegrityGate } from "./bundle_integrity.js";
+import { writeConcernTimings, type ConcernTimingSample } from "./concern_timings.js";
+import { tableFingerprint } from "./table_fingerprint.js";
+
 import { hardenedSpawnEnv } from "../_lib/spawn_env.js";
 import {
   atomic_write_json,
@@ -59,6 +63,8 @@ import { _py_json_dumps } from './py_json_dumps.js';
 import { _fallback_yaml } from './fallback_yaml.js';
 import { detectSurface } from '../_lib/surface.js';
 import { recordCapture, recordOpportunity } from "../_lib/collector_denominator.js";
+import { EXIT_ALLOW, EXIT_BLOCK, EXIT_WARN, EXIT_USAGE } from './exit_codes.js';
+export { EXIT_ALLOW, EXIT_BLOCK, EXIT_WARN };
 export { _fallback_yaml } from './fallback_yaml.js';
 
 // Free-form JSON values flow through every helper here; a documented
@@ -84,10 +90,6 @@ const REPO_ROOT = path.resolve(
 );
 const MANIFEST_PATH = path.join(REPO_ROOT, "src", "scripts", "hook_manifest.yaml");
 
-export const EXIT_ALLOW = 0;
-export const EXIT_BLOCK = 1;
-export const EXIT_WARN = 2;
-
 // Per Council Round 2 (Q3): `agent_error` covers agent-level crashes
 // that are not concern-triggered, so chat-history can checkpoint
 // partial sessions on abnormal exit.
@@ -206,12 +208,7 @@ export function _parse_concern_stdout(stdout_text: string): JsonObject {
  * correctness.
  */
 export function _manifest_fingerprint(text: string): string {
-  let h = 0x811c9dc5;
-  for (let i = 0; i < text.length; i += 1) {
-    h ^= text.charCodeAt(i);
-    h = Math.imul(h, 0x01000193) >>> 0;
-  }
-  return `${h.toString(16)}:${String(text.length)}`;
+  return tableFingerprint(text);
 }
 
 export function _load_yaml(p: string): JsonObject {
@@ -251,12 +248,10 @@ export function _load_yaml(p: string): JsonObject {
   return _isObject(data) ? data : {};
 }
 
-
 interface ConcernDef extends JsonObject {
   name: string;
 }
 
-
 /**
  * Per-concern tool filter — the `tools:` key.
  *
@@ -424,7 +419,6 @@ export function _resolve_concerns(
   return out;
 }
 
-
 /**
  * Write the raw stdin payload to a capture directory when
  * `AGENT_HOOK_CAPTURE_DIR` is set. Fail-silent: any IO / JSON error must
@@ -506,6 +500,7 @@ interface RunResult {
   rc: number;
   stderr: string;
   stdout: string;
+  /** Elapsed ms, NOT floored — floored where STORED. See `concern_timings.ts`. */
   duration_ms: number;
 }
 
@@ -680,8 +675,7 @@ function _run_concern_inproc(
     }
     clearHookStdinOverride();
   }
-  const elapsed = Math.floor(performance.now() - started);
-  return { rc, stderr: err, stdout: out, duration_ms: elapsed };
+  return { rc, stderr: err, stdout: out, duration_ms: performance.now() - started };
 }
 
 function _run_concern(concern: ConcernDef, envelope: JsonObject): RunResult {
@@ -736,7 +730,7 @@ function _run_concern(concern: ConcernDef, envelope: JsonObject): RunResult {
     env: concern_env,
     timeout: 30000,
   });
-  const elapsed = Math.floor(performance.now() - started);
+  const elapsed = performance.now() - started;
   if (proc.error) {
     // OSError / timeout equivalent — log execution-failed so the
     // never-block contract keeps a trace.
@@ -796,6 +790,7 @@ interface FeedbackEntry extends JsonObject {
   concern: string;
 }
 
+
 /**
  * Write per-concern feedback files + summary rollup.
  *
@@ -1064,7 +1059,7 @@ function _parse_args(argv: string[]): Args {
     process.stderr.write(
       `dispatch_hook: the following arguments are required: ${missing.join(", ")}\n`,
     );
-    process.exit(2);
+    process.exit(EXIT_USAGE);
   }
   return args;
 }
@@ -1251,6 +1246,15 @@ export function main(argv?: string[]): number {
     }
   }
 
+  // Step 3.1 — the bundle we execute must be the bundle the build produced.
+  // Beside `denyOnStdinFailure` for its reason: the verdict needs the resolved
+  // concern list. Rules: `bundle_integrity.ts`.
+  if (_IN_BUNDLE) {
+    const stop = runBundleIntegrityGate(fileURLToPath(import.meta.url), args.platform,
+      args.event, concerns.some((c) => !_is_advisory(c)));
+    if (stop !== null) return stop;
+  }
+
   const envelope = _build_envelope(args, payload_text);
   const session_id = _resolve_session_id(envelope);
   const started_at = _now_iso();
@@ -1286,6 +1290,7 @@ export function main(argv?: string[]): number {
   // classes are present, which any concern loses, the single measurement pass,
   // and the at-most-four envelope shapes — so the loop below reads a shape
   // rather than re-deriving one. Rationale and cost model: payload_stub.ts.
+  const timing_samples: ConcernTimingSample[] = [];
   const keep_by_concern = concerns.map(
     (c) => [c, _concern_body_classes(c)] as const,
   );
@@ -1308,6 +1313,7 @@ export function main(argv?: string[]): number {
     const concern_started = _now_iso();
     const { rc: rawRcResult, stderr: stderr_text, stdout: stdout_text, duration_ms } =
       _run_concern(concern, concern_envelope);
+    timing_samples.push({ concern: String(concern["name"]), duration_us: duration_ms * 1000 });
     let rc = rawRcResult;
     const raw_rc = rc;
     if (rc >= 3) {
@@ -1376,7 +1382,7 @@ export function main(argv?: string[]): number {
       severity: _severity_for(rc),
       decision: (reply["decision"] || _severity_for(rc)) as JsonValue,
       reason: (reply["reason"] ?? null) as JsonValue,
-      duration_ms,
+      duration_ms: Math.floor(duration_ms),
       started_at: concern_started,
       completed_at: _now_iso(),
       fail_closed: Boolean(concern["fail_closed"]),
@@ -1392,6 +1398,7 @@ export function main(argv?: string[]): number {
     });
   }
   const final_rc = _reduce(rcs);
+  writeConcernTimings(String(envelope["event"] ?? ""), String(envelope["platform"] ?? ""), timing_samples);
   _write_feedback(envelope, session_id, feedback_entries, final_rc, started_at);
   _record_rule_trips(envelope, feedback_entries);
   if (context_blocks.length > 0 && final_rc === EXIT_ALLOW) {
@@ -1459,7 +1466,6 @@ function _sortedRepr(s: ReadonlySet<string>): string {
  */
 let _stdin_read_failed: string | null = null;
 
-
 // Bundle-safety: never auto-run when inlined into an esbuild bundle, where
 // every module shares the bundle's `import.meta.url` (declare at top of file).
 function _isCliEntry(): boolean {

package/src/scripts/hooks/edit_shape_hook.ts

@@ -86,11 +86,10 @@ 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 in the
 // stdout payload — see the file header for why this never blocks on `claude`.
-const EXIT_WARN = 2;
 
 /** Committed threshold (roadmap 5.1): minimum current line count of the
  *  replaced file before this concern has anything to say. */

package/src/scripts/hooks/end_review_nudge_hook.ts

@@ -253,6 +253,7 @@ import {
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { atomic_write_json, is_replay_mode } from './state_io.js';
+import { EXIT_WARN } from './exit_codes.js';
 
 /** Default fire threshold — the council's high-risk shape (roadmap 5.1). */
 export const MUTATION_LINE_THRESHOLD = 50;
@@ -319,7 +320,6 @@ export function isSafeTranscriptPath(
 // reported at exit 2 so `host_semantics.emitFor` reduces it to severity
 // `"warn"` and forwards `additional_context`; see the file header for why
 // this exit code never actually blocks the turn on `claude`.
-const EXIT_WARN = 2;
 
 /** One `git diff --numstat` row: added/deleted line counts + the path. */
 export interface NumstatRow {

package/src/scripts/hooks/evidence_independence.ts

@@ -52,8 +52,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { atomic_write_json } from "./state_io.js";
 import { readHookStdin } from "./hook_stdin.js";
 import { isCodePath, isTestPath } from "../_lib/test_delta.js";
+import { EXIT_ALLOW, EXIT_BLOCK } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
 // MUST equal dispatch_hook.EXIT_BLOCK. The dispatcher's internal ladder is
 // 0 allow / 1 block / 2 warn — NOT the 2-means-block shape a PreToolUse guard
 // reads naturally from Claude's own native contract. This constant was 2 when
@@ -61,7 +61,6 @@ const EXIT_ALLOW = 0;
 // and the gate emitted advisory context while the operation went through.
 // Pinned against the dispatcher's export by
 // tests/hooks/concern_block_exit_parity.test.ts.
-const EXIT_BLOCK = 1;
 
 export const STATE_FILE = path.join("agents", "state", "evidence-dispatch.json");
 

package/src/scripts/hooks/exit_codes.ts

@@ -0,0 +1,128 @@
+/**
+ * The hook exit-code table — one frozen definition, imported everywhere.
+ *
+ * road-to-a-kernel-that-guards-its-plumbing 4.1.
+ *
+ * WHAT WAS WRONG. Thirty-three files under `src/scripts/hooks/` each declared
+ * their own `const EXIT_ALLOW = 0` / `EXIT_BLOCK = 1` / `EXIT_WARN = 2`, two of
+ * them under a third name (`EXIT_OK`). Thirty-three copies of a contract is
+ * thirty-three places it can be changed in one and not the others, and the
+ * change that matters here is not a typo: exit 1 and exit 2 mean the OPPOSITE
+ * things on Claude Code from what they mean in this tree's internal language
+ * (`host_semantics.ts` exists entirely to lower one onto the other). A number
+ * that means "advisory" here and "hard deny" there is not a constant anyone
+ * should be re-deriving per file.
+ *
+ * WHAT THE TABLE ADDS BEYOND THE NUMBERS. `owner` and `authorizedBy` — who
+ * decides that a concern emits this code, and what authorises the dispatcher to
+ * act on it. A bare `1` in a concern says nothing about whether that concern was
+ * ever allowed to refuse; the manifest's `severity` is what authorises it, and
+ * the dispatcher enforces that ceiling (`_is_advisory`). Recording it beside the
+ * number is what makes the table a contract rather than an enum.
+ *
+ * WHAT IS NOT IN SCOPE. The `*-dispatcher.sh` trampolines carry inline
+ * `process.exit(0)` in a `node -e` one-liner that reads a workspace root off
+ * stdin. They are shell, they cannot import, and their exit code is the
+ * one-liner's, never a verdict. `lint_exit_codes` scans `.ts` only.
+ */
+
+/** Allow — the concern has no objection. The overwhelmingly common verdict. */
+export const EXIT_ALLOW = 0;
+
+/** Block — the concern refuses. Only a `severity: blocking` concern may. */
+export const EXIT_BLOCK = 1;
+
+/** Warn — advisory. The dispatcher exits 0 and surfaces the reason. */
+export const EXIT_WARN = 2;
+
+/**
+ * Error — the concern crashed or could not decide.
+ *
+ * `3` is the floor, not the only value: the dispatcher treats every rc ≥ 3 the
+ * same way, and what that way IS depends on the concern's declared severity.
+ */
+export const EXIT_ERROR = 3;
+
+/**
+ * Usage error on the process's OWN argv — not a verdict, and not a row.
+ *
+ * `dispatch_hook` and `replay_hook` are also CLIs: run with `--platform`
+ * missing they exit before any concern is consulted. The number is 2 by the
+ * POSIX convention for a usage error, which COLLIDES with `EXIT_WARN` by
+ * coincidence and not by meaning — nothing advisory has happened, and no
+ * concern has spoken.
+ *
+ * Named rather than left as a bare `2`, and kept OUT of `EXIT_CODES`, because
+ * both readings are wrong: importing `EXIT_WARN` here would assert a verdict
+ * that was never reached, and adding a fifth row would put a non-verdict in a
+ * table whose whole subject is what a concern may say. `lint_exit_codes`
+ * refuses the bare literal, so the next writer has to pick one of the two
+ * deliberately.
+ */
+export const EXIT_USAGE = 2;
+
+export interface ExitCodeRow {
+    /** The numeric code, or its floor for the open-ended error band. */
+    readonly code: number;
+    readonly name: 'allow' | 'block' | 'warn' | 'error';
+    readonly meaning: string;
+    /** Who decides a concern emits this code. */
+    readonly owner: string;
+    /** What authorises the dispatcher to act on it. */
+    readonly authorizedBy: string;
+}
+
+/**
+ * The frozen table. Ordered by code; the last row is a band, not a value.
+ *
+ * `as const` plus `Object.freeze` rather than a plain array: this is the kind of
+ * structure a later convenience ("just push a row for the new verdict") turns
+ * into a fourth dialect, and the whole point of the file is that there is one.
+ */
+export const EXIT_CODES: readonly ExitCodeRow[] = Object.freeze([
+    Object.freeze({
+        code: EXIT_ALLOW,
+        name: 'allow',
+        meaning: 'no objection; the dispatcher passes the call through',
+        owner: 'every concern — the default verdict',
+        authorizedBy: 'nothing; allowing needs no authority',
+    }),
+    Object.freeze({
+        code: EXIT_BLOCK,
+        name: 'block',
+        meaning: 'refuse the call; the dispatcher lowers this onto the host deny channel',
+        owner: 'a concern declared `severity: blocking` in hook_manifest.yaml',
+        authorizedBy:
+            'the manifest entry plus its row in the BLOCKING_ALLOWLIST of ' +
+            'tests/hooks/concern_severity.test.ts — an advisory concern emitting this is ' +
+            'downgraded to warn by dispatch_hook._is_advisory',
+    }),
+    Object.freeze({
+        code: EXIT_WARN,
+        name: 'warn',
+        meaning: 'advisory; the dispatcher exits 0 and surfaces the reason',
+        owner: 'any concern',
+        authorizedBy:
+            'nothing; warning is the ceiling for an advisory concern and is always available ' +
+            'to a blocking one',
+    }),
+    Object.freeze({
+        code: EXIT_ERROR,
+        name: 'error',
+        meaning:
+            'the concern crashed, timed out, or could not decide — any rc >= 3. The dispatcher ' +
+            'resolves it by the concern`s declared severity, never by the number itself',
+        owner: 'no concern emits this on purpose; the runtime does',
+        authorizedBy:
+            'hook_manifest.yaml `fail_closed` and `severity` together — see ' +
+            'docs/contracts/hook-architecture-v1.md § Exit-code semantics',
+    }),
+] as const);
+
+/** The row a raw exit code resolves to, or `null` for a negative code. */
+export function rowFor(code: number): ExitCodeRow | null {
+    if (code >= EXIT_ERROR) {
+        return EXIT_CODES[3] ?? null;
+    }
+    return EXIT_CODES.find((r) => r.code === code) ?? null;
+}

package/src/scripts/hooks/host_lowering.json

@@ -0,0 +1 @@
+{"fingerprint":"08575a71d81fd8a5ef9e4b400f4a38cb66c26e1dd701d98f3cdc0bdc9e4758b4:22235","table":{"schema_version":1,"hosts":{"claude":{"surfaces":{"any":{"entry_shape":"claude-settings-hooks","json_shape":"hook-specific-output","fail_policy":"propagate","timeout_unit":"seconds","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://code.claude.com/docs/en/hooks.md","docs_digest":"9dd68316c1111c118e3ddb82861ac6271a8cd164cee0d371b26165efff35fe88","probe_at":"2026-09-06","host_version":"2.1.263","expires":"2027-09-06"},"slots":{"session_start":{"native":"SessionStart","block_exit":null,"answered_at":"2026-09-29"},"session_end":{"native":"SessionEnd","block_exit":null,"answered_at":"2026-09-29"},"stop":{"native":"Stop","block_exit":2,"answered_at":"2026-09-29"},"user_prompt_submit":{"native":"UserPromptSubmit","block_exit":2,"answered_at":"2026-09-29"},"pre_tool_use":{"native":"PreToolUse","block_exit":2,"answered_at":"2026-09-29"},"post_tool_use":{"native":"PostToolUse","block_exit":null,"answered_at":"2026-09-29"},"pre_compact":{"native":"PreCompact","block_exit":null,"answered_at":"2026-09-29"},"subagent_start":{"native":"SubagentStart","block_exit":null,"answered_at":"2026-09-29"},"subagent_stop":{"native":"SubagentStop","block_exit":null,"answered_at":"2026-09-29"}}}}},"augment":{"surfaces":{"any":{"entry_shape":"augment-settings-hooks","json_shape":"none","fail_policy":"discard","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://docs.augmentcode.com/cli/hooks.md","docs_digest":"e500823be8303717020c1823f670e06d100108f6e3ac4b8d12a46d91fd1898fa","probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{"session_start":{"native":"SessionStart","block_exit":null,"answered_at":"2026-09-29"},"session_end":{"native":"SessionEnd","block_exit":null,"answered_at":"2026-09-29"},"stop":{"native":"Stop","block_exit":null,"answered_at":"2026-09-29"},"pre_tool_use":{"native":"PreToolUse","block_exit":null,"answered_at":"2026-09-29"},"post_tool_use":{"native":"PostToolUse","block_exit":null,"answered_at":"2026-09-29"}}}}},"cursor":{"surfaces":{"any":{"entry_shape":"cursor-hooks-json","json_shape":"none","fail_policy":"propagate","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://cursor.com/docs/hooks.md","docs_digest":"7294a2d63b19d79a5283c948afe174cba8b06a7585563d34a2c41b90f5df0d39","probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{"session_start":{"native":"sessionStart","block_exit":null,"answered_at":"2026-09-29"},"session_end":{"native":"sessionEnd","block_exit":null,"answered_at":"2026-09-29"},"stop":{"native":"stop","block_exit":null,"answered_at":"2026-09-29"},"user_prompt_submit":{"native":"beforeSubmitPrompt","block_exit":null,"answered_at":"2026-09-29"},"post_tool_use":{"native":"postToolUse","block_exit":null,"answered_at":"2026-09-29"}}}}},"cline":{"surfaces":{"any":{"entry_shape":"cline-per-event-script","json_shape":"none","fail_policy":"discard","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://docs.cline.bot/customization/hooks.md","docs_digest":"ef87561721f4cb80fe6d682b6866d638a4952dd416d36cd5ab398426ce64084b","probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{"session_start":{"native":["TaskStart","TaskResume"],"block_exit":null,"answered_at":"2026-09-29"},"session_end":{"native":"TaskComplete","block_exit":null,"answered_at":"2026-09-29"},"stop":{"native":"TaskCancel","block_exit":null,"answered_at":"2026-09-29"},"user_prompt_submit":{"native":"UserPromptSubmit","block_exit":null,"answered_at":"2026-09-29"},"post_tool_use":{"native":"PostToolUse","block_exit":null,"answered_at":"2026-09-29"}}}}},"windsurf":{"surfaces":{"any":{"entry_shape":"windsurf-hooks-json","json_shape":"none","fail_policy":"propagate","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://docs.devin.ai/desktop/cascade/hooks.md","docs_digest":"460ffe7aa91998804920f6722c0153b9948eadd5edafa19582298475a19835a2","probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{"session_start":{"native":"post_setup_worktree","block_exit":null,"answered_at":"2026-09-29"},"user_prompt_submit":{"native":"pre_user_prompt","block_exit":null,"answered_at":"2026-09-29"},"stop":{"native":"post_cascade_response","block_exit":null,"answered_at":"2026-09-29"}}}}},"gemini":{"surfaces":{"any":{"entry_shape":"gemini-settings-hooks","json_shape":"none","fail_policy":"propagate","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://geminicli.com/docs/hooks/reference.md","docs_digest":"06d37f2f66812ee78bb46c37a112203376f0bae4d3b8b44ac79d0bda4b86a118","probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{"session_start":{"native":"SessionStart","block_exit":null,"answered_at":"2026-09-29","matcher":""},"session_end":{"native":"SessionEnd","block_exit":null,"answered_at":"2026-09-29","matcher":""},"stop":{"native":"AfterAgent","block_exit":null,"answered_at":"2026-09-29","matcher":""},"user_prompt_submit":{"native":"BeforeAgent","block_exit":null,"answered_at":"2026-09-29","matcher":""},"post_tool_use":{"native":"AfterTool","block_exit":null,"answered_at":"2026-09-29","matcher":".*"}}}}},"cowork":{"surfaces":{"any":{"entry_shape":"none","json_shape":"none","fail_policy":"discard","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":null,"docs_digest":null,"probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{}}}},"copilot":{"surfaces":{"any":{"entry_shape":"none","json_shape":"none","fail_policy":"discard","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://docs.github.com/en/copilot/concepts/agents/hooks.md","docs_digest":"bfd40aa93ad62133efc17a50f189034f01594dc89a5d31a13a0c541d691acede","probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{}}}},"codex":{"surfaces":{"any":{"entry_shape":"none","json_shape":"none","fail_policy":"discard","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://developers.openai.com/codex/hooks.md","docs_digest":"724881d81f1a9fdb35ea42d4851a11b1f6606bbc6e9d2d05c1e8c466fc25c630","probe_at":"2026-10-01","host_version":"0.148.0","expires":"2027-09-29"},"slots":{}}}}}}}