@event4u/agent-config 14.18.0 → 14.20.0

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

@@ -45,7 +45,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import recycleThresholdConfig from '../../config/recycle-threshold-budget.json';
 
-import { RECYCLE_ENVELOPE_REL } from '../_lib/recycle_envelope_paths.js';
+import { recycle_envelope_rel } from '../_lib/recycle_envelope_paths.js';
 import {
     emptyCounters,
     eolSessionKey,
@@ -180,8 +180,16 @@ export function readState(file: string): SessionEolState {
  * session's state — a wrong resume instead of an empty one. An envelope whose
  * `written_at` predates the advisory is not this session's.
  */
-export function envelopeExists(workspaceRoot: string, since: string | null = null): boolean {
-    const target = path.join(workspaceRoot, RECYCLE_ENVELOPE_REL);
+export function envelopeExists(
+    workspaceRoot: string,
+    since: string | null = null,
+    sessionId: string | null = null,
+): boolean {
+    // Phase 2.1: the record is keyed by session, so the counter-check must look
+    // at THIS session's path. Checking the shared name would read a peer's
+    // record as proof that this session wrote one — the same cross-session
+    // confusion the key exists to remove, re-created in the checker.
+    const target = path.join(workspaceRoot, recycle_envelope_rel(sessionId));
     let raw: string;
     try {
         raw = fs.readFileSync(target, 'utf-8');
@@ -212,10 +220,10 @@ export function envelopeExists(workspaceRoot: string, since: string | null = nul
  * the next action the advisory recommended is the one that destroys the
  * session.
  */
-export function buildMissingEnvelopeLine(workspaceRoot: string): string {
+export function buildMissingEnvelopeLine(workspaceRoot: string, sessionId: string | null = null): string {
     return (
         `recycle advised earlier, but no envelope exists at ` +
-        `${path.join(workspaceRoot, RECYCLE_ENVELOPE_REL)} — /clear now starts the successor ` +
+        `${path.join(workspaceRoot, recycle_envelope_rel(sessionId))} — /clear now starts the successor ` +
         `from nothing. Re-run \`agent-config session:recycle\` and check that it prints the ` +
         `absolute path it wrote before clearing.`
     );
@@ -334,11 +342,14 @@ export function main(): number {
     // `AGENT_RECYCLE_THRESHOLD_TOKENS=0` is documented as the emergency switch
     // for the whole advisory lane, and a lane that keeps one more warn after
     // being switched off is not off.
+    // Raw id, not `sessionKey`: the record path is built from the id the host
+    // exported (`safe_stem`), never from the hashed state-file key.
+    const rawSessionId = payloadSessionId(payload, envelope) || null;
     const shouldWarnMissing =
         threshold !== null &&
         state.advisory_fired_at !== null &&
         (state.missing_envelope_warned_at ?? null) === null &&
-        !envelopeExists(workspaceRoot, state.advisory_fired_at);
+        !envelopeExists(workspaceRoot, state.advisory_fired_at, rawSessionId);
 
     const nextState: SessionEolState = {
         schema_version: 1,
@@ -415,7 +426,7 @@ export function main(): number {
             `${JSON.stringify({
                 decision: 'warn',
                 reason: 'session-eol: recycle advised, no envelope written',
-                additional_context: buildMissingEnvelopeLine(workspaceRoot),
+                additional_context: buildMissingEnvelopeLine(workspaceRoot, rawSessionId),
             })}\n`,
         );
         return EXIT_WARN;

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");
 }

package/src/scripts/install.ts

@@ -75,6 +75,7 @@ import { build_merge_entries } from './_lib/json_pointers.js';
 import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 import * as installed_lock from './_lib/installed_lock.js';
 import * as mcp_bridge from './_lib/mcp_bridge.js';
+import * as mcp_consent from './_lib/mcp_consent_residual.js';
 import * as scoped_projection from './_lib/scoped_projection.js';
 import * as surface_tiers from './_lib/surface_tiers.js';
 import * as global_deploy_inventory from './_lib/global_deploy_inventory.js';
@@ -90,6 +91,7 @@ import * as catalogue from './_lib/skill_catalogue.js';
 import { isInteractiveSession, type SessionProbe } from '../shared/interactiveContext.js';
 import * as claude_desktop_bundler from './_lib/claude_desktop_bundler.js';
 import * as claude_settings_hooks from './_lib/claude_settings_hooks.js';
+import { hostBindings } from './hooks/host_lowering.js';
 import { find_project_root_with_anchor, load_agent_settings } from './_lib/agent_settings.js';
 import {
     LEGACY_ALL,
@@ -417,7 +419,7 @@ function yamlSafeLoad(text: string): unknown {
 }
 
 // ---------------------------------------------------------------------------
-// Module-level constants (install.py:51-116)
+// Module-level constants.
 // ---------------------------------------------------------------------------
 
 const DEFAULT_PROFILE = 'balanced';
@@ -1022,14 +1024,6 @@ const AUGMENT_LEGACY_TRAMPOLINES: readonly string[] = [
     'augment-onboarding-gate.sh',
     'augment-context-hygiene.sh',
 ];
-const AUGMENT_DISPATCHER_BINDINGS: ReadonlyArray<readonly [string, string]> = [
-    ['session_start', 'SessionStart'],
-    ['session_end', 'SessionEnd'],
-    ['stop', 'Stop'],
-    ['pre_tool_use', 'PreToolUse'],
-    ['post_tool_use', 'PostToolUse'],
-];
-
 function _deploy_augment_trampoline(package_root: string, name: string, force: boolean): string | null {
     const src = path.join(package_root, 'scripts', 'hooks', name);
     if (!pathExists(src)) {
@@ -1073,8 +1067,8 @@ function ensure_augment_user_hooks(package_root: string, force: boolean): Record
     _remove_legacy_augment_trampolines();
 
     const per_event: Record<string, unknown[]> = {};
-    for (const [ac_event, native] of AUGMENT_DISPATCHER_BINDINGS) {
-        const cmd = `${dst} ${ac_event} ${native}`;
+    for (const { slot, native } of hostBindings('augment')) {
+        const cmd = `${dst} ${slot} ${native}`;
         const entry = { hooks: [{ type: 'command', command: cmd }] };
         (per_event[native] ??= []).push(entry);
     }
@@ -1130,14 +1124,6 @@ const _prune_tier_b_modules = (
 ): [number, Record<string, DeployResult>] =>
     _prune_modules_by(dr, mcp_bridge.tierBPrunePredicate(tier_b));
 
-const CURSOR_DISPATCHER_BINDINGS: ReadonlyArray<readonly [string, string]> = [
-    ['session_start', 'sessionStart'],
-    ['session_end', 'sessionEnd'],
-    ['stop', 'stop'],
-    ['user_prompt_submit', 'beforeSubmitPrompt'],
-    ['post_tool_use', 'postToolUse'],
-];
-
 function _cursor_dispatch_command(ac_event: string, native: string): string {
     // Hook-resilience shim (P1.4): missing binary → silent exit 0; a
     // present dispatcher's exit code propagates (fail_closed concerns
@@ -1152,8 +1138,8 @@ function _cursor_dispatch_command(ac_event: string, native: string): string {
 
 function ensure_cursor_bridge(project_root: string, force: boolean): Record<string, unknown>[] {
     const hooks: Record<string, unknown[]> = {};
-    for (const [ac_event, native] of CURSOR_DISPATCHER_BINDINGS) {
-        (hooks[native] ??= []).push({ command: _cursor_dispatch_command(ac_event, native) });
+    for (const { slot, native } of hostBindings('cursor')) {
+        (hooks[native] ??= []).push({ command: _cursor_dispatch_command(slot, native) });
     }
     const bridge = { version: 1, hooks };
     return merge_json_file(
@@ -1187,8 +1173,8 @@ function ensure_cursor_user_hooks(package_root: string, force: boolean): Record<
     }
 
     const hooks: Record<string, unknown[]> = {};
-    for (const [ac_event, native] of CURSOR_DISPATCHER_BINDINGS) {
-        (hooks[native] ??= []).push({ command: `${dst} ${ac_event} ${native}` });
+    for (const { slot, native } of hostBindings('cursor')) {
+        (hooks[native] ??= []).push({ command: `${dst} ${slot} ${native}` });
     }
 
     const settings_patch = { version: 1, hooks };
@@ -1200,15 +1186,6 @@ function ensure_cursor_user_hooks(package_root: string, force: boolean): Record<
     );
 }
 
-const CLINE_DISPATCHER_BINDINGS: ReadonlyArray<readonly [string, string]> = [
-    ['session_start', 'TaskStart'],
-    ['session_start', 'TaskResume'],
-    ['session_end', 'TaskComplete'],
-    ['stop', 'TaskCancel'],
-    ['user_prompt_submit', 'UserPromptSubmit'],
-    ['post_tool_use', 'PostToolUse'],
-];
-
 /** `shlex.quote` — POSIX shell single-quote escaping. */
 function shlexQuote(s: string): string {
     if (s === '') return "''";
@@ -1221,7 +1198,7 @@ function clineProjectHookBody(native_event: string, ac_event: string, workspace_
     // template uses doubled braces ({{ }}) that .format() collapses to single.
     return (
         '#!/usr/bin/env bash\n' +
-        '# Generated by event4u/agent-config install.py — DO NOT EDIT.\n' +
+        '# Generated by event4u/agent-config — DO NOT EDIT.\n' +
         `# Project-scope Cline hook for ${native_event} → agent-config ${ac_event}.\n` +
         '# Phase 7.6 (docs/contracts/hook-architecture-v1.md).\n' +
         'set -u\n' +
@@ -1249,14 +1226,14 @@ function ensure_cline_bridge(project_root: string, force: boolean): void {
 
     const workspace_quoted = shlexQuote(resolvePath(project_root));
     let written = 0;
-    for (const [ac_event, native_event] of CLINE_DISPATCHER_BINDINGS) {
-        const target = path.join(hooks_dir, native_event);
-        const body = clineProjectHookBody(native_event, ac_event, workspace_quoted);
+    for (const { slot, native } of hostBindings('cline')) {
+        const target = path.join(hooks_dir, native);
+        const body = clineProjectHookBody(native, slot, workspace_quoted);
         if (pathExists(target) && readText(target) === body && !force) {
             continue;
         }
         if (pathExists(target) && !force) {
-            skip(`.clinerules/hooks/${native_event} exists, needs update (use --force)`);
+            skip(`.clinerules/hooks/${native} exists, needs update (use --force)`);
             continue;
         }
         writeText(target, body);
@@ -1292,13 +1269,13 @@ function ensure_cline_user_hooks(package_root: string, force: boolean): void {
     }
 
     const trampoline_quoted = shlexQuote(trampoline);
-    for (const [ac_event, native_event] of CLINE_DISPATCHER_BINDINGS) {
-        const wrapper = path.join(CLINE_USER_DIR, native_event);
+    for (const { slot, native } of hostBindings('cline')) {
+        const wrapper = path.join(CLINE_USER_DIR, native);
         const body =
             '#!/usr/bin/env bash\n' +
-            '# Generated by event4u/agent-config install.py — DO NOT EDIT.\n' +
-            `# User-scope Cline hook for ${native_event} → agent-config ${ac_event}.\n` +
-            `exec ${trampoline_quoted} ${ac_event} ${native_event}\n`;
+            '# Generated by event4u/agent-config — DO NOT EDIT.\n' +
+            `# User-scope Cline hook for ${native} → agent-config ${slot}.\n` +
+            `exec ${trampoline_quoted} ${slot} ${native}\n`;
         if (pathExists(wrapper) && readText(wrapper) === body && !force) {
             continue;
         }
@@ -1307,12 +1284,6 @@ function ensure_cline_user_hooks(package_root: string, force: boolean): void {
     }
 }
 
-const WINDSURF_DISPATCHER_BINDINGS: ReadonlyArray<readonly [string, string]> = [
-    ['session_start', 'post_setup_worktree'],
-    ['user_prompt_submit', 'pre_user_prompt'],
-    ['stop', 'post_cascade_response'],
-];
-
 function _windsurf_dispatch_command(ac_event: string, native: string): string {
     // Hook-resilience shim (P1.4): missing binary → silent exit 0; a
     // present dispatcher's exit code propagates (fail_closed concerns
@@ -1327,9 +1298,9 @@ function _windsurf_dispatch_command(ac_event: string, native: string): string {
 
 function ensure_windsurf_bridge(project_root: string, force: boolean): Record<string, unknown>[] {
     const hooks: Record<string, unknown[]> = {};
-    for (const [ac_event, native] of WINDSURF_DISPATCHER_BINDINGS) {
+    for (const { slot, native } of hostBindings('windsurf')) {
         (hooks[native] ??= []).push({
-            command: _windsurf_dispatch_command(ac_event, native),
+            command: _windsurf_dispatch_command(slot, native),
             show_output: false,
         });
     }
@@ -1365,9 +1336,9 @@ function ensure_windsurf_user_hooks(package_root: string, force: boolean): Recor
     }
 
     const hooks: Record<string, unknown[]> = {};
-    for (const [ac_event, native] of WINDSURF_DISPATCHER_BINDINGS) {
+    for (const { slot, native } of hostBindings('windsurf')) {
         (hooks[native] ??= []).push({
-            command: `${dst} ${ac_event} ${native}`,
+            command: `${dst} ${slot} ${native}`,
             show_output: false,
         });
     }
@@ -1381,14 +1352,6 @@ function ensure_windsurf_user_hooks(package_root: string, force: boolean): Recor
     );
 }
 
-const GEMINI_DISPATCHER_BINDINGS: ReadonlyArray<readonly [string, string, string]> = [
-    ['session_start', 'SessionStart', ''],
-    ['session_end', 'SessionEnd', ''],
-    ['stop', 'AfterAgent', ''],
-    ['user_prompt_submit', 'BeforeAgent', ''],
-    ['post_tool_use', 'AfterTool', '.*'],
-];
-
 function _gemini_dispatch_command(ac_event: string, native: string): string {
     // Hook-resilience shim (P1.4): missing binary → silent exit 0; a
     // present dispatcher's exit code propagates (fail_closed concerns
@@ -1405,10 +1368,10 @@ function _gemini_hooks_dict(
     command_factory: (ac_event: string, native: string) => string,
 ): Record<string, unknown[]> {
     const out: Record<string, unknown[]> = {};
-    for (const [ac_event, native, matcher] of GEMINI_DISPATCHER_BINDINGS) {
+    for (const { slot, native, matcher } of hostBindings('gemini')) {
         (out[native] ??= []).push({
             matcher,
-            hooks: [{ type: 'command', command: command_factory(ac_event, native) }],
+            hooks: [{ type: 'command', command: command_factory(slot, native) }],
         });
     }
     return out;
@@ -1724,15 +1687,37 @@ function ensure_kiro_bridge(project_root: string, force: boolean): void {
 
 // --- Post-install smoke test ---
 
-const SMOKE_PROBE_EVENTS: ReadonlyArray<readonly [string, string]> = [
+/**
+ * Platforms whose bridge the smoke probe exercises, with the slot it probes.
+ *
+ * The NATIVE event is derived from `host_lowering.yaml`, never written here.
+ * The hand-written list this replaced probed `['cursor', 'beforeShellExecution']`
+ * — an event no cursor bridge has ever written — so the probe could not fail on
+ * a real binding regression, which is the only thing it exists to catch. A
+ * platform whose table row does not carry the probed slot is a hard error, not
+ * a skip: a silent skip is how the previous list stayed wrong.
+ */
+const SMOKE_PROBE_SLOTS: ReadonlyArray<readonly [string, string]> = [
     ['augment', 'session_start'],
-    ['claude', 'SessionStart'],
-    ['cursor', 'beforeShellExecution'],
+    ['claude', 'session_start'],
+    ['cursor', 'session_start'],
     ['cline', 'session_start'],
-    ['windsurf', 'post_setup_worktree'],
-    ['gemini', 'SessionStart'],
+    ['windsurf', 'session_start'],
+    ['gemini', 'session_start'],
 ];
 
+export function smokeProbeEvents(): ReadonlyArray<readonly [string, string]> {
+    return SMOKE_PROBE_SLOTS.map(([platform, slot]) => {
+        const binding = hostBindings(platform).find((b) => b.slot === slot);
+        if (binding === undefined) {
+            throw new Error(
+                `install smoke probe: host_lowering.yaml has no \`${slot}\` binding for \`${platform}\``,
+            );
+        }
+        return [platform, binding.native] as const;
+    });
+}
+
 const SMOKE_BRIDGE_PATHS: Record<string, string> = {
     augment: '.augment/settings.json',
     claude: '.claude/settings.json',
@@ -1787,7 +1772,7 @@ function _smoke_test_hooks(project_root: string, package_root: string): number {
     const skipped: string[] = [];
     const passed: string[] = [];
 
-    for (const [platform, native] of SMOKE_PROBE_EVENTS) {
+    for (const [platform, native] of smokeProbeEvents()) {
         const rel_bridge = SMOKE_BRIDGE_PATHS[platform] ?? '';
         const bridge_path = rel_bridge ? path.join(project_root, rel_bridge) : null;
         const bridge_present = Boolean(
@@ -2619,15 +2604,6 @@ function _is_agent_config_source_repo(project_root: string): [boolean, string] {
         }
     }
 
-    const installer_self = path.join(project_root, 'scripts', 'install.py');
-    try {
-        if (isFile(installer_self) && resolvePath(installer_self) === resolvePath(_HERE)) {
-            return [true, 'src/scripts/install.py (self)'];
-        }
-    } catch {
-        /* OSError → pass */
-    }
-
     return [false, ''];
 }
 
@@ -4028,7 +4004,7 @@ function _merge_tools_aliases(tools: string | null, ai: string | null): string {
     return items.length > 0 ? items.join(',') : 'all';
 }
 
-const PROG = 'install.py';
+const PROG = 'agent-config install';
 // Verbatim argparse usage block at COLUMNS=80 (captured from the .py). The
 // `--help` BODY (per-flag descriptions) is a documented divergence — argparse
 // re-wraps it to the live terminal width, which is not worth reproducing; the
@@ -5146,11 +5122,9 @@ function _main_project_install(
             ...ensure_augment_bridge(project_root, opts.force),
         ];
         if (_is_tool_enabled(tools, 'claude-code')) {
-            merged_keys_by_tool['claude-code'] = [
-                ...ensure_claude_bridge(project_root, opts.force),
-                ...ensure_mcp_bridge(project_root, opts.force),
-            ];
+            merged_keys_by_tool['claude-code'] = ensure_claude_bridge(project_root, opts.force);
         }
+        mcp_bridge.registerMcpHosts(merge_json_file, project_root, opts.force, package_root, tools, merged_keys_by_tool);
         if (_is_tool_enabled(tools, 'cursor')) {
             merged_keys_by_tool['cursor'] = ensure_cursor_bridge(project_root, opts.force);
         }
@@ -5251,6 +5225,7 @@ function _main_project_install(
             );
             process.stdout.write('\n');
         }
+        mcp_consent.printResiduals(tools, state.QUIET);
         if (_is_tool_enabled(tools, 'claude-code')) {
             const team_hint = _team_setup_hint_line(project_root);
             if (team_hint !== null) {
@@ -5364,10 +5339,6 @@ export {
     ROOCODE_MARKER,
     ZED_MARKER,
     // ADR-200 py2ts: re-exported for test_install_snapshot.ts twin
-    CURSOR_DISPATCHER_BINDINGS,
-    CLINE_DISPATCHER_BINDINGS,
-    WINDSURF_DISPATCHER_BINDINGS,
-    GEMINI_DISPATCHER_BINDINGS,
     ensure_cursor_bridge,
     ensure_cline_bridge,
     ensure_mcp_bridge,

package/src/scripts/install_anthropic_key.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Interactive Anthropic-API-key installer for scripts/skill_trigger_eval.py.
+# Interactive Anthropic-API-key installer for src/scripts/skill_trigger_eval.ts.
 #
 # Reads the key with `read -s` so it never echoes to the terminal and
 # never lands in shell history or scrollback. Writes atomically to
@@ -7,7 +7,7 @@
 # ~/.config/agent-config/anthropic.key is read as a fallback by the
 # loaders so pre-2.4 installs keep working until the namespace shim runs.
 #
-# Contract — companion to scripts/skill_trigger_eval.py:
+# Contract — companion to src/scripts/skill_trigger_eval.ts:
 #   - File path:  $HOME/.event4u/agent-config/anthropic.key
 #   - File mode:  0600 (owner read/write only)
 #   - Key format: must start with `sk-ant-`