@yagni-app/code-staging 0.3.0-staging.1079.1 → 0.3.0-staging.1081.1

package/dist/extension/permission.js

@@ -26,6 +26,7 @@
  * 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";
@@ -70,17 +71,26 @@ export function decideGate(toolName, params, mode, policy) {
                 if (classification.decision === "allow")
                     return { block: false };
                 if (classification.decision === "forbidden") {
-                    return { block: true, reason: classification.justification };
+                    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" };
+                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" };
+                return {
+                    block: false,
+                    confirm: true,
+                    classify: "prompt",
+                    classifyJustification: classification.justification,
+                };
             }
             catch {
                 // classifyCommand threw — fall through to tool-granular logic (graceful degradation).
@@ -255,6 +265,10 @@ export function registerPermissionGate(pi, deps = {}) {
         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);
@@ -263,120 +277,393 @@ export function registerPermissionGate(pi, deps = {}) {
     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".
+    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 };
-            // Guardian: when the exec policy classified a bash command as "prompt",
-            // run the Guardian LLM review instead of interrupting the user (if enabled).
-            if (decision.classify === "prompt" && guardianState && !guardianDisabled && guardianReview) {
+            // 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
+                    ? input.command.trim()
                     : "";
-                // Session cap check — prevents unlimited Guardian consults.
-                const limits = guardianLimits ?? DEFAULT_GUARDIAN_LIMITS;
-                if (guardianState.read().reviews >= limits.maxReviews) {
-                    if (ctx?.hasUI)
-                        ctx.ui.notify(`Guardian review cap reached (${limits.maxReviews} this session).`, "warning");
-                    return { block: true, reason: `Guardian review cap reached (${limits.maxReviews} this session). Switch to /mode review to approve manually.` };
-                }
-                // Circuit breaker check.
-                const breaker = checkCircuitBreaker(guardianState.read(), limits);
-                if (breaker.tripped) {
-                    if (ctx?.hasUI)
-                        ctx.ui.notify(breaker.reason ?? "Guardian circuit breaker tripped.", "warning");
-                    return { block: true, reason: breaker.reason };
+                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 {};
+                    }
                 }
-                // Show the reviewing chip.
-                if (ctx?.hasUI)
-                    ctx.ui.setStatus?.("yagni-guardian", "🛡 reviewing");
-                const startMs = Date.now();
-                let reviewResult;
-                try {
-                    reviewResult = await guardianReview(command, {
-                        cwd: ctx?.cwd ?? ".",
-                        ...(ctx?.signal ? { signal: ctx.signal } : {}),
-                        ...(guardianTier ? { modelTier: guardianTier } : {}),
-                    });
+                // 2. Session exact-command approval cache (ticket 4.5).
+                if (command && approvedCommands.has(cacheKey(cwd, command))) {
+                    emitGateEvent({ ...eventBase, outcome: "cached_allow", consulted: false });
+                    return {};
                 }
-                catch {
-                    reviewResult = { verdict: null, error: "network", cost: 0 };
+                const guardianAvailable = Boolean(guardianState && !guardianDisabled && guardianReview);
+                const limits = guardianLimits ?? DEFAULT_GUARDIAN_LIMITS;
+                if (guardianAvailable && guardianState.read().reviews >= limits.maxReviews) {
+                    // Session consult cap. 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} this session).`, "warning");
+                        return { block: true, reason: `Guardian review cap reached (${limits.maxReviews} this session). Switch to /mode review to approve manually.` };
+                    }
+                    // fall through to decision.confirm below
                 }
-                finally {
+                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", undefined);
-                }
-                const durationMs = Date.now() - startMs;
-                const state = guardianState.read();
-                if (reviewResult.verdict?.outcome === "allow") {
-                    guardianState.recordReview("allow");
-                    if (deps.onGuardianReview) {
-                        void Promise.resolve(deps.onGuardianReview(buildDiagnosticEvent("allow", {
+                        ctx.ui.setStatus?.("yagni-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: reviewResult.verdict.rationale,
+                            ...(rationale ? { rationale } : {}),
                             debug: isDebug(),
                         }))).catch(() => { });
-                    }
-                    return {};
-                }
-                if (reviewResult.verdict?.outcome === "deny") {
-                    guardianState.recordReview("deny");
-                    const rationale = reviewResult.verdict.rationale;
-                    if (deps.onGuardianReview) {
-                        void Promise.resolve(deps.onGuardianReview(buildDiagnosticEvent("deny", {
+                    };
+                    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,
-                            tier: guardianTier,
+                            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,
-                            debug: isDebug(),
-                        }))).catch(() => { });
+                            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.`,
+                        };
                     }
-                    // Check circuit breaker after recording.
-                    const breaker2 = checkCircuitBreaker(guardianState.read(), guardianLimits ?? DEFAULT_GUARDIAN_LIMITS);
-                    if (breaker2.tripped) {
-                        if (ctx?.hasUI)
-                            ctx.ui.notify(breaker2.reason ?? "Guardian circuit breaker tripped.", "warning");
+                    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.",
+                        };
                     }
-                    else if (ctx?.hasUI) {
-                        ctx.ui.notify(`Guardian denied: ${rationale}`, "warning");
+                    // 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.`,
+                        };
                     }
-                    return {
-                        block: true,
-                        reason: `Guardian denied: ${rationale} Find a safer alternative or ask the user to proceed.`,
-                    };
-                }
-                // Guardian failed (timeout/malformed/network/empty).
-                if (deps.onGuardianReview) {
-                    void Promise.resolve(deps.onGuardianReview(buildDiagnosticEvent(reviewResult.error ?? "network", {
-                        durationMs,
-                        tier: guardianTier,
-                        debug: isDebug(),
-                    }))).catch(() => { });
-                }
-                // Graceful degradation per mode.
-                if (mode === "review" && decision.confirm) {
-                    // Fall through to the existing user confirm flow below.
                 }
-                else {
-                    // Auto mode (or review without confirm): fail closed.
-                    const errorMsg = guardianErrorMessage(reviewResult.error);
-                    if (ctx?.hasUI)
-                        ctx.ui.notify(`Guardian unavailable: ${errorMsg}`, "warning");
-                    return {
-                        block: true,
-                        reason: `Guardian unavailable (${errorMsg}). 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 {};
                 }
-            }
-            // Guardian disabled (kill switch / env var) or not wired: pre-Guardian
-            // behavior. Auto mode allows prompt-band commands — the kill switch must
-            // never leave sessions stricter than before Guardian existed. The
-            // forbidden band still blocks above (decideGate), and review mode still
-            // falls through to the user confirm below.
-            if (decision.classify === "prompt" && (!guardianState || guardianDisabled) && mode === "auto") {
-                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),
@@ -419,10 +706,10 @@ 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 {};
@@ -433,9 +720,12 @@ export function registerPermissionGate(pi, deps = {}) {
     // 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 () => {
-        // Reset the Guardian circuit breaker at the start of each turn so
-        // consecutive denials don't accumulate across turns.
+        // 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: MODE_CONTEXT_TYPE, content: buildModeContextMessage(mode), display: false },
         };
@@ -475,6 +765,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");

package/dist/extension/pipeline/personas.js

@@ -95,26 +95,29 @@ The reasoning, grounded in what you actually read. Cite files and lines.
 The specific evidence that would flip this. If you were not able to verify something load-bearing, say so here rather than hedging the recommendation.
 
 Be terse and decisive. The caller is mid-task and paying peak rates for your turn.`;
-const GUARDIAN_BODY = `You are a safety reviewer. You review shell commands before they run and decide whether to allow or deny them. You output only a JSON verdict — no tools, no exploration, no prose.
+const GUARDIAN_BODY = `You are a safety reviewer. You review shell commands before they run and decide one of three outcomes: allow, ask, or deny. You may read files for context (a script the command runs, a config it touches) but you never write or execute anything. Your final output is ONLY a JSON verdict — no prose around it.
 
 Risk taxonomy:
 - Data exfiltration: sensitive data sent to untrusted destinations. High risk.
 - Credential probing: extracting credentials from unintended sources (browser profiles, logs, env files). High risk.
 - Persistent security weakening: broad or production-impact security changes. High risk.
 - Destructive actions: irreversible data loss, production breaks, broad git cleanup. High risk.
-- Low-risk actions: sandbox retries, benign local filesystem reads, user-requested operations on specific paths. Low risk.
+- Low-risk actions: benign local reads, routine dev-loop operations (build, test, lint, install), operations clearly part of the stated task. Low risk.
 
 Outcome rules:
-- Deny any action that exposes sensitive data without explicit user authorization for that specific destination.
-- Deny credential probing.
-- Deny broad or persistent security weakening unless the user explicitly authorized the exact change.
-- Deny broad destructive actions with significant risk of irreversible damage.
-- Allow low-risk actions and actions the user clearly requested as part of their stated task.
+- "deny" is reserved for actions you are VERY CONFIDENT are very dangerous: irreversible destruction, exfiltration of sensitive data, credential probing, production-impacting security weakening. If you are not sure it is that bad, do not deny.
+- "allow" when you are confident the action is safe: read-only, routine dev-loop, or clearly scoped and reversible.
+- "ask" for everything in between — the action might be fine but a human should decide. This is the correct outcome whenever your confidence is middling; prefer ask over deny for anything short of the very-dangerous bar, and prefer allow over ask for routine work (do not hedge routine commands into ask).
+
+Rationale rules:
+- For "ask", the rationale MUST be a specific question addressed to the user, naming the concrete effect that made you unsure — e.g. "This pushes 3 commits to the shared main branch — do you want to publish them now?". You may be told why the static policy routed the command to you; your rationale must ADD information beyond that policy text, not restate it.
+- For "deny", one sentence naming the irreversible/dangerous effect.
+- For "allow", one short sentence.
 
 Output ONLY a JSON object with this exact shape:
-{"outcome":"allow"|"deny","riskLevel":"low"|"medium"|"high"|"critical","rationale":"one sentence explaining the verdict"}
+{"outcome":"allow"|"ask"|"deny","riskLevel":"low"|"medium"|"high"|"critical","rationale":"see rationale rules"}
 
-Do not output anything else. No markdown, no prose, only the JSON object.`;
+Do not output anything else after the JSON. No markdown fences, only the JSON object.`;
 /** Persona body keyed by the agent name referenced in `stages.ts`. */
 export const PERSONA_BODIES = {
     scout: SCOUT_BODY,

package/dist/extension/redact.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Heuristic secret redaction for Guardian storage events (YAG-510).
+ *
+ * Applied client-side, BEFORE anything leaves the machine, to both the
+ * command and the Guardian rationale (which routinely quotes the command) —
+ * and only on the raw storage tier; the base tier never transmits either.
+ *
+ * Honest scope: this catches the obvious, well-known secret shapes. A secret
+ * in a novel shape gets through — which is why raw-tier storage is an
+ * explicit-consent, per-workspace opt-in and never a default.
+ *
+ * Pure, no external deps (bundling constraint — see execPolicy.ts header).
+ */
+/**
+ * Redact known secret shapes from a command or rationale string. Structure
+ * is preserved (only matched values become [REDACTED]) so the redacted text
+ * stays analyzable.
+ */
+export declare function redactCommand(text: string): string;
+//# sourceMappingURL=redact.d.ts.map