@event4u/agent-config 14.18.0 → 14.20.0

package/src/scripts/_lib/host_permission_checks.ts

@@ -0,0 +1,251 @@
+/**
+ * host_permission_checks — report the host permission settings that produce
+ * confirmation prompts, and write none of them.
+ *
+ * WHY REPORT AND NOT WRITE. Three settings decide how often a normal coding
+ * task is interrupted, and all three belong to the consumer:
+ * `permissions.deny` rules that cover reads, the working tree's absence from
+ * `permissions.additionalDirectories`, and `permissions.defaultMode`. Writing
+ * any of them would be this package deciding a consumer's permission posture
+ * from inside their repository, which is the one thing a permission surface
+ * must never do quietly. `src/templates/consumer-settings/claude-settings.json`
+ * carries `enabledPlugins` and `hooks` and zero `permissions` keys; this check
+ * exists so that stays true and the consumer still gets the answer.
+ *
+ * WHY IT NAMES ALL THREE EVEN WHEN ALL THREE ARE ABSENT. Absent is a real
+ * answer and the most common one. A check that goes silent on the default
+ * project reports "nothing found" and "I did not look" identically, which is
+ * the measured-zero-versus-not-measured failure this tree's own report
+ * contracts argue against. So each setting is named on every run, with its
+ * resolved value or the word absent.
+ *
+ * READ ONLY, AND FAILURE-TOLERANT. An unreadable or malformed settings file is
+ * reported, never repaired: a consumer's JSON is theirs, and a doctor that
+ * rewrites what it came to inspect is not a doctor.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import type { WiringCheck } from "./runtime_wiring_checks.js";
+
+/** Injected so a test never reads the developer's own home directory. */
+export interface HostPermissionDeps {
+    projectRoot: string;
+    homeDir: string;
+    readFile: (p: string) => string | null;
+    isDirectory: (p: string) => boolean;
+}
+
+/** The permission block as the host writes it; every field optional. */
+interface PermissionBlock {
+    allow?: unknown;
+    deny?: unknown;
+    ask?: unknown;
+    additionalDirectories?: unknown;
+    defaultMode?: unknown;
+}
+
+/** One settings layer, in the host's own precedence order. */
+export interface SettingsLayer {
+    label: string;
+    file: string;
+    present: boolean;
+    unreadable: boolean;
+    permissions: PermissionBlock;
+}
+
+/**
+ * Tool names whose every documented effect is a read, plus the read-shaped
+ * `Bash(<cmd>:*)` heads. A deny covering one of these is the class that turns a
+ * category-A call back into a prompt, which is why it is worth naming
+ * separately from a deny on a write.
+ */
+const READ_SHAPED = [
+    "Read", "Glob", "Grep", "LS", "NotebookRead",
+    "Bash(cat", "Bash(ls", "Bash(head", "Bash(tail", "Bash(grep",
+    "Bash(rg", "Bash(find", "Bash(wc", "Bash(git status", "Bash(git log",
+    "Bash(git diff", "Bash(git show",
+];
+
+/** The four `defaultMode` values probed from Claude Code 2.1.263. */
+const KNOWN_MODES = ["default", "acceptEdits", "plan", "bypassPermissions"];
+
+function _strings(value: unknown): string[] {
+    return Array.isArray(value) ? value.filter((v): v is string => typeof v === "string") : [];
+}
+
+/** Default deps — the only place the real filesystem is touched. */
+export function defaultHostPermissionDeps(projectRoot: string): HostPermissionDeps {
+    return {
+        projectRoot,
+        homeDir: os.homedir(),
+        readFile: (p) => {
+            try {
+                return fs.readFileSync(p, "utf8");
+            } catch {
+                return null;
+            }
+        },
+        isDirectory: (p) => {
+            try {
+                return fs.statSync(p).isDirectory();
+            } catch {
+                return false;
+            }
+        },
+    };
+}
+
+/**
+ * Resolve the three settings layers the host reads, in its precedence order.
+ *
+ * There was no resolver for this before — `security_audit_config.ts` is the
+ * only place all three paths appear together, and only as glob strings — so
+ * this is the first code in the tree that reads `permissions` at all.
+ */
+export function readSettingsLayers(deps: HostPermissionDeps): SettingsLayer[] {
+    const candidates: Array<[string, string]> = [
+        ["user-global", path.join(deps.homeDir, ".claude", "settings.json")],
+        ["project", path.join(deps.projectRoot, ".claude", "settings.json")],
+        ["project-local", path.join(deps.projectRoot, ".claude", "settings.local.json")],
+    ];
+    return candidates.map(([label, file]) => {
+        const raw = deps.readFile(file);
+        if (raw === null) {
+            return { label, file, present: false, unreadable: false, permissions: {} };
+        }
+        try {
+            const parsed = JSON.parse(raw) as Record<string, unknown>;
+            const perms = parsed["permissions"];
+            return {
+                label,
+                file,
+                present: true,
+                unreadable: false,
+                permissions:
+                    perms !== null && typeof perms === "object" ? (perms as PermissionBlock) : {},
+            };
+        } catch {
+            return { label, file, present: true, unreadable: true, permissions: {} };
+        }
+    });
+}
+
+/** Deny rules that cover a read, with the layer each came from. */
+export function readDenyRules(layers: readonly SettingsLayer[]): Array<[string, string]> {
+    const hits: Array<[string, string]> = [];
+    for (const layer of layers) {
+        for (const rule of _strings(layer.permissions.deny)) {
+            if (READ_SHAPED.some((prefix) => rule.startsWith(prefix))) {
+                hits.push([layer.label, rule]);
+            }
+        }
+    }
+    return hits;
+}
+
+/** Every `additionalDirectories` entry across the layers; the host unions them. */
+export function additionalDirectories(layers: readonly SettingsLayer[]): string[] {
+    const seen: string[] = [];
+    for (const layer of layers) {
+        for (const dir of _strings(layer.permissions.additionalDirectories)) {
+            if (!seen.includes(dir)) seen.push(dir);
+        }
+    }
+    return seen;
+}
+
+/** The winning `defaultMode`, or `null` when no layer sets one. */
+export function resolvedDefaultMode(layers: readonly SettingsLayer[]): string | null {
+    let winner: string | null = null;
+    for (const layer of layers) {
+        const mode = layer.permissions.defaultMode;
+        if (typeof mode === "string" && mode.trim()) winner = mode.trim();
+    }
+    return winner;
+}
+
+/**
+ * Is the project root a LINKED worktree?
+ *
+ * A linked worktree's `.git` is a file holding a `gitdir:` pointer, never a
+ * directory. It matters here because a worktree root is a working directory the
+ * host was not started in, which is exactly the case
+ * `additionalDirectories` exists to cover — and the case a consumer is least
+ * likely to have thought about.
+ */
+export function isLinkedWorktree(deps: HostPermissionDeps): boolean {
+    const dotGit = path.join(deps.projectRoot, ".git");
+    const raw = deps.readFile(dotGit);
+    if (raw === null) return false;
+    return !deps.isDirectory(dotGit) && raw.trimStart().startsWith("gitdir:");
+}
+
+/** The copyable snippet — the consumer pastes it, this package never writes it. */
+export function permissionSnippet(projectRoot: string): string {
+    return JSON.stringify(
+        { permissions: { additionalDirectories: [projectRoot], defaultMode: "default" } },
+        null,
+        2,
+    );
+}
+
+/**
+ * The doctor row.
+ *
+ * `warn` when something reportable was found, `ok` otherwise. Never `fail`:
+ * these are the consumer's own choices, and a doctor that fails a build over a
+ * setting it is forbidden to write would be asking for a change it will not
+ * make.
+ */
+export function checkHostPermissionSettings(deps: HostPermissionDeps): WiringCheck {
+    const layers = readSettingsLayers(deps);
+    const unreadable = layers.filter((l) => l.unreadable);
+    const denies = readDenyRules(layers);
+    const dirs = additionalDirectories(layers);
+    const mode = resolvedDefaultMode(layers);
+    const worktree = isLinkedWorktree(deps);
+    const rootListed = dirs.some(
+        (d) => path.resolve(d) === path.resolve(deps.projectRoot),
+    );
+
+    const lines: string[] = [];
+    lines.push(
+        denies.length === 0
+            ? "read-deny rules: absent — no permissions.deny rule covers a read"
+            : `read-deny rules: ${denies.length} — ` +
+              denies.map(([layer, rule]) => `${rule} (${layer})`).join(", "),
+    );
+    lines.push(
+        rootListed
+            ? `working tree in additionalDirectories: present (${deps.projectRoot})`
+            : `working tree in additionalDirectories: absent (${deps.projectRoot}` +
+              `${worktree ? ", a linked worktree" : ""})`,
+    );
+    lines.push(
+        mode === null
+            ? "permissions.defaultMode: absent — the host's own built-in default applies"
+            : `permissions.defaultMode: ${mode}` +
+              (KNOWN_MODES.includes(mode) ? "" : " — not a value this tree has probed"),
+    );
+    for (const layer of unreadable) {
+        lines.push(`unreadable: ${layer.file} (${layer.label}) is not valid JSON`);
+    }
+
+    // A linked worktree unlisted in additionalDirectories is the one finding
+    // worth surfacing on its own: the host was started somewhere else, so every
+    // call into this tree is a call into a directory it was not granted.
+    const reportable =
+        denies.length > 0 || unreadable.length > 0 || (worktree && !rootListed);
+
+    return {
+        id: "host-permission-settings",
+        status: reportable ? "warn" : "ok",
+        message: lines.join("; "),
+        remedy:
+            "agent-config never writes permissions — paste this into " +
+            `${path.join(deps.projectRoot, ".claude", "settings.local.json")} yourself if you want it: ` +
+            permissionSnippet(deps.projectRoot).replace(/\s+/g, " "),
+    };
+}

package/src/scripts/_lib/install_reach_checks.ts

@@ -34,6 +34,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import type { WiringCheck } from './runtime_wiring_checks.js';
+import { TOOL_TO_HOST, residualReport } from './mcp_consent_residual.js';
 
 /**
  * Root agent-instruction files, as a multi-vendor ecosystem convention rather
@@ -477,11 +478,41 @@ export function checkOverrideSet(projectRoot: string): WiringCheck {
     };
 }
 
+/**
+ * Step 3.2 — what remains non-automatic per host, and where that came from.
+ *
+ * Belongs to reach rather than to a doctor-local check because that is what it
+ * measures: the gap between "installed" and "actually running". A residual is
+ * exactly the distance the install did not cover.
+ *
+ * Reports the residual, never a checklist of what worked — a list of successes
+ * is noise a reader has to filter, while a named residual is the one thing they
+ * can act on. An UNRECORDED host warns too, because "nobody checked" must not
+ * read as "nothing to do".
+ */
+export function checkMcpConsentResidual(): WiringCheck {
+    const id = 'mcp-consent-residual';
+    const lines = residualReport(Object.keys(TOOL_TO_HOST));
+    if (lines.length === 0) {
+        return { id, status: 'ok', message: 'no MCP consent residual recorded for any known host', remedy: '' };
+    }
+    const actionable = lines.filter((l) => l.state === 'residual');
+    return {
+        id,
+        status: 'warn',
+        message: lines.map((l) => l.text).join(' · '),
+        remedy:
+            actionable.length > 0
+                ? 'complete the step named above on each host you use'
+                : 'record an observation for the unchecked hosts, or ignore if you do not use them',
+    };
+}
+
 // ---------------------------------------------------------------------------
 // Wiring — the shape `cmd_doctor` consumes
 // ---------------------------------------------------------------------------
 
-export const REACH_CHECK_IDS = ['instruction-path-reach', 'version-axis', 'override-set'] as const;
+export const REACH_CHECK_IDS = ['instruction-path-reach', 'version-axis', 'override-set', 'mcp-consent-residual'] as const;
 
 export function reachRunners(opts: {
     projectRoot: string;
@@ -491,5 +522,6 @@ export function reachRunners(opts: {
         'instruction-path-reach': () => checkInstructionPaths(opts.projectRoot),
         'version-axis': () => checkVersionAxis(opts.projectRoot, opts.resolvableVersion),
         'override-set': () => checkOverrideSet(opts.projectRoot),
+        'mcp-consent-residual': () => checkMcpConsentResidual(),
     };
 }

package/src/scripts/_lib/mcp_bridge.ts

@@ -15,6 +15,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { probeHostCapabilities } from './host_capability.js';
 
 /** `install.ts`'s deploy tuple: [written, skipped, status, paths]. */
 export type DeployTuple = [number, number, string, string[]];
@@ -35,14 +36,43 @@ export type MergeJsonFile = (
  * installer end up with the same entry rather than two that drift.
  */
 export const MCP_SERVER_KEY = 'agent-config';
-export const MCP_BRIDGE_ENTRY = {
-    mcpServers: {
-        [MCP_SERVER_KEY]: {
-            command: 'npx',
-            args: ['-y', '@event4u/agent-config', 'mcp-server'],
+export const MCP_PACKAGE_NAME = '@event4u/agent-config';
+
+/**
+ * The entry, pinned to the version the installer is running from.
+ *
+ * Unpinned, `npx -y @event4u/agent-config` resolves the `latest` dist-tag on
+ * every server start, so the server a consumer runs is whatever the registry
+ * served most recently — not the one their installer approved, and not the one
+ * their lockfile records. The pin makes those the same artefact.
+ *
+ * A version that cannot be read is left unpinned rather than guessed: an
+ * invented specifier would fail to resolve at server start, which is a worse
+ * failure than the drift it was meant to close.
+ */
+export function mcpBridgeEntry(packageRoot: string): Record<string, unknown> {
+    const version = readPackageVersion(packageRoot);
+    const spec = version === null ? MCP_PACKAGE_NAME : `${MCP_PACKAGE_NAME}@${version}`;
+    return {
+        mcpServers: {
+            [MCP_SERVER_KEY]: {
+                command: 'npx',
+                args: ['-y', spec, 'mcp-server'],
+            },
         },
-    },
-};
+    };
+}
+
+/** The manifest `version`, or `null` when it is absent or unreadable. */
+export function readPackageVersion(packageRoot: string): string | null {
+    try {
+        const raw = fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8');
+        const v = (JSON.parse(raw) as { version?: unknown }).version;
+        return typeof v === 'string' && v.trim() !== '' ? v : null;
+    } catch {
+        return null;
+    }
+}
 
 /**
  * `.mcp.json` — the project-scope MCP config Claude Code reads.
@@ -66,9 +96,191 @@ export const MCP_BRIDGE_ENTRY = {
  */
 export function makeEnsureMcpBridge(
     mergeJsonFile: MergeJsonFile,
-): (projectRoot: string, force: boolean) => Record<string, unknown>[] {
-    return (projectRoot, force) =>
-        mergeJsonFile(path.join(projectRoot, '.mcp.json'), MCP_BRIDGE_ENTRY, force, '.mcp.json');
+): (projectRoot: string, force: boolean, packageRoot?: string) => Record<string, unknown>[] {
+    return (projectRoot, force, packageRoot = projectRoot) =>
+        mergeJsonFile(
+            path.join(projectRoot, '.mcp.json'),
+            mcpBridgeEntry(packageRoot),
+            force,
+            '.mcp.json',
+        );
+}
+
+/**
+ * Where each host reads a PROJECT-scope MCP config, and which capability-manifest
+ * row gates writing to it (roadmap step 3.3).
+ *
+ * Keyed by the installer's `--tools` id; `hostId` is the SEPARATE
+ * platform identifier the capability manifest is keyed by (`claude`, not
+ * `claude-code`). Conflating the two namespaces is the mistake
+ * `host_capability.ts` warns about in its own registry doc, so the mapping is
+ * written out rather than derived.
+ *
+ * Presence in this table is NOT permission to write. It records where the file
+ * would go IF the axis said the host reads one; the axis decides, and it says
+ * `true` only once someone observed it.
+ */
+export const MCP_PROJECT_CONFIG: Readonly<Record<string, { hostId: string; relPath: string }>> = {
+    'claude-code': { hostId: 'claude', relPath: '.mcp.json' },
+    cursor: { hostId: 'cursor', relPath: '.cursor/mcp.json' },
+    'gemini-cli': { hostId: 'gemini', relPath: '.gemini/settings.json' },
+};
+
+/** One host to register, resolved from the `--tools` set and the capability axis. */
+export interface McpRegistrationTarget {
+    toolId: string;
+    hostId: string;
+    relPath: string;
+}
+
+/** Injectable capability reader — the installer passes the real probe. */
+export type ReadsProjectMcpConfig = (hostId: string) => boolean;
+
+/**
+ * The hosts an install may register the server on, beyond `claude-code`.
+ *
+ * TWO gates, both required. `--tools` is the consumer's selection; the
+ * capability axis is the evidence. A host is registered only where BOTH say so,
+ * so a config file this package already writes for hooks does not silently
+ * acquire an MCP entry on the strength of the file existing.
+ *
+ * `claude-code` is excluded here on purpose: its `.mcp.json` registration
+ * predates the axis and is written unconditionally by `makeEnsureMcpBridge`.
+ * Routing it through the axis would DELETE a working registration, because the
+ * axis reports `false` for every host today — "nobody answered", not "checked
+ * and absent". This function adds reach; it never removes any.
+ *
+ * MEASURED STATE, 2026-09-07: the capability registry carries one row
+ * (`claude`) and it does not set `reads_project_mcp_config`, so this returns an
+ * EMPTY list for every `--tools` set. That is the honest reading of the axis,
+ * not a defect in this function — and it is a recorded absence, never a finding
+ * that these hosts do not read such a file.
+ */
+export function mcpRegistrationTargets(
+    tools: ReadonlySet<string>,
+    readsConfig: ReadsProjectMcpConfig,
+): McpRegistrationTarget[] {
+    const out: McpRegistrationTarget[] = [];
+    for (const [toolId, spec] of Object.entries(MCP_PROJECT_CONFIG)) {
+        if (toolId === 'claude-code') continue;
+        if (!tools.has(toolId)) continue;
+        if (!readsConfig(spec.hostId)) continue;
+        out.push({ toolId, hostId: spec.hostId, relPath: spec.relPath });
+    }
+    return out;
+}
+
+/**
+ * Merge the server entry into every target's config file.
+ *
+ * Returns the merged keys per tool id, in the shape the installer's
+ * `merged_keys_by_tool` lockfile record expects. An empty map is the normal
+ * result today and is not an error.
+ */
+export function makeEnsureMcpRegistrations(
+    mergeJsonFile: MergeJsonFile,
+): (
+    projectRoot: string,
+    force: boolean,
+    packageRoot: string,
+    targets: readonly McpRegistrationTarget[],
+) => Record<string, Record<string, unknown>[]> {
+    return (projectRoot, force, packageRoot, targets) => {
+        const merged: Record<string, Record<string, unknown>[]> = {};
+        for (const t of targets) {
+            merged[t.toolId] = mergeJsonFile(
+                path.join(projectRoot, ...t.relPath.split('/')),
+                mcpBridgeEntry(packageRoot),
+                force,
+                t.relPath,
+            );
+        }
+        return merged;
+    };
+}
+
+/** The axis reader the installer uses. Injected in tests, never overridden there. */
+function readsProjectMcpConfig(hostId: string): boolean {
+    return probeHostCapabilities(hostId).reads_project_mcp_config;
+}
+
+/**
+ * Write every MCP registration one install owes, and record the merged keys.
+ *
+ * ONE call site rather than three, because `install.ts` is 3,900 lines over the
+ * source-size ratchet's ceiling and every line added there is a line the ratchet
+ * charges for. The composition is the same either way; where it lives is the
+ * only thing that differs, and it belongs beside the entry it writes.
+ *
+ * `claude-code` is registered whenever it is selected — that write predates the
+ * axis and routing it through would DELETE it, the axis being `false` for every
+ * host today. Every OTHER host needs both gates: the `--tools` selection and an
+ * OBSERVED `reads_project_mcp_config`.
+ */
+export function registerMcpHosts(
+    mergeJsonFile: MergeJsonFile,
+    projectRoot: string,
+    force: boolean,
+    packageRoot: string,
+    tools: ReadonlySet<string>,
+    into: Record<string, Record<string, unknown>[]>,
+    readsConfig: ReadsProjectMcpConfig = readsProjectMcpConfig,
+): void {
+    const ensure = makeEnsureMcpRegistrations(mergeJsonFile);
+    const claude = MCP_PROJECT_CONFIG['claude-code'];
+    if (tools.has('claude-code') && claude !== undefined) {
+        const merged = ensure(projectRoot, force, packageRoot, [
+            { toolId: 'claude-code', hostId: claude.hostId, relPath: claude.relPath },
+        ]);
+        (into['claude-code'] ??= []).push(...(merged['claude-code'] ?? []));
+    }
+    for (const [toolId, keys] of Object.entries(
+        ensure(projectRoot, force, packageRoot, mcpRegistrationTargets(tools, readsConfig)),
+    )) {
+        (into[toolId] ??= []).push(...keys);
+    }
+}
+
+/**
+ * Rewrite a stale `.mcp.json` entry in place, touching only the key we own.
+ *
+ * Install writes the entry once; nothing re-read it afterwards, so a pin
+ * written by one install stayed frozen at that version for the life of the
+ * file — which is exactly the drift the pin was added to close, one release
+ * later. This is the update path.
+ *
+ * Scope discipline: the ONLY key rewritten is `mcpServers[MCP_SERVER_KEY]`.
+ * A server a consumer added by hand sits beside it and is not read, compared,
+ * reordered or rewritten — the same contract `merge_json_file` honours on the
+ * install path, and the reason uninstall can subtract exactly one key.
+ *
+ * Returns `'absent'` (no file, or no entry of ours to repair — install owns
+ * that case, not this one), `'current'`, or `'rewritten'`.
+ */
+export function migrateMcpBridge(
+    projectRoot: string,
+    packageRoot: string,
+): 'absent' | 'current' | 'rewritten' {
+    const file = path.join(projectRoot, '.mcp.json');
+    let doc: Record<string, unknown>;
+    try {
+        doc = JSON.parse(fs.readFileSync(file, 'utf-8')) as Record<string, unknown>;
+    } catch {
+        return 'absent';
+    }
+    const servers = doc['mcpServers'];
+    if (servers === null || typeof servers !== 'object' || Array.isArray(servers)) return 'absent';
+    const table = servers as Record<string, unknown>;
+    if (table[MCP_SERVER_KEY] === undefined) return 'absent';
+
+    const wanted = (mcpBridgeEntry(packageRoot)['mcpServers'] as Record<string, unknown>)[
+        MCP_SERVER_KEY
+    ];
+    if (JSON.stringify(table[MCP_SERVER_KEY]) === JSON.stringify(wanted)) return 'current';
+
+    table[MCP_SERVER_KEY] = wanted;
+    fs.writeFileSync(file, `${JSON.stringify(doc, null, 2)}\n`, 'utf-8');
+    return 'rewritten';
 }
 
 /**