@event4u/agent-config 14.18.0 → 14.19.0

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 {

package/src/scripts/hooks/permission_gate.ts

@@ -0,0 +1,117 @@
+/**
+ * permission_gate — whether a `pre_tool_use` call gets an explicit
+ * `permissionDecision`, and which one.
+ *
+ * Four independent conditions, each able to withhold an allow on its own: the
+ * host offers the field on `pre_tool_use` only; the dispatcher's reduced
+ * severity must already be `allow`; no concern may have voted `ask` or `deny`;
+ * and the call itself must be category A. An allow is emitted only when all
+ * four hold, so widening any one of them is a visible edit rather than an
+ * emergent effect.
+ *
+ * Separate from `dispatch_hook` because that file is against the per-file
+ * source-size budget, and because the seam is real: the dispatcher runs
+ * concerns and reduces exit codes, this module reads the result and decides
+ * what the host is told about permission.
+ */
+import { isCategoryA, type ToolInput } from "./category_a.js";
+import {
+  composePermissionDecision,
+  type PermissionDecision,
+  type PermissionEmission,
+} from "./host_semantics.js";
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function _isObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Mirrors `dispatch_hook.EXIT_ALLOW` / `EXIT_BLOCK`; imported would be a cycle. */
+const EXIT_ALLOW = 0;
+const EXIT_BLOCK = 1;
+
+/** The host's `tool_name`, or `""` when the event carries none. */
+export function _payload_tool_name(envelope: JsonObject): string {
+  const payload = envelope["payload"];
+  if (!_isObject(payload)) return "";
+  const raw = payload["tool_name"];
+  return typeof raw === "string" ? raw : "";
+}
+
+/** The host's `tool_input` object, or `{}` when the event carries none. */
+export function _payload_tool_input(envelope: JsonObject): ToolInput {
+  const payload = envelope["payload"];
+  if (!_isObject(payload)) return {};
+  const raw = payload["tool_input"];
+  return _isObject(raw) ? (raw as ToolInput) : {};
+}
+
+/**
+ * The root every category-A path argument must resolve inside.
+ *
+ * The host's own `cwd` wins over `workspace_root` because the latter is the
+ * dispatcher's process cwd, which in a worktree is the parent checkout rather
+ * than the tree the user is working in — confining against it would admit a
+ * path outside the tree the call actually runs in.
+ */
+export function _working_tree_root(envelope: JsonObject): string {
+  const payload = envelope["payload"];
+  if (_isObject(payload) && typeof payload["cwd"] === "string" && payload["cwd"].trim()) {
+    return payload["cwd"];
+  }
+  const workspace = envelope["workspace_root"];
+  return typeof workspace === "string" ? workspace : "";
+}
+
+/**
+ * One concern's permission verdict.
+ *
+ * A block is a deny. A concern may also say `{"decision":"ask"}` on stdout —
+ * the field has been recorded in the feedback file since v1 and read by
+ * nothing, so an advisory concern that wanted a confirmation got silence.
+ * `ask` is honoured regardless of the exit code: an advisory concern cannot
+ * block and must not have to in order to be heard. Everything else abstains,
+ * which composes as `allow`.
+ */
+export function _concern_permission_verdict(
+  rc: number,
+  reply: JsonObject,
+): PermissionDecision {
+  if (rc === EXIT_BLOCK) return "deny";
+  const stated = String(reply["decision"] ?? "").trim().toLowerCase();
+  if (stated === "ask") return "ask";
+  if (stated === "deny") return "deny";
+  return "allow";
+}
+
+/**
+ * The permission field to hand the host, or `null` to keep the legacy envelope.
+ *
+ * Four independent conditions, each able to withhold the allow on its own:
+ * the host offers the field on `pre_tool_use` only; the reduced severity must
+ * already be `allow`; no concern may have voted `ask` or `deny`; and the call
+ * itself must be category A. An allow is emitted only when all four hold, so
+ * widening any one of them is a visible edit rather than an emergent effect.
+ */
+export function _permission_for(
+  event: string,
+  envelope: JsonObject,
+  final_rc: number,
+  verdicts: readonly PermissionDecision[],
+): PermissionEmission | null {
+  if (event !== "pre_tool_use") return null;
+  if (final_rc !== EXIT_ALLOW) return null;
+  if (composePermissionDecision(verdicts) !== "allow") return null;
+  const tool_name = _payload_tool_name(envelope);
+  if (!isCategoryA(tool_name, _payload_tool_input(envelope), _working_tree_root(envelope))) {
+    return null;
+  }
+  return {
+    decision: "allow",
+    reason:
+      `agent-config: category-A ${tool_name} inside the working tree — ` +
+      `no concern gates it and none asked to.`,
+  };
+}

package/src/scripts/hooks_status.ts

@@ -45,7 +45,9 @@ const MANIFEST_PATH = path.join(
   "hook_manifest.yaml",
 );
 
-// (label, project-relative bridge path, install hint).
+// (project-relative bridge path, one-line note shown when the bridge is not
+// live). The note is printed verbatim, so a note that is not a command must
+// not read as one.
 // Path may be a directory (cline) — existence => any file inside.
 //
 // Cowork has no project-scope bridge path: the Claude desktop app's
@@ -58,17 +60,17 @@ const MANIFEST_PATH = path.join(
 // Once upstream lands the fix and a stable settings location is
 // documented, swap the empty path here for that location.
 export const PLATFORM_BRIDGES: Record<string, [string, string]> = {
-  augment: [".augment/settings.json", "src/scripts/install.py"],
-  claude: [".claude/settings.json", "src/scripts/install.py"],
+  augment: [".augment/settings.json", "run `agent-config install`"],
+  claude: [".claude/settings.json", "run `agent-config install`"],
   cowork: [
     "",
     "upstream-blocked: anthropics/claude-code#40495 + #27398 (settings.json ignored in Cowork sandbox)",
   ],
-  cursor: [".cursor/hooks.json", "src/scripts/install.py"],
-  cline: [".clinerules/hooks", "src/scripts/install.py"],
-  windsurf: [".windsurf/hooks.json", "src/scripts/install.py"],
-  gemini: [".gemini/settings.json", "src/scripts/install.py"],
-  copilot: ["", "rule-only fallback (no hook surface)"],
+  cursor: [".cursor/hooks.json", "run `agent-config install`"],
+  cline: [".clinerules/hooks", "run `agent-config install`"],
+  windsurf: [".windsurf/hooks.json", "run `agent-config install`"],
+  gemini: [".gemini/settings.json", "run `agent-config install`"],
+  copilot: ["", "rule-only fallback — this package binds no hook here"],
 };
 
 export interface PlatformRow {
@@ -180,11 +182,11 @@ export function _render_table(matrix: StatusMatrix): string {
       lines.push(`    ${event.padEnd(22)} → ${concerns}`);
     }
     if (row.hint) {
-      lines.push(`    hint: run ${row.hint}`);
+      lines.push(`    hint: ${row.hint}`);
     }
   }
   lines.push("");
-  lines.push("Source of truth: scripts/hook_manifest.yaml");
+  lines.push("Source of truth: src/scripts/hook_manifest.yaml");
   lines.push("Contract: docs/contracts/hook-architecture-v1.md");
   return lines.join("\n");
 }