@yagni-app/code 0.2.1 → 0.3.1

package/dist/extension/permission.js

@@ -4,7 +4,8 @@
  * YAGNI Code registers no tool_call handler today, so the interactive session has
  * no plan/approval surface. P3 adds one on pi's documented `tool_call` block seam
  * plus a `/mode` command:
- *   - auto   (default): never blocks. Byte-identical to today, so this is additive.
+ *   - auto   (default): ordinary coding tools run directly; external tracker
+ *              changes still require fresh human confirmation.
  *   - plan   : blocks write/edit/bash so the agent can explore + propose without
  *              touching the tree.
  *   - review : surfaces a three-way ctx.ui.select before a write/edit/bash; a
@@ -14,7 +15,7 @@
  *              adds a session-scoped bless rule AND drafts a decision capture.
  *
  * `decideGate` is PURE; the live wiring holds the mode in a small closure (no
- * module-global state). The default auto mode remains fail-open, but stricter
+ * module-global state). The default auto mode remains direct for coding tools, but stricter
  * modes fail closed for side-effect tools if the gate itself errors. Bless rules
  * are session-scoped, path-prefix-bound, never persisted, and never consulted in
  * plan mode (plan blocks outright before isBlessed is reached).
@@ -25,19 +26,35 @@
  * When the mode leaves plan, stale plan-context messages are filtered out of
  * the context so the model doesn't keep believing it is restricted.
  */
+import { describePrefix, matchesGrant, validateGrant, } from "./approvedPrefixes.js";
 import { makeBlessStore as defaultMakeBlessStore } from "./bless.js";
+import { classifyCommand, DEFAULT_EXEC_POLICY } from "./execPolicy.js";
+import { isDebug } from "./diagnostics.js";
+import { buildDiagnosticEvent, checkCircuitBreaker, DEFAULT_GUARDIAN_LIMITS, } from "./guardian.js";
+export function createModeHolder(initial = "auto") {
+    let current = initial;
+    const listeners = new Set();
+    return {
+        get: () => current,
+        set: (m) => {
+            current = m;
+            for (const fn of listeners)
+                fn(m);
+        },
+        onSet: (fn) => { listeners.add(fn); },
+    };
+}
 export const DEFAULT_PERMISSION_POLICY = {
-    planBlockTools: ["write", "edit", "bash"],
-    reviewConfirmTools: ["write", "edit", "bash"],
+    planBlockTools: ["write", "edit", "bash", "file_ticket", "update_ticket_status"],
+    reviewConfirmTools: ["write", "edit", "bash", "file_ticket", "update_ticket_status"],
+    alwaysConfirmTools: ["file_ticket", "update_ticket_status"],
 };
 /**
- * Pure permission decision for one tool call under a mode + policy. auto always
- * allows; plan blocks the write/exec set; review marks writes for confirmation
+ * Pure permission decision for one tool call under a mode + policy. Auto allows
+ * ordinary tools; plan blocks the write/exec set; review marks writes for confirmation
  * unless a recorded decision blesses them.
  */
 export function decideGate(toolName, params, mode, policy) {
-    if (mode === "auto")
-        return { block: false };
     if (mode === "plan") {
         if (policy.planBlockTools.includes(toolName)) {
             return {
@@ -47,6 +64,47 @@ export function decideGate(toolName, params, mode, policy) {
         }
         return { block: false };
     }
+    if (policy.alwaysConfirmTools?.includes(toolName)) {
+        return { block: false, confirm: true };
+    }
+    // Exec policy: classify bash commands before the tool-granular logic.
+    if (toolName === "bash") {
+        const command = typeof params.command === "string" ? params.command.trim() : "";
+        if (command) {
+            try {
+                const execPolicy = policy.execPolicy ?? DEFAULT_EXEC_POLICY;
+                const classification = classifyCommand(command, execPolicy);
+                if (classification.decision === "allow")
+                    return { block: false };
+                if (classification.decision === "forbidden") {
+                    return {
+                        block: true,
+                        reason: `${classification.justification}. Do not attempt the same outcome via a workaround or indirect execution — use a materially safer alternative, or ask the user.`,
+                    };
+                }
+                // prompt — signal to the handler so it can run the Guardian.
+                // In auto mode the handler runs the Guardian; in review mode the
+                // handler runs the Guardian first, then falls back to user confirm.
+                if (mode === "auto") {
+                    return { block: false, classify: "prompt", classifyJustification: classification.justification };
+                }
+                // review mode
+                if (policy.isBlessed?.(toolName, params))
+                    return { block: false };
+                return {
+                    block: false,
+                    confirm: true,
+                    classify: "prompt",
+                    classifyJustification: classification.justification,
+                };
+            }
+            catch {
+                // classifyCommand threw — fall through to tool-granular logic (graceful degradation).
+            }
+        }
+    }
+    if (mode === "auto")
+        return { block: false };
     // review
     if (policy.reviewConfirmTools.includes(toolName)) {
         if (policy.isBlessed?.(toolName, params))
@@ -55,9 +113,13 @@ export function decideGate(toolName, params, mode, policy) {
     }
     return { block: false };
 }
-/** The customType tag on injected plan-mode context (filterable later). */
-export const PLAN_CONTEXT_TYPE = "yagni-plan-context";
+/** The customType tag on injected mode-context messages (filterable later). */
+export const MODE_CONTEXT_TYPE = "yagni-mode-context";
+/** Legacy alias — the original plan-mode tag, kept for backward compat. */
+export const PLAN_CONTEXT_TYPE = MODE_CONTEXT_TYPE;
 const PLAN_MARKER = "[PLAN MODE ACTIVE]";
+const AUTO_MARKER = "[AUTO MODE]";
+const REVIEW_MARKER = "[REVIEW MODE]";
 export const PLAN_CONTEXT_MESSAGE = `${PLAN_MARKER}
 You are in plan mode: explore and design, change nothing.
 - write, edit, and bash are held by the permission gate; do not attempt them.
@@ -65,38 +127,86 @@ You are in plan mode: explore and design, change nothing.
 - Produce a concrete numbered plan of the steps you would take, with the files involved.
 - End by asking the user to review the plan; they run /mode auto (or /mode review) to execute it.
 - Once executing, track the plan's steps with todo_write.`;
-function mentionsPlanMarker(content) {
+const AUTO_CONTEXT_MESSAGE = `${AUTO_MARKER}
+You are in auto mode. Coding commands run directly.
+- Proactively verify your work: run tests, lint, and typecheck after changes.
+- Destructive commands (rm -rf, git reset --hard, git push --force) are blocked by the exec policy.
+- Ambiguous commands are reviewed by the Guardian before running.`;
+const REVIEW_CONTEXT_MESSAGE = `${REVIEW_MARKER}
+You are in review mode. Each bash, write, and edit may be confirmed before running.
+- Safe commands (ls, cat, git status) run without prompting.
+- Ambiguous commands are reviewed by the Guardian first; if the Guardian allows, they run without prompting.
+- If the Guardian denies or is unavailable, you will be asked to confirm.
+- Propose verification steps but wait for approval before running them.`;
+/** Build the mode-awareness context message for the current permission mode. */
+export function buildModeContextMessage(mode) {
+    switch (mode) {
+        case "plan":
+            return PLAN_CONTEXT_MESSAGE;
+        case "review":
+            return REVIEW_CONTEXT_MESSAGE;
+        case "auto":
+            return AUTO_CONTEXT_MESSAGE;
+    }
+}
+const MODE_MARKERS = {
+    plan: PLAN_MARKER,
+    auto: AUTO_MARKER,
+    review: REVIEW_MARKER,
+};
+function mentionsModeMarker(content) {
     if (typeof content === "string")
-        return content.includes(PLAN_MARKER);
+        return Object.values(MODE_MARKERS).some((m) => content.includes(m));
     if (Array.isArray(content)) {
         return content.some((c) => typeof c?.text === "string" &&
-            (c.text.includes(PLAN_MARKER)));
+            Object.values(MODE_MARKERS).some((m) => c.text.includes(m)));
     }
     return false;
 }
+/** Which mode marker does this message carry, if any? */
+function modeMarkerFor(content) {
+    const text = typeof content === "string"
+        ? content
+        : Array.isArray(content)
+            ? content.find((c) => typeof c?.text === "string")?.text
+            : undefined;
+    if (!text)
+        return null;
+    for (const [mode, marker] of Object.entries(MODE_MARKERS)) {
+        if (text.includes(marker))
+            return marker;
+    }
+    return null;
+}
 /**
- * Drop previously injected plan-mode context once plan mode is off, so the
- * model stops believing writes are held. Pure; returns the SAME array when
- * nothing needs filtering so callers can cheaply detect a no-op.
+ * Drop previously injected mode-context messages from a DIFFERENT mode so the
+ * model does not keep believing it is in a prior mode. Messages matching the
+ * current mode are kept (the fresh injection from before_agent_start should
+ * survive). Pure; returns the SAME array when nothing needs filtering so callers
+ * can cheaply detect a no-op.
  */
-export function filterStalePlanContext(messages) {
+export function filterStaleModeContext(messages, currentMode) {
+    const currentMarker = currentMode ? MODE_MARKERS[currentMode] : undefined;
     const keep = messages.filter((m) => {
         const msg = m;
-        if (msg?.customType === PLAN_CONTEXT_TYPE)
-            return false;
-        if (msg?.role === "user" && mentionsPlanMarker(msg.content))
-            return false;
+        if (msg?.customType === MODE_CONTEXT_TYPE) {
+            // Keep if it matches the current mode; strip if from a different mode
+            // (or if we don't know the current mode — strip all to be safe).
+            const marker = modeMarkerFor(msg.content);
+            return currentMarker !== undefined && marker === currentMarker;
+        }
+        if (msg?.role === "user" && mentionsModeMarker(msg.content)) {
+            const marker = modeMarkerFor(msg.content);
+            return currentMarker !== undefined && marker === currentMarker;
+        }
         return true;
     });
     return keep.length === messages.length ? messages : keep;
 }
-const MODE_STATUS = {
-    auto: undefined,
-    plan: "⏸ plan",
-    review: "✓ review",
-};
+/** Legacy alias — the original plan-mode filter name. */
+export const filterStalePlanContext = filterStaleModeContext;
 const MODE_COPY = {
-    auto: "auto: changes apply without prompting (default).",
+    auto: "auto: coding changes apply directly; external tracker changes ask first (default).",
     plan: "plan: write, edit, and bash are held so the agent can explore and propose only.",
     review: "review: you confirm each write, edit, or bash command before it applies.",
 };
@@ -104,7 +214,41 @@ function isMode(value) {
     return value === "auto" || value === "plan" || value === "review";
 }
 function sideEffectTools(policy) {
-    return new Set([...policy.planBlockTools, ...policy.reviewConfirmTools]);
+    return new Set([
+        ...policy.planBlockTools,
+        ...policy.reviewConfirmTools,
+        ...(policy.alwaysConfirmTools ?? []),
+    ]);
+}
+function boundedPromptValue(value, fallback) {
+    if (typeof value !== "string")
+        return fallback;
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (normalized.length === 0)
+        return fallback;
+    return normalized.length <= 80 ? normalized : `${normalized.slice(0, 77)}…`;
+}
+function externalTrackerPrompt(toolName, input) {
+    if (toolName === "file_ticket") {
+        const title = boundedPromptValue(input.title, "Untitled ticket");
+        const target = boundedPromptValue(input.target_key, "default project/team");
+        return `File “${title}” in ${target}?`;
+    }
+    if (toolName === "update_ticket_status") {
+        const ref = boundedPromptValue(input.ref, "ticket");
+        const status = boundedPromptValue(input.status, "requested status");
+        return `Move ${ref} to ${status}?`;
+    }
+    return "Confirm external tracker change";
+}
+function guardianErrorMessage(error) {
+    switch (error) {
+        case "timeout": return "review timed out";
+        case "malformed": return "unclear verdict";
+        case "empty": return "no response";
+        case "network": return "service unavailable";
+        default: return "unknown error";
+    }
 }
 /**
  * Wire the tool_call gate + the /mode command onto a shared mode holder. Default
@@ -114,6 +258,11 @@ export function registerPermissionGate(pi, deps = {}) {
     const basePolicy = deps.policy ?? DEFAULT_PERMISSION_POLICY;
     let mode = deps.mode ?? "auto";
     const makeStore = deps.makeBlessStore ?? defaultMakeBlessStore;
+    deps.modeHolder?.onSet((m) => {
+        if (m !== mode)
+            approvedCommands.clear();
+        mode = m;
+    });
     // The session bless store is created lazily on the first tool_call (it needs
     // the cwd). Its isBlessed backs the review-mode auto-approve, UNLESS the caller
     // injected its own isBlessed (e.g. a test policy) — that always wins.
@@ -121,22 +270,420 @@ export function registerPermissionGate(pi, deps = {}) {
     const effectivePolicy = {
         planBlockTools: basePolicy.planBlockTools,
         reviewConfirmTools: basePolicy.reviewConfirmTools,
+        alwaysConfirmTools: basePolicy.alwaysConfirmTools,
+        // execPolicy MUST be carried through: decideGate reads policy.execPolicy
+        // and dropping it here silently reverts every custom policy to the
+        // default (round-2 review blocker).
+        execPolicy: basePolicy.execPolicy,
         isBlessed: basePolicy.isBlessed ?? ((tool, params) => blessStore?.isBlessed(tool, params) ?? false),
     };
     const sideEffects = sideEffectTools(effectivePolicy);
+    const guardianState = deps.guardianState;
+    const guardianLimits = deps.guardianLimits;
+    const guardianDisabled = deps.guardianDisabled ?? false;
+    const guardianReview = deps.guardianReview;
+    const guardianTier = deps.guardianTier;
+    // --- YAG-510 gate state ---
+    // Grants: in-memory list seeded from deps, appended on "don't ask again".
+    // Deliberately NOT live-reloaded from disk: auto mode can write files, so a
+    // mid-session re-read of rules.json would let the agent (or a prompt
+    // injection) author its own grants and self-authorize within the same
+    // session. New grants from concurrent sessions apply at next launch — the
+    // startup load is the trust boundary (PR #1698 review).
+    const grants = [...(deps.grants ?? [])];
+    // Keyed by cwd: a session can change working directory (cd, /go worktrees),
+    // and a repoKey memoized from the first cwd would let repo-A grants match
+    // commands running in repo B (PR #1694 review).
+    const repoKeys = new Map();
+    const resolveRepoKeyFor = (cwd) => {
+        let key = repoKeys.get(cwd);
+        if (key === undefined) {
+            key = deps.resolveRepoKey ? deps.resolveRepoKey(cwd) : cwd;
+            repoKeys.set(cwd, key);
+        }
+        return key;
+    };
+    // Session exact-command approval cache (ticket 4.5): a user-approved ask
+    // covers an identical later command. Keyed by cwd + trimmed command,
+    // LRU-capped, cleared on every /mode transition.
+    const APPROVED_CACHE_MAX = 50;
+    const approvedCommands = new Map();
+    const cacheKey = (cwd, command) => `${cwd}\u0000${command}`;
+    const rememberApproved = (cwd, command) => {
+        const key = cacheKey(cwd, command);
+        approvedCommands.delete(key);
+        approvedCommands.set(key, true);
+        if (approvedCommands.size > APPROVED_CACHE_MAX) {
+            const oldest = approvedCommands.keys().next().value;
+            if (oldest !== undefined)
+                approvedCommands.delete(oldest);
+        }
+    };
+    // Per-USER-PROMPT bounds (reset in before_agent_start, which fires once per
+    // user prompt — NOT per LLM turn): genuine ask verdicts are uncapped (the
+    // user's patience is the bound); error-fallback asks are capped so
+    // a provider outage can't become an ask storm; the breaker escalation is
+    // offered once, and a decline latches back to hard blocks.
+    const ERROR_ASK_CAP = 3;
+    let errorFallbackAsks = 0;
+    let breakerEscalationOffered = false;
+    const emitGateEvent = (event) => {
+        if (!deps.onGuardianEvent)
+            return;
+        try {
+            void Promise.resolve(deps.onGuardianEvent(event)).catch(() => { });
+        }
+        catch {
+            // Fail-soft: storage must never affect the gate.
+        }
+    };
+    /** Bounded single-line command rendering for dialog titles. */
+    const boundedCommand = (command) => {
+        const flat = command.replace(/\s+/g, " ").trim();
+        return flat.length <= 240 ? flat : `${flat.slice(0, 237)}…`;
+    };
+    const ASK_TIMEOUT_MS = 120_000;
+    const ASK_YES = "Yes, run it";
+    const ASK_NO = "No";
+    /**
+     * The single human-in-the-loop ask surface (YAG-510): used for ask
+     * verdicts, Guardian-unavailable/disabled fallbacks, and the breaker
+     * escalation — one UI, one cache, one event stream. Always passes the
+     * turn's abort signal (without it a turn-abort leaves the dialog hanging)
+     * and a timeout (pi renders a countdown; expiry fails closed).
+     */
+    const askUser = async (ctx, title, rememberLabel) => {
+        if (ctx.signal?.aborted)
+            return "aborted";
+        const options = rememberLabel ? [ASK_YES, rememberLabel, ASK_NO] : [ASK_YES, ASK_NO];
+        let choice;
+        try {
+            choice = await ctx.ui.select(title, options, {
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
+                timeout: ASK_TIMEOUT_MS,
+            });
+        }
+        catch {
+            choice = undefined;
+        }
+        if (choice === ASK_YES)
+            return "yes";
+        if (rememberLabel !== null && choice === rememberLabel)
+            return "remember";
+        if (choice === ASK_NO)
+            return "no";
+        return ctx.signal?.aborted ? "aborted" : "dismissed";
+    };
+    const buildAskTitle = (command, rationale, riskLevel) => {
+        const risk = riskLevel ? ` (risk: ${riskLevel})` : "";
+        return `Guardian asks${risk}\n${rationale}\n$ ${boundedCommand(command)}`;
+    };
     pi.on("tool_call", async (event, ctx) => {
+        // Snapshot the mode ONCE: /mode can flip mid-await, and post-await reads
+        // of the closure variable would disagree with the decision already made.
+        const modeAtEntry = mode;
         try {
             const input = event.input ?? {};
-            const decision = decideGate(event.toolName, input, mode, effectivePolicy);
+            const decision = decideGate(event.toolName, input, modeAtEntry, effectivePolicy);
             if (decision.block)
                 return { block: true, reason: decision.reason };
+            // Prompt band (YAG-510 order): grants → exact-command cache → cap/
+            // breaker → Guardian consult → allow/ask/deny. Grants and the cache are
+            // checked BEFORE the cap and breaker: a user-approved command must
+            // never be blocked by "review cap reached".
+            if (decision.classify === "prompt") {
+                const command = typeof input.command === "string"
+                    ? input.command.trim()
+                    : "";
+                const cwd = ctx?.cwd ?? ".";
+                const execJustification = decision.classifyJustification;
+                const eventBase = {
+                    command,
+                    ...(execJustification ? { execJustification } : {}),
+                    mode: modeAtEntry,
+                    ...(guardianTier ? { tier: guardianTier } : {}),
+                };
+                // 1. Persisted grants — auto mode only (review's contract is
+                // confirm-each-command). A grant can never cover forbidden commands:
+                // decideGate already returned block for those.
+                if (modeAtEntry === "auto" && command) {
+                    const grant = matchesGrant(command, grants, resolveRepoKeyFor(cwd));
+                    if (grant) {
+                        emitGateEvent({ ...eventBase, outcome: "prefix_allow", consulted: false });
+                        return {};
+                    }
+                }
+                // 2. Session exact-command approval cache (ticket 4.5).
+                if (command && approvedCommands.has(cacheKey(cwd, command))) {
+                    emitGateEvent({ ...eventBase, outcome: "cached_allow", consulted: false });
+                    return {};
+                }
+                const guardianAvailable = Boolean(guardianState && !guardianDisabled && guardianReview);
+                const limits = guardianLimits ?? DEFAULT_GUARDIAN_LIMITS;
+                if (guardianAvailable && guardianState.read().reviews >= limits.maxReviews) {
+                    // Sliding-window consult cap (capacity recovers as old reviews age
+                    // out — a long-lived session is never bricked). Review mode falls
+                    // through to its ordinary confirm (no LLM cost); auto blocks.
+                    if (modeAtEntry === "auto") {
+                        if (ctx?.hasUI)
+                            ctx.ui.notify(`Guardian review cap reached (${limits.maxReviews} in the last hour).`, "warning");
+                        return { block: true, reason: `Guardian review cap reached (${limits.maxReviews} in the last hour). Capacity recovers as older reviews age out; switch to /mode review to approve manually, or retry this step later.` };
+                    }
+                    // fall through to decision.confirm below
+                }
+                else if (guardianAvailable) {
+                    // Circuit breaker (pre-consult). With a UI, escalate to ONE ask per
+                    // user prompt — asking beats stopping; a decline latches back to
+                    // hard blocks for the rest of the prompt.
+                    const breaker = checkCircuitBreaker(guardianState.read(), limits);
+                    if (breaker.tripped) {
+                        if (ctx?.hasUI && !breakerEscalationOffered && !ctx.signal?.aborted) {
+                            breakerEscalationOffered = true;
+                            const title = `Guardian denied ${guardianState.read().consecutiveDenials} commands in a row.\nAllow the latest command anyway?\n$ ${boundedCommand(command)}`;
+                            const resolution = await askUser(ctx, title, null);
+                            if (resolution === "yes") {
+                                guardianState.resetTurn();
+                                rememberApproved(cwd, command);
+                                emitGateEvent({ ...eventBase, outcome: "breaker_ask_approved", consulted: false });
+                                return {};
+                            }
+                            if (resolution === "aborted") {
+                                emitGateEvent({ ...eventBase, outcome: "aborted", consulted: false });
+                                return { block: true };
+                            }
+                        }
+                        emitGateEvent({ ...eventBase, outcome: "breaker_blocked", consulted: false });
+                        if (ctx?.hasUI)
+                            ctx.ui.notify(breaker.reason ?? "Guardian circuit breaker tripped.", "warning");
+                        return { block: true, reason: breaker.reason };
+                    }
+                    // Show the reviewing chip.
+                    if (ctx?.hasUI)
+                        ctx.ui.setStatus?.("yagni-guardian", "Guardian Reviewing");
+                    const startMs = Date.now();
+                    let reviewResult;
+                    try {
+                        reviewResult = await guardianReview(command, {
+                            cwd,
+                            ...(ctx?.signal ? { signal: ctx.signal } : {}),
+                            ...(guardianTier ? { modelTier: guardianTier } : {}),
+                            timeoutMs: limits.timeoutMs,
+                            ...(execJustification ? { execJustification } : {}),
+                        });
+                    }
+                    catch {
+                        reviewResult = { verdict: null, error: "network", cost: 0 };
+                    }
+                    finally {
+                        if (ctx?.hasUI)
+                            ctx.ui.setStatus?.("yagni-guardian", undefined);
+                    }
+                    const durationMs = Date.now() - startMs;
+                    const emitDiag = (outcome, rationale) => {
+                        if (!deps.onGuardianReview)
+                            return;
+                        void Promise.resolve(deps.onGuardianReview(buildDiagnosticEvent(outcome, {
+                            durationMs,
+                            tier: guardianTier,
+                            ...(rationale ? { rationale } : {}),
+                            debug: isDebug(),
+                        }))).catch(() => { });
+                    };
+                    const verdict = reviewResult.verdict;
+                    if (verdict?.outcome === "allow") {
+                        guardianState.recordReview("allow");
+                        emitDiag("allow", verdict.rationale);
+                        emitGateEvent({
+                            ...eventBase,
+                            outcome: "allow",
+                            riskLevel: verdict.riskLevel,
+                            rationale: verdict.rationale,
+                            durationMs,
+                            consulted: true,
+                        });
+                        return {};
+                    }
+                    if (verdict?.outcome === "deny") {
+                        guardianState.recordReview("deny");
+                        const rationale = verdict.rationale;
+                        emitDiag("deny", rationale);
+                        emitGateEvent({
+                            ...eventBase,
+                            outcome: "deny",
+                            riskLevel: verdict.riskLevel,
+                            rationale,
+                            durationMs,
+                            consulted: true,
+                        });
+                        // Check circuit breaker after recording.
+                        const breaker2 = checkCircuitBreaker(guardianState.read(), limits);
+                        if (breaker2.tripped) {
+                            if (ctx?.hasUI)
+                                ctx.ui.notify(breaker2.reason ?? "Guardian circuit breaker tripped.", "warning");
+                        }
+                        else if (ctx?.hasUI) {
+                            ctx.ui.notify(`Guardian denied: ${rationale}`, "warning");
+                        }
+                        return {
+                            block: true,
+                            reason: `Guardian denied: ${rationale} Do not attempt the same outcome via a workaround or indirect execution — find a materially safer alternative, or ask the user to proceed.`,
+                        };
+                    }
+                    if (verdict?.outcome === "ask") {
+                        guardianState.recordReview("ask");
+                        emitDiag("ask", verdict.rationale);
+                        if (!ctx?.hasUI) {
+                            // Headless (includes every /go child stage): fail closed.
+                            emitGateEvent({
+                                ...eventBase,
+                                outcome: "ask_headless_blocked",
+                                riskLevel: verdict.riskLevel,
+                                rationale: verdict.rationale,
+                                durationMs,
+                                consulted: true,
+                            });
+                            return {
+                                block: true,
+                                reason: `Guardian needs user approval: ${verdict.rationale} No UI available — the command was held. Find a safer alternative or leave this step for the user.`,
+                            };
+                        }
+                        // Offer "don't ask again" only when the grant would actually
+                        // cover this command (grant-time validation).
+                        const grantCandidate = validateGrant(command, effectivePolicy.execPolicy ?? DEFAULT_EXEC_POLICY, resolveRepoKeyFor(cwd));
+                        const rememberLabel = grantCandidate
+                            ? `Yes, and don't ask again for \`${describePrefix(grantCandidate.pattern)}\` in this repo`
+                            : null;
+                        const resolution = await askUser(ctx, buildAskTitle(command, verdict.rationale, verdict.riskLevel), rememberLabel);
+                        if (resolution === "yes") {
+                            rememberApproved(cwd, command);
+                            emitGateEvent({
+                                ...eventBase,
+                                outcome: "ask_approved",
+                                riskLevel: verdict.riskLevel,
+                                rationale: verdict.rationale,
+                                durationMs,
+                                consulted: true,
+                            });
+                            return {};
+                        }
+                        if (resolution === "remember" && grantCandidate) {
+                            const grantRecord = {
+                                ...grantCandidate,
+                                cwd,
+                                addedAt: new Date().toISOString(),
+                            };
+                            grants.push(grantRecord);
+                            try {
+                                deps.persistGrant?.(grantRecord);
+                            }
+                            catch {
+                                // Fail-soft: the in-memory grant still applies this session.
+                            }
+                            emitGateEvent({
+                                ...eventBase,
+                                outcome: "ask_approved_remembered",
+                                riskLevel: verdict.riskLevel,
+                                rationale: verdict.rationale,
+                                durationMs,
+                                consulted: true,
+                            });
+                            return {};
+                        }
+                        if (resolution === "aborted") {
+                            // The user is abandoning the turn — no steering text (do not
+                            // tell an aborting model it was "denied").
+                            emitGateEvent({ ...eventBase, outcome: "aborted", durationMs, consulted: true });
+                            return { block: true };
+                        }
+                        emitGateEvent({
+                            ...eventBase,
+                            outcome: "ask_denied",
+                            riskLevel: verdict.riskLevel,
+                            rationale: verdict.rationale,
+                            durationMs,
+                            consulted: true,
+                        });
+                        if (resolution === "no") {
+                            return {
+                                block: true,
+                                reason: "The user declined this command. Ask what they would like to do differently, or take a different approach.",
+                            };
+                        }
+                        // dismissed / dialog timeout — neutral reason, no "denied" spin.
+                        return {
+                            block: true,
+                            reason: "The permission dialog was dismissed; the command was not run. Ask the user how to proceed.",
+                        };
+                    }
+                    // Guardian failed (timeout/malformed/network/empty/aborted).
+                    const error = reviewResult.error ?? "network";
+                    emitDiag(error);
+                    if (error === "aborted" || ctx?.signal?.aborted) {
+                        // The user aborted mid-consult — silent block: no dialog, no
+                        // "Guardian unavailable" warning on a turn they deliberately
+                        // killed. (Belt and braces with reviewCommand's own aborted
+                        // detection — an aborted child can die in shapes that look like
+                        // other errors.)
+                        emitGateEvent({ ...eventBase, outcome: "aborted", durationMs, consulted: false });
+                        return { block: true };
+                    }
+                    if (modeAtEntry === "review" && decision.confirm) {
+                        // Review mode: fall through to the ordinary confirm below —
+                        // uncapped; the mode's contract is manual approval and an outage
+                        // must not lock the user out of their own confirm flow.
+                    }
+                    else if (ctx?.hasUI && !ctx.signal?.aborted && errorFallbackAsks < ERROR_ASK_CAP) {
+                        // Auto mode with a user present: ask instead of stopping —
+                        // bounded per prompt so an outage can't become an ask storm.
+                        errorFallbackAsks += 1;
+                        const errorMsg = guardianErrorMessage(error);
+                        const resolution = await askUser(ctx, `Guardian unavailable (${errorMsg}).\nRun this command anyway?\n$ ${boundedCommand(command)}`, null);
+                        if (resolution === "yes") {
+                            rememberApproved(cwd, command);
+                            emitGateEvent({ ...eventBase, outcome: "ask_approved", guardianError: error, durationMs, consulted: false });
+                            return {};
+                        }
+                        if (resolution === "aborted") {
+                            emitGateEvent({ ...eventBase, outcome: "aborted", durationMs, consulted: false });
+                            return { block: true };
+                        }
+                        emitGateEvent({ ...eventBase, outcome: "ask_denied", guardianError: error, durationMs, consulted: false });
+                        const timeoutNote = error === "timeout" ? " The timeout is not evidence the command is unsafe." : "";
+                        return {
+                            block: true,
+                            reason: `The user declined while the Guardian was unavailable (${errorMsg}).${timeoutNote} Find a safer alternative or ask the user.`,
+                        };
+                    }
+                    else {
+                        const errorMsg = guardianErrorMessage(error);
+                        emitGateEvent({ ...eventBase, outcome: error, durationMs, consulted: false });
+                        if (ctx?.hasUI)
+                            ctx.ui.notify(`Guardian unavailable: ${errorMsg}`, "warning");
+                        const timeoutNote = error === "timeout" ? " Do not assume the command is unsafe from the timeout alone; you may retry once or ask the user." : "";
+                        return {
+                            block: true,
+                            reason: `Guardian unavailable (${errorMsg}).${timeoutNote} Switch to /mode review to approve manually.`,
+                        };
+                    }
+                }
+                else if (modeAtEntry === "auto") {
+                    // Guardian disabled (kill switch / env var) or not wired: pre-Guardian
+                    // behavior (#1692). Auto mode allows prompt-band commands — the kill
+                    // switch must never leave sessions stricter than before Guardian
+                    // existed, and it must not replace Guardian with dialogs either. The
+                    // forbidden band still blocks above (decideGate); grants and the
+                    // approval cache were already consulted above.
+                    return {};
+                }
+                // review mode with Guardian disabled/capped: fall through to confirm.
+            }
             if (decision.confirm) {
                 // Review mode needs a confirmation. With no dialog-capable UI (headless),
                 // fail CLOSED: the user explicitly chose a stricter mode, so a write we
                 // cannot get consent for is held rather than silently auto-applied (this
                 // mirrors plan mode, which blocks regardless of UI).
                 if (!ctx?.hasUI) {
-                    return { block: true, reason: `review mode: ${event.toolName} held (no UI to confirm). Switch to /mode auto to apply.` };
+                    return { block: true, reason: `${event.toolName} held (no UI to confirm this action).` };
                 }
                 // Lazily bind the bless store to this session's cwd.
                 if (!blessStore)
@@ -144,14 +691,16 @@ export function registerPermissionGate(pi, deps = {}) {
                 // Three-way prompt (pi's confirm is boolean-only, so use select): Yes,
                 // Yes-and-remember (only when a path-prefix bless is meaningful), or No.
                 const dir = blessStore.describeDir(input);
-                const blessable = dir !== null;
+                const blessable = dir !== null && !effectivePolicy.alwaysConfirmTools?.includes(event.toolName);
                 const yes = "Yes";
                 const no = "No";
                 const remember = blessable
                     ? `Yes, and don't ask again for ${event.toolName} in ${dir}`
                     : undefined;
                 const options = blessable ? [yes, remember, no] : [yes, no];
-                const choice = await ctx.ui.select("YAGNI Code review mode", options);
+                const choice = await ctx.ui.select(effectivePolicy.alwaysConfirmTools?.includes(event.toolName)
+                    ? externalTrackerPrompt(event.toolName, input)
+                    : "YAGNI Code review mode", options);
                 if (choice === yes)
                     return {};
                 if (blessable && choice === remember) {
@@ -169,43 +718,40 @@ export function registerPermissionGate(pi, deps = {}) {
             return {};
         }
         catch {
-            if (mode !== "auto" && sideEffects.has(event.toolName)) {
+            if (modeAtEntry !== "auto" && sideEffects.has(event.toolName)) {
                 return {
                     block: true,
-                    reason: `permission gate failed while ${mode} mode was active; held ${event.toolName}. Switch to /mode auto to apply.`,
+                    reason: `permission gate failed while ${modeAtEntry} mode was active; held ${event.toolName}. Switch to /mode auto to apply.`,
                 };
             }
             return {};
         }
     });
-    // Model awareness: while plan mode is on, every agent start carries a hidden
-    // plan-mode context message so the model plans instead of attempting held
-    // writes. Off-plan turns inject nothing.
+    // Model awareness: every agent turn carries a hidden mode-context message so
+    // the model knows what it can do (auto: verify proactively, review: wait for
+    // approval, plan: hold writes). The context hook strips stale mode context
+    // from prior turns so old mode messages don't accumulate.
     pi.on("before_agent_start", async () => {
-        if (mode !== "plan")
-            return;
+        // before_agent_start fires once per USER PROMPT (not per LLM turn).
+        // Reset the per-prompt bounds here: the Guardian denial streak, the
+        // error-fallback ask budget, and the breaker-escalation latch.
+        deps.guardianState?.resetTurn();
+        errorFallbackAsks = 0;
+        breakerEscalationOffered = false;
         return {
-            message: { customType: PLAN_CONTEXT_TYPE, content: PLAN_CONTEXT_MESSAGE, display: false },
+            message: { customType: MODE_CONTEXT_TYPE, content: buildModeContextMessage(mode), display: false },
         };
     });
-    // Once plan mode is off, strip the stale plan context so the model does not
-    // keep believing writes are held.
+    // Strip stale mode-context messages from prior turns so the model does not
+    // see contradictory mode instructions.
     pi.on("context", async (event) => {
-        if (mode === "plan")
-            return;
-        const filtered = filterStalePlanContext(event.messages);
+        const filtered = filterStaleModeContext(event.messages, mode);
         if (filtered === event.messages)
             return;
         return { messages: filtered };
     });
     const paintMode = (ctx) => {
-        try {
-            if (ctx.hasUI)
-                ctx.ui.setStatus?.("yagni-mode", MODE_STATUS[mode]);
-        }
-        catch {
-            // The chip is chrome; never let it break /mode.
-        }
+        deps.modeHolder?.set(mode);
     };
     pi.registerCommand("mode", {
         description: "Set the permission tier: /mode auto | plan | review. No argument shows the current mode.",
@@ -224,6 +770,11 @@ export function registerPermissionGate(pi, deps = {}) {
                 return;
             }
             const leavingPlan = mode === "plan" && arg !== "plan";
+            if (arg !== mode) {
+                // A mode change is a trust-posture change: session ask-approvals do
+                // not carry across it (grants persist but are suppressed in review).
+                approvedCommands.clear();
+            }
             mode = arg;
             paintMode(ctx);
             notify(`Permission mode set to ${mode}. ${MODE_COPY[mode]}`, "info");