@event4u/agent-config 14.10.0 → 14.12.0

package/src/scripts/hooks/rule_inject_hook.ts

@@ -0,0 +1,318 @@
+#!/usr/bin/env tsx
+/**
+ * Rule-inject — the delivery twin of `skill-route`, with the opposite payload
+ * policy (`road-to-trigger-delivered-rule-bodies` Phase 1).
+ *
+ * BODIES, NEVER POINTERS — and the difference from its twin is deliberate
+ * rather than incidental. `skill_route_hook.ts:14` ships "POINTERS, NEVER
+ * BODIES" on this same slot, and it is right to: a skill is a thing the agent
+ * *invokes*, so naming it is enough. A rule is a thing the agent must already
+ * be *under*, and the only datum anyone has on pointer-shaped rule delivery is
+ * the 36.2 %-against-48 % run at `docs/CLAIMS.md:188-189`. Whatever that
+ * instrument's flaws — and ADR-202 closed it — it points one way.
+ *
+ * DEFAULT OFF, AND OFF MEANS ZERO BYTES. The concern registers on two slots but
+ * returns before reading the router unless `lean_projection.mode: delivery` is
+ * set. Under every shipped default it emits nothing, costs no injection budget,
+ * and leaves the standing corpus exactly as it is today. That is why its
+ * `hook-token-budget.json` row is registered against the per-prompt cap rather
+ * than a measured emission: there is no measured emission to register yet.
+ *
+ * ONE MATCHER, SHARED WITH THE OFFLINE MODEL. Everything about selection,
+ * ordering, capping and body loading comes from `_lib/rule_injection.ts`, which
+ * `model_rule_injection.ts` also imports. Step 0.5 states the reason in as many
+ * words: an experiment whose offline pricing and runtime delivery use different
+ * matchers measures nothing.
+ *
+ * ONCE PER SESSION PER RULE, RE-ARMED ON COMPACTION. A rule's body is injected
+ * the first time one of its triggers fires and not again, because the model
+ * already has it. Compaction is exactly the event that makes that false, so
+ * `pre_compact` clears the seen-set — the same pin-lost shape `language-mirror`
+ * uses. State lives under `agents/runtime/state/`, the class
+ * `context-hygiene.json` already occupies; no new state convention is created.
+ *
+ * NEVER BLOCKS. Every failure path returns 0: unreadable stdin, malformed JSON,
+ * missing router, unreadable body, unwritable state. The one non-zero exit is
+ * the host's advisory context channel (exit 2 + `decision: "warn"`), the same
+ * channel `ui-route-nudge` and `code-graph-nudge` already use on `pre_tool_use`
+ * with `severity: advisory` — a warn there is an injection, not a deny.
+ *
+ * HOST BOUNDARY, STATED RATHER THAN IMPLIED. `user_prompt_submit` and
+ * `pre_tool_use` are bound on a subset of hosts, and only `claude` honours a
+ * deny at all. On a host where neither slot is bound this concern cannot run,
+ * which is the whole reason the flip step 2.4 gates on is Claude-only. Run
+ * `agent-config hooks:status` for the host you are actually on.
+ *
+ * SUBAGENTS ARE OUT OF REACH, MEASURED. Neither slot fires inside a spawned
+ * child session and the `subagent_start` payload carries no prompt field — see
+ * `agents/evidence/investigations/subagent-start-payload-probe.md` (2026-08-23,
+ * claude 2.1.241, three verdicts). Delivery is therefore orchestrator-only, and
+ * no third binding is added.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { hookSectionEnabled, leanProjectionModeRaw } from '../_lib/hook_settings.js';
+import { deliversBodies, normalizeLeanProjectionMode } from '../_lib/lean_projection_mode.js';
+import {
+    loadRuleBody,
+    loadRouter,
+    matchTierRules,
+    selectForInjection,
+} from '../_lib/rule_injection.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+
+/**
+ * Per-prompt injection ceiling, in UTF-8 BYTES.
+ *
+ * DERIVED, NOT PICKED: `model_rule_injection --corpus tests/eval/routing-matrix`
+ * measured the matched-body-token distribution over the frozen labelled corpus
+ * at p50 1,728 / p90 4,804 / p99 8,248 / max 12,957 exact-BPE tokens, and step
+ * 1.1 specifies "the p90 from 0.4, rounded to 500" — 4,804 rounds up to 5,000.
+ *
+ * BYTES rather than tokens, and the unit change is the point rather than a
+ * detail. `_lib/token_count.ts` resolves `js-tiktoken` at module load, so a
+ * token-capped concern drags a tokenizer into EVERY hook dispatch on every
+ * slot, for a concern that is default-OFF and emits nothing. Measured: 202 ms
+ * -> 196 ms on the `pre_tool_use` p95 when the concern is unbound entirely, and
+ * the CI latency gate went red on the branch that introduced it while passing
+ * on main. So the runtime cap is the same bound in the unit
+ * `hook-token-budget.json` already enforces — 5,000 tok at the ~4 bytes/token
+ * this corpus measures is 20,480 B, which is exactly this concern's registered
+ * row. Cap and budget row are now one number instead of two units.
+ *
+ * Re-run that command if the corpus or the bodies move; a cap copied from a
+ * stale measurement is worse than no cap, because it looks derived.
+ */
+export const CAP_BYTES = 20480;
+
+/** Tools whose input names a file this concern can match path triggers against. */
+export const FILE_TOOLS = new Set(['Write', 'Edit', 'NotebookEdit', 'Read', 'MultiEdit']);
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function str(o: JsonObject, ...keys: string[]): string | null {
+    for (const k of keys) {
+        const v = o[k];
+        if (typeof v === 'string' && v !== '') return v;
+    }
+    return null;
+}
+
+/** Workspace root the envelope points at, falling back to the process cwd. */
+export function workspaceRoot(env: JsonObject): string {
+    return str(env, 'workspace', 'cwd', 'project_dir') ?? process.cwd();
+}
+
+// ── seen-set state ───────────────────────────────────────────────────────
+
+export interface SeenState {
+    rules: string[];
+}
+
+export function statePath(root: string, session: string): string {
+    const safe = session.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 80) || 'unknown';
+    return path.join(root, 'agents', 'runtime', 'state', 'rule-inject', `${safe}.json`);
+}
+
+export function readSeen(root: string, session: string): Set<string> {
+    try {
+        const raw = fs.readFileSync(statePath(root, session), 'utf-8');
+        const parsed = JSON.parse(raw) as SeenState;
+        return new Set(Array.isArray(parsed.rules) ? parsed.rules.map(String) : []);
+    } catch {
+        return new Set(); // fresh session, or a file nothing can parse
+    }
+}
+
+export function writeSeen(root: string, session: string, seen: Set<string>): void {
+    const p = statePath(root, session);
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        const payload: SeenState = { rules: [...seen].sort() };
+        fs.writeFileSync(`${p}.tmp`, `${JSON.stringify(payload)}\n`, 'utf-8');
+        fs.renameSync(`${p}.tmp`, p);
+    } catch {
+        /* unwritable state must never fail a turn — worst case a re-injection */
+    }
+}
+
+export function clearSeen(root: string, session: string): void {
+    try {
+        fs.rmSync(statePath(root, session), { force: true });
+    } catch {
+        /* ignore */
+    }
+}
+
+// ── payload extraction ───────────────────────────────────────────────────
+
+/** The user's prompt, across the shapes the hosts use. */
+export function extractPrompt(payload: JsonObject): string {
+    return str(payload, 'prompt', 'user_prompt', 'userPrompt', 'message', 'text') ?? '';
+}
+
+/** The file path a file-touching tool call names, or `null`. */
+export function extractFilePath(payload: JsonObject): string | null {
+    const ti = payload['tool_input'] ?? payload['toolInput'] ?? payload['input'];
+    if (!isObject(ti)) return null;
+    return str(ti, 'file_path', 'path', 'filePath', 'notebook_path');
+}
+
+// ── decision ─────────────────────────────────────────────────────────────
+
+export interface Injection {
+    rules: string[];
+    bytes: number;
+    body: string;
+}
+
+/**
+ * Build the injection for one event, or `null` for silence.
+ *
+ * `prompt` drives keyword / phrase / command triggers; `openFiles` drives
+ * `path_prefix` / `file_pattern`. On the tool slot the prompt is deliberately
+ * empty, so a file event can only ever fire a path trigger — a tool call is not
+ * a restatement of the user's request and must not re-fire keyword rules.
+ */
+export function buildInjection(
+    root: string,
+    prompt: string,
+    openFiles: string[] | null,
+    command: string | null,
+    seen: Set<string>,
+): Injection | null {
+    let router;
+    try {
+        router = loadRouter(root);
+    } catch {
+        return null; // no router — nothing to deliver, and never a failure
+    }
+    const matches = matchTierRules(router, prompt, openFiles, command).filter(
+        (m) => !seen.has(m.id),
+    );
+    if (matches.length === 0) return null;
+    const sel = selectForInjection(root, matches, CAP_BYTES);
+    const parts: string[] = [];
+    const ids: string[] = [];
+    for (const m of sel.selected) {
+        const body = loadRuleBody(root, m.id);
+        if (body === null) continue;
+        ids.push(m.id);
+        parts.push(`<rule id="${m.id}" tier="${m.tier}">\n${body.trim()}\n</rule>`);
+    }
+    if (ids.length === 0) return null;
+    return { rules: ids, bytes: sel.bytes, body: parts.join('\n\n') };
+}
+
+// ── main ─────────────────────────────────────────────────────────────────
+
+/**
+ * Whether the settings gate applies.
+ *
+ * Through the dispatcher the gate is absolute: no `lean_projection.mode:
+ * delivery`, no bytes. A DIRECT CLI invocation is a probe by definition — an
+ * operator piping an envelope into this file is asking to see what it would
+ * deliver — so there the mode defaults to on. `AGENT_CONFIG_REPLAY` re-imposes
+ * the gate, which is what keeps `bench_hook_injection` measuring the shipped
+ * default (zero bytes) rather than the probe.
+ */
+export function gateOpen(root: string, cliEntry: boolean): boolean {
+    if (deliversBodies(normalizeLeanProjectionMode(leanProjectionModeRaw(root)))) return true;
+    if (hookSectionEnabled(root, 'rule_inject')) return true;
+    return cliEntry && process.env['AGENT_CONFIG_REPLAY'] !== '1';
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let eventOverride: string | null = null;
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--event') {
+            i += 1;
+            eventOverride = argv[i] ?? null;
+        }
+    }
+
+    let env: JsonObject = {};
+    try {
+        const raw = readHookStdin();
+        const parsed = raw.trim() ? (JSON.parse(raw) as unknown) : {};
+        env = isObject(parsed) ? parsed : {};
+    } catch {
+        return EXIT_ALLOW; // malformed envelope — never block
+    }
+
+    const root = workspaceRoot(env);
+    const payload = isObject(env['payload']) ? (env['payload'] as JsonObject) : env;
+    const slot = eventOverride ?? str(env, 'event') ?? 'user_prompt_submit';
+    const session = str(env, 'session_id', 'sessionId') ?? str(payload, 'session_id', 'sessionId') ?? 'unknown';
+
+    if (slot === 'pre_compact') {
+        clearSeen(root, session);
+        return EXIT_ALLOW; // re-arm is silent; the next turn re-injects
+    }
+    if (slot !== 'user_prompt_submit' && slot !== 'pre_tool_use') return EXIT_ALLOW;
+    if (!gateOpen(root, _isCliEntry())) return EXIT_ALLOW;
+
+    let prompt = '';
+    let openFiles: string[] | null = null;
+    let command: string | null = null;
+    if (slot === 'user_prompt_submit') {
+        prompt = extractPrompt(payload);
+        if (prompt === '') return EXIT_ALLOW;
+        const m = /^\s*(\/[A-Za-z0-9:_-]+)/.exec(prompt);
+        command = m ? (m[1] as string) : null;
+    } else {
+        const tool = str(payload, 'tool_name', 'toolName', 'tool');
+        if (tool === null || !FILE_TOOLS.has(tool)) return EXIT_ALLOW;
+        const fp = extractFilePath(payload);
+        if (fp === null) return EXIT_ALLOW;
+        openFiles = [fp];
+    }
+
+    const seen = readSeen(root, session);
+    const injection = buildInjection(root, prompt, openFiles, command, seen);
+    if (injection === null) return EXIT_ALLOW; // silence is the default
+
+    for (const id of injection.rules) seen.add(id);
+    writeSeen(root, session, seen);
+
+    process.stdout.write(
+        `${JSON.stringify({
+            decision: 'warn',
+            reason: `rule-inject: ${injection.rules.length} rule body/bodies on ${slot} (${injection.bytes} B)`,
+            additional_context: injection.body,
+        })}\n`,
+    );
+    return EXIT_WARN;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url`.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/hooks/suggestion_capture_hook.ts

@@ -0,0 +1,368 @@
+#!/usr/bin/env tsx
+/**
+ * Suggestion-block capture — a two-slot latch, counts only.
+ *
+ * ## What it measures and why it exists
+ *
+ * `command_suggester/render.ts` emits a numbered-options block with exactly one
+ * `Recommendation: N — …` line and the as-is option always last. Nothing records
+ * whether those blocks are ever *answered*, so no roadmap can cite a selection
+ * rate — and the model-carried alternative is measured and dead:
+ * `orchestration_record` captured 1 of 369 dispatches. This instrument exists so
+ * that figure is not repeated by construction.
+ *
+ * ## Two slots, not one — and the probe is why
+ *
+ * `road-to-suggestion-block-capture` planned a single `user_prompt_submit` hook
+ * reading the transcript tail. A live probe
+ * (`agents/evidence/analysis/suggestion-capture-probe.md`) found something
+ * cheaper: **`stop` carries `last_assistant_message` in the payload**, so the
+ * "was a block emitted" half needs no file read at all, and the turn-1 blind
+ * spot (`transcript_path` present but the file not yet written) does not arise.
+ *
+ *   stop                → detect the signature in `last_assistant_message`,
+ *                         write a latch keyed by `prompt_id`
+ *   user_prompt_submit  → CONSUME the latch, classify `prompt`, append one line
+ *
+ * ## The misclassification guard, which is the whole correctness argument
+ *
+ * A bare `1` three turns later must never read as a pick. So the latch is
+ * **consumed exactly once**: `user_prompt_submit` deletes it after reading, and
+ * a prompt arriving with no latch is `other`, never `option_n`. A latch older
+ * than `LATCH_TTL_MS` is `stale_block`. An unparseable latch is `stale_block`
+ * too — never a guess.
+ *
+ * ## Privacy is a property of the schema, not of a scrubber
+ *
+ * `src/config/suggestion-capture.json` registers five fields and **none can hold
+ * free text**: a timestamp, a boolean, an options COUNT, and two closed enums.
+ * `option_n` records THAT a numbered option was chosen and out of how many —
+ * deliberately not WHICH, because the block's option order is content and the
+ * capture-rate question does not need it. A type with no field able to carry a
+ * prompt cannot leak one; a scrubber can fail.
+ *
+ * Default-OFF (`hooks.suggestion_capture.enabled: true`). `fail_closed: false`,
+ * always exit 0: an instrument must never break a turn it is only observing.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { unwrap } from './envelope.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+const SETTINGS_FILE = '.agent-settings.yml';
+const SINK_REL = path.join('agents', 'runtime', 'state', 'audit', 'suggestion-capture.jsonl');
+const LATCH_REL = path.join('agents', 'runtime', 'state', 'suggestion-latch.json');
+/** A block older than this cannot be what the current prompt is answering. */
+export const LATCH_TTL_MS = 15 * 60 * 1000;
+
+export type Classification = 'option_n' | 'as_is' | 'other' | 'stale_block';
+export type EvidenceClass = 'render-signature' | 'latch-consumed' | 'latch-stale' | 'no-latch';
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+const isObject = (v: unknown): v is JsonObject =>
+    typeof v === 'object' && v !== null && !Array.isArray(v);
+
+const str = (v: JsonValue | undefined): string => (typeof v === 'string' ? v : '');
+
+/* ── the render signature ──────────────────────────────────────────────────── */
+
+/**
+ * Exactly one `Recommendation:`/`Empfehlung:` line, plus at least two numbered
+ * options. Both halves are required: a numbered list alone is ordinary prose,
+ * and a `Recommendation:` line alone is a sentence.
+ *
+ * The label is matched in both languages because `user-interaction`'s Iron Law 1
+ * makes a wrong-language label a rule violation, not a variant — so a German
+ * session's block carries `Empfehlung:` and a single-language matcher would
+ * under-count exactly the sessions the mirror rule produces.
+ */
+export function detectBlock(text: string): { emitted: boolean; optionsCount: number } {
+    if (text === '') return { emitted: false, optionsCount: 0 };
+    const lines = text.split('\n');
+    const recommendation = lines.filter((l) => /^\s*(?:\*\*)?(?:Recommendation|Empfehlung)\s*:/i.test(l)).length;
+    const numbered = new Set<string>();
+    for (const l of lines) {
+        const m = /^\s*(\d{1,2})[.)]\s+\S/.exec(l);
+        if (m?.[1] !== undefined) numbered.add(m[1]);
+    }
+    const emitted = recommendation === 1 && numbered.size >= 2;
+    return { emitted, optionsCount: emitted ? numbered.size : 0 };
+}
+
+/* ── classification ────────────────────────────────────────────────────────── */
+
+/**
+ * The as-is escape hatch, matched by intent rather than by an exact string:
+ * `command-suggestion-policy` requires it present and last but fixes no wording,
+ * so a literal matcher would silently classify every as-is pick as `other`.
+ */
+const AS_IS_RE = /\b(as[- ]is|as is|unver(?:ä|ae)ndert|so lassen|wie es ist|keep it|leave it|no change)\b/i;
+
+export function classify(prompt: string, optionsCount: number): Classification {
+    const t = prompt.trim();
+    if (t === '') return 'other';
+    if (AS_IS_RE.test(t)) return 'as_is';
+    // A bare number, or a number with trailing punctuation — the shape a pick
+    // actually takes. `1. do the thing` is NOT a pick: it is an instruction that
+    // happens to start with a digit, and counting it would inflate the rate.
+    const bare = /^(\d{1,2})\s*[.)]?\s*$/.exec(t);
+    if (bare?.[1] !== undefined) {
+        const n = Number(bare[1]);
+        // Out-of-range is `other`: a "7" against a 3-option block is answering
+        // something else, and recording it as a pick would corrupt the metric
+        // the whole instrument exists to produce.
+        if (n >= 1 && (optionsCount === 0 || n <= optionsCount)) return 'option_n';
+    }
+    return 'other';
+}
+
+/* ── settings, latch, sink ─────────────────────────────────────────────────── */
+
+/** `hooks.suggestion_capture.enabled: true` — the same mini-parse siblings use. */
+export function enabled(root: string): boolean {
+    let raw: string;
+    try {
+        raw = fs.readFileSync(path.join(root, SETTINGS_FILE), 'utf8');
+    } catch {
+        return false;
+    }
+    let inHooks = false;
+    let inSection = false;
+    for (const line of raw.split('\n')) {
+        if (/^hooks:\s*$/.test(line)) {
+            inHooks = true;
+            inSection = false;
+            continue;
+        }
+        if (/^\S/.test(line)) {
+            inHooks = false;
+            inSection = false;
+            continue;
+        }
+        if (!inHooks) continue;
+        if (/^\s{2}suggestion_capture:\s*$/.test(line)) {
+            inSection = true;
+            continue;
+        }
+        if (/^\s{2}\S/.test(line)) {
+            inSection = false;
+            continue;
+        }
+        if (inSection && /^\s{4}enabled:\s*true\s*$/.test(line)) return true;
+    }
+    return false;
+}
+
+export interface Latch {
+    readonly prompt_id: string;
+    readonly options_count: number;
+    readonly at: number;
+}
+
+export function writeLatch(root: string, latch: Latch): void {
+    const p = path.join(root, LATCH_REL);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, `${JSON.stringify(latch)}\n`, 'utf8');
+}
+
+/** Read AND delete. Consume-once is the misclassification guard, not a detail. */
+export function consumeLatch(root: string): Latch | null {
+    const p = path.join(root, LATCH_REL);
+    let raw: string;
+    try {
+        raw = fs.readFileSync(p, 'utf8');
+    } catch {
+        return null;
+    }
+    try {
+        fs.rmSync(p, { force: true });
+    } catch {
+        /* a latch we cannot delete is still consumed for this turn */
+    }
+    try {
+        const v = JSON.parse(raw) as unknown;
+        if (!isObject(v)) return null;
+        const at = v['at'];
+        const oc = v['options_count'];
+        const pid = v['prompt_id'];
+        if (typeof at !== 'number' || typeof oc !== 'number' || typeof pid !== 'string') return null;
+        return { prompt_id: pid, options_count: oc, at };
+    } catch {
+        return null; // unparseable → stale_block, never a guess
+    }
+}
+
+export interface Record_ {
+    readonly ts: string;
+    readonly block_emitted: boolean;
+    readonly options_count: number;
+    readonly evidence_class: EvidenceClass;
+    readonly turn_classification: Classification;
+}
+
+/** The exact key set `src/config/suggestion-capture.json` registers. */
+export const RECORD_KEYS: readonly string[] = [
+    'ts',
+    'block_emitted',
+    'options_count',
+    'evidence_class',
+    'turn_classification',
+];
+
+export function appendRecord(root: string, rec: Record_, now: Date): void {
+    const p = path.join(root, SINK_REL);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const line = {
+        ts: now.toISOString().replace(/\.\d{3}Z$/, 'Z'),
+        block_emitted: rec.block_emitted,
+        options_count: rec.options_count,
+        evidence_class: rec.evidence_class,
+        turn_classification: rec.turn_classification,
+    };
+    fs.appendFileSync(p, `${JSON.stringify(line)}\n`, 'utf8');
+}
+
+/* ── the two slots ─────────────────────────────────────────────────────────── */
+
+/** Decide what a prompt turn should record. Pure, so the tests drive it directly. */
+export function classifyTurn(
+    prompt: string,
+    latch: Latch | null,
+    nowMs: number,
+): { record: boolean; evidence_class: EvidenceClass; turn_classification: Classification; options_count: number } {
+    if (latch === null) {
+        // No block preceded this turn. Recording every ordinary turn would make
+        // the sink a prompt log with the volume of one, so nothing is written.
+        return { record: false, evidence_class: 'no-latch', turn_classification: 'other', options_count: 0 };
+    }
+    if (nowMs - latch.at > LATCH_TTL_MS) {
+        return {
+            record: true,
+            evidence_class: 'latch-stale',
+            turn_classification: 'stale_block',
+            options_count: latch.options_count,
+        };
+    }
+    return {
+        record: true,
+        evidence_class: 'latch-consumed',
+        turn_classification: classify(prompt, latch.options_count),
+        options_count: latch.options_count,
+    };
+}
+
+/**
+ * Canonical event name, from either invocation shape.
+ *
+ * The dispatcher supplies `envelope.event` (`stop`, `user_prompt_submit`); a
+ * direct/legacy invocation carries only the host's own `hook_event_name`
+ * (`Stop`, `UserPromptSubmit`). Reading just the second one is how the first
+ * version of this concern became a silent no-op under the dispatcher: it ran,
+ * matched nothing, and exited 0 — indistinguishable from a disabled hook.
+ */
+export function eventOf(envelope: JsonObject, payload: JsonObject): string {
+    const canonical = str(envelope['event'] as JsonValue | undefined);
+    const native = str(
+        (envelope['native_event'] ?? payload['hook_event_name']) as JsonValue | undefined,
+    );
+    const raw = (canonical !== '' ? canonical : native).toLowerCase();
+    if (raw === 'stop') return 'stop';
+    if (raw === 'userpromptsubmit' || raw === 'user_prompt_submit') return 'user_prompt_submit';
+    return raw;
+}
+
+/**
+ * The dispatcher calls every in-process concern as `main(argv)` — see
+ * `_run_concern_inproc` in `hooks/dispatch_hook.ts`, and the `ConcernMain`
+ * signature in `hooks/concern_registry.ts`.
+ *
+ * This used to be `main(now: Date = new Date())`, and the mismatch made the
+ * concern a SILENT NO-OP on every live dispatch: argv arrived where a Date was
+ * expected, `now.getTime()` threw `TypeError: now.getTime is not a function`,
+ * and the outer catch — "an instrument never breaks the turn it observes" —
+ * swallowed it and returned EXIT_ALLOW. The dispatcher recorded exit 0 and no
+ * output, which is indistinguishable from a disabled hook. Three earlier
+ * isolation attempts read that silence as a `--project-dir` problem; it was
+ * this.
+ *
+ * The clock stays injectable because the TTL and the timestamp need to be
+ * driven from a test, but it is now the SECOND parameter, where the dispatcher
+ * cannot land on it.
+ */
+export function main(_argv: readonly string[] = [], now: Date = new Date()): number {
+    let envelope: JsonObject;
+    let payload: JsonObject;
+    try {
+        [envelope, payload] = unwrap(readHookStdin(), 'claude');
+    } catch {
+        return EXIT_ALLOW;
+    }
+
+    // `workspace_root` is the dispatcher's; `cwd` is the host payload's. Both
+    // are read because the concern must work under either invocation.
+    const root =
+        str(envelope['workspace_root'] as JsonValue | undefined) ||
+        str(payload['cwd'] as JsonValue | undefined) ||
+        str(envelope['project_root'] as JsonValue | undefined) ||
+        '.';
+    if (!enabled(root)) return EXIT_ALLOW;
+
+    const event = eventOf(envelope, payload);
+    try {
+        if (event === 'stop') {
+            const { emitted, optionsCount } = detectBlock(
+                str(payload['last_assistant_message'] as JsonValue | undefined),
+            );
+            if (emitted) {
+                writeLatch(root, {
+                    prompt_id: str(payload['prompt_id'] as JsonValue | undefined),
+                    options_count: optionsCount,
+                    at: now.getTime(),
+                });
+            }
+            return EXIT_ALLOW;
+        }
+        if (event === 'user_prompt_submit') {
+            const latch = consumeLatch(root);
+            const v = classifyTurn(str(payload['prompt'] as JsonValue | undefined), latch, now.getTime());
+            if (v.record) {
+                appendRecord(
+                    root,
+                    {
+                        ts: '',
+                        block_emitted: true,
+                        options_count: v.options_count,
+                        evidence_class: v.evidence_class,
+                        turn_classification: v.turn_classification,
+                    },
+                    now,
+                );
+            }
+            return EXIT_ALLOW;
+        }
+    } catch {
+        return EXIT_ALLOW; // an instrument never breaks the turn it observes
+    }
+    return EXIT_ALLOW;
+}
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (isCliEntry()) process.exit(main());
+
+export { SINK_REL, LATCH_REL };