@event4u/agent-config 16.2.0 → 16.3.0

package/src/scripts/hooks/concern_failure_policy.ts

@@ -0,0 +1,280 @@
+/**
+ * What a concern's DECLARED SEVERITY means when the concern produced no verdict.
+ *
+ * Extracted from `dispatch_hook.ts` on 2026-10-03, and not for tidiness.
+ * `check_source_size_budget` measured that file at exactly 1,500 lines on
+ * `main` — sitting precisely on the cap — and step 3.3's additions put it 203
+ * lines over. The ratchet turns one way, and the doctrine every entry in
+ * `gate-violation-baselines.json` records is that a MOVE gives the budget back
+ * where raising the baseline spends it. The same move
+ * `_lib/concern_sla_window.ts` made out of `bench_hook_latency.ts`.
+ *
+ * It is also the better boundary on its own terms. Everything here answers one
+ * question — what a concern's declaration permits and requires when the
+ * concern itself said nothing — and none of it is about RUNNING a concern,
+ * which is what the dispatcher does. `stdin_failure_policy.ts` is its sibling:
+ * the same question for a payload the dispatcher could not read.
+ *
+ * The dispatcher re-exports every symbol here, so callers and tests that
+ * imported them from `dispatch_hook.js` are unaffected.
+ */
+import { EXIT_ALLOW, EXIT_BLOCK, EXIT_ERROR } from './exit_codes.js';
+
+type JsonObject = Record<string, unknown>;
+
+/**
+ * P0.2 (road-to-rule-coherence) — is this concern declared advisory?
+ *
+ * An advisory concern MUST never produce a BLOCK verdict on any host. Four
+ * PreToolUse concerns document themselves as advisory in prose
+ * (`design_slop_hook`: "FLAGS, NEVER A BLOCK") while the transport happily
+ * turned their WARN into a host-level deny. Prose is not enforcement: the
+ * manifest now declares severity and the dispatcher enforces the ceiling.
+ */
+export function _is_advisory(concern: JsonObject): boolean {
+  return String(concern["severity"] ?? "").trim().toLowerCase() === "advisory";
+}
+
+/**
+ * Is this concern declared `severity: blocking`?
+ *
+ * The positive twin of `_is_advisory`, and NOT its negation. A concern whose
+ * `severity` is absent, misspelt or any third value is neither — and step 3.3
+ * below promotes a crash to a refusal only on an EXPLICIT `blocking`, so an
+ * undeclared concern keeps the historical fail-open rather than inheriting a
+ * refusal from a typo. `lint_hook_manifest` requires the key, so the middle
+ * case should not exist; this reads it as the safe direction anyway, because
+ * the cost of the two mistakes is not symmetric.
+ */
+export function _is_blocking(concern: JsonObject): boolean {
+  return String(concern["severity"] ?? "").trim().toLowerCase() === "blocking";
+}
+
+/**
+ * What an `rc >= 3` (crash / could-not-decide) becomes — step 3.3 of
+ * `road-to-a-kernel-that-guards-its-plumbing`.
+ *
+ * WHAT CHANGED, AND WHAT AUTHORISES IT.
+ * Until this step the resolution read the `fail_closed:` FLAG: a crash blocked
+ * when the concern opted in and allowed otherwise. Three of nine
+ * `severity: blocking` concerns carried the flag, so six guards declared
+ * blocking in the manifest — the declaration that AUTHORISES a refusal, and the
+ * one `_is_advisory` already enforces as a ceiling — and then allowed the call
+ * through whenever they crashed. A guard that refuses when it works and permits
+ * when it breaks is not a guard: a crash is exactly the moment the check did
+ * not happen, so it is the moment the answer matters most.
+ *
+ * So `severity` now decides both directions. It is the ceiling (an advisory
+ * concern may never block) AND the floor (a blocking concern that could not
+ * decide refuses). `fail_closed:` is no longer consulted on this branch — all
+ * three concerns carrying it are `severity: blocking`, so no verdict moves
+ * because it stopped being read here.
+ *
+ * WHAT A SLOW CONCERN IS NOT, ON EITHER PATH.
+ * This branch resolves a concern that produced NO VERDICT. It is not a latency
+ * gate and no reading of `concern_sla_ms` reaches it. On the default in-process
+ * route a kill-timeout cannot preempt synchronous code, so an overrun there is
+ * a POST-HOC observation about a concern that did in fact answer — refusing it
+ * afterwards would deny a call whose guard passed, buying no enforcement while
+ * spending exactly the availability risk Risk 1 of the owning roadmap holds
+ * down. On the spawn route the timeout stays the historical 30 s, because the
+ * registered SLA measures in-process concern work and is three to fifteen times
+ * smaller than interpreter startup alone; `SPAWN_TIMEOUT_MS` carries that
+ * measurement and the probe that refused the substitution.
+ *
+ * So `sla_ms x 3` remains what the warn-only window made it: a number the bench
+ * prints beside each measured p95, gating nothing. Its readings are recorded
+ * with the owning plan and no count is repeated here — a review of an earlier
+ * revision found two different tallies in one diff, because a number had been
+ * pasted into an implementation comment while the record kept accumulating.
+ * The readings validate the bound as an OBSERVATION, which is the only thing
+ * this step asks of them.
+ *
+ * The discriminator for this branch is whether a VERDICT EXISTS. A crash and a
+ * killed spawn leave none, so they fail closed. A slow success leaves one, so
+ * it is honoured, however slow it was.
+ *
+ * THE ONE-RETRY ESCAPE, AND WHY THE STOP SLOT NEEDS IT.
+ * `turn-end-gate` and `run-continuation` are `severity: blocking` on `stop`,
+ * and `tests/hooks/concern_severity.test.ts` records the hazard in as many
+ * words: a turn-end gate that fails closed "does not degrade, it wedges the
+ * session". Neither carries `skip_on_refusal_retry`, so without this clause a
+ * DETERMINISTIC crash in either would refuse every Stop, indefinitely, with no
+ * escape the user can reach.
+ *
+ * So the promotion is spent ONCE. On the retry the host itself marks
+ * (`stop_hook_active`, read by `_is_refusal_retry`) a crash falls back to
+ * fail-open and the turn ends. The legitimate refusal path is untouched: a
+ * concern that DECIDED to refuse returns `EXIT_BLOCK` and never reaches this
+ * branch. What a broken concern loses is only the power to refuse forever on
+ * the strength of being broken.
+ *
+ * `pre_tool_use` is untouched by the clause — `_is_refusal_retry` is false on
+ * every event but `stop` — and that asymmetry is deliberate. A crashing
+ * tool-call guard refuses every attempt, which is the right answer there: the
+ * user can run a different command and nothing is wedged, whereas a turn that
+ * cannot end leaves no move at all.
+ */
+export function _resolve_execution_failure(
+  concern: JsonObject,
+  refusal_retry: boolean,
+): number {
+  if (!_is_blocking(concern)) return EXIT_ALLOW;
+  if (refusal_retry) return EXIT_ALLOW;
+  return EXIT_BLOCK;
+}
+
+/**
+ * The spawn kill-timeout, and why `concern_sla_ms` is NOT what sets it.
+ *
+ * Step 3.3 of `road-to-a-kernel-that-guards-its-plumbing` reads "timeout for a
+ * blocking concern becomes `sla_ms x 3`". That clause is NOT landed, and the
+ * reason is a unit mismatch that is measurable rather than arguable.
+ *
+ * `concern_sla_ms` is derived from the per-concern `duration_ms` this file
+ * reports into the timings sink, which on the in-process route brackets
+ * `main_fn(argsList)` and nothing else — the concern's OWN work. The registered
+ * rows are 0.564 to 1.587 ms, so `sla_ms x 3` is 1.7 to 4.8 ms.
+ *
+ * A `spawnSync` timeout bounds something else entirely: fork, interpreter
+ * start, module graph load, and only then the same work. The bench's own
+ * control row measures the interpreter term alone at p95 17 ms on the 1 vCPU
+ * reference class and 26 ms on the GitHub runner — three to fifteen times the
+ * whole proposed bound, before the concern has run a line.
+ *
+ * Wiring it was tried on this branch and probed against the real dispatcher.
+ * With `AGENT_CONFIG_HOOKS_ISOLATED=1` on `claude/pre_tool_use`, all six
+ * blocking concerns returned `ETIMEDOUT`, left no verdict, and — resolved by
+ * `_resolve_execution_failure` — turned the dispatch into a deny: exit 2 on an
+ * ordinary `Read`. That is Risk 1 of the owning roadmap ("fail-closed wedges
+ * slow hosts") firing on every host rather than a slow one, reached through a
+ * documented escape hatch. The two changes are individually defensible and
+ * lethal together, which is exactly the shape a measured bound is supposed to
+ * prevent.
+ *
+ * So the bound stays where the window put it: an observation
+ * `src/scripts/_lib/concern_sla_window.ts` prints on every bench run, gating
+ * nothing. The spawn path keeps the historical 30 s. Re-wiring it needs a
+ * SPAWN-path measurement — which this tree does not have, because the sink it
+ * would come from records the in-process number — and not a second reading of
+ * the one registered here.
+ *
+ * `spawn_path_keeps_the_historical_timeout` in `dispatch_hook.test.ts` pins
+ * this: it dispatches a blocking concern whose NAME carries a registered SLA
+ * row down the spawn path and asserts the call is allowed. Under the bound it
+ * reds.
+ */
+export const SPAWN_TIMEOUT_MS = 30000;
+
+/**
+ * The signal name a killed child reports, or the honest placeholder.
+ *
+ * A SIGNALLED child has `status === null` and `signal` set, and reaches the
+ * dispatcher's spawn branch with no `proc.error` whenever the signal came from
+ * outside this process — an OOM kill, a SIGTERM from a supervisor, a crash in
+ * the child's own runtime. `proc.status ?? 0` read that as exit 0, i.e. ALLOW,
+ * which is a fail-OPEN at the one moment the error band exists to fail closed:
+ * the concern was killed, so it decided nothing. The coalescing default was
+ * harmless while the band meant fail-open for six of nine blocking concerns;
+ * with the severity resolution it is the difference between a guard that
+ * refuses when it is killed and one that waves the call through. Found by an
+ * independent review, 2026-10-03, latent since the spawn path was written.
+ *
+ * `null` for both fields is possible and is reported as an unknown signal
+ * rather than guessed at — a refusal whose cause reads "unknown" is still
+ * actionable, and one whose cause is invented is not.
+ */
+export function signalLabel(signal: NodeJS.Signals | null): string {
+    return signal === null ? 'unknown signal' : signal;
+}
+
+/**
+ * What an operator is told when a blocking concern refuses without deciding.
+ *
+ * Printed where the refusal is produced rather than left in a source comment.
+ * Both review seats of 2026-10-03 named the same gap: on `pre_tool_use` a
+ * deterministically crashing blocking concern refuses every tool call, and the
+ * operator cannot discover the escape hatch from inside a wedged session.
+ * `stop` is bounded by the one-retry clause and needs no such line, so the
+ * caller prints this only where the denial can repeat.
+ */
+export function noVerdictRefusalNotice(name: string): string {
+    return (
+        `dispatch_hook: '${name}' is severity: blocking and produced no ` +
+        `verdict, so this call is refused. If it keeps failing, ` +
+        `AGENT_CONFIG_HOOKS_ISOLATED=1 runs concerns out of process and ` +
+        `agents/runtime/state/dispatch-issues.jsonl names the cause.\n`
+    );
+}
+
+/**
+ * What a finished `spawnSync` actually said, in the vocabulary of verdicts.
+ *
+ * Three ways a spawned concern produces NO VERDICT, and until 2026-10-03 only
+ * two of them were recognised as such:
+ *
+ *  - **`proc.error`** — an OSError, or the kill-timeout expiring. Always a
+ *    no-verdict and always was.
+ *  - **`status === null` with a signal** — the child was killed from outside
+ *    this process: an OOM kill, a supervisor SIGTERM, an abort in the child's
+ *    own runtime. `proc.status ?? 0` read this as exit 0, i.e. ALLOW, which is
+ *    a fail-OPEN at the one moment the error band exists to fail closed. The
+ *    coalescing default was harmless while the band meant fail-open for six of
+ *    nine blocking concerns; with the severity resolution it is the difference
+ *    between a guard that refuses when it is killed and one that waves the call
+ *    through. Found by an independent review, latent since the spawn path was
+ *    written.
+ *  - **an exit code in the error band** — a child that simply exited 3. This
+ *    logged nothing until step 3.3: `proc.error` covers the first case, the
+ *    in-process route logs its own throw, and this fell between the two. That
+ *    was survivable while the band meant fail-open; now it can produce a
+ *    refusal, and a refusal whose cause is in no record is one nobody can act
+ *    on.
+ *
+ * Returning a classification rather than writing the log here keeps this module
+ * free of I/O — the caller owns `log_dispatch_issue` and the workspace it needs,
+ * and this owns what the three cases MEAN.
+ */
+export interface SpawnClassification {
+    /** The exit code the dispatcher should carry forward. */
+    readonly rc: number;
+    /** `execution_failed` detail to record, or `null` when there is nothing to record. */
+    readonly issueDetail: string | null;
+    /** True when the concern produced no verdict and its own stdout must be discarded. */
+    readonly noVerdict: boolean;
+    /** Prefix for the stderr line, or `null` to pass the child's stderr through unchanged. */
+    readonly stderrNote: string | null;
+}
+
+export function classifySpawnResult(
+    error: Error | undefined,
+    status: number | null,
+    signal: NodeJS.Signals | null,
+): SpawnClassification {
+    if (error !== undefined) {
+        const err = error as NodeJS.ErrnoException;
+        const typeName = err.code === 'ETIMEDOUT' ? 'TimeoutExpired' : err.name || 'OSError';
+        return {
+            rc: EXIT_ERROR,
+            issueDetail: `${typeName}: ${err.message}`,
+            noVerdict: true,
+            stderrNote: err.message,
+        };
+    }
+    if (status === null) {
+        const sig = signalLabel(signal);
+        return {
+            rc: EXIT_ERROR,
+            issueDetail: `concern was terminated by ${sig} without a verdict`,
+            noVerdict: true,
+            stderrNote: `terminated by ${sig}`,
+        };
+    }
+    return {
+        rc: status,
+        issueDetail:
+            status >= EXIT_ERROR ? `concern exited ${String(status)} without a verdict` : null,
+        noVerdict: false,
+        stderrNote: null,
+    };
+}

package/src/scripts/hooks/dispatch_hook.ts

@@ -12,7 +12,7 @@
  * Per `docs/contracts/hook-architecture-v1.md`. Reads `src/scripts/hook_manifest.yaml`,
  * resolves which concerns fire on the given (platform, event) tuple, and runs each
  * sequentially with the stdin envelope contract. Reduces concern exit codes per the
- * spec (0=allow, 1=block, 2=warn, ≥3=error → fail-open unless concern is fail_closed).
+ * spec (0=allow, 1=block, 2=warn, ≥3=error → resolved by declared `severity`).
  *
  * Invocation:
  *
@@ -59,6 +59,13 @@ import { _concern_body_classes, planPayloadShapes } from "./payload_stub.js";
 import { resolveSessionRole, type SessionRole } from "../_lib/session_role.js";
 import { stdinReadFailure, denyOnStdinFailure } from './stdin_failure_policy.js';
 export { stdinReadFailure, denyOnStdinFailure, _is_fail_closed_blocking } from './stdin_failure_policy.js';
+// Severity policy — what a declaration means when the concern said nothing.
+// Re-exported so the move out of this file left every importer unaffected.
+import {
+  _is_advisory, _is_blocking, _resolve_execution_failure,
+  classifySpawnResult, noVerdictRefusalNotice, SPAWN_TIMEOUT_MS,
+} from './concern_failure_policy.js';
+export { _is_advisory, _is_blocking, _resolve_execution_failure };
 import { _py_json_dumps } from './py_json_dumps.js';
 import { _fallback_yaml } from './fallback_yaml.js';
 import { detectSurface } from '../_lib/surface.js';
@@ -128,18 +135,6 @@ export function _severity_for(rc: number): string {
   return _SEVERITY_BY_EXIT[rc] ?? "error";
 }
 
-/**
- * P0.2 (road-to-rule-coherence) — is this concern declared advisory?
- *
- * An advisory concern MUST never produce a BLOCK verdict on any host. Four
- * PreToolUse concerns document themselves as advisory in prose
- * (`design_slop_hook`: "FLAGS, NEVER A BLOCK") while the transport happily
- * turned their WARN into a host-level deny. Prose is not enforcement: the
- * manifest now declares severity and the dispatcher enforces the ceiling.
- */
-export function _is_advisory(concern: JsonObject): boolean {
-  return String(concern["severity"] ?? "").trim().toLowerCase() === "advisory";
-}
 
 function _now_iso(): string {
   // Python: datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ").
@@ -198,32 +193,25 @@ export function _parse_concern_stdout(stdout_text: string): JsonObject {
  * path (`yaml.safe_load(text) or {}`); version 1.1 matches PyYAML.safe_load.
  */
 /**
- * Cheap content fingerprint of a manifest source — FNV-1a 32-bit plus the byte
- * length, hex.
+ * Content fingerprint of a manifest source — delegated to `tableFingerprint`,
+ * which owns the algorithm and the measurement.
  *
- * Deliberately NOT a crypto hash: `require('node:crypto')` costs 8 ms of
- * process start, which is most of what the precompiled manifest exists to
- * save. This runs in about 0.2 ms over 61 kB and only has to detect an edited
- * source, not resist an adversary — a wrong answer costs the slow path, never
- * correctness.
+ * road-to-blocking-severities 3.1: this comment used to argue against a crypto
+ * hash for a function that already used one. The retired argument and the
+ * numbers that retired it live there now.
  */
 export function _manifest_fingerprint(text: string): string {
   return tableFingerprint(text);
 }
 
 export function _load_yaml(p: string): JsonObject {
-  // Precompiled fast path. The manifest is ~61 kB of YAML and is parsed on
-  // EVERY dispatch, which measured 12 ms of a ~103 ms dispatch (plus 8 ms to
-  // load the `yaml` module itself). The sibling `.json` is the same data with
-  // comments stripped — 14.7 kB — and JSON.parse of it is sub-millisecond.
+  // Precompiled fast path. The manifest is ~61 kB of YAML parsed on EVERY
+  // dispatch — 12 ms of a ~103 ms dispatch, plus 8 ms to load the `yaml` module
+  // itself. The sibling `.json` is the same data with comments stripped,
+  // 14.7 kB, and JSON.parse of it is sub-millisecond.
   //
-  // Freshness is decided by the SOURCE CONTENT, not by mtime. The first version
-  // of this compared mtimes and that was a measured defect, not a theoretical
-  // one: on a fresh `actions/checkout` both files get the checkout timestamp in
-  // whatever order git wrote them, so whether the optimisation applied at all
-  // was a coin flip. It won on the PR (p95 129 ms) and lost on the trunk
-  // (p95 186 ms) for the same commit. A fingerprint is deterministic wherever
-  // the tree came from.
+  // Freshness is SOURCE CONTENT, never mtime — the measured defect behind that
+  // is in `table_fingerprint.ts`, told once rather than in all three readers.
   //
   // Reading the YAML unconditionally costs ~0 ms (it is the PARSE that is
   // expensive), so the fast path still skips ~20 ms.
@@ -235,7 +223,14 @@ export function _load_yaml(p: string): JsonObject {
       if (
         _isObject(raw) &&
         raw["fingerprint"] === _manifest_fingerprint(text) &&
-        _isObject(raw["manifest"])
+        _isObject(raw["manifest"]) &&
+        // road-to-blocking-severities 2.3, the manifest twin of the check in
+        // `host_lowering.resolveTable`, which carries the full reasoning. In
+        // one line: the label above binds this file to the YAML SOURCE and says
+        // nothing about the body underneath, so an edited `manifest` body with
+        // an untouched label was served — on the table that decides which
+        // concern runs on which slot at all. Absent field → fall through.
+        raw["body_fingerprint"] === _manifest_fingerprint(JSON.stringify(raw["manifest"]))
       ) {
         return raw["manifest"];
       }
@@ -565,10 +560,10 @@ function _resolve_tsx_invocation(
  * Escape hatch: AGENT_CONFIG_HOOKS_ISOLATED=1 forces the historical
  * spawn-per-concern path (also used by the bench harness for A/B numbers).
  *
- * Known trade-off vs the spawn path: the 30 s kill-timeout cannot preempt
- * in-process synchronous code. Concerns are repo-owned, budget-capped and
- * fail-open; the latency budget gate (hook-latency-budget.json) is the
- * standing regression net.
+ * Known trade-off vs the spawn path: a kill-timeout cannot preempt in-process
+ * synchronous code, so a slow concern is bounded on neither route — see
+ * `SPAWN_TIMEOUT_MS`. A CRASH is caught here, surfaces as rc 3, and the caller
+ * resolves it by declared severity.
  */
 /**
  * ## Why this still re-serialises the envelope per concern (step 1.1, MEASURED NULL)
@@ -678,6 +673,7 @@ function _run_concern_inproc(
   return { rc, stderr: err, stdout: out, duration_ms: performance.now() - started };
 }
 
+
 function _run_concern(concern: ConcernDef, envelope: JsonObject): RunResult {
   // In-process fast path — the default whenever the concern is in the
   // static registry (all manifest concerns; parity is CI-enforced).
@@ -728,31 +724,31 @@ function _run_concern(concern: ConcernDef, envelope: JsonObject): RunResult {
     encoding: "utf-8",
     cwd: workspace,
     env: concern_env,
-    timeout: 30000,
+    timeout: SPAWN_TIMEOUT_MS, // historical bound; `SPAWN_TIMEOUT_MS` says why
   });
   const elapsed = performance.now() - started;
-  if (proc.error) {
-    // OSError / timeout equivalent — log execution-failed so the
-    // never-block contract keeps a trace.
-    const err = proc.error as NodeJS.ErrnoException;
-    const typeName =
-      err.code === "ETIMEDOUT" ? "TimeoutExpired" : err.name || "OSError";
+  // Three ways a spawn produces no verdict; `classifySpawnResult` owns the
+  // reading, this writes the record and carries the code.
+  const outcome = classifySpawnResult(proc.error, proc.status, proc.signal);
+  if (outcome.issueDetail !== null) {
     log_dispatch_issue(
       workspace,
       String(concern["name"] || "unknown"),
       "execution_failed",
-      `${typeName}: ${err.message}`,
+      outcome.issueDetail,
       fix_hint(),
     );
+  }
+  if (outcome.noVerdict) {
     return {
-      rc: 3,
-      stderr: `${String(concern["name"])}: ${err.message}`,
+      rc: outcome.rc,
+      stderr: `${String(concern["name"])}: ${String(outcome.stderrNote)}\n${proc.stderr || ""}`,
       stdout: "",
       duration_ms: elapsed,
     };
   }
   return {
-    rc: proc.status ?? 0,
+    rc: outcome.rc,
     stderr: proc.stderr || "",
     stdout: proc.stdout || "",
     duration_ms: elapsed,
@@ -1317,14 +1313,18 @@ export function main(argv?: string[]): number {
     let rc = rawRcResult;
     const raw_rc = rc;
     if (rc >= 3) {
-      if (!concern["fail_closed"]) {
-        rc = EXIT_ALLOW; // fail-open
-      } else {
-        rc = EXIT_BLOCK;
-      }
+      // Resolved by DECLARED SEVERITY, no longer by `fail_closed:`. Every
+      // crash path has already written an `execution_failed` row, so a refusal
+      // here is traceable to a named failure. See `_resolve_execution_failure`.
+      rc = _resolve_execution_failure(concern, refusal_retry);
       if (stderr_text) {
         process.stderr.write(stderr_text);
       }
+      // The escape, printed only where a denial can repeat — `stop` is bounded
+      // by the one-retry clause above. Reasoning: `noVerdictRefusalNotice`.
+      if (rc === EXIT_BLOCK && !refusal_retry) {
+        process.stderr.write(noVerdictRefusalNotice(String(concern["name"])));
+      }
     }
     // P0.2 severity ceiling: an advisory concern can never block, on any host.
     // This covers BOTH the concern emitting EXIT_BLOCK directly and the

package/src/scripts/hooks/exit_codes.ts

@@ -114,7 +114,8 @@ export const EXIT_CODES: readonly ExitCodeRow[] = Object.freeze([
             '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 ' +
+            'hook_manifest.yaml `severity` alone — blocking refuses, anything else fails ' +
+            'open; `fail_closed` is no longer read on this branch. See ' +
             'docs/contracts/hook-architecture-v1.md § Exit-code semantics',
     }),
 ] as const);

package/src/scripts/hooks/host_lowering.json

@@ -1 +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":{}}}}}}}
+{"fingerprint":"08575a71d81fd8a5ef9e4b400f4a38cb66c26e1dd701d98f3cdc0bdc9e4758b4:22235","body_fingerprint":"26a02a8e0fb2b6be6eb1def6ae8792c021425598bd672c850e6582726d96a6a5:6376","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":{}}}}}}}

package/src/scripts/hooks/host_lowering.ts

@@ -251,7 +251,25 @@ export function resolveTable(yamlText: string, compiledText: string | null): Hos
             if (
                 raw['fingerprint'] === tableFingerprint(yamlText) &&
                 typeof table === 'object' &&
-                table !== null
+                table !== null &&
+                // road-to-blocking-severities 2.3 — the BODY, not only its
+                // label. `fingerprint` above says the file was compiled from
+                // the YAML as it stands; it says nothing about whether the
+                // body underneath was edited afterwards, and an edited body
+                // with an untouched label was served. `body_fingerprint` is
+                // the fingerprint of the exact bytes the compiler emitted, so
+                // re-stringifying what we just parsed recovers them.
+                //
+                // A compiled file WITHOUT the field — one written before 2.3 —
+                // falls through here, which is slow and correct: accepting it
+                // would make the check optional and therefore absent.
+                //
+                // What it covers is a partial edit, never an author: anyone
+                // who edits the body can recompute this as easily as the
+                // compiler. The deny in `block_plumbing_writes` and the
+                // ratification record are the mechanisms aimed at an author;
+                // this one is aimed at a mistake.
+                raw['body_fingerprint'] === tableFingerprint(JSON.stringify(table))
             ) {
                 return _structure(table as Record<string, unknown>);
             }

package/src/scripts/hooks/one_question_per_ask_hook.ts

@@ -14,33 +14,38 @@
  * names the count so the caller can split the ask instead of guessing what
  * happened.
  *
- * 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. 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.
+ * WHAT IT SEES, honestly. `_lib/structured_ask.ts` carries ONE observed
+ * per-host tool — `claude`'s `AskUserQuestion`, 48 calls across versions
+ * 2.1.252 to 2.1.284 between 2026-09-01 and 2026-10-02.
  *
- * 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".
+ * THIS GUARD DOES NOT USE THAT ROW, and the distinction matters enough to say
+ * rather than leave to a reader. `verdict()` calls `isStructuredAskTool(tool)`
+ * with no host id, so the shape branch is unreachable from here and the name
+ * SHAPE pattern decides on every host, `claude` included — filtered by the
+ * manifest's per-concern `tools:` key to the same candidate names. Threading a
+ * host id through would NARROW what this guard matches on the one host where a
+ * picker is known to exist (`ask_user_question` would stop matching), which is
+ * a behaviour change and not a header repair, so it is deliberately not made
+ * here.
  *
- * 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.
+ * This header carried the opposite claim until 2026-10-05 — that no host's
+ * delivered surface had been observed carrying a picker — and it was wrong in
+ * a specific, instructive way rather than merely stale. Its measurement base
+ * was one `false` row taken from a SUBAGENT leg, whose surface carries no
+ * picker because a subagent has no user to ask. The step from "this leg has
+ * none" to "no host has been observed with one" is the substitution the
+ * observation protocol exists to refuse, and the registry comment now records
+ * which leg each reading came from for that reason. The old wording is
+ * described 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 other eight hosts in `docs/enforcement-by-host.md` still have no row at
+ * all — never looked, not measured — so nothing here is a claim about them.
+ *
+ * WHAT THE OBSERVATION DOES NOT CHANGE: the deny threshold. One question per
+ * call is `ask-when-uncertain`'s Iron Law, not a host limit, and all 47
+ * parsed calls already carried exactly one. The guard has had nothing to deny
+ * and that is the expected reading, not evidence it is inert.
  *
  * 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
@@ -162,6 +167,17 @@ export function selfTest(): number {
             { tool_name: 'ask_user_question', tool_input: { question: 'which one?' } },
             false,
         ],
+        [
+            // PINS THE HEADER'S INVARIANT. `ask_user_question` is not the name
+            // claude's observed shape row carries, so this case denies only
+            // while `verdict()` passes no host id and the name-SHAPE pattern
+            // decides. Thread a host id through and the shape branch rejects
+            // the name, the call stops being an ask, and this flips to allow —
+            // which is the silent narrowing the header says is not being made.
+            'a snake_case picker with two questions is still denied — this guard is host-blind',
+            { tool_name: 'ask_user_question', tool_input: { questions: [{}, {}] } },
+            true,
+        ],
         [
             'an empty ask passes — malformed, but not this guard\'s failure',
             { tool_name: 'AskUserQuestion', tool_input: { questions: [] } },