@bridge_gpt/mcp-server 0.2.67 → 0.2.69

package/build/bridge-permissions.js

@@ -0,0 +1,1362 @@
+/**
+ * Bridge-managed Claude Code permission rules for the `/drive-epic-run`
+ * supervisor (BAPI-1398, AC-8), and the one pinned SessionStart upgrade-notice
+ * hook (BAPI-1446).
+ *
+ * The supervisor runs in auto mode. Every in-scope action it takes — a
+ * sanctioned CLI verb, a Bridge MCP tool, a read, a tally write — must resolve
+ * without a permission prompt or a classifier denial. Narrow
+ * `permissions.allow` rules resolve before the auto-mode classifier, so the
+ * installer writes one exact rule for every shell and tool form the posture
+ * prescribes, into the project's LOCAL settings file,
+ * `.claude/settings.local.json`. Claude Code reads that file as project-scoped
+ * settings, and it is per developer and gitignored. The rules must never go into
+ * the committed `.claude/settings.json`: they can hold a developer's own
+ * launcher path, they belong to one developer's manifest, and a committed allow
+ * rule would widen every teammate's sessions. The MCP tool rules are written
+ * under the key the server is actually registered as in `.mcp.json` (canonical
+ * `bridge`, or a kept legacy registration key), so they match the tool
+ * names Claude Code really sees. The auto-mode
+ * classifier ignores `autoMode` in project settings, so the prose
+ * `autoMode.allow` / `autoMode.environment` entries go into the USER's
+ * `~/.claude/settings.json` — and only with the user's explicit consent. Install
+ * never asks for it (BAPI-1448): the `bridge-permissions` subcommand
+ * ({@link runBridgePermissionsCli}) owns that write, and `/drive-epic-run` offers
+ * it in-session only when the entries are missing.
+ *
+ * Ownership. A JSON string in an allow list cannot carry a marker, and Claude
+ * Code's settings loader is not given unknown keys. Bridge therefore records the
+ * exact strings it inserted in its own manifest, `.bridge/bridge-permissions.json`
+ * (gitignored, per developer). `doctor` reads it to report present / missing /
+ * drifted, and removal deletes exactly those strings. A string the user already
+ * had before Bridge wrote it is never claimed, so removal never takes it away.
+ * The manifest is separate from `.bridge/install-state.json` because that file's
+ * contract forbids absolute home paths, and a local launcher override is often
+ * one.
+ *
+ * File discipline matches `claude-settings.ts`: a missing settings file is `{}`;
+ * a malformed one is reported as `malformed` and never written; changed files
+ * are written with a 2-space indent and one trailing newline; an unchanged file
+ * is not rewritten, so a second run leaves every file byte-identical.
+ *
+ * Never broad: no `Bash(*)`, no wildcard launcher, and no rule that covers a
+ * credential file. A launcher override that cannot be written as an exact,
+ * secret-free command prefix is refused rather than approximated.
+ *
+ * The SessionStart hook (BAPI-1446) lives in the same local settings file and is
+ * owned the same way: the manifest's `hooks.SessionStart` records the one exact
+ * command Bridge wrote, removal deletes exactly that command, and permission and
+ * hook changes share one settings snapshot so neither overwrites the other.
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { inspectClaudeHookContainers, mergeClaudeSettingsWithCommandHookChecked, removeClaudeSettingsCommandHook, } from "./claude-settings.js";
+import { MCP_PACKAGE_NAME, MCP_SERVER_NAME, resolveRegistrationKey } from "./mcp-identity.js";
+import { isPlainReleaseVersion } from "./update-check.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** The environment variable the posture reads for a local launcher override. */
+export const BRIDGE_LAUNCHER_ENV = "BAPI_MCP_CLI";
+/** The default packaged launcher prefix — byte-identical to the posture's default. */
+export const BRIDGE_DEFAULT_LAUNCHER = `npx -y ${MCP_PACKAGE_NAME}`;
+/** Repository-relative path of Bridge's permission-ownership manifest. */
+export const BRIDGE_PERMISSIONS_MANIFEST_RELPATH = ".bridge/bridge-permissions.json";
+/**
+ * Repository-relative path of the project settings file the rules go into. It is
+ * the per-developer, gitignored local file — never the committed
+ * `.claude/settings.json`.
+ */
+export const BRIDGE_PROJECT_SETTINGS_RELPATH = ".claude/settings.local.json";
+/** Current manifest schema version. */
+export const BRIDGE_PERMISSIONS_MANIFEST_VERSION = 1;
+/** The Claude Code hook event the upgrade notice runs on. */
+export const SESSION_START_HOOK_EVENT = "SessionStart";
+/** The exact arguments after the launcher: the internal offline check command. */
+export const SESSION_START_HOOK_SUFFIX = "check-update --hook claude-session-start";
+/** Run only on a fresh session start, not on resume, clear, or compact. */
+export const SESSION_START_HOOK_MATCHER = "startup";
+/** Seconds Claude Code waits for the hook. A cold `npx` launch can exceed it. */
+export const SESSION_START_HOOK_TIMEOUT_SECONDS = 5;
+/** The auto-mode sentinel that keeps Claude Code's built-in entries in a list. */
+export const AUTO_MODE_DEFAULTS_SENTINEL = "$defaults";
+/**
+ * The sanctioned recovery verbs, as their packaged CLI subcommands, in
+ * the posture's verb-table order. Adding a verb here without adding it to the
+ * posture's verb table (or the reverse) is caught by the static coverage test.
+ */
+export const BRIDGE_SANCTIONED_VERB_SUBCOMMANDS = [
+    "unpark",
+    "continue-child",
+    "grant-continuation",
+    "adopt-current-head-and-unpark",
+    "stop-run",
+    "abandon-run",
+    "scope-reparse",
+    "dispatch-remediation",
+    "merge-child",
+    "scope-catch-up",
+    "patch-policy",
+    "resume-run",
+    "resume-ci",
+    "rerun-ci",
+];
+/** The Bridge MCP tools the supervisor calls. */
+export const BRIDGE_SUPERVISOR_MCP_TOOLS = [
+    "ping",
+    "explain_run",
+    "get_epic_snapshot",
+    "poll_ci_checks",
+    "second_opinion",
+    "report_mcp_bug",
+    // BAPI-1399: the prerequisite scan reads the epic and its child tickets.
+    "get_ticket",
+];
+/** The private run-state directory the tally, patch, and context files live in. */
+export const BRIDGE_RUN_STATE_DIR = "~/.local/state/bapi-conductor-runs";
+/**
+ * Launcher override characters that cannot be part of an exact, safe rule
+ * prefix: shell operators, quotes (the posture writes the launcher unquoted),
+ * rule-pattern metacharacters, an environment assignment (`=`), and a home
+ * shorthand that the shell would expand differently from the rule.
+ */
+const UNSAFE_LAUNCHER_PATTERN = /[;&|<>$`\\'"*?()[\]{}=~\n\r\t\0]/;
+/** Upper bound on a launcher override, so a pasted blob is never a rule. */
+const MAX_LAUNCHER_CHARS = 256;
+/** Tokens that suggest a credential was pasted into the launcher value. */
+const SECRET_LIKE_PATTERN = /(api[_-]?key|token|secret|passw(or)?d|bearer|bapi_[a-z0-9]{8,})/i;
+/**
+ * Resolve the launcher prefix exactly as the posture resolves it: unset, empty,
+ * or whitespace-only means the default packaged launcher; anything else is used
+ * verbatim. Internal runs of whitespace collapse to one space, because that is
+ * how the posture writes the launcher's words. An override that cannot be an
+ * exact, secret-free prefix is refused — never approximated with a wildcard.
+ * The refusal reason never echoes the value.
+ */
+export function resolvePermissionLauncher(env) {
+    const raw = env[BRIDGE_LAUNCHER_ENV];
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return { ok: true, prefix: BRIDGE_DEFAULT_LAUNCHER, source: "default" };
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length > MAX_LAUNCHER_CHARS) {
+        return { ok: false, reason: `${BRIDGE_LAUNCHER_ENV} is longer than ${MAX_LAUNCHER_CHARS} characters` };
+    }
+    if (UNSAFE_LAUNCHER_PATTERN.test(trimmed)) {
+        return {
+            ok: false,
+            reason: `${BRIDGE_LAUNCHER_ENV} contains a quote, shell operator, wildcard, or assignment, ` +
+                "so it cannot be matched by an exact permission rule",
+        };
+    }
+    if (SECRET_LIKE_PATTERN.test(trimmed)) {
+        return {
+            ok: false,
+            reason: `${BRIDGE_LAUNCHER_ENV} looks like it carries a credential, which must never be part of a rule`,
+        };
+    }
+    return { ok: true, prefix: trimmed.split(/\s+/).join(" "), source: "override" };
+}
+// ---------------------------------------------------------------------------
+// Rule catalogs
+// ---------------------------------------------------------------------------
+/**
+ * The project `permissions.allow` catalog for one launcher prefix. Every entry is
+ * an exact command or an exact prefix followed by its arguments — never a broad
+ * rule. `serverNames` are the MCP registration keys the tool rules are written
+ * under (see {@link resolveSupervisorServerNames}). Order is stable so output and
+ * the manifest are deterministic.
+ */
+export function buildProjectPermissionRules(launcherPrefix, serverNames = [MCP_SERVER_NAME]) {
+    const rules = [];
+    // The sanctioned verbs, in the launcher's exact form.
+    for (const verb of BRIDGE_SANCTIONED_VERB_SUBCOMMANDS) {
+        rules.push(`Bash(${launcherPrefix} epic-implementer ${verb} *)`);
+    }
+    // drive-epic preview and attach, and the readiness reads.
+    rules.push(`Bash(${launcherPrefix} drive-epic *)`);
+    rules.push(`Bash(${launcherPrefix} epic-implementer readiness *)`);
+    // Read-only supporting commands.
+    rules.push(`Bash(${launcherPrefix} epic-implementer continuation-receipt *)`);
+    rules.push(`Bash(${launcherPrefix} epic-implementer doctor)`);
+    rules.push(`Bash(${launcherPrefix} plane status)`);
+    // BAPI-1448: the read-only user-scope check `/drive-epic-run` runs first. There is
+    // deliberately NO rule for `--user-consented`: Claude Code's own permission prompt
+    // for that write is the second consent layer.
+    rules.push(`Bash(${launcherPrefix} bridge-permissions --check --json)`);
+    rules.push("Bash(pmset -g log)");
+    rules.push("Bash(git ls-tree *)");
+    rules.push("Bash(gh auth status)");
+    // Stage 0's local checks, exactly as the posture spells them.
+    rules.push("Bash(source .venv/bin/activate)");
+    rules.push("Bash(ENVIRONMENT=TEST python scripts/conductor_health_check.py --json)");
+    rules.push("Bash(alembic -c alembic.ini heads)");
+    rules.push("Bash(alembic -c alembic.ini current)");
+    // The private tally directory: create, restrict, read, and append.
+    rules.push(`Bash(mkdir -p ${BRIDGE_RUN_STATE_DIR}/*)`);
+    rules.push(`Bash(chmod 700 ${BRIDGE_RUN_STATE_DIR}/*)`);
+    rules.push(`Bash(chmod 600 ${BRIDGE_RUN_STATE_DIR}/*)`);
+    rules.push(`Read(${BRIDGE_RUN_STATE_DIR}/**)`);
+    rules.push(`Edit(${BRIDGE_RUN_STATE_DIR}/**)`);
+    rules.push(`Write(${BRIDGE_RUN_STATE_DIR}/**)`);
+    // BAPI-1399: the value-free prerequisite presence check, exactly as prescribed.
+    // Only a validated variable name fills the `*`; the form prints present or missing.
+    rules.push('Bash([ -n "${*:+x}" ] && echo present || echo missing)');
+    // Claude Code checks each `&&` / `||` segment of a compound command on its
+    // own, so each segment of the prescribed form has its own exact rule. A
+    // segment outside these three (for example one that prints a value) matches
+    // no rule.
+    rules.push('Bash([ -n "${*:+x}" ])');
+    rules.push("Bash(echo present)");
+    rules.push("Bash(echo missing)");
+    // BAPI-1399: reading `.bridge/epic-workarounds/` at the fetched epic head, and
+    // the marker-checked hand-off comment on the run's own integration PR. The
+    // `workarounds.md` write is covered by the run-state Write rule above.
+    rules.push("Bash(git fetch origin 'epic/*')");
+    rules.push("Bash(git rev-parse 'origin/epic/*')");
+    rules.push("Bash(git show '*:.bridge/epic-workarounds/*.md')");
+    rules.push("Bash(gh pr view 'epic/*' --json number,isDraft,state,headRefOid,baseRefName,comments)");
+    rules.push(`Bash(gh pr comment * --body-file ${BRIDGE_RUN_STATE_DIR}/*/workarounds.md)`);
+    // The notes-log commit on docs/<KEY>-conductor-run-notes.
+    rules.push("Bash(git switch -c 'docs/*-conductor-run-notes')");
+    rules.push("Bash(git add docs/epic-implementer/run-notes/)");
+    rules.push("Bash(git commit -m * -- docs/epic-implementer/run-notes/)");
+    // The Bridge MCP tools the supervisor uses, under each installed server key.
+    for (const serverName of serverNames) {
+        for (const tool of BRIDGE_SUPERVISOR_MCP_TOOLS) {
+            rules.push(`mcp__${serverName}__${tool}`);
+        }
+    }
+    return rules;
+}
+/**
+ * The user-settings `autoMode` prose. It describes the run sandbox — the run's
+ * branches and worktrees, the Bridge server, and third-party sandbox accounts the
+ * project explicitly names — so the classifier treats the supervisor's in-scope
+ * work as routine. `sandboxAccounts` adds named accounts when a caller knows them;
+ * none is ever inferred.
+ */
+export function buildUserAutoModeEntries(sandboxAccounts = []) {
+    const named = sandboxAccounts.map((a) => a.trim()).filter((a) => a.length > 0);
+    const accounts = named.length > 0
+        ? `the third-party sandbox accounts the project names (${named.join(", ")})`
+        : "any third-party sandbox account the project explicitly names as a sandbox in its configuration or documentation";
+    return {
+        environment: [
+            "Bridge Epic Implementer runs (/drive-epic-run): a run's sandbox is its own branches " +
+                "(epic/<KEY> and each child ticket's branch_name) and the worktrees made for them, " +
+                `the Bridge server, and ${accounts}.`,
+        ],
+        allow: [
+            "Bridge /drive-epic-run supervisor: the packaged Bridge CLI's sanctioned " +
+                "epic-implementer recovery verbs, drive-epic preview and attach, and readiness, applied " +
+                "to the run's own sandbox; reads, waits, the private tally under " +
+                `${BRIDGE_RUN_STATE_DIR}/, and Bridge bug reports.`,
+        ],
+    };
+}
+/** Absolute path of the project's local (gitignored) Claude settings file. */
+export function projectSettingsPath(cwd) {
+    return path.join(cwd, ...BRIDGE_PROJECT_SETTINGS_RELPATH.split("/"));
+}
+/**
+ * The MCP registration keys the tool rules must be written under, read from the
+ * project's `.mcp.json`. A canonical or legacy registration yields its own key;
+ * a conflict (both keys present) yields both, so whichever one Claude Code loads
+ * is covered. A missing, malformed, or Bridge-less file yields the canonical key,
+ * because that is the key a fresh install writes.
+ */
+export async function resolveSupervisorServerNames(cwd, deps) {
+    let servers;
+    try {
+        const parsed = JSON.parse(await deps.readFile(path.join(cwd, ".mcp.json")));
+        servers =
+            parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+                ? parsed.mcpServers
+                : undefined;
+    }
+    catch {
+        servers = undefined;
+    }
+    const resolution = resolveRegistrationKey(servers);
+    if (resolution.state === "canonical" || resolution.state === "legacy")
+        return [resolution.key];
+    if (resolution.state === "conflict")
+        return [...resolution.keys];
+    return [MCP_SERVER_NAME];
+}
+/** Absolute path of the user's Claude settings file. */
+export function userSettingsPath(homeDir) {
+    return path.join(homeDir, ".claude", "settings.json");
+}
+/** Absolute path of Bridge's permission-ownership manifest. */
+export function bridgePermissionsManifestPath(cwd) {
+    return path.join(cwd, ...BRIDGE_PERMISSIONS_MANIFEST_RELPATH.split("/"));
+}
+/**
+ * Read a settings file: missing is `{}`-equivalent, malformed is never used. Only
+ * `ENOENT` means missing. Any other read error (`EACCES` included) is refused like
+ * malformed JSON, so no writer replaces a file it could not read.
+ */
+export async function readSettingsFile(filePath, deps) {
+    let raw;
+    try {
+        raw = await deps.readFile(filePath);
+    }
+    catch (error) {
+        const code = error?.code;
+        return code === "ENOENT" ? { status: "missing" } : { status: "malformed" };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { status: "malformed" };
+        }
+        return { status: "valid", settings: parsed, raw };
+    }
+    catch {
+        return { status: "malformed" };
+    }
+}
+function serializeSettings(settings) {
+    return `${JSON.stringify(settings, null, 2)}\n`;
+}
+function emptyManifest() {
+    return {
+        version: BRIDGE_PERMISSIONS_MANIFEST_VERSION,
+        launcher: null,
+        project: [],
+        userAllow: [],
+        userEnvironment: [],
+    };
+}
+function stringList(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.every((v) => typeof v === "string") ? value : null;
+}
+/** Read and validate the manifest. An invalid manifest owns nothing. */
+export async function readBridgePermissionsManifest(cwd, deps) {
+    let raw;
+    try {
+        raw = await deps.readFile(bridgePermissionsManifestPath(cwd));
+    }
+    catch {
+        return { status: "missing" };
+    }
+    try {
+        const doc = JSON.parse(raw);
+        if (doc === null || typeof doc !== "object" || Array.isArray(doc))
+            return { status: "invalid" };
+        if (doc.version !== BRIDGE_PERMISSIONS_MANIFEST_VERSION)
+            return { status: "invalid" };
+        const project = stringList(doc.project);
+        const userAllow = stringList(doc.userAllow);
+        const userEnvironment = stringList(doc.userEnvironment);
+        const launcher = doc.launcher;
+        if (!project || !userAllow || !userEnvironment)
+            return { status: "invalid" };
+        if (launcher !== null && typeof launcher !== "string")
+            return { status: "invalid" };
+        const manifest = {
+            version: BRIDGE_PERMISSIONS_MANIFEST_VERSION,
+            launcher,
+            project,
+            userAllow,
+            userEnvironment,
+        };
+        if (doc.hooks !== undefined) {
+            const hooks = doc.hooks;
+            if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks))
+                return { status: "invalid" };
+            const sessionStart = stringList(hooks[SESSION_START_HOOK_EVENT]);
+            if (!sessionStart)
+                return { status: "invalid" };
+            manifest.hooks = { SessionStart: sessionStart };
+        }
+        return { status: "valid", manifest };
+    }
+    catch {
+        return { status: "invalid" };
+    }
+}
+/** Serialize the manifest with a stable key order. */
+export function serializeBridgePermissionsManifest(manifest) {
+    const doc = {
+        version: manifest.version,
+        launcher: manifest.launcher,
+        project: manifest.project,
+        userAllow: manifest.userAllow,
+        userEnvironment: manifest.userEnvironment,
+    };
+    // Written last and only when something is owned, so a manifest without hooks
+    // serializes byte-for-byte as it did before hooks existed.
+    if (manifest.hooks && manifest.hooks.SessionStart.length > 0) {
+        doc.hooks = { SessionStart: manifest.hooks.SessionStart };
+    }
+    return `${JSON.stringify(doc, null, 2)}\n`;
+}
+async function writeManifestIfChanged(cwd, next, deps) {
+    const target = bridgePermissionsManifestPath(cwd);
+    const text = serializeBridgePermissionsManifest(next);
+    let current = null;
+    try {
+        current = await deps.readFile(target);
+    }
+    catch {
+        current = null;
+    }
+    if (current === text)
+        return true;
+    try {
+        await deps.mkdir(path.dirname(target), { recursive: true });
+        await deps.writeFile(target, text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeSettings(filePath, settings, deps) {
+    try {
+        await deps.mkdir(path.dirname(filePath), { recursive: true });
+        await deps.writeFile(filePath, serializeSettings(settings));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// List helpers
+// ---------------------------------------------------------------------------
+/** The `permissions.allow` list, `[]` when absent, or null when not a string list. */
+function projectAllowList(settings) {
+    const permissions = settings.permissions;
+    if (permissions === undefined)
+        return [];
+    if (permissions === null || typeof permissions !== "object" || Array.isArray(permissions))
+        return null;
+    const allow = permissions.allow;
+    if (allow === undefined)
+        return [];
+    return stringList(allow);
+}
+function withProjectAllowList(settings, allow) {
+    const permissions = settings.permissions && typeof settings.permissions === "object"
+        ? settings.permissions
+        : {};
+    return { ...settings, permissions: { ...permissions, allow } };
+}
+/** An `autoMode` list, `undefined` when absent, or null when not a string list. */
+function autoModeList(settings, key) {
+    const autoMode = settings.autoMode;
+    if (autoMode === undefined)
+        return undefined;
+    if (autoMode === null || typeof autoMode !== "object" || Array.isArray(autoMode))
+        return null;
+    const list = autoMode[key];
+    if (list === undefined)
+        return undefined;
+    return stringList(list);
+}
+function withAutoModeLists(settings, lists) {
+    const autoMode = settings.autoMode && typeof settings.autoMode === "object"
+        ? settings.autoMode
+        : {};
+    return { ...settings, autoMode: { ...autoMode, ...lists } };
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+/**
+ * Build the SessionStart hook command for a resolved launcher and a validated pin.
+ * The default launcher is pinned by appending `@<pin>` to its package token; a
+ * valid `BAPI_MCP_CLI` override already names its own build and gets the exact
+ * hook suffix appended unchanged.
+ */
+export function buildSessionStartHookCommand(launcher, pinnedVersion) {
+    const prefix = launcher.source === "default" ? `${launcher.prefix}@${pinnedVersion}` : launcher.prefix;
+    return `${prefix} ${SESSION_START_HOOK_SUFFIX}`;
+}
+/** Every command leaf registered for an event, in order. */
+function sessionStartCommands(settings) {
+    const hooks = settings.hooks;
+    if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks))
+        return [];
+    const entries = hooks[SESSION_START_HOOK_EVENT];
+    if (!Array.isArray(entries))
+        return [];
+    const commands = [];
+    for (const entry of entries) {
+        const leaves = entry?.hooks;
+        if (!Array.isArray(leaves))
+            continue;
+        for (const leaf of leaves) {
+            const found = leaf;
+            if (found && found.type === "command" && typeof found.command === "string") {
+                commands.push(found.command);
+            }
+        }
+    }
+    return commands;
+}
+/**
+ * True when `command` is registered exactly once, in an entry that carries the
+ * startup matcher, on a leaf that carries the five-second timeout.
+ */
+function isHookConfiguredCorrectly(settings, command) {
+    const hooks = settings.hooks;
+    const entries = hooks[SESSION_START_HOOK_EVENT];
+    let found = 0;
+    let correct = false;
+    for (const entry of entries) {
+        const leaves = entry?.hooks;
+        if (!Array.isArray(leaves))
+            continue;
+        for (const leaf of leaves) {
+            const candidate = leaf;
+            if (candidate && candidate.type === "command" && candidate.command === command) {
+                found += 1;
+                correct =
+                    entry.matcher === SESSION_START_HOOK_MATCHER &&
+                        candidate.timeout === SESSION_START_HOOK_TIMEOUT_SECONDS;
+            }
+        }
+    }
+    return found === 1 && correct;
+}
+/**
+ * Is an UNRECORDED command narrowly recognizable as Bridge's own hook? Only on
+ * install or upgrade, and only when the whole string is the default exact-pinned
+ * launcher or the current override prefix, followed by the exact hook suffix.
+ * `@latest`, an unpinned launcher, extra flags, another executable, and another
+ * package path are all NOT recognized.
+ */
+function isRecognizedBridgeHookCommand(command, launcher) {
+    if (launcher.source === "override" && command === `${launcher.prefix} ${SESSION_START_HOOK_SUFFIX}`) {
+        return true;
+    }
+    const lead = `${BRIDGE_DEFAULT_LAUNCHER}@`;
+    const tail = ` ${SESSION_START_HOOK_SUFFIX}`;
+    if (!command.startsWith(lead) || !command.endsWith(tail))
+        return false;
+    return isPlainReleaseVersion(command.slice(lead.length, command.length - tail.length));
+}
+/** A command that looks like a Bridge hook without being recognized as one. */
+function looksLikeBridgeHook(command) {
+    return command.includes("check-update") && command.includes("claude-session-start");
+}
+/**
+ * Compute the settings that leave exactly one correctly configured Bridge hook,
+ * in memory. Owned commands are the manifest-recorded ones plus, on install or
+ * upgrade only, narrowly recognized unrecorded ones. Every owned command is
+ * removed before the desired one is merged, so a changed pin is replaced rather
+ * than duplicated; commands that are not owned are never touched.
+ */
+function planSessionStartHook(settings, command, recorded, launcher) {
+    // A present-but-wrong-typed `hooks` or `SessionStart` is refused, never replaced.
+    if (inspectClaudeHookContainers(settings, [SESSION_START_HOOK_EVENT]) === "malformed") {
+        return "malformed";
+    }
+    const present = sessionStartCommands(settings);
+    const recordedSet = new Set(recorded);
+    const owned = unique(present.filter((c) => recordedSet.has(c) || isRecognizedBridgeHookCommand(c, launcher)));
+    const unrecognized = present.filter((c) => !owned.includes(c) && looksLikeBridgeHook(c)).length;
+    const others = owned.filter((c) => c !== command);
+    if (others.length === 0 && present.includes(command) && isHookConfiguredCorrectly(settings, command)) {
+        return { settings, changed: false, command, replaced: 0, unrecognized };
+    }
+    let working = settings;
+    for (const stale of owned) {
+        working = removeClaudeSettingsCommandHook(working, SESSION_START_HOOK_EVENT, stale);
+    }
+    const rebuilt = mergeClaudeSettingsWithCommandHookChecked(working, command, [SESSION_START_HOOK_EVENT], {
+        eventMatchers: { [SESSION_START_HOOK_EVENT]: SESSION_START_HOOK_MATCHER },
+        eventTimeouts: { [SESSION_START_HOOK_EVENT]: SESSION_START_HOOK_TIMEOUT_SECONDS },
+    });
+    if (!rebuilt.ok)
+        return "malformed";
+    return { settings: rebuilt.settings, changed: true, command, replaced: others.length, unrecognized };
+}
+/**
+ * Write the project `permissions.allow` catalog for the resolved launcher, and
+ * optionally the pinned SessionStart hook.
+ *
+ * Only missing strings are appended; every other entry and key is kept. Strings
+ * Bridge recorded earlier that are no longer desired (for example after the
+ * launcher changed) are removed. The manifest gains exactly the strings this run
+ * inserted. Nothing is written when nothing changes.
+ *
+ * Permissions and the hook are applied to ONE settings snapshot and written once,
+ * and the manifest is written only after the settings write succeeds. A scope that
+ * cannot be changed safely (malformed structure, failed write) keeps its prior
+ * ownership record, and a settings success followed by a manifest failure is
+ * reported as a `partial` hook outcome rather than as full provisioning.
+ */
+export async function applyProjectPermissions(params, deps) {
+    const launcher = resolvePermissionLauncher(params.env);
+    const request = params.sessionStartHook;
+    if (!launcher.ok) {
+        return {
+            launcher,
+            project: { status: "launcher-refused", skipped: [] },
+            manifestRecorded: false,
+            ...(request ? { hook: { status: "refused", reason: launcher.reason } } : {}),
+        };
+    }
+    const desired = buildProjectPermissionRules(launcher.prefix, await resolveSupervisorServerNames(params.cwd, deps));
+    const settingsPath = projectSettingsPath(params.cwd);
+    const manifestRead = await readBridgePermissionsManifest(params.cwd, deps);
+    const manifest = manifestRead.status === "valid" ? manifestRead.manifest : emptyManifest();
+    const read = await readSettingsFile(settingsPath, deps);
+    if (read.status === "malformed") {
+        return {
+            launcher,
+            project: { status: "malformed", path: settingsPath, skipped: desired },
+            manifestRecorded: false,
+            ...(request ? { hook: invalidPinOr(request, { status: "malformed", path: settingsPath }) } : {}),
+        };
+    }
+    const current = read.status === "valid" ? read.settings : {};
+    let working = current;
+    // ---- Permission rules ----
+    const allow = projectAllowList(current);
+    let project;
+    let permissionsChanged = false;
+    let permissionsApplied = false;
+    let inserted = [];
+    let ownedStill = manifest.project;
+    if (allow === null) {
+        project = { status: "malformed", path: settingsPath, skipped: desired };
+    }
+    else {
+        const desiredSet = new Set(desired);
+        const stale = manifest.project.filter((rule) => !desiredSet.has(rule));
+        const staleSet = new Set(stale);
+        const removedStale = allow.filter((rule) => staleSet.has(rule));
+        const kept = allow.filter((rule) => !staleSet.has(rule));
+        const keptSet = new Set(kept);
+        inserted = desired.filter((rule) => !keptSet.has(rule));
+        const alreadyPresent = desired.filter((rule) => keptSet.has(rule));
+        if (inserted.length > 0 || removedStale.length > 0) {
+            working = withProjectAllowList(working, [...kept, ...inserted]);
+            permissionsChanged = true;
+        }
+        ownedStill = manifest.project.filter((rule) => desiredSet.has(rule));
+        permissionsApplied = true;
+        project = {
+            status: "unchanged",
+            path: settingsPath,
+            inserted,
+            alreadyPresent,
+            removedStale,
+        };
+    }
+    // ---- SessionStart hook ----
+    let hookPlan = null;
+    let hook;
+    if (request) {
+        if (!isPlainReleaseVersion(request.pinnedVersion)) {
+            hook = { status: "skipped", reason: "invalid-pin" };
+        }
+        else {
+            const command = buildSessionStartHookCommand(launcher, request.pinnedVersion);
+            const planned = planSessionStartHook(working, command, manifest.hooks?.SessionStart ?? [], launcher);
+            if (planned === "malformed") {
+                hook = { status: "malformed", path: settingsPath };
+            }
+            else {
+                hookPlan = planned;
+                working = planned.settings;
+            }
+        }
+    }
+    const hookChanged = hookPlan?.changed === true;
+    // ---- One settings write ----
+    if (permissionsChanged || hookChanged) {
+        const ok = await writeSettings(settingsPath, working, deps);
+        if (!ok) {
+            return {
+                launcher,
+                project: permissionsApplied
+                    ? { status: "io-error", path: settingsPath, skipped: inserted }
+                    : project,
+                manifestRecorded: false,
+                ...(request ? { hook: hookPlan ? { status: "io-error", path: settingsPath } : hook } : {}),
+            };
+        }
+        if (project.status === "unchanged" && permissionsChanged)
+            project = { ...project, status: "written" };
+    }
+    // ---- One manifest write, after the settings are durable ----
+    const nextManifest = { ...manifest };
+    if (permissionsApplied) {
+        nextManifest.launcher = launcher.prefix;
+        nextManifest.project = unique([...ownedStill, ...inserted]);
+    }
+    if (hookPlan)
+        nextManifest.hooks = { SessionStart: [hookPlan.command] };
+    const needsManifest = permissionsApplied || hookPlan !== null;
+    const manifestRecorded = needsManifest ? await writeManifestIfChanged(params.cwd, nextManifest, deps) : false;
+    if (hookPlan) {
+        const base = {
+            path: settingsPath,
+            command: hookPlan.command,
+            replaced: hookPlan.replaced,
+            unrecognized: hookPlan.unrecognized,
+        };
+        hook = manifestRecorded
+            ? { status: hookChanged ? "written" : "unchanged", ...base }
+            : { status: "partial", ...base };
+    }
+    return { launcher, project, manifestRecorded, ...(request && hook ? { hook } : {}) };
+}
+/**
+ * Plain-language report lines for a hook outcome, shared by install and upgrade so
+ * the two cannot drift. `lines` are progress; `warnings` need attention but never
+ * change a primary exit code. Nothing here echoes a similar-looking user command:
+ * unrecognized candidates are counted only.
+ */
+export function describeSessionStartHookOutcome(hook) {
+    const lines = [];
+    const warnings = [];
+    switch (hook.status) {
+        case "written":
+        case "unchanged":
+        case "partial": {
+            if (hook.status === "written") {
+                lines.push(`SessionStart upgrade-notice hook (Claude Code only, per developer) in ${hook.path}:`);
+                lines.push(`  wrote ${hook.command}`);
+                if (hook.replaced > 0) {
+                    lines.push(`  replaced ${hook.replaced} earlier Bridge hook command(s) with this one`);
+                }
+            }
+            else if (hook.status === "unchanged") {
+                lines.push(`SessionStart upgrade-notice hook already present in ${hook.path}.`);
+            }
+            else {
+                warnings.push(`the SessionStart upgrade-notice hook was written to ${hook.path}, but ` +
+                    `${BRIDGE_PERMISSIONS_MANIFEST_RELPATH} could not be updated; doctor and removal may not see it`);
+            }
+            if (hook.unrecognized > 0) {
+                warnings.push(`${hook.unrecognized} existing SessionStart command(s) resemble Bridge's hook but were not ` +
+                    "recognized as Bridge's, so they were left in place");
+            }
+            break;
+        }
+        case "skipped":
+            warnings.push("the SessionStart upgrade-notice hook was not written: no valid pinned Bridge version could be " +
+                "determined for this project");
+            break;
+        case "refused":
+            warnings.push(`the SessionStart upgrade-notice hook was not written: ${hook.reason}`);
+            break;
+        case "malformed":
+            warnings.push(`${hook.path} has a malformed hooks structure and was left unchanged; ` +
+                "the SessionStart upgrade-notice hook was NOT written");
+            break;
+        case "io-error":
+            warnings.push(`${hook.path} could not be written; the SessionStart upgrade-notice hook was NOT written`);
+            break;
+    }
+    return { lines, warnings };
+}
+/** A malformed settings file cannot take the hook, but an invalid pin is reported first. */
+function invalidPinOr(request, fallback) {
+    return isPlainReleaseVersion(request.pinnedVersion)
+        ? fallback
+        : { status: "skipped", reason: "invalid-pin" };
+}
+/**
+ * Write Bridge's `autoMode.allow` and `autoMode.environment` prose into the
+ * user's settings. Call ONLY after the user consented. A list Bridge creates
+ * starts with `"$defaults"` so Claude Code's built-in entries are kept; an
+ * existing list keeps every entry it had, `"$defaults"` included, except an
+ * entry this project's manifest recorded as Bridge's own that Bridge no longer
+ * wants (its wording changed): that one is replaced, so an upgrade never leaves
+ * stale Bridge prose beside the new text. Entries Bridge did not record are
+ * never touched.
+ */
+export async function applyUserAutoModeEntries(params, deps) {
+    const entries = buildUserAutoModeEntries(params.sandboxAccounts);
+    const settingsPath = userSettingsPath(params.homeDir);
+    const proposed = [...entries.allow, ...entries.environment];
+    const read = await readSettingsFile(settingsPath, deps);
+    if (read.status === "malformed") {
+        return { user: { status: "malformed", path: settingsPath, skipped: proposed }, manifestRecorded: false };
+    }
+    const current = read.status === "valid" ? read.settings : {};
+    const allowList = autoModeList(current, "allow");
+    const environmentList = autoModeList(current, "environment");
+    if (allowList === null || environmentList === null) {
+        return { user: { status: "malformed", path: settingsPath, skipped: proposed }, manifestRecorded: false };
+    }
+    const manifestRead = await readBridgePermissionsManifest(params.cwd, deps);
+    const manifest = manifestRead.status === "valid" ? manifestRead.manifest : emptyManifest();
+    const merge = (existing, wanted, recorded) => {
+        const wantedSet = new Set(wanted);
+        const staleSet = new Set(recorded.filter((entry) => !wantedSet.has(entry)));
+        const prior = existing ?? [AUTO_MODE_DEFAULTS_SENTINEL];
+        const removed = prior.filter((entry) => staleSet.has(entry));
+        const base = prior.filter((entry) => !staleSet.has(entry));
+        const have = new Set(base);
+        const added = wanted.filter((entry) => !have.has(entry));
+        const present = wanted.filter((entry) => have.has(entry));
+        const owned = recorded.filter((entry) => wantedSet.has(entry));
+        return { next: [...base, ...added], added, present, removed, owned, created: existing === undefined };
+    };
+    const allowMerge = merge(allowList, entries.allow, manifest.userAllow);
+    const environmentMerge = merge(environmentList, entries.environment, manifest.userEnvironment);
+    const inserted = [...allowMerge.added, ...environmentMerge.added];
+    const alreadyPresent = [...allowMerge.present, ...environmentMerge.present];
+    const removedStale = [...allowMerge.removed, ...environmentMerge.removed];
+    let status = "unchanged";
+    if (inserted.length > 0 || removedStale.length > 0) {
+        const next = withAutoModeLists(current, { allow: allowMerge.next, environment: environmentMerge.next });
+        const ok = await writeSettings(settingsPath, next, deps);
+        if (!ok) {
+            return { user: { status: "io-error", path: settingsPath, skipped: inserted }, manifestRecorded: false };
+        }
+        status = "written";
+    }
+    const manifestRecorded = await writeManifestIfChanged(params.cwd, {
+        ...manifest,
+        userAllow: unique([...allowMerge.owned, ...allowMerge.added]),
+        userEnvironment: unique([...environmentMerge.owned, ...environmentMerge.added]),
+    }, deps);
+    return {
+        user: { status, path: settingsPath, inserted, alreadyPresent, removedStale },
+        manifestRecorded,
+    };
+}
+/**
+ * Inspect both scopes without writing anything. Project rules are `present`
+ * when every desired rule is in the allow list, `missing` when any is absent,
+ * and `drifted` when the manifest's launcher differs from the one resolved now
+ * or a Bridge-owned rule is no longer desired. User entries are `present` when
+ * every proposed entry is in its list and `missing` otherwise.
+ */
+export async function inspectBridgePermissions(params, deps) {
+    const launcher = resolvePermissionLauncher(params.env);
+    const manifestRead = await readBridgePermissionsManifest(params.cwd, deps);
+    const manifest = manifestRead.status === "valid" ? manifestRead.manifest : emptyManifest();
+    let project;
+    const projectPath = projectSettingsPath(params.cwd);
+    if (!launcher.ok) {
+        project = { state: "launcher-refused" };
+    }
+    else {
+        const read = await readSettingsFile(projectPath, deps);
+        const allow = read.status === "malformed" ? null : projectAllowList(read.status === "valid" ? read.settings : {});
+        if (allow === null) {
+            project = { state: "malformed", path: projectPath };
+        }
+        else {
+            const desired = buildProjectPermissionRules(launcher.prefix, await resolveSupervisorServerNames(params.cwd, deps));
+            const have = new Set(allow);
+            const missing = desired.filter((rule) => !have.has(rule));
+            const desiredSet = new Set(desired);
+            const stale = manifest.project.filter((rule) => !desiredSet.has(rule) && have.has(rule));
+            const launcherChanged = manifest.launcher !== null && manifest.launcher !== launcher.prefix;
+            if (launcherChanged || stale.length > 0) {
+                project = {
+                    state: "drifted",
+                    path: projectPath,
+                    missing,
+                    stale,
+                    reason: launcherChanged
+                        ? "the launcher prefix changed since the rules were written"
+                        : "Bridge-written rules no longer match the current catalog or MCP server key",
+                };
+            }
+            else if (missing.length > 0) {
+                project = { state: "missing", path: projectPath, missing };
+            }
+            else {
+                project = { state: "present", path: projectPath, count: desired.length };
+            }
+        }
+    }
+    const userPath = userSettingsPath(params.homeDir);
+    const userRead = await readSettingsFile(userPath, deps);
+    let user;
+    if (userRead.status === "malformed") {
+        user = { state: "malformed", path: userPath };
+    }
+    else {
+        const settings = userRead.status === "valid" ? userRead.settings : {};
+        const allowList = autoModeList(settings, "allow");
+        const environmentList = autoModeList(settings, "environment");
+        if (allowList === null || environmentList === null) {
+            user = { state: "malformed", path: userPath };
+        }
+        else {
+            const entries = buildUserAutoModeEntries();
+            const haveAllow = new Set(allowList ?? []);
+            const haveEnvironment = new Set(environmentList ?? []);
+            const missing = [
+                ...entries.allow.filter((e) => !haveAllow.has(e)),
+                ...entries.environment.filter((e) => !haveEnvironment.has(e)),
+            ];
+            user =
+                missing.length === 0
+                    ? { state: "present", path: userPath, count: entries.allow.length + entries.environment.length }
+                    : { state: "missing", path: userPath, missing };
+        }
+    }
+    return { launcher, recordedLauncher: manifest.launcher, project, user };
+}
+/**
+ * Remove ONLY the strings Bridge recorded in its manifest, from both settings
+ * files. Every other entry and key stays, including a user's own identical
+ * string that predates Bridge (it was never recorded). A malformed file is never
+ * written; its recorded strings stay recorded and are reported as unremovable.
+ */
+export async function removeBridgePermissions(params, deps) {
+    const manifestRead = await readBridgePermissionsManifest(params.cwd, deps);
+    const manifest = manifestRead.status === "valid" ? manifestRead.manifest : emptyManifest();
+    const next = { ...manifest };
+    // Project scope: the permission rules and the SessionStart hook share ONE
+    // settings snapshot and ONE write, so neither removal can overwrite the other.
+    const projectPath = projectSettingsPath(params.cwd);
+    const recordedHooks = manifest.hooks?.SessionStart ?? [];
+    let project;
+    let hook;
+    if (manifest.project.length === 0 && recordedHooks.length === 0) {
+        project = { status: "nothing-recorded", path: projectPath, removed: [] };
+        hook = { status: "nothing-recorded", path: projectPath, removed: [] };
+    }
+    else {
+        const read = await readSettingsFile(projectPath, deps);
+        if (read.status === "malformed") {
+            project =
+                manifest.project.length === 0
+                    ? { status: "nothing-recorded", path: projectPath, removed: [] }
+                    : { status: "malformed", path: projectPath, unremovable: manifest.project };
+            hook =
+                recordedHooks.length === 0
+                    ? { status: "nothing-recorded", path: projectPath, removed: [] }
+                    : { status: "malformed", path: projectPath, unremovable: recordedHooks };
+        }
+        else {
+            const settings = read.status === "valid" ? read.settings : {};
+            let working = settings;
+            // Rules.
+            const allow = projectAllowList(settings);
+            let rulesRemoved = [];
+            let rulesMalformed = false;
+            if (manifest.project.length > 0) {
+                if (allow === null) {
+                    rulesMalformed = true;
+                }
+                else {
+                    const owned = new Set(manifest.project);
+                    rulesRemoved = allow.filter((rule) => owned.has(rule));
+                    if (rulesRemoved.length > 0) {
+                        working = withProjectAllowList(working, allow.filter((rule) => !owned.has(rule)));
+                    }
+                }
+            }
+            // Hook: only the exact recorded commands, never a recognizable lookalike.
+            let hooksRemoved = [];
+            let hooksMalformed = false;
+            if (recordedHooks.length > 0) {
+                if (inspectClaudeHookContainers(working, [SESSION_START_HOOK_EVENT]) === "malformed") {
+                    hooksMalformed = true;
+                }
+                else {
+                    const present = new Set(sessionStartCommands(working));
+                    for (const command of recordedHooks) {
+                        if (present.has(command))
+                            hooksRemoved.push(command);
+                        working = removeClaudeSettingsCommandHook(working, SESSION_START_HOOK_EVENT, command);
+                    }
+                }
+            }
+            // One write, only when something changed and the file exists.
+            let writeOk = true;
+            if ((rulesRemoved.length > 0 || hooksRemoved.length > 0) && read.status === "valid") {
+                writeOk = await writeSettings(projectPath, working, deps);
+            }
+            if (manifest.project.length === 0) {
+                project = { status: "nothing-recorded", path: projectPath, removed: [] };
+            }
+            else if (rulesMalformed) {
+                project = { status: "malformed", path: projectPath, unremovable: manifest.project };
+            }
+            else if (writeOk || rulesRemoved.length === 0) {
+                project = { status: "removed", path: projectPath, removed: rulesRemoved };
+                next.project = [];
+                next.launcher = null;
+            }
+            else {
+                project = { status: "io-error", path: projectPath, unremovable: rulesRemoved };
+            }
+            if (recordedHooks.length === 0) {
+                hook = { status: "nothing-recorded", path: projectPath, removed: [] };
+            }
+            else if (hooksMalformed) {
+                hook = { status: "malformed", path: projectPath, unremovable: recordedHooks };
+            }
+            else if (writeOk || hooksRemoved.length === 0) {
+                // Ownership clears only once the settings write succeeded (or there was
+                // nothing left in the file to remove).
+                hook = { status: "removed", path: projectPath, removed: hooksRemoved };
+                next.hooks = undefined;
+            }
+            else {
+                hook = { status: "io-error", path: projectPath, unremovable: hooksRemoved };
+            }
+        }
+    }
+    // User scope.
+    const userPath = userSettingsPath(params.homeDir);
+    let user;
+    const ownedUser = [...manifest.userAllow, ...manifest.userEnvironment];
+    if (ownedUser.length === 0) {
+        user = { status: "nothing-recorded", path: userPath, removed: [] };
+    }
+    else {
+        const read = await readSettingsFile(userPath, deps);
+        const settings = read.status === "valid" ? read.settings : {};
+        const allowList = read.status === "malformed" ? null : autoModeList(settings, "allow");
+        const environmentList = read.status === "malformed" ? null : autoModeList(settings, "environment");
+        if (allowList === null || environmentList === null) {
+            user = { status: "malformed", path: userPath, unremovable: ownedUser };
+        }
+        else {
+            const ownedAllow = new Set(manifest.userAllow);
+            const ownedEnvironment = new Set(manifest.userEnvironment);
+            const removedAllow = (allowList ?? []).filter((e) => ownedAllow.has(e));
+            const removedEnvironment = (environmentList ?? []).filter((e) => ownedEnvironment.has(e));
+            const removed = [...removedAllow, ...removedEnvironment];
+            let ok = true;
+            if (removed.length > 0 && read.status === "valid") {
+                const lists = {};
+                if (allowList !== undefined)
+                    lists.allow = allowList.filter((e) => !ownedAllow.has(e));
+                if (environmentList !== undefined)
+                    lists.environment = environmentList.filter((e) => !ownedEnvironment.has(e));
+                ok = await writeSettings(userPath, withAutoModeLists(read.settings, lists), deps);
+            }
+            if (ok) {
+                user = { status: "removed", path: userPath, removed };
+                next.userAllow = [];
+                next.userEnvironment = [];
+            }
+            else {
+                user = { status: "io-error", path: userPath, unremovable: removed };
+            }
+        }
+    }
+    const changed = next.project.length !== manifest.project.length ||
+        next.userAllow.length !== manifest.userAllow.length ||
+        next.userEnvironment.length !== manifest.userEnvironment.length ||
+        (next.hooks?.SessionStart.length ?? 0) !== (manifest.hooks?.SessionStart.length ?? 0);
+    const manifestUpdated = manifestRead.status === "valid" && changed ? await writeManifestIfChanged(params.cwd, next, deps) : true;
+    return { project, hook, user, manifestUpdated };
+}
+/**
+ * The consent text for the user-settings write (BAPI-1448). The CLI's interactive
+ * mode prints everything up to the last line and reads the answer at that line;
+ * `/drive-epic-run` step 3a reproduces the same text byte for byte, and a test pins
+ * the two together.
+ */
+export const USER_AUTO_MODE_CONSENT_PROMPT = "Epic runs work best in Claude Code's auto mode, where Claude acts without asking you each\n" +
+    "time. Auto mode has a safety check that can pause routine run steps, like creating the epic's\n" +
+    "branches or updating the run's own records, because it doesn't know they belong to the run.\n" +
+    "\n" +
+    "Bridge can add a short description of the run's sandbox to ~/.claude/settings.json so the\n" +
+    "check recognizes this work. It describes:\n" +
+    "  • the run's own branches (epic/<KEY> and each child ticket's branch) and their worktrees\n" +
+    "  • the Bridge server\n" +
+    "  • any sandbox accounts your project names\n" +
+    "It grants no other access, and you can remove it any time with --remove-bridge-permissions.\n" +
+    "\n" +
+    "Add it? (y/N) ";
+function logList(log, items) {
+    for (const item of items)
+        log(`    ${item}`);
+}
+/**
+ * The installer's permission step. Writes the project rules and the pinned
+ * SessionStart hook to `.claude/settings.local.json` and reports them. It never
+ * reads, writes, or mentions the user's `~/.claude/settings.json`: that write is
+ * the `bridge-permissions` subcommand's job (BAPI-1448). Every rule written is
+ * listed, with the launcher prefix it covers. A malformed file is reported on
+ * stderr and skipped; the rest of the install continues.
+ */
+export async function runBridgePermissionsInstallStep(deps) {
+    const { log, errorLog } = deps;
+    log("");
+    log("Bridge permission rules for /drive-epic-run (auto mode):");
+    if (deps.ensureGitignored) {
+        for (const relPath of [BRIDGE_PERMISSIONS_MANIFEST_RELPATH, BRIDGE_PROJECT_SETTINGS_RELPATH]) {
+            try {
+                await deps.ensureGitignored(relPath);
+            }
+            catch {
+                errorLog(`  warning: could not add ${relPath} to .gitignore (non-fatal).`);
+            }
+        }
+    }
+    const project = await applyProjectPermissions({ cwd: deps.cwd, env: deps.env, sessionStartHook: deps.sessionStartHook }, deps);
+    if (!project.launcher.ok) {
+        errorLog(`  warning: project permission rules were not written: ${project.launcher.reason}.`);
+        errorLog(`  Unset ${BRIDGE_LAUNCHER_ENV}, or set it to a plain command prefix, then re-run install.`);
+    }
+    else {
+        log(`  Launcher prefix covered: ${project.launcher.prefix}`);
+        const scope = project.project;
+        if (scope.status === "written" || scope.status === "unchanged") {
+            log(`  ${scope.path}:`);
+            if (scope.inserted.length > 0) {
+                log(`  Wrote ${scope.inserted.length} permissions.allow rule(s):`);
+                logList(log, scope.inserted);
+            }
+            if (scope.alreadyPresent.length > 0) {
+                log(`  Already present (${scope.alreadyPresent.length}):`);
+                logList(log, scope.alreadyPresent);
+            }
+            if (scope.removedStale.length > 0) {
+                log(`  Removed ${scope.removedStale.length} rule(s) Bridge wrote for an earlier launcher:`);
+                logList(log, scope.removedStale);
+            }
+        }
+        else if (scope.status === "malformed" || scope.status === "io-error") {
+            errorLog(`  warning: ${scope.path} ${scope.status === "malformed" ? "is not valid JSON settings and was left unchanged" : "could not be written"}; ` +
+                `these ${scope.skipped.length} rule(s) were NOT written:`);
+            logList(errorLog, scope.skipped);
+        }
+        if (!project.manifestRecorded && (scope.status === "written" || scope.status === "unchanged")) {
+            errorLog(`  warning: could not update ${BRIDGE_PERMISSIONS_MANIFEST_RELPATH}; doctor and removal may not see these rules.`);
+        }
+    }
+    // The hook is reported on its own: a refused launcher or a malformed hooks
+    // structure never hides, or is hidden by, the permission-rule result above.
+    if (project.hook) {
+        const described = describeSessionStartHookOutcome(project.hook);
+        for (const line of described.lines)
+            log(`  ${line}`);
+        for (const warning of described.warnings)
+            errorLog(`  warning: ${warning}.`);
+    }
+    return { project };
+}
+/**
+ * The removal flag's step. Removes only Bridge-recorded strings and reports what
+ * it removed and what it could not. Returns a process exit code: 0 when every
+ * recorded string is gone, 1 when a malformed or unwritable file kept some.
+ */
+export async function runBridgePermissionsRemoval(deps) {
+    const { log, errorLog } = deps;
+    const result = await removeBridgePermissions({ cwd: deps.cwd, homeDir: deps.homeDir }, deps);
+    let failed = false;
+    for (const [label, scope] of [
+        ["project permissions.allow", result.project],
+        ["project SessionStart hook", result.hook],
+        ["user autoMode", result.user],
+    ]) {
+        if (scope.status === "nothing-recorded") {
+            // The hook is a newer scope: say nothing when it never owned anything, so an
+            // install that never wrote one keeps its original removal output.
+            if (label === "project SessionStart hook")
+                continue;
+            log(`${label}: nothing Bridge wrote is recorded (${scope.path}).`);
+        }
+        else if (scope.status === "removed") {
+            log(`${label}: removed ${scope.removed.length} Bridge entr${scope.removed.length === 1 ? "y" : "ies"} from ${scope.path}.`);
+            logList(log, scope.removed);
+        }
+        else if (scope.status === "malformed" || scope.status === "io-error") {
+            failed = true;
+            errorLog(`${label}: ${scope.path} ${scope.status === "malformed" ? "is not valid JSON settings" : "could not be written"}; ` +
+                "these Bridge entries could not be removed:");
+            logList(errorLog, scope.unremovable);
+        }
+    }
+    if (!result.manifestUpdated) {
+        failed = true;
+        errorLog(`warning: could not update ${BRIDGE_PERMISSIONS_MANIFEST_RELPATH}.`);
+    }
+    log("Entries you added yourself were left in place.");
+    return failed ? 1 : 0;
+}
+/**
+ * Parse the subcommand's argv. Only no flags, `--check --json` (either order),
+ * `--user-consented`, and `--help` are accepted; every other form — an unknown flag,
+ * a repeated flag, `--check` without `--json`, `--check` with `--user-consented` — is
+ * refused here, before any file is read.
+ */
+export function parseBridgePermissionsArgv(argv) {
+    if (argv.length === 0)
+        return { ok: true, mode: "interactive" };
+    if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h"))
+        return { ok: true, mode: "help" };
+    if (argv.length === 1 && argv[0] === "--user-consented")
+        return { ok: true, mode: "user-consented" };
+    if (argv.length === 2 && argv.includes("--check") && argv.includes("--json")) {
+        return { ok: true, mode: "check-json" };
+    }
+    return { ok: false, error: `Unsupported arguments: ${BRIDGE_PERMISSIONS_USAGE_HINT}` };
+}
+const BRIDGE_PERMISSIONS_USAGE_HINT = "use no flags, `--check --json`, `--user-consented`, or `--help`.";
+/** Static help text for the subcommand. */
+export function getBridgePermissionsUsage() {
+    return [
+        "Usage:",
+        `  npx -y ${MCP_PACKAGE_NAME} bridge-permissions                 Ask, then add Bridge's auto-mode`,
+        "                                                    sandbox description to ~/.claude/settings.json",
+        `  npx -y ${MCP_PACKAGE_NAME} bridge-permissions --check --json  Read-only: print the user-scope state`,
+        "                                                    (present, missing, or malformed) as JSON",
+        `  npx -y ${MCP_PACKAGE_NAME} bridge-permissions --user-consented`,
+        "                                                    Write without asking. Reserved for /drive-epic-run,",
+        "                                                    after you said yes to its question in the current",
+        "                                                    session. Do not script it.",
+        "",
+        "Run from the project root: the ownership manifest is .bridge/bridge-permissions.json in the",
+        "current directory. Without a terminal, no-flag mode writes nothing and prints what it would add.",
+        `Remove the entries later with: npx -y ${MCP_PACKAGE_NAME} install --remove-bridge-permissions`,
+    ].join("\n");
+}
+/** Report one user-settings write: wording shared by the interactive and consented modes. */
+function reportUserAutoModeWrite(result, log, errorLog) {
+    const scope = result.user;
+    let exitCode = 0;
+    if (scope.status === "written" || scope.status === "unchanged") {
+        log(`${scope.path}:`);
+        if (scope.inserted.length > 0) {
+            log(`Wrote ${scope.inserted.length} autoMode entr${scope.inserted.length === 1 ? "y" : "ies"} ("$defaults" kept):`);
+            logList(log, scope.inserted);
+        }
+        if (scope.alreadyPresent.length > 0) {
+            log(`Already present (${scope.alreadyPresent.length}):`);
+            logList(log, scope.alreadyPresent);
+        }
+        if (!result.manifestRecorded) {
+            errorLog(`warning: could not update ${BRIDGE_PERMISSIONS_MANIFEST_RELPATH}; doctor and removal may not see these entries.`);
+        }
+    }
+    else if (scope.status === "malformed" || scope.status === "io-error") {
+        exitCode = 1;
+        errorLog(`warning: ${scope.path} ${scope.status === "malformed" ? "is not valid JSON settings and was left unchanged" : "could not be written"}; ` +
+            "these autoMode entries were NOT written:");
+        logList(errorLog, scope.skipped);
+    }
+    return exitCode;
+}
+/** Split the consent text into its printed body and its final prompt line. */
+function splitConsentPrompt() {
+    const at = USER_AUTO_MODE_CONSENT_PROMPT.lastIndexOf("\n");
+    return {
+        body: USER_AUTO_MODE_CONSENT_PROMPT.slice(0, at),
+        prompt: USER_AUTO_MODE_CONSENT_PROMPT.slice(at + 1),
+    };
+}
+/**
+ * Run the subcommand and return the process exit code. It never throws: an
+ * unexpected failure is reported (without detail) on stderr and returned as `1`.
+ *
+ *   - no flags, interactive: print the consent text, read one answer; only `y` or
+ *     `yes` writes. Blank, EOF, and a read failure write nothing and exit 0.
+ *   - no flags, no terminal: write nothing, print the entries it would add, exit 0.
+ *   - `--check --json`: read-only; one JSON object for the user scope, exit 0 even
+ *     when the scope is `malformed`.
+ *   - `--user-consented`: write without asking (reserved for `/drive-epic-run`).
+ *
+ * Only the user-settings step runs here; project rules and hooks are never touched.
+ */
+export async function runBridgePermissionsCli(argv, deps) {
+    const parsed = parseBridgePermissionsArgv(argv);
+    if (!parsed.ok) {
+        deps.errorLog(parsed.error);
+        deps.errorLog(getBridgePermissionsUsage());
+        return 1;
+    }
+    try {
+        if (parsed.mode === "help") {
+            deps.log(getBridgePermissionsUsage());
+            return 0;
+        }
+        if (parsed.mode === "check-json") {
+            const inspection = await inspectBridgePermissions({ cwd: deps.cwd, homeDir: deps.homeDir, env: deps.env }, deps);
+            const user = inspection.user;
+            const payload = {
+                state: user.state,
+                path: user.path,
+            };
+            if ("missing" in user)
+                payload.missing = user.missing;
+            deps.log(JSON.stringify(payload));
+            return 0;
+        }
+        if (parsed.mode === "user-consented") {
+            const result = await applyUserAutoModeEntries({ cwd: deps.cwd, homeDir: deps.homeDir }, deps);
+            return reportUserAutoModeWrite(result, deps.log, deps.errorLog);
+        }
+        // No flags.
+        if (!deps.isTTY || !deps.promptLine) {
+            const entries = buildUserAutoModeEntries();
+            deps.log(`${userSettingsPath(deps.homeDir)} was not changed (no interactive terminal). It would add, to autoMode.allow and autoMode.environment:`);
+            logList(deps.log, [...entries.allow, ...entries.environment]);
+            deps.log("Run this command in a terminal to be asked, or let /drive-epic-run ask in your session.");
+            return 0;
+        }
+        const { body, prompt } = splitConsentPrompt();
+        deps.log(body);
+        let answer = "";
+        try {
+            answer = String((await deps.promptLine(prompt)) ?? "").trim().toLowerCase();
+        }
+        catch {
+            answer = "";
+        }
+        if (answer !== "y" && answer !== "yes") {
+            deps.log(`${userSettingsPath(deps.homeDir)} was not changed.`);
+            return 0;
+        }
+        const result = await applyUserAutoModeEntries({ cwd: deps.cwd, homeDir: deps.homeDir }, deps);
+        return reportUserAutoModeWrite(result, deps.log, deps.errorLog);
+    }
+    catch {
+        deps.errorLog("bridge-permissions: unexpected error; nothing further was changed.");
+        return 1;
+    }
+}
+/** One-line prompt on stderr; EOF resolves as an empty answer so it can never hang. */
+function promptLineOnStderr(promptText) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        let answered = false;
+        rl.on("close", () => {
+            if (!answered)
+                resolve("");
+        });
+        rl.question(promptText, (answer) => {
+            answered = true;
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+/** Production entry for the `bridge-permissions` subcommand: real filesystem, real home. */
+export async function runBridgePermissionsCliFromProcess(argv) {
+    const isTTY = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    return runBridgePermissionsCli(argv, {
+        // The manifest belongs to the project in the current directory, so there is no
+        // Git-root lookup: help says "run from the project root".
+        cwd: process.cwd(),
+        homeDir: os.homedir(),
+        env: process.env,
+        isTTY,
+        promptLine: isTTY ? promptLineOnStderr : undefined,
+        readFile: (filePath) => fs.readFile(filePath, "utf-8"),
+        writeFile: (filePath, data) => fs.writeFile(filePath, data, { encoding: "utf-8" }),
+        mkdir: (dirPath, options) => fs.mkdir(dirPath, options),
+        log: (message) => console.log(message),
+        errorLog: (message) => console.error(message),
+    });
+}