@event4u/agent-config 14.17.0 → 14.19.0

package/src/scripts/hooks/host_lowering.ts

@@ -0,0 +1,215 @@
+/**
+ * host_lowering — the reader for `host_lowering.yaml`.
+ *
+ * The table is the single place a host's block-exit, emission shape, fail
+ * policy and bridge bindings are written. Before it, those five facts lived in
+ * `host_semantics.ts`, in five private per-host binding constants in
+ * `install.ts`, and in prose; three rounds of prose corrections did not stop
+ * the drift, because prose has no single reader.
+ *
+ * LOADING IS STRICT. A missing or malformed table throws rather than
+ * degrading to an empty one. An empty table would resolve `VERIFIED_PLATFORMS`
+ * to the empty set, which silently downgrades the one host that actually
+ * enforces from blocking to advisory — the exact failure this roadmap's risk
+ * register ranks first. A throw is loud; a silent downgrade is not. The
+ * dispatcher already reads `hook_manifest.yaml` unconditionally from the same
+ * tree, so this adds no new class of failure.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parse as parseYaml } from 'yaml';
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+const _IN_BUNDLE = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+const _REPO_ROOT = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    ...(_IN_BUNDLE ? ['..', '..'] : ['..', '..', '..']),
+);
+
+export const HOST_LOWERING_PATH = path.join(_REPO_ROOT, 'src', 'scripts', 'hooks', 'host_lowering.yaml');
+
+/** Provenance of a row. Every field may be null; `expires` may not. */
+export interface VerifiedBlock {
+    docs_at: string | null;
+    docs_url: string | null;
+    probe_at: string | null;
+    host_version: string | null;
+    expires: string;
+}
+
+export interface SlotRow {
+    /** Host-native event name(s) for this slot, in emission order. */
+    native: string[];
+    /** Exit code the host honours as a refusal here, or null if unestablished. */
+    block_exit: number | null;
+    /** Entry-shape-specific extra (gemini's per-binding matcher). */
+    matcher?: string;
+}
+
+export interface SurfaceRow {
+    entry_shape: string;
+    json_shape: string;
+    fail_policy: string;
+    timeout_unit: string;
+    timeout_default: number | null;
+    verified: VerifiedBlock | null;
+    /** Insertion-ordered: bridge entries are written in this order. */
+    slots: Map<string, SlotRow>;
+}
+
+export type HostLowering = Map<string, Map<string, SurfaceRow>>;
+
+/** The surface every row carries today — see the table header. */
+export const DEFAULT_SURFACE = 'any';
+
+function _asString(v: unknown): string | null {
+    if (v === null || v === undefined) return null;
+    // A bare `2027-09-06` parses as a Date under YAML 1.1 timestamp rules.
+    if (v instanceof Date) return v.toISOString().slice(0, 10);
+    return String(v);
+}
+
+function _parse(text: string): HostLowering {
+    const raw = parseYaml(text) as Record<string, unknown> | null;
+    const hostsRaw = raw?.['hosts'];
+    if (typeof hostsRaw !== 'object' || hostsRaw === null) {
+        throw new Error('host_lowering.yaml: missing `hosts:` map');
+    }
+    const out: HostLowering = new Map();
+    for (const [host, hv] of Object.entries(hostsRaw as Record<string, unknown>)) {
+        const surfacesRaw = (hv as Record<string, unknown> | null)?.['surfaces'];
+        if (typeof surfacesRaw !== 'object' || surfacesRaw === null) {
+            throw new Error(`host_lowering.yaml: ${host} has no \`surfaces:\` map`);
+        }
+        const surfaces = new Map<string, SurfaceRow>();
+        for (const [surface, sv] of Object.entries(surfacesRaw as Record<string, unknown>)) {
+            const s = sv as Record<string, unknown>;
+            const verifiedRaw = s['verified'] as Record<string, unknown> | null | undefined;
+            let verified: VerifiedBlock | null = null;
+            if (verifiedRaw) {
+                const expires = _asString(verifiedRaw['expires']);
+                if (!expires) {
+                    throw new Error(`host_lowering.yaml: ${host}/${surface} verified block has no \`expires\``);
+                }
+                verified = {
+                    docs_at: _asString(verifiedRaw['docs_at']),
+                    docs_url: _asString(verifiedRaw['docs_url']),
+                    probe_at: _asString(verifiedRaw['probe_at']),
+                    host_version: _asString(verifiedRaw['host_version']),
+                    expires,
+                };
+            }
+            const slots = new Map<string, SlotRow>();
+            for (const [slot, rvRaw] of Object.entries((s['slots'] ?? {}) as Record<string, unknown>)) {
+                const rv = rvRaw as Record<string, unknown>;
+                const nativeRaw = rv['native'];
+                const native = Array.isArray(nativeRaw) ? nativeRaw.map(String) : [String(nativeRaw)];
+                const be = rv['block_exit'];
+                const row: SlotRow = {
+                    native,
+                    block_exit: typeof be === 'number' ? be : null,
+                };
+                if (typeof rv['matcher'] === 'string') row.matcher = rv['matcher'];
+                slots.set(slot, row);
+            }
+            surfaces.set(surface, {
+                entry_shape: String(s['entry_shape'] ?? 'none'),
+                json_shape: String(s['json_shape'] ?? 'none'),
+                fail_policy: String(s['fail_policy'] ?? 'discard'),
+                timeout_unit: String(s['timeout_unit'] ?? 'unknown'),
+                timeout_default: typeof s['timeout_default'] === 'number' ? s['timeout_default'] : null,
+                verified,
+                slots,
+            });
+        }
+        out.set(host, surfaces);
+    }
+    return out;
+}
+
+let _cache: HostLowering | null = null;
+
+/** Parse the table once per process. Throws on a missing or malformed file. */
+export function loadHostLowering(): HostLowering {
+    if (_cache === null) _cache = _parse(fs.readFileSync(HOST_LOWERING_PATH, 'utf-8'));
+    return _cache;
+}
+
+/** Test seam — drop the memoized table so a fixture can be loaded instead. */
+export function _resetHostLoweringCache(table?: HostLowering): void {
+    _cache = table ?? null;
+}
+
+/** Parse a fixture table without touching the committed file. */
+export function parseHostLowering(text: string): HostLowering {
+    return _parse(text);
+}
+
+export function surfaceRow(
+    host: string,
+    surface: string = DEFAULT_SURFACE,
+    table: HostLowering = loadHostLowering(),
+): SurfaceRow | null {
+    return table.get(host)?.get(surface) ?? table.get(host)?.get(DEFAULT_SURFACE) ?? null;
+}
+
+/**
+ * Is the row's provenance still current?
+ *
+ * A row past `expires` is treated exactly as `verified: null` — it cannot
+ * carry a blocking binding. Comparison is on the calendar date so the answer
+ * does not depend on the runner's clock time of day.
+ */
+export function isVerifiedNow(row: SurfaceRow | null, today: string = new Date().toISOString().slice(0, 10)): boolean {
+    if (row?.verified == null) return false;
+    return row.verified.expires >= today;
+}
+
+/** Hosts carrying an unexpired `verified` block. */
+export function verifiedPlatforms(table: HostLowering = loadHostLowering()): ReadonlySet<string> {
+    const out = new Set<string>();
+    for (const [host, surfaces] of table) {
+        for (const row of surfaces.values()) {
+            if (isVerifiedNow(row)) {
+                out.add(host);
+                break;
+            }
+        }
+    }
+    return out;
+}
+
+/** Exit code this host honours as a refusal on `slot`, or null. */
+export function blockExitFor(host: string, slot: string, table: HostLowering = loadHostLowering()): number | null {
+    const row = surfaceRow(host, DEFAULT_SURFACE, table);
+    if (!isVerifiedNow(row)) return null;
+    return row?.slots.get(slot)?.block_exit ?? null;
+}
+
+/** One bridge binding: an agent-config slot lowered onto one native event. */
+export interface HostBinding {
+    slot: string;
+    native: string;
+    matcher: string;
+}
+
+/**
+ * Ordered bridge bindings for a host.
+ *
+ * Order is the table's `slots:` insertion order and is part of the generated
+ * output — the emitted bridge JSON is keyed by native event, so re-ordering
+ * changes bytes. Never sort this.
+ */
+export function hostBindings(host: string, table: HostLowering = loadHostLowering()): HostBinding[] {
+    const row = surfaceRow(host, DEFAULT_SURFACE, table);
+    if (!row) return [];
+    const out: HostBinding[] = [];
+    for (const [slot, sr] of row.slots) {
+        for (const native of sr.native) {
+            out.push({ slot, native, matcher: sr.matcher ?? '' });
+        }
+    }
+    return out;
+}

package/src/scripts/hooks/host_lowering.yaml

@@ -0,0 +1,185 @@
+# host_lowering — how each host lowers a dispatcher verdict into its own hook
+# contract, and what this tree has actually established about that lowering.
+#
+# WHY THIS FILE EXISTS. Before it, five facts about a host lived in five
+# places: `VERIFIED_PLATFORMS` and the block-capable event set in
+# `hooks/host_semantics.ts`, five private per-host binding constants in
+# `install.ts`, and prose in half a dozen docs. Three rounds of corrections to
+# that prose did not stop it drifting, because prose has no single reader. This
+# table is the single reader.
+#
+# WHAT A ROW IS. A row is keyed `(host, surface, slot)`. It describes what this
+# package does and what this package has established — never what the host is
+# capable of. `verified: null` means nobody established anything; it does NOT
+# mean the host cannot enforce.
+#
+# THE `surface` AXIS IS PRESENT AND DEGENERATE, DELIBERATELY. Every row today
+# is `any`, because nothing in this tree has measured an IDE-versus-CLI
+# difference in hook lowering on any host. The key carries the dimension so a
+# future measurement lands as a new row rather than as a rewrite; inventing
+# `ide:`/`cli:` rows nobody measured is the defect this roadmap exists to stop.
+#
+# CONSUMED BY:
+#   - src/scripts/hooks/host_semantics.ts   (VERIFIED_PLATFORMS, isBlockCapable, emission shape)
+#   - src/scripts/_lib/host_bindings.ts     (per-host bridge bindings + the install smoke probe)
+#   - src/scripts/lint_hook_manifest.ts     (schema + expiry gate)
+#
+# COLUMNS
+#   block_exit       exit code this host honours as a refusal on that slot;
+#                    `null` = this tree has not established that it honours one.
+#   json_shape       structured-output envelope the dispatcher may emit.
+#   entry_shape      shape of the bridge entry the installer writes.
+#   fail_policy      `propagate` = the dispatcher's exit code reaches the host;
+#                    `discard`   = the trampoline exits 0 regardless.
+#   timeout_unit     unit the host's own hook-timeout setting is expressed in.
+#   timeout_default  host default for that timeout. `null` = not established here.
+#   verified         provenance of the row, or `null`. `expires` is mandatory
+#                    when the block is present — see lint_hook_manifest.
+#   slots            ORDERED. Bridge entries are written in this order, so the
+#                    order is part of the generated output and must not be
+#                    sorted. `native` may be a list where one slot has two
+#                    native events (cline session_start).
+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
+        # Transcribed from the behaviour host_semantics.ts already implements —
+        # this row is a description of the status quo, not a new claim.
+        # docs_at/host_version are null because the original read was never
+        # dated; that absence is the record, and the lint reports it.
+        verified:
+          docs_at: null
+          docs_url: https://docs.claude.com/en/docs/claude-code/hooks
+          probe_at: null
+          host_version: null
+          expires: 2027-09-06
+        slots:
+          session_start:      { native: SessionStart,      block_exit: null }
+          session_end:        { native: SessionEnd,        block_exit: null }
+          stop:               { native: Stop,              block_exit: 2 }
+          user_prompt_submit: { native: UserPromptSubmit,  block_exit: 2 }
+          pre_tool_use:       { native: PreToolUse,        block_exit: 2 }
+          post_tool_use:      { native: PostToolUse,       block_exit: null }
+          pre_compact:        { native: PreCompact,        block_exit: null }
+          subagent_start:     { native: SubagentStart,     block_exit: null }
+          subagent_stop:      { native: SubagentStop,      block_exit: null }
+
+  augment:
+    surfaces:
+      any:
+        entry_shape: augment-settings-hooks
+        json_shape: none
+        # augment-dispatcher.sh exits 0 unconditionally: a verdict reaches the
+        # trampoline and stops there.
+        fail_policy: discard
+        timeout_unit: unknown
+        timeout_default: null
+        verified: null
+        slots:
+          session_start:  { native: SessionStart,  block_exit: null }
+          session_end:    { native: SessionEnd,    block_exit: null }
+          stop:           { native: Stop,          block_exit: null }
+          pre_tool_use:   { native: PreToolUse,    block_exit: null }
+          post_tool_use:  { native: PostToolUse,   block_exit: null }
+
+  cursor:
+    surfaces:
+      any:
+        entry_shape: cursor-hooks-json
+        json_shape: none
+        fail_policy: propagate
+        timeout_unit: unknown
+        timeout_default: null
+        verified: null
+        slots:
+          session_start:      { native: sessionStart,        block_exit: null }
+          session_end:        { native: sessionEnd,          block_exit: null }
+          stop:               { native: stop,                block_exit: null }
+          user_prompt_submit: { native: beforeSubmitPrompt,  block_exit: null }
+          post_tool_use:      { native: postToolUse,         block_exit: null }
+
+  cline:
+    surfaces:
+      any:
+        entry_shape: cline-per-event-script
+        json_shape: none
+        # The generated per-event script swallows the dispatcher's exit code
+        # and prints `{}`.
+        fail_policy: discard
+        timeout_unit: unknown
+        timeout_default: null
+        verified: null
+        slots:
+          session_start:      { native: [TaskStart, TaskResume], block_exit: null }
+          session_end:        { native: TaskComplete,            block_exit: null }
+          stop:               { native: TaskCancel,              block_exit: null }
+          user_prompt_submit: { native: UserPromptSubmit,        block_exit: null }
+          post_tool_use:      { native: PostToolUse,             block_exit: null }
+
+  windsurf:
+    surfaces:
+      any:
+        entry_shape: windsurf-hooks-json
+        json_shape: none
+        fail_policy: propagate
+        timeout_unit: unknown
+        timeout_default: null
+        verified: null
+        slots:
+          session_start:      { native: post_setup_worktree,   block_exit: null }
+          user_prompt_submit: { native: pre_user_prompt,       block_exit: null }
+          stop:               { native: post_cascade_response, block_exit: null }
+
+  gemini:
+    surfaces:
+      any:
+        entry_shape: gemini-settings-hooks
+        json_shape: none
+        fail_policy: propagate
+        timeout_unit: unknown
+        timeout_default: null
+        # A live deny probe was attempted on 2026-09-06 against Gemini CLI
+        # 0.50.0 in an isolated scratch workspace and could not run: the CLI
+        # aborts with IneligibleTierError before any turn begins, so no tool
+        # call and therefore no BeforeTool hook is reachable. An unrunnable
+        # probe establishes nothing, so this stays null.
+        verified: null
+        slots:
+          session_start:      { native: SessionStart, block_exit: null, matcher: "" }
+          session_end:        { native: SessionEnd,   block_exit: null, matcher: "" }
+          stop:               { native: AfterAgent,   block_exit: null, matcher: "" }
+          user_prompt_submit: { native: BeforeAgent,  block_exit: null, matcher: "" }
+          post_tool_use:      { native: AfterTool,    block_exit: null, matcher: ".*" }
+
+  cowork:
+    surfaces:
+      any:
+        entry_shape: none
+        json_shape: none
+        # cowork-dispatcher.sh exits 0 unconditionally, and the host is
+        # upstream-blocked from reading any settings source this package writes.
+        fail_policy: discard
+        timeout_unit: unknown
+        timeout_default: null
+        verified: null
+        slots: {}
+
+  copilot:
+    surfaces:
+      any:
+        entry_shape: none
+        json_shape: none
+        fail_policy: discard
+        timeout_unit: unknown
+        timeout_default: null
+        # `fallback_only: true` in hook_manifest.yaml. This package binds
+        # nothing here and has measured nothing here.
+        verified: null
+        slots: {}

package/src/scripts/hooks/host_semantics.ts

@@ -34,6 +34,8 @@
  * this module exists to remove.
  */
 
+import { blockExitFor, DEFAULT_SURFACE, loadHostLowering, surfaceRow, verifiedPlatforms } from "./host_lowering.js";
+
 /** Internal severity, mirroring dispatch_hook's EXIT_ALLOW / BLOCK / WARN. */
 export type Severity = "allow" | "warn" | "block";
 
@@ -50,53 +52,38 @@ export interface Emission {
 /**
  * Hosts with a documented, verified native hook contract. Anything absent
  * from this set falls through to the legacy pass-through.
+ *
+ * Read from `host_lowering.yaml`: a host is here when it carries a `verified`
+ * block whose `expires` has not passed. An expired row is therefore
+ * indistinguishable from `verified: null` at this boundary, which is what
+ * makes the expiry a real control rather than a comment.
  */
-export const VERIFIED_PLATFORMS: ReadonlySet<string> = new Set(["claude"]);
-
-/** Internal event name -> Claude Code `hookEventName` for JSON output. */
-const CLAUDE_HOOK_EVENT_NAME: Record<string, string> = {
-    pre_tool_use: "PreToolUse",
-    post_tool_use: "PostToolUse",
-    user_prompt_submit: "UserPromptSubmit",
-    session_start: "SessionStart",
-    session_end: "SessionEnd",
-    stop: "Stop",
-    pre_compact: "PreCompact",
-    subagent_start: "SubagentStart",
-    subagent_stop: "SubagentStop",
-};
+export const VERIFIED_PLATFORMS: ReadonlySet<string> = verifiedPlatforms();
 
-/**
- * Events where Claude Code honours exit 2 as a real block. Everywhere else
- * exit 2 either cannot block (PostToolUse: "the tool already ran";
- * SessionStart: "shows stderr to user only") or is far too blunt, so a block
- * degrades to visible advisory context instead of a silent no-op.
- */
-const CLAUDE_BLOCK_CAPABLE_EVENTS: ReadonlySet<string> = new Set([
-    "pre_tool_use",
-    "user_prompt_submit",
-    "stop",
-]);
+/** Internal event name -> host-native event name, for structured output. */
+function nativeEventName(platform: string, event: string): string {
+    return surfaceRow(platform, DEFAULT_SURFACE, loadHostLowering())?.slots.get(event)?.native[0] ?? event;
+}
 
 /**
  * Does this (platform, event) pair let a hook actually REFUSE the action?
  *
  * Exported because a second consumer now needs the same fact and must not
  * re-derive it: `dispatch_hook`'s stdin-read-failure policy denies only where a
- * deny is honoured (`b-stdin-read-failure-policy`, option (c)). A copy of
- * `CLAUDE_BLOCK_CAPABLE_EVENTS` one module away is a copy that drifts, and the
- * drift direction here is the dangerous one: a stale copy would deny on a slot
- * where the deny is discarded, refusing nothing while looking like enforcement.
+ * deny is honoured (`b-stdin-read-failure-policy`, option (c)). A second copy
+ * of the block-capable slot set would be a copy that drifts, and the drift
+ * direction here is the dangerous one: a stale copy would deny on a slot where
+ * the deny is discarded, refusing nothing while looking like enforcement. Both
+ * consumers now read `host_lowering.yaml`, so there is one set to drift from.
  *
  * An unverified platform is NOT block-capable by this predicate, and that is
  * deliberate rather than incidental: `emitFor` hands such a platform its legacy
  * exit code verbatim, so this tree has no evidence its host honours a deny at
- * all. Claiming capability without evidence is the over-claim the hook-coverage
+ * all. A row whose `verified` block has expired reads as unverified here. Claiming capability without evidence is the over-claim the hook-coverage
  * corrections in this estate exist to remove.
  */
 export function isBlockCapable(platform: string, event: string): boolean {
-    if (!VERIFIED_PLATFORMS.has(platform)) return false;
-    return CLAUDE_BLOCK_CAPABLE_EVENTS.has(event);
+    return blockExitFor(platform, event) !== null;
 }
 
 function _joinReasons(reasons: readonly string[]): string {
@@ -112,12 +99,70 @@ function _joinReasons(reasons: readonly string[]): string {
  * advisory path) always intended.
  */
 export function claudeAdditionalContext(event: string, text: string): string {
-    const hookEventName = CLAUDE_HOOK_EVENT_NAME[event] ?? event;
+    const hookEventName = nativeEventName("claude", event);
     return `${JSON.stringify({
         hookSpecificOutput: { hookEventName, additionalContext: text },
     })}\n`;
 }
 
+/**
+ * A host permission verdict for a `pre_tool_use` call.
+ *
+ * Probed against the running host on 2026-09-06 (Claude Code **2.1.263**,
+ * `/opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/bin/claude.exe`):
+ * the binary's own strings read `` `permissionDecision` - "allow", "deny", or
+ * "ask" (PreToolUse only) ``. The pin is the point — an unpinned capability
+ * claim rots the way the one it replaces did.
+ */
+export type PermissionDecision = "allow" | "deny" | "ask";
+
+/**
+ * Compose the concerns' permission verdicts into the one the host receives.
+ *
+ * ONE `ask` OR `deny` BEATS EVERY `allow`. This is the composition policy the
+ * host contract left undecided, and leaving it undecided is what stalled the
+ * emission path before: a dispatcher that reduces many concerns to one exit
+ * code has to say what happens when they disagree, and the only answer that
+ * cannot lower a floor is the most restrictive one.
+ *
+ * `null` means emit no permission field at all — nobody voted, so the legacy
+ * `additionalContext` envelope stands. That is deliberately distinct from
+ * `"allow"`: an absent field leaves the host's own permission machinery in
+ * charge, while an `allow` asserts this package looked at the call and has
+ * nothing to stop. Collapsing the two would turn "no concern matched this tool"
+ * into an affirmative grant, which is the widening failure the category-A
+ * classifier exists to prevent.
+ */
+export function composePermissionDecision(
+    verdicts: readonly PermissionDecision[],
+): PermissionDecision | null {
+    if (verdicts.length === 0) return null;
+    if (verdicts.includes("deny")) return "deny";
+    if (verdicts.includes("ask")) return "ask";
+    return "allow";
+}
+
+/**
+ * Build the Claude Code `hookSpecificOutput.permissionDecision` envelope.
+ *
+ * Exit 0 carries it, like every other JSON reply — the host parses stdout only
+ * on exit 0, so a decision emitted with any other exit code is discarded.
+ */
+export function claudePermissionDecision(
+    event: string,
+    decision: PermissionDecision,
+    reason: string,
+): string {
+    const hookEventName = nativeEventName("claude", event);
+    return `${JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName,
+            permissionDecision: decision,
+            permissionDecisionReason: reason,
+        },
+    })}\n`;
+}
+
 /**
  * Will `emitFor` actually put the reasons on a stream?
  *
@@ -146,11 +191,25 @@ export function emissionCarriesReasons(platform: string, severity: Severity): bo
     return severity !== "allow";
 }
 
+/** An explicit permission verdict the dispatcher wants the host to receive. */
+export interface PermissionEmission {
+    decision: PermissionDecision;
+    reason: string;
+}
+
 /**
  * Translate (platform, event, severity, reasons) into a native emission.
  *
  * `legacyExit` is the internal reduced code; unverified platforms get it back
  * verbatim so their behaviour is byte-identical to before this module landed.
+ *
+ * `permission` is emitted ONLY on a `pre_tool_use` event whose reduced severity
+ * is already `allow`. Both halves of that guard are load-bearing. The event
+ * guard is the host's — the field is documented "(PreToolUse only)". The
+ * severity guard is this package's: a `warn` or `block` reaching here means a
+ * concern had something to say, and an `allow` alongside it would be exactly
+ * the case `composePermissionDecision` refuses. So an allow can never travel
+ * with a finding, by construction rather than by the caller remembering.
  */
 export function emitFor(
     platform: string,
@@ -158,6 +217,7 @@ export function emitFor(
     severity: Severity,
     reasons: readonly string[],
     legacyExit: number,
+    permission?: PermissionEmission | null,
 ): Emission {
     if (!VERIFIED_PLATFORMS.has(platform)) {
         return { exit: legacyExit, stdout: "", stderr: "" };
@@ -165,15 +225,23 @@ export function emitFor(
     const reason = _joinReasons(reasons);
 
     if (severity === "allow") {
+        if (permission && event === "pre_tool_use") {
+            return {
+                exit: 0,
+                stdout: claudePermissionDecision(event, permission.decision, permission.reason),
+                stderr: "",
+            };
+        }
         return { exit: 0, stdout: "", stderr: "" };
     }
 
     if (severity === "block") {
-        if (CLAUDE_BLOCK_CAPABLE_EVENTS.has(event)) {
-            // Exit 2 + stderr: the ONLY documented way to make Claude Code
-            // refuse the action and feed the reason back to the model.
+        const blockExit = blockExitFor(platform, event);
+        if (blockExit !== null) {
+            // The host's own refusal code + stderr: the ONLY documented way to
+            // make it refuse the action and feed the reason back to the model.
             const label = reason || "blocked by agent-config hook policy";
-            return { exit: 2, stdout: "", stderr: `${label}\n` };
+            return { exit: blockExit, stdout: "", stderr: `${label}\n` };
         }
         // Not block-capable (post_tool_use, session_start, …). Exit 2 here
         // would discard stdout and still not block, so surface the reason as

package/src/scripts/hooks/journal_record_hook.ts

@@ -93,6 +93,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { hookSectionEnabled } from '../_lib/hook_settings.js';
+import { detectSurface, readSurface, type Surface } from '../_lib/surface.js';
 import {
     RECORDED_EVENTS,
     isJournalAvailable,
@@ -182,6 +183,8 @@ export interface JournalInput {
     task_id: string | null;
     prompt_id: string | null;
     capability: string;
+    /** Closed vocabulary. The dispatcher resolves it; re-derived only as a fallback. */
+    surface: Surface;
 }
 
 /**
@@ -208,6 +211,11 @@ export function reduceEnvelope(envelope: JsonObject): JournalInput | null {
         task_id: firstString(envelope, payload, ['task_id', 'taskId']),
         prompt_id: firstString(envelope, payload, ['prompt_id', 'promptId']),
         capability: capabilityFor(event, envelope, payload),
+        // The dispatcher writes it into the envelope; a direct invocation
+        // (`agent-config …:hook < event.json`) has no dispatcher, so fall back
+        // to the same detector rather than recording a field the caller never
+        // had a chance to set.
+        surface: readSurface(envelope['surface']) === 'unknown' ? detectSurface(payload) : readSurface(envelope['surface']),
     };
 }
 
@@ -248,6 +256,7 @@ export function processEnvelope(envelope: JsonValue, consumerRoot: string): numb
                 task_id: input.task_id,
                 prompt_id: input.prompt_id,
                 capability: input.capability,
+                surface: input.surface,
             });
         });
     } catch {
@@ -294,6 +303,7 @@ export function recordedFor(envelope: JsonValue, consumerRoot: string): SkipReas
                 task_id: input.task_id,
                 prompt_id: input.prompt_id,
                 capability: input.capability,
+                surface: input.surface,
             });
         });
     } catch {