@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/hooks/code_graph_context_hook.ts

@@ -31,19 +31,23 @@
  * "per-host `enforced_by` resolved from the table, not from a host name" means
  * in practice.
  *
- * Once per session (a latch keyed by session id), so it cannot nag.
+ * Once per distinct SEARCH TARGET, capped at five lines per session (step 2.2),
+ * so it cannot nag. It was once-per-session until step 2.1 added `Bash`: with
+ * shell searches in scope a single line covered the first `grep` of a session
+ * and nothing after it, which is the opposite of the problem — the state that
+ * matters is the state at the question being asked.
  * fail_closed: false — every error path returns allow; a context line must
  * never break a tool call.
  */
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { type GraphState, graphState } from '../code_graph/detect.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 CODE_EXT = /\.(php|ts|tsx|mts|cts|js|jsx|mjs|cjs)$/i;
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
@@ -56,13 +60,127 @@ function isObject(v: unknown): v is JsonObject {
 interface ToolIntent {
     isSearch: boolean;
     isCodeRead: boolean;
+    /**
+     * What this call is ABOUT — a Grep/Glob pattern, a read path, or the search
+     * term of a shell search. The per-target latch key (step 2.2): the same
+     * question asked twice is one question, and a hook that answered it once
+     * has nothing to add the second time.
+     *
+     * Empty when the call is neither a search nor a code read, and never the
+     * raw command line of an arbitrary Bash call — see {@link bashSearchToken}.
+     */
+    target: string;
+}
+
+/**
+ * The shell search heads this hook recognises.
+ *
+ * A closed list on purpose. "Any Bash command might be a search" is the reading
+ * that makes the hook chatty — Risk-Register rank 2 — so a command whose head
+ * is not here is silent AND does not latch, exactly as a non-code `Read` is.
+ */
+const SEARCH_HEADS = new Set(['grep', 'rg', 'ag', 'find', 'ack', 'fd']);
+
+/**
+ * Short options that consume the NEXT word as their value.
+ *
+ * Without this the value is read as the search term: a completion review of
+ * step 2.1 measured `grep -A 5 foo` keying the latch on `"5"` and
+ * `rg -g *.ts alpha` keying on `"*.ts"` — which also silenced a second,
+ * genuinely different search behind the same glob. A latch keyed on an option's
+ * argument is worse than no latch: it collapses distinct questions onto one slot.
+ */
+const VALUE_TAKING = new Set([
+    '-A', '-B', '-C', '-m', '-e', '-f', '-g', '-t', '-T', '-d', '--include',
+    '--exclude', '--glob', '--max-count', '--after-context', '--before-context',
+    '--context', '--regexp', '--file', '--type', '--maxdepth', '--depth',
+]);
+
+/** Asking a tool for its own usage is not a search, and must not spend a slot. */
+const NOT_A_SEARCH = new Set(['--help', '-h', '--version', '-V', '--usage']);
+
+/** `find` carries its subject in `-name`, not in the first positional. */
+const FIND_SUBJECT = new Set(['-name', '-iname', '-path', '-ipath', '-regex']);
+
+/**
+ * The search term inside ONE pipeline segment, or `null`.
+ *
+ * Split out from {@link bashSearchToken} so a pipeline can be scanned segment
+ * by segment: `cat x | grep needle` is a search, and reading only the head of
+ * the whole command missed every one of them. The same review measured that.
+ */
+function segmentSearchToken(words: readonly string[]): string | null {
+    if (words.length === 0) return null;
+    let i = 0;
+    let head = (words[0] as string).split('/').pop() as string;
+    if (head === 'git') {
+        // `git -C <path> grep <term>` is the form this tree's own token-efficiency
+        // rule mandates, and a `words[1] === 'grep'` test missed all of it. Scan
+        // past git's own options to the subcommand.
+        let j = 1;
+        while (j < words.length && (words[j] as string).startsWith('-')) {
+            j += VALUE_TAKING.has(words[j] as string) || words[j] === '-C' ? 2 : 1;
+        }
+        if (words[j] !== 'grep') return null;
+        head = 'git grep';
+        i = j + 1;
+    } else if (SEARCH_HEADS.has(head)) {
+        i = 1;
+    } else {
+        return null;
+    }
+    const rest = words.slice(i);
+    if (rest.some((w) => NOT_A_SEARCH.has(w))) return null;
+    if (head === 'find') {
+        const at = rest.findIndex((w) => FIND_SUBJECT.has(w));
+        if (at !== -1 && at + 1 < rest.length) return strip(rest[at + 1] as string);
+    }
+    for (let k = 0; k < rest.length; k += 1) {
+        const w = rest[k] as string;
+        if (w.startsWith('-')) {
+            if (VALUE_TAKING.has(w)) k += 1; // its value is not the subject
+            continue;
+        }
+        return strip(w);
+    }
+    return head;
+}
+
+function strip(w: string): string {
+    return w.replace(/^["']|["']$/g, '');
+}
+
+/**
+ * The thing a shell search is searching FOR, or `null` when the command is not
+ * a structure search at all.
+ *
+ * Reads EVERY pipeline segment, not just the first: `cat x | grep needle` and
+ * `… | rg symbol` are searches, and they are the common shape. The first
+ * segment that is a search wins, so one line yields one latch key.
+ *
+ * `git grep` is the one two-word head and is resolved past git's own options.
+ * Failing a positional subject the key is the command's head, which collapses a
+ * flag-only search onto one slot rather than leaking a command line into a
+ * state file — and the key is stored as a digest in any case
+ * ({@link latchKey}).
+ */
+export function bashSearchToken(command: string): string | null {
+    for (const segment of command.split(/\||&&|;/)) {
+        const words = segment.trim().split(/\s+/).filter((w) => w !== '');
+        const hit = segmentSearchToken(words);
+        if (hit !== null) return hit;
+    }
+    return null;
 }
 
 /**
  * Best-effort read of the intercepted tool + its target from the envelope.
  *
- * Carried over from the nudge unchanged, and the manifest's `tools:` filter is
- * pinned against exactly this branch surface — Grep, Glob, Read.
+ * The manifest's `tools:` filter is pinned against exactly this branch surface
+ * — Grep, Glob, Read, Bash. `Bash` joined it in step 2.1 for the reason the
+ * step gives: the searches an agent actually runs in this tree are shell
+ * searches, so a matcher that saw only the structured search tools was watching
+ * the door nobody uses.
  */
 export function classifyTool(envelope: JsonObject): ToolIntent {
     const payload = isObject(envelope['payload']) ? envelope['payload'] : envelope;
@@ -72,13 +190,29 @@ export function classifyTool(envelope: JsonObject): ToolIntent {
     const ti = (isObject(payload['tool_input']) ? payload['tool_input'] : envelope['tool_input']) as
         | JsonObject
         | undefined;
-    const isSearch = name === 'Grep' || name === 'Glob';
-    let isCodeRead = false;
+    const silent: ToolIntent = { isSearch: false, isCodeRead: false, target: '' };
+
+    if (name === 'Grep' || name === 'Glob') {
+        const pat = isObject(ti) ? (ti['pattern'] ?? ti['query']) : undefined;
+        return { isSearch: true, isCodeRead: false, target: typeof pat === 'string' ? pat : name };
+    }
     if (name === 'Read' && isObject(ti)) {
         const fp = ti['file_path'] ?? ti['path'];
-        if (typeof fp === 'string') isCodeRead = CODE_EXT.test(fp);
+        if (typeof fp === 'string' && CODE_EXT.test(fp)) {
+            return { isSearch: false, isCodeRead: true, target: fp };
+        }
+        return silent;
+    }
+    if (name === 'Bash' && isObject(ti)) {
+        const cmd = ti['command'];
+        if (typeof cmd !== 'string') return silent;
+        const token = bashSearchToken(cmd);
+        // Any other Bash command is silent AND does not latch: it consumed no
+        // slot, so the next real search still gets its line.
+        if (token === null) return silent;
+        return { isSearch: true, isCodeRead: false, target: token };
     }
-    return { isSearch, isCodeRead };
+    return silent;
 }
 
 function sessionId(envelope: JsonObject): string {
@@ -89,33 +223,117 @@ function sessionId(envelope: JsonObject): string {
 function latchFile(root: string): string {
     return path.join(root, 'agents', 'runtime', 'state', 'code-graph-context.json');
 }
-function alreadySpoke(root: string, session: string): boolean {
+
+/**
+ * At most this many context lines in one session (step 2.2).
+ *
+ * The cap is the chattiness bound, and it is the half that does not depend on
+ * the agent's behaviour: per-target alone is unbounded, because a session that
+ * greps thirty distinct symbols would hear thirty lines and the consumer would
+ * turn the hook off. Five is a stated default, not a measurement — a session
+ * that has been told the graph's state five times has been told.
+ */
+export const MAX_CONTEXT_LINES_PER_SESSION = 5;
+
+/** How many sessions the latch file retains before evicting the oldest. */
+export const MAX_SESSIONS_LATCHED = 200;
+
+/**
+ * What the latch file records for a target: a truncated digest, never the
+ * target itself.
+ *
+ * A council review of step 2.1 (2026-10-01, anthropic + openai) asked for one
+ * concrete thing before the shell tool was routed here — that command text is
+ * neither persisted nor carried into diagnostics. Routing on the shell tool
+ * makes the target a search TERM an operator typed, and a term can be a
+ * customer name, a token fragment or an internal hostname. Nothing downstream
+ * needs to read it back: the latch answers "have I spoken about this one", and
+ * equality over a digest answers that exactly as well.
+ *
+ * Not a security boundary and not claimed as one — a short digest of a short
+ * term is guessable by anyone who can enumerate terms. It is the same
+ * PII-exclusion-by-construction move `domain-safety-pii` § Surface 2 asks for:
+ * the file is shaped so the plaintext is not in it to leak.
+ */
+export function latchKey(target: string): string {
+    return createHash('sha256').update(target).digest('hex').slice(0, 16);
+}
+
+/**
+ * Should this target get a line, given what this session already heard?
+ *
+ * Pure, so the two rules it encodes can be tested without a filesystem: a
+ * repeat is silent at any count, and a NEW target is silent once the cap is
+ * reached. Takes the target in the clear and hashes here, so no caller can
+ * forget to.
+ */
+export function speaksFor(spoken: readonly string[], target: string): boolean {
+    if (spoken.includes(latchKey(target))) return false;
+    return spoken.length < MAX_CONTEXT_LINES_PER_SESSION;
+}
+
+function readLatch(root: string): Record<string, string[]> {
     try {
-        const state = JSON.parse(fs.readFileSync(latchFile(root), 'utf-8')) as Record<string, boolean>;
-        return state[session] === true;
+        const raw = JSON.parse(fs.readFileSync(latchFile(root), 'utf-8')) as Record<string, unknown>;
+        const out: Record<string, string[]> = {};
+        for (const [k, v] of Object.entries(raw)) {
+            // A pre-2.2 file stored `true` per session. Read it as "this session
+            // is done", which is what it meant — never as an empty list, which
+            // would hand an upgraded session a fresh budget it already spent.
+            if (Array.isArray(v)) out[k] = v.filter((x): x is string => typeof x === 'string');
+            else if (v === true) out[k] = Array.from({ length: MAX_CONTEXT_LINES_PER_SESSION }, (_, i) => `legacy:${String(i)}`);
+        }
+        return out;
     } catch {
-        return false;
+        return {};
     }
 }
-function latch(root: string, session: string): void {
+
+/**
+ * The cheap read-only half, so the `git status` probe behind `graphState` runs
+ * only for a call that could still produce a line (Risk-Register rank 3).
+ *
+ * Advisory only — {@link latchTarget} re-reads and remains the authority. A
+ * disagreement between the two can only come from a concurrent write, and it
+ * resolves toward silence, which is the safe direction for a context line.
+ */
+export function wouldSpeak(root: string, session: string, target: string): boolean {
+    return speaksFor(readLatch(root)[session] ?? [], target);
+}
+
+/**
+ * Decide and record in one step, because the two must not drift apart: a reader
+ * that says yes and a writer that records something else is how a cap leaks.
+ * Returns whether the caller may speak.
+ */
+export function latchTarget(root: string, session: string, target: string): boolean {
+    const state = readLatch(root);
+    const spoken = state[session] ?? [];
+    if (!speaksFor(spoken, target)) return false;
     try {
-        const p = latchFile(root);
-        let state: Record<string, boolean> = {};
-        try {
-            state = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, boolean>;
-        } catch {
-            /* fresh */
+        state[session] = [...spoken, latchKey(target)];
+        // Nothing prunes a finished session, so without this the file
+        // accumulated up to five digests per session id for the life of the
+        // repository — a review's finding, and the sibling instrument added in
+        // the same change caps itself and says why local-and-gitignored is not
+        // the same as free. Insertion order is the eviction order: the oldest
+        // session is the one least likely to speak again, and re-latching a
+        // dropped session costs one extra line, never a wrong answer.
+        const ids = Object.keys(state);
+        for (const old of ids.slice(0, Math.max(0, ids.length - MAX_SESSIONS_LATCHED))) {
+            if (old !== session) delete state[old];
         }
-        state[session] = true;
+        const p = latchFile(root);
         fs.mkdirSync(path.dirname(p), { recursive: true });
         fs.writeFileSync(p, JSON.stringify(state));
     } catch {
         /* fail-open: a persistence failure must not break the tool call */
     }
+    return true;
 }
 
 /**
- * The three-state staleness token this hook reports.
+ * The four-state staleness token this hook reports.
  *
  * Re-exported, not defined here: Phase 3's verbs must print the same token, and
  * an engine module importing this hook to learn it would invert the dependency
@@ -140,6 +358,13 @@ export function contextLine(state: GraphState): string {
             'grep is the other path — say which one answered.'
         );
     }
+    if (state === 'edited') {
+        return (
+            'code-graph: level with HEAD, but indexed files are edited in the working tree. ' +
+            'Relationship answers miss anything written since the last build — ' +
+            '`agent-config code-graph refresh` picks the edits up, or use grep and say so.'
+        );
+    }
     const n = state.slice('behind:'.length);
     return (
         `code-graph: ${n} commit(s) behind. Relationship answers may miss anything newer — ` +
@@ -161,11 +386,14 @@ export function main(): number {
     const pr = envelope['workspace_root'] ?? envelope['project_root'];
     const root = typeof cwd === 'string' && cwd ? cwd : typeof pr === 'string' && pr ? pr : '.';
 
-    const { isSearch, isCodeRead } = classifyTool(envelope);
+    const { isSearch, isCodeRead, target } = classifyTool(envelope);
     if (!isSearch && !isCodeRead) return EXIT_ALLOW;
 
     const session = sessionId(envelope);
-    if (alreadySpoke(root, session)) return EXIT_ALLOW; // once per session
+    // Once per distinct target, at most five per session (2.2). Checked BEFORE
+    // `graphState`, because that call now runs a `git status` probe and a line
+    // this session will not emit must not pay for one.
+    if (!wouldSpeak(root, session, target)) return EXIT_ALLOW;
 
     let state: GraphState;
     try {
@@ -177,7 +405,7 @@ export function main(): number {
     // so a session that builds a graph mid-flight still gets the line once.
     if (state === 'absent') return EXIT_ALLOW;
 
-    latch(root, session);
+    if (!latchTarget(root, session, target)) return EXIT_ALLOW;
     process.stdout.write(`${JSON.stringify({ decision: 'warn', reason: contextLine(state) })}\n`);
     return EXIT_WARN;
 }

package/src/scripts/hooks/comment_discipline_hook.ts

@@ -47,9 +47,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { isScannable, scanText, type CommentFinding } from '../lint_code_comments.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
-
-const EXIT_ALLOW = 0;
-const EXIT_WARN = 2;
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
 /** Findings named in the advisory line. The rest are counted, never listed. */
 export const MAX_REPORTED = 3;

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/concern_registry.ts

@@ -52,6 +52,7 @@ import { main as gitAuthorizationMain } from '../git_authorization_hook.js';
 import { main as evidenceIndependenceMain } from './evidence_independence.js';
 import { main as blockNoVerifyMain } from './block_no_verify.js';
 import { main as blockKernelRuleWritesMain } from './block_kernel_rule_writes.js';
+import { main as blockPlumbingWritesMain } from './block_plumbing_writes.js';
 import { main as blockConfigWeakeningMain } from './block_config_weakening.js';
 import { main as blockSpeakingInboxDirMain } from './block_speaking_inbox_dir.js';
 import { main as oneQuestionPerAskMain } from './one_question_per_ask_hook.js';
@@ -118,6 +119,7 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/evidence_independence.ts': evidenceIndependenceMain as ConcernMain,
     'src/scripts/hooks/block_no_verify.ts': blockNoVerifyMain as ConcernMain,
     'src/scripts/hooks/block_kernel_rule_writes.ts': blockKernelRuleWritesMain as ConcernMain,
+    'src/scripts/hooks/block_plumbing_writes.ts': blockPlumbingWritesMain as ConcernMain,
     'src/scripts/hooks/block_config_weakening.ts': blockConfigWeakeningMain as ConcernMain,
     'src/scripts/hooks/block_speaking_inbox_dir.ts': blockSpeakingInboxDirMain as ConcernMain,
     'src/scripts/hooks/one_question_per_ask_hook.ts': oneQuestionPerAskMain as ConcernMain,