@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/hooks/exit_codes.ts

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

package/src/scripts/hooks/host_lowering.json

@@ -0,0 +1 @@
+{"fingerprint":"08575a71d81fd8a5ef9e4b400f4a38cb66c26e1dd701d98f3cdc0bdc9e4758b4:22235","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

@@ -21,6 +21,8 @@ import { fileURLToPath } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { tableFingerprint } from './table_fingerprint.js';
+
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 const _IN_BUNDLE = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
 const _REPO_ROOT = path.resolve(
@@ -30,10 +32,59 @@ const _REPO_ROOT = path.resolve(
 
 export const HOST_LOWERING_PATH = path.join(_REPO_ROOT, 'src', 'scripts', 'hooks', 'host_lowering.yaml');
 
+/**
+ * Compiled sibling of the table above — the same data with comments stripped.
+ *
+ * WHY IT EXISTS, measured rather than assumed. The dispatcher consults this
+ * table on EVERY dispatch (`emitFor` needs `blockExitFor`), and since
+ * `hook_manifest.json` landed it is the ONLY remaining YAML reader on that
+ * path — so it pays both its own parse and the cold load of the `yaml` module
+ * nothing else pulls in any more. Measured on one developer machine: the
+ * 16.8 kB source parses in 3.1-7.0 ms and the `yaml` module costs a further
+ * 8.1 ms to load, against `JSON.parse` of the 5.9 kB compiled form at 0.03 ms.
+ *
+ * Exactly the shape `compile_hook_manifest` already established for the
+ * manifest, including the content fingerprint — see `table_fingerprint` for
+ * why freshness is decided by content and never by mtime.
+ */
+export const HOST_LOWERING_JSON_PATH = path.join(_REPO_ROOT, 'src', 'scripts', 'hooks', 'host_lowering.json');
+
 /** Provenance of a row. Every field may be null; `expires` may not. */
 export interface VerifiedBlock {
     docs_at: string | null;
     docs_url: string | null;
+    /**
+     * sha256 of the `docs_url` body as last ESTABLISHED for this row.
+     *
+     * "Established" means recorded by a human-run fill, not merely seen. The
+     * watcher re-hashes the page on every run and writes the new value only
+     * when the field was empty; on a DRIFT it deliberately leaves the recorded
+     * digest alone, so the field keeps pointing at the body someone actually
+     * read while `expires` carries the alarm.
+     *
+     * Three earlier wordings were wrong and all three are named rather than
+     * quietly replaced, because each was corrected by evidence the next one
+     * then contradicted. "As fetched on `docs_at`" was refuted by the very
+     * first fill (digests taken 2026-10-01 against rows whose `docs_at` is
+     * 2026-09-29). "As fetched by the LAST digest run" was refuted by the
+     * writer (after a drift the last run computed a different hash than the
+     * field holds). "`docs_at` + `docs_digest` are ONE pair" was refuted by
+     * the same committed data as the first — stating it was a relapse, caught
+     * in review.
+     *
+     * The two fields are simply INDEPENDENT. `docs_at` dates a human reading
+     * the page for the row's ANSWERS; `docs_digest` names the body the watcher
+     * compares against. Nothing guarantees they were the same fetch, and no
+     * wording that implies they were can survive this table's own rows.
+     *
+     * Null where there is nothing to hash — a row whose `docs_url` is null —
+     * and null is also the pre-fill state `check_host_docs_digest --fetch
+     * --write` resolves. It is deliberately NOT part of the expiry test: a
+     * digest is evidence about the page, `expires` is this package's review-by
+     * date, and collapsing the two would make a vendor's CSS rebuild look like
+     * a lapsed citation.
+     */
+    docs_digest: string | null;
     probe_at: string | null;
     host_version: string | null;
     expires: string;
@@ -44,6 +95,21 @@ export interface SlotRow {
     native: string[];
     /** Exit code the host honours as a refusal here, or null if unestablished. */
     block_exit: number | null;
+    /**
+     * The date this pair was last answered, or null when it never was.
+     *
+     * `block_exit: null` alone cannot distinguish "looked, found none" from
+     * "nobody looked", and the whole point of this table is that a zero is a
+     * fact with a date on it. `lint_hook_manifest` requires the date; the
+     * parser keeps it nullable so a malformed table still parses into
+     * something the linter can report on rather than throwing first.
+     */
+    answered_at: string | null;
+    /**
+     * Citation for this pair, when it differs from the row's
+     * `verified.docs_url`. Absent means the row's URL is the citation.
+     */
+    docs_url: string | null;
     /** Entry-shape-specific extra (gemini's per-binding matcher). */
     matcher?: string;
 }
@@ -72,7 +138,18 @@ function _asString(v: unknown): string | null {
 }
 
 function _parse(text: string): HostLowering {
-    const raw = parseYaml(text) as Record<string, unknown> | null;
+    return _structure(parseYaml(text) as Record<string, unknown> | null);
+}
+
+/**
+ * Build the table from an ALREADY-PARSED document.
+ *
+ * Split out of `_parse` so the compiled-JSON fast path below reaches exactly
+ * the same validation on exactly the same shape — the YAML step is the only
+ * thing it skips. A second structuring function would be a second thing to
+ * drift; there is one, and both paths call it.
+ */
+function _structure(raw: Record<string, unknown> | null): HostLowering {
     const hostsRaw = raw?.['hosts'];
     if (typeof hostsRaw !== 'object' || hostsRaw === null) {
         throw new Error('host_lowering.yaml: missing `hosts:` map');
@@ -96,6 +173,7 @@ function _parse(text: string): HostLowering {
                 verified = {
                     docs_at: _asString(verifiedRaw['docs_at']),
                     docs_url: _asString(verifiedRaw['docs_url']),
+                    docs_digest: _asString(verifiedRaw['docs_digest']),
                     probe_at: _asString(verifiedRaw['probe_at']),
                     host_version: _asString(verifiedRaw['host_version']),
                     expires,
@@ -110,6 +188,8 @@ function _parse(text: string): HostLowering {
                 const row: SlotRow = {
                     native,
                     block_exit: typeof be === 'number' ? be : null,
+                    answered_at: _asString(rv['answered_at']),
+                    docs_url: _asString(rv['docs_url']),
                 };
                 if (typeof rv['matcher'] === 'string') row.matcher = rv['matcher'];
                 slots.set(slot, row);
@@ -131,12 +211,75 @@ function _parse(text: string): HostLowering {
 
 let _cache: HostLowering | null = null;
 
-/** Parse the table once per process. Throws on a missing or malformed file. */
+/**
+ * Parse the table once per process. Throws on a missing or malformed file.
+ *
+ * Tries the compiled sibling first and falls through to the YAML source on
+ * anything unexpected — missing, unreadable, malformed, or a fingerprint that
+ * does not match the live source. A stale or absent compiled file is therefore
+ * SLOW and never WRONG, which is the property that lets the optimisation ship
+ * without a second correctness argument.
+ */
 export function loadHostLowering(): HostLowering {
-    if (_cache === null) _cache = _parse(fs.readFileSync(HOST_LOWERING_PATH, 'utf-8'));
+    if (_cache !== null) return _cache;
+    // Reading the YAML unconditionally costs ~0.03 ms — it is the PARSE that is
+    // expensive — so the fast path still skips the whole 11-15 ms.
+    const text = fs.readFileSync(HOST_LOWERING_PATH, 'utf-8');
+    let compiled: string | null;
+    try {
+        compiled = fs.readFileSync(HOST_LOWERING_JSON_PATH, 'utf-8');
+    } catch {
+        compiled = null;
+    }
+    _cache = resolveTable(text, compiled);
     return _cache;
 }
 
+/**
+ * Pick the path and build the table — the whole decision, with no I/O.
+ *
+ * Split from `loadHostLowering` so the FALLBACK semantics are testable. They
+ * are the half that carries the risk: the fast path is easy to verify and a
+ * mis-shaped fallback would be a wrong table rather than a slow one. A test
+ * that could only reach the happy path would be watching the safe half.
+ */
+export function resolveTable(yamlText: string, compiledText: string | null): HostLowering {
+    if (compiledText !== null) {
+        try {
+            const raw = JSON.parse(compiledText) as Record<string, unknown>;
+            const table = raw['table'];
+            if (
+                raw['fingerprint'] === tableFingerprint(yamlText) &&
+                typeof table === 'object' &&
+                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>);
+            }
+        } catch {
+            // Malformed JSON → the source below. Never fail on the optimisation.
+        }
+    }
+    return _parse(yamlText);
+}
+
 /** Test seam — drop the memoized table so a fixture can be loaded instead. */
 export function _resetHostLoweringCache(table?: HostLowering): void {
     _cache = table ?? null;