@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/build/bridge-permissions.js

@@ -1,6 +1,7 @@
 /**
  * Bridge-managed Claude Code permission rules for the `/drive-epic-run`
- * supervisor (BAPI-1398, AC-8).
+ * 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
@@ -18,7 +19,10 @@
  * 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.
+ * `~/.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
@@ -38,9 +42,19 @@
  * 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
 // ---------------------------------------------------------------------------
@@ -58,6 +72,14 @@ export const BRIDGE_PERMISSIONS_MANIFEST_RELPATH = ".bridge/bridge-permissions.j
 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";
 /**
@@ -80,6 +102,9 @@ export const BRIDGE_SANCTIONED_VERB_SUBCOMMANDS = [
     "resume-run",
     "resume-ci",
     "rerun-ci",
+    "resolve-handoff",
+    // BAPI-1532: answer a named plan failure with one forced regeneration.
+    "regenerate-plan",
 ];
 /** The Bridge MCP tools the supervisor calls. */
 export const BRIDGE_SUPERVISOR_MCP_TOOLS = [
@@ -158,8 +183,14 @@ export function buildProjectPermissionRules(launcherPrefix, serverNames = [MCP_S
     rules.push(`Bash(${launcherPrefix} epic-implementer readiness *)`);
     // Read-only supporting commands.
     rules.push(`Bash(${launcherPrefix} epic-implementer continuation-receipt *)`);
+    // BAPI-1469: the bounded, read-only wait the Monitoring loop runs between passes.
+    rules.push(`Bash(${launcherPrefix} epic-implementer wait-run *)`);
     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)");
@@ -193,10 +224,24 @@ export function buildProjectPermissionRules(launcherPrefix, serverNames = [MCP_S
     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 notes-log commit on docs/<KEY>-conductor-run-notes, made in a private
+    // worktree under the run-state directory so the shared checkout is never
+    // switched. The notes files themselves are written under the run-state
+    // Read/Edit/Write rules above.
+    rules.push(`Bash(git worktree add -b 'docs/*-conductor-run-notes' ${BRIDGE_RUN_STATE_DIR}/*/notes-worktree HEAD)`);
+    rules.push(`Bash(git -C ${BRIDGE_RUN_STATE_DIR}/*/notes-worktree add docs/epic-implementer/run-notes/)`);
+    rules.push(`Bash(git -C ${BRIDGE_RUN_STATE_DIR}/*/notes-worktree commit -m * -- docs/epic-implementer/run-notes/)`);
+    rules.push(`Bash(git worktree remove ${BRIDGE_RUN_STATE_DIR}/*/notes-worktree)`);
+    // BAPI-1496: the owner-tagged worker-supervisor pause before a local launch,
+    // the ownership-guarded post-completion teardown of this run's own plane, and
+    // the paired owner-tagged resume. Only the quoted owner tag or run id fills
+    // the `*`. The bare `plane down` and bare `resume` are operator overrides the
+    // supervisor never runs, so they have no rule.
+    rules.push("Bash(python scripts/worker_supervisor.py pause --owner '*')");
+    rules.push(`Bash(${launcherPrefix} plane down --expect-epic-run-id '*')`);
+    rules.push("Bash(python scripts/worker_supervisor.py resume --owner '*')");
+    // The planned-hand-off comparison's one read of each dependent child PR.
+    rules.push("Bash(gh pr view * --json number,body)");
     // 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) {
@@ -269,14 +314,19 @@ export function userSettingsPath(homeDir) {
 export function bridgePermissionsManifestPath(cwd) {
     return path.join(cwd, ...BRIDGE_PERMISSIONS_MANIFEST_RELPATH.split("/"));
 }
-/** Read a settings file: missing is `{}`-equivalent, malformed is never used. */
+/**
+ * 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 {
-        return { status: "missing" };
+    catch (error) {
+        const code = error?.code;
+        return code === "ENOENT" ? { status: "missing" } : { status: "malformed" };
     }
     try {
         const parsed = JSON.parse(raw);
@@ -329,10 +379,23 @@ export async function readBridgePermissionsManifest(cwd, deps) {
             return { status: "invalid" };
         if (launcher !== null && typeof launcher !== "string")
             return { status: "invalid" };
-        return {
-            status: "valid",
-            manifest: { version: BRIDGE_PERMISSIONS_MANIFEST_VERSION, launcher, project, userAllow, userEnvironment },
+        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" };
@@ -340,13 +403,19 @@ export async function readBridgePermissionsManifest(cwd, deps) {
 }
 /** Serialize the manifest with a stable key order. */
 export function serializeBridgePermissionsManifest(manifest) {
-    return `${JSON.stringify({
+    const doc = {
         version: manifest.version,
         launcher: manifest.launcher,
         project: manifest.project,
         userAllow: manifest.userAllow,
         userEnvironment: manifest.userEnvironment,
-    }, null, 2)}\n`;
+    };
+    // 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);
@@ -422,56 +491,303 @@ function unique(values) {
     return [...new Set(values)];
 }
 /**
- * Write the project `permissions.allow` catalog for the resolved launcher.
+ * 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 };
+        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);
-    const current = read.status === "valid" ? read.settings : {};
-    const allow = read.status === "malformed" ? null : projectAllowList(current);
-    if (allow === null) {
+    if (read.status === "malformed") {
         return {
             launcher,
             project: { status: "malformed", path: settingsPath, skipped: desired },
             manifestRecorded: false,
+            ...(request ? { hook: invalidPinOr(request, { status: "malformed", path: settingsPath }) } : {}),
         };
     }
-    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);
-    const inserted = desired.filter((rule) => !keptSet.has(rule));
-    const alreadyPresent = desired.filter((rule) => keptSet.has(rule));
-    const nextAllow = [...kept, ...inserted];
-    let status = "unchanged";
-    if (inserted.length > 0 || removedStale.length > 0) {
-        const ok = await writeSettings(settingsPath, withProjectAllowList(current, nextAllow), deps);
+    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: { status: "io-error", path: settingsPath, skipped: inserted }, manifestRecorded: false };
+            return {
+                launcher,
+                project: permissionsApplied
+                    ? { status: "io-error", path: settingsPath, skipped: inserted }
+                    : project,
+                manifestRecorded: false,
+                ...(request ? { hook: hookPlan ? { status: "io-error", path: settingsPath } : hook } : {}),
+            };
         }
-        status = "written";
+        if (project.status === "unchanged" && permissionsChanged)
+            project = { ...project, status: "written" };
     }
-    const ownedStill = manifest.project.filter((rule) => desiredSet.has(rule));
-    const manifestRecorded = await writeManifestIfChanged(params.cwd, { ...manifest, launcher: launcher.prefix, project: unique([...ownedStill, ...inserted]) }, deps);
-    return {
-        launcher,
-        project: { status, path: settingsPath, inserted, alreadyPresent, removedStale },
-        manifestRecorded,
-    };
+    // ---- 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
@@ -622,32 +938,96 @@ 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.
+    // 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;
-    if (manifest.project.length === 0) {
+    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);
-        const allow = read.status === "malformed" ? null : projectAllowList(read.status === "valid" ? read.settings : {});
-        if (allow === null) {
-            project = { status: "malformed", path: projectPath, unremovable: manifest.project };
+        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 owned = new Set(manifest.project);
-            const removed = allow.filter((rule) => owned.has(rule));
-            let ok = true;
-            if (removed.length > 0 && read.status === "valid") {
-                ok = await writeSettings(projectPath, withProjectAllowList(read.settings, allow.filter((rule) => !owned.has(rule))), deps);
+            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)));
+                    }
+                }
             }
-            if (ok) {
-                project = { status: "removed", path: projectPath, removed };
+            // 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: removed };
+                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 };
             }
         }
     }
@@ -693,23 +1073,40 @@ export async function removeBridgePermissions(params, deps) {
     }
     const changed = next.project.length !== manifest.project.length ||
         next.userAllow.length !== manifest.userAllow.length ||
-        next.userEnvironment.length !== manifest.userEnvironment.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, user, manifestUpdated };
+    return { project, hook, user, manifestUpdated };
 }
-/** The one consent question for the user-settings write. */
-export const USER_AUTO_MODE_CONSENT_PROMPT = "Add Bridge's auto-mode sandbox description to ~/.claude/settings.json, so /drive-epic-run's " +
-    "in-scope work is not stopped by the auto-mode classifier? (y/N) ";
+/**
+ * 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, then asks ONCE for
- * consent before touching the user's settings. A declined or non-interactive
- * install leaves the user file untouched and prints what it would have added.
- * 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.
+ * 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;
@@ -725,7 +1122,7 @@ export async function runBridgePermissionsInstallStep(deps) {
             }
         }
     }
-    const project = await applyProjectPermissions({ cwd: deps.cwd, env: deps.env }, deps);
+    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.`);
@@ -757,41 +1154,16 @@ export async function runBridgePermissionsInstallStep(deps) {
             errorLog(`  warning: could not update ${BRIDGE_PERMISSIONS_MANIFEST_RELPATH}; doctor and removal may not see these rules.`);
         }
     }
-    // User settings: one question, and nothing written without a yes.
-    const entries = buildUserAutoModeEntries();
-    const proposed = [...entries.allow, ...entries.environment];
-    const userPath = userSettingsPath(deps.homeDir);
-    if (!deps.promptLine) {
-        log(`  ${userPath} was not changed (non-interactive install). It would add, to autoMode.allow and autoMode.environment:`);
-        logList(log, proposed);
-        log("  Re-run install in a terminal to add them.");
-        return { project, userConsent: "non-interactive", user: null };
-    }
-    const answer = (await deps.promptLine(USER_AUTO_MODE_CONSENT_PROMPT)).trim().toLowerCase();
-    if (answer !== "y" && answer !== "yes") {
-        log(`  ${userPath} was not changed. These entries were not added:`);
-        logList(log, proposed);
-        return { project, userConsent: "declined", user: null };
-    }
-    const user = await applyUserAutoModeEntries({ cwd: deps.cwd, homeDir: deps.homeDir }, deps);
-    const scope = user.user;
-    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);
-        }
+    // 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}.`);
     }
-    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 autoMode entries were NOT written:");
-        logList(errorLog, scope.skipped);
-    }
-    return { project, userConsent: "granted", user };
+    return { project };
 }
 /**
  * The removal flag's step. Removes only Bridge-recorded strings and reports what
@@ -804,9 +1176,14 @@ export async function runBridgePermissionsRemoval(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") {
@@ -827,3 +1204,178 @@ export async function runBridgePermissionsRemoval(deps) {
     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),
+    });
+}