@yagni-app/code 1.0.6 → 1.0.8

package/dist/extension/permission/gate.js

@@ -27,8 +27,10 @@
  * the context so the model doesn't keep believing it is restricted.
  */
 import { describePrefix, matchesGrant, validateGrant, } from "./approvedPrefixes.js";
+import { logEvent } from "../errorSink.js";
 import { makeBlessStore as defaultMakeBlessStore } from "../bless.js";
 import { classifyCommand, DEFAULT_EXEC_POLICY } from "./execPolicy.js";
+import { evaluateRules } from "../permissionRules/engine.js";
 import { isDebug } from "../diagnostics.js";
 import { buildDiagnosticEvent, checkCircuitBreaker, DEFAULT_GUARDIAN_LIMITS, } from "./guardian.js";
 export function createModeHolder(initial = "auto") {
@@ -49,6 +51,52 @@ export const DEFAULT_PERMISSION_POLICY = {
     reviewConfirmTools: ["write", "edit", "bash", "file_ticket", "update_ticket_status"],
     alwaysConfirmTools: ["file_ticket", "update_ticket_status"],
 };
+export function allowRuleFloorVerdict(toolName, params, mode, policy) {
+    // Floor 0 — plan mode: the mode's contract (no mutations without Guardian
+    // review; grants are already skipped in plan) applies BEFORE any allow
+    // rule. Side-effect tools route to the existing plan-mode gate below; a
+    // non-side-effect tool (read/grep/ask_yagni/…) allows — plan mode never
+    // held reads. Deny/ask rules fired before this point (they only restrict).
+    if (mode === "plan" && sideEffectToolsFor(policy).has(toolName)) {
+        return { kind: "hold" };
+    }
+    // Floor 1 — the exec-policy forbidden band (bash only). An allow rule can
+    // never un-forbid a destructive command.
+    if (toolName === "bash") {
+        const cmdRaw = params.command;
+        const command = typeof cmdRaw === "string" ? cmdRaw.trim() : "";
+        if (command) {
+            try {
+                const execPolicy = policy.execPolicy ?? DEFAULT_EXEC_POLICY;
+                const classification = classifyCommand(command, execPolicy);
+                if (classification.decision === "forbidden") {
+                    return {
+                        kind: "block",
+                        reason: `${classification.justification}. Do not attempt the same outcome via a workaround or indirect execution — use a materially safer alternative, or ask the user.`,
+                    };
+                }
+            }
+            catch {
+                // classifyCommand threw — no floor opinion from here (the normal gate
+                // path re-runs classification with its own fail-closed handling).
+            }
+        }
+    }
+    // Floor 2 — alwaysConfirmTools keeps its fresh-consent contract
+    // (file_ticket / update_ticket_status) in every mode.
+    if (policy.alwaysConfirmTools?.includes(toolName)) {
+        return { kind: "confirm" };
+    }
+    return { kind: "allow" };
+}
+/** The side-effect tool set for a policy (plan-mode hold decision). */
+function sideEffectToolsFor(policy) {
+    return new Set([
+        ...policy.planBlockTools,
+        ...policy.reviewConfirmTools,
+        ...(policy.alwaysConfirmTools ?? []),
+    ]);
+}
 /**
  * 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
@@ -288,6 +336,56 @@ function guardianErrorMessage(error) {
         default: return "unknown error";
     }
 }
+/**
+ * The pi tool_call handler wiring (crash-honest attribution). Extracted so
+ * the telemetry contract is testable against the production path: a thrown
+ * gate records reject — never accept — logs a gate_crashed line (metadata
+ * only), and rethrows so pi's handling of a crashed handler is unchanged.
+ */
+export function wireToolCallGate(pi, run, onToolDecision) {
+    pi.on("tool_call", async (event, ctx) => {
+        const slot = { source: "config" };
+        let result;
+        let crashed = false;
+        try {
+            result = await run(event, ctx, slot);
+            return result;
+        }
+        catch (err) {
+            crashed = true;
+            logEvent({
+                source: "permission-rules",
+                level: "error",
+                event: "gate_crashed",
+                fields: {
+                    tool: event.toolName,
+                    errorClass: err instanceof Error ? err.constructor.name : String(err),
+                },
+            });
+            throw err;
+        }
+        finally {
+            if (onToolDecision) {
+                try {
+                    const input = (event.input ?? {});
+                    const filePath = typeof input.path === "string" ? input.path : typeof input.file_path === "string" ? input.file_path : undefined;
+                    onToolDecision({
+                        toolName: event.toolName,
+                        ...(event.toolCallId ? { toolCallId: event.toolCallId } : {}),
+                        // An explicit block is a reject; an allow is an accept; a CRASH
+                        // is a reject (fail-closed attribution) — never an accept.
+                        decision: result?.block || crashed ? "reject" : "accept",
+                        source: slot.source,
+                        ...(filePath ? { filePath } : {}),
+                    });
+                }
+                catch {
+                    // Telemetry must never affect the gate.
+                }
+            }
+        }
+    });
+}
 /**
  * Wire the tool_call gate + the /mode command onto a shared mode holder. Default
  * auto, so absent any /mode this is a no-op over today's behavior.
@@ -300,6 +398,8 @@ export function registerPermissionGate(pi, deps = {}) {
     deps.modeHolder?.onSet((m) => {
         if (m !== mode)
             approvedCommands.clear();
+        if (m !== mode)
+            ruleAskApprovals.clear();
         mode = m;
     });
     // The session bless store is created lazily on the first tool_call (it needs
@@ -349,6 +449,23 @@ export function registerPermissionGate(pi, deps = {}) {
     // LRU-capped, cleared on every /mode transition.
     const APPROVED_CACHE_MAX = 50;
     const approvedCommands = new Map();
+    // Session cache for ASK-RULE approvals (the rules analog of the exact-command
+    // approval cache above): a user "yes" on a permission-rule ask covers an
+    // identical later (tool, rule, input) call for the rest of the session, so a
+    // retrying model cannot re-prompt the same question in a loop. Keyed by
+    // tool + rule raw + the primary input param; cleared with the other caches
+    // on every /mode transition (mode changes re-ask — the safe direction).
+    const ruleAskApprovals = new Map();
+    const ruleAskKey = (toolName, ruleRaw, params) => {
+        const primary = typeof params.command === "string"
+            ? params.command
+            : typeof params.path === "string"
+                ? params.path
+                : typeof params.url === "string"
+                    ? params.url
+                    : JSON.stringify(params);
+        return `${toolName}\u0000${ruleRaw}\u0000${primary}`;
+    };
     const cacheKey = (cwd, command) => `${cwd}\u0000${command}`;
     const rememberApproved = (cwd, command) => {
         const key = cacheKey(cwd, command);
@@ -372,7 +489,16 @@ export function registerPermissionGate(pi, deps = {}) {
     // calls can start their reviews in the same millisecond, and a timestamp
     // alone would silently drop the second review's spend as a "duplicate".
     let reviewSpendSeq = 0;
-    const emitGateEvent = (event) => {
+    const GUARDIAN_OUTCOME_SOURCE = {
+        ask_approved: "user_temporary",
+        breaker_ask_approved: "user_temporary",
+        ask_approved_remembered: "user_permanent",
+        ask_denied: "user_reject",
+    };
+    const emitGateEvent = (slot, event) => {
+        const mapped = GUARDIAN_OUTCOME_SOURCE[event.outcome];
+        if (mapped)
+            slot.source = mapped;
         if (!deps.onGuardianEvent)
             return;
         try {
@@ -387,48 +513,279 @@ export function registerPermissionGate(pi, deps = {}) {
         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 ask dialog now waits indefinitely, so an unanswered ask is a silent
+     * unbounded pause: a lost RPC client or an abandoned dialog hangs the
+     * session with nothing in the trail to explain why. Emit one sanitized
+     * event when the dialog OPENS — kind + tool ONLY. The sink's default-on
+     * contract is content-free (raw content is gated behind YAGNI_DEBUG), and
+     * even the rule string stays out: it is user-authored free text that can
+     * embed secret-bearing fragments (env assignments, URL credentials), and
+     * a rule ask is already fully identified by kind "rule" + the tool. Fail-
+     * soft; the sink never throws into the gate.
+     */
+    const logAskOpened = (kind, toolName) => {
+        try {
+            logEvent({
+                source: "guardian",
+                level: "info",
+                event: "guardian_ask_opened",
+                fields: { kind, tool: toolName },
+            });
+        }
+        catch {
+            /* telemetry must never affect the gate */
+        }
+    };
+    /**
+     * The paired resolution event: with no dialog timeout, the pause DURATION
+     * and its OUTCOME are the story (answered vs ESC-dismissed vs turn-aborted),
+     * and a dismissed dialog would otherwise leave no trail line of its own.
+     * kind + tool + outcome only — all enum values, nothing content-bearing.
+     * durationMs makes the pause directly readable instead of timestamp-diffing
+     * two lines. Same fail-soft contract as the open event.
+     */
+    const logAskResolved = (kind, toolName, outcome, openedAt) => {
+        try {
+            logEvent({
+                source: "guardian",
+                level: "info",
+                event: "guardian_ask_resolved",
+                fields: { kind, tool: toolName, outcome, durationMs: Date.now() - openedAt },
+            });
+        }
+        catch {
+            /* telemetry must never affect the gate */
+        }
+    };
+    /**
+     * The single choice-to-resolution mapping BOTH ask dialogs share — one
+     * place, so the two surfaces can never drift. The option labels the dialog
+     * actually offered are passed in; the rule rung is null when the plain
+     * dialog didn't offer it. An aborted turn wins over any choice value; a
+     * real user ESC maps to "dismissed" (the no-abort, no-answer bucket —
+     * ESC resolves undefined in pi). A THROWN select never reaches this
+     * function: the dialogs route it to thrownChoiceResolution, which is the
+     * ONLY source of outcome "error". Both fail closed identically
+     * downstream — only the telemetry distinguishes them.
+     */
+    const resolveChoice = (choice, opts) => {
+        if (opts.aborted)
+            return "aborted";
+        if (choice === ASK_YES)
+            return "yes";
+        if (opts.rememberLabel !== null && choice === opts.rememberLabel)
+            return "remember";
+        if (opts.ruleLabel != null && choice === opts.ruleLabel)
+            return "rule";
+        if (choice === ASK_NO)
+            return "no";
+        // No abort and no recognizable answer — a real ESC (pi resolves a
+        // dismissed dialog as undefined) or any unmatched value. NEVER the
+        // thrown-select path: that maps to "error" in thrownChoiceResolution.
+        return "dismissed";
+    };
+    /**
+     * Map a THROWN select to its resolution: the UI/RPC layer failed (dead
+     * client, disposed dialog) — never a human answer. Distinct from ESC in
+     * the trail so a lost client is attributable; blocks exactly like a
+     * dismissal downstream (fail closed).
+     */
+    const thrownChoiceResolution = (aborted) => aborted ? "aborted" : "error";
     /**
      * 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).
+     * turn's abort signal (without it a turn-abort leaves the dialog hanging).
+     *
+     * No dialog timeout — Claude Code parity: a permission ask waits
+     * indefinitely for the human. The only dismissal paths are the user
+     * answering, dismissing the dialog (ESC), the turn aborting (Ctrl-C /
+     * interrupt), or the UI layer failing (outcome "error", fail closed).
+     * The old 120s auto-fail-closed cap is gone; an unattended dialog pauses
+     * the session rather than denying the command.
      */
-    const askUser = async (ctx, title, rememberLabel) => {
+    const askUser = async (ctx, title, rememberLabel, kind = "guardian_verdict", toolName = "bash") => {
         if (ctx.signal?.aborted)
             return "aborted";
+        logAskOpened(kind, toolName);
+        const openedAt = Date.now();
         const options = rememberLabel ? [ASK_YES, rememberLabel, ASK_NO] : [ASK_YES, ASK_NO];
         let choice;
+        let selectThrew = false;
         try {
             choice = await ctx.ui.select(title, options, {
                 ...(ctx.signal ? { signal: ctx.signal } : {}),
-                timeout: ASK_TIMEOUT_MS,
             });
         }
         catch {
-            choice = undefined;
+            selectThrew = true;
         }
-        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 resolution = selectThrew
+            ? thrownChoiceResolution(ctx.signal?.aborted ?? false)
+            : resolveChoice(choice, { rememberLabel, aborted: ctx.signal?.aborted ?? false });
+        logAskResolved(kind, toolName, resolution, openedAt);
+        return resolution;
+    };
+    /**
+     * variant: the Guardian ask dialog with an optional third option
+     * (persist a user-level permission rule). Same semantics as askUser
+     * (indefinite wait, turn-abort signal only). kind/toolName are threaded
+     * through — never hardcoded here — so a future non-bash caller cannot
+     * silently misattribute the dialog in the trail.
+     */
+    const askUserWithOptions = async (ctx, title, rememberLabel, ruleLabel, kind = "guardian_verdict", toolName = "bash") => {
+        if (ctx.signal?.aborted)
+            return "aborted";
+        logAskOpened(kind, toolName);
+        const openedAt = Date.now();
+        const options = [
+            ASK_YES,
+            ...(rememberLabel ? [rememberLabel] : []),
+            ...(ruleLabel ? [ruleLabel] : []),
+            ASK_NO,
+        ];
+        let choice;
+        let selectThrew = false;
+        try {
+            choice = await ctx.ui.select(title, options, {
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
+            });
+        }
+        catch {
+            selectThrew = true;
+        }
+        const resolution = selectThrew
+            ? thrownChoiceResolution(ctx.signal?.aborted ?? false)
+            : resolveChoice(choice, { rememberLabel, ruleLabel, aborted: ctx.signal?.aborted ?? false });
+        logAskResolved(kind, toolName, resolution, openedAt);
+        return resolution;
     };
     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) => {
+    const gateToolCall = async (event, ctx, slot) => {
         // 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;
+        // set when an allow-rule verdict hits an alwaysConfirmTools tool
+        // (Floor 2) — forces the confirm flow below instead of short-circuiting.
+        let ruleAskConfirm = false;
         try {
             const input = event.input ?? {};
+            // settings permission rules run BEFORE hooks (Claude Code
+            // semantics: a deny rule blocks even when a hook would allow). Order
+            // deny → ask → allow; the verdict is final for deny/ask, and allow
+            // short-circuits everything below EXCEPT the two hard floors.
+            const rulesDeps = deps.permissionRules;
+            // The guard + evaluation share ONE try: a poisoned rules array can
+            // throw at the `.length` guard just as easily as inside evaluateRules,
+            // and both are engine errors — both must log engine_error and degrade
+            // to the normal gate, never escape to the outer fail-open catch.
+            let ruleVerdict = null;
+            try {
+                if (rulesDeps && rulesDeps.length > 0) {
+                    const cwd = ctx?.cwd ?? ".";
+                    ruleVerdict = evaluateRules(rulesDeps, {
+                        toolName: event.toolName,
+                        params: input,
+                        cwd,
+                        isProjectTrusted: (() => { try {
+                            return ctx?.isProjectTrusted() ?? true;
+                        }
+                        catch {
+                            return true;
+                        } })(),
+                        userStateHome: deps.rulesUserStateHome ?? cwd,
+                        projectRoot: deps.rulesProjectRoot ?? null,
+                        ...(deps.rulesHomeDir ? { homeDir: deps.rulesHomeDir } : {}),
+                    });
+                }
+            }
+            catch (err) {
+                // Fail-soft: a rule-engine error never blocks or allows — but it
+                // must not be SILENT: for a would-be deny this degrades to the
+                // normal gate (likely an allow), so the trail needs the failure.
+                // Error class only — never the thrown message (it can carry
+                // command content) or the user content.
+                logEvent({
+                    source: "permission-rules",
+                    level: "warn",
+                    event: "engine_error",
+                    fields: {
+                        tool: event.toolName,
+                        error: err instanceof Error ? err.constructor.name : typeof err,
+                    },
+                });
+            }
+            if (ruleVerdict) {
+                try {
+                    deps.onRuleVerdict?.({ ...ruleVerdict, toolName: event.toolName, cwd: ctx?.cwd ?? "." });
+                }
+                catch { /* logging must never affect the gate */ }
+                if (ruleVerdict.verdict === "deny") {
+                    const origin = ruleVerdict.rule.source === "user" ? "your user settings" : ruleVerdict.rule.source === "local" ? "the project's local settings" : "the project's settings";
+                    return {
+                        block: true,
+                        reason: `${event.toolName} was denied by a permission rule in ${origin} (${ruleVerdict.rule.raw}). Do not attempt the same outcome via a workaround or indirect execution — ask the user to change the rule if this action is genuinely needed.`,
+                    };
+                }
+                if (ruleVerdict.verdict === "ask") {
+                    // Ask is final: nothing below may auto-allow it. With a UI, the
+                    // user arbitrates; headless (incl. /go children) fails closed.
+                    if (!ctx?.hasUI) {
+                        return {
+                            block: true,
+                            reason: `${event.toolName} requires user approval (permission rule ${ruleVerdict.rule.raw}); no UI available — the call was held.`,
+                        };
+                    }
+                    if (ctx.signal?.aborted)
+                        return { block: true };
+                    // Session approval cache: an identical (tool, rule, input) "yes"
+                    // earlier this session covers this call — a retrying model must
+                    // not re-prompt the same question (dialog-storm guard).
+                    const askKey = ruleAskKey(event.toolName, ruleVerdict.rule.raw, input);
+                    if (ruleAskApprovals.has(askKey))
+                        return {};
+                    const origin = ruleVerdict.rule.source === "user" ? "your user settings" : ruleVerdict.rule.source === "local" ? "the project's local settings" : "the project's settings";
+                    const choice = await askUser(ctx, `Permission rule (ask) in ${origin}:\n${ruleVerdict.rule.raw}\nAllow ${event.toolName}?`, null, "rule", event.toolName);
+                    if (choice === "yes") {
+                        if (ruleAskApprovals.size > APPROVED_CACHE_MAX)
+                            ruleAskApprovals.clear();
+                        ruleAskApprovals.set(askKey, true);
+                        return {};
+                    }
+                    if (choice === "aborted")
+                        return { block: true };
+                    return {
+                        block: true,
+                        reason: `The user declined ${event.toolName} (permission rule ${ruleVerdict.rule.raw}). Ask what they would like to do differently, or take a different approach.`,
+                    };
+                }
+                // verdict === "allow": the floors decide whether the allow
+                // short-circuits. Linear by construction — allowRuleFloorVerdict
+                // owns the three invariants (plan-mode hold, forbidden band,
+                // alwaysConfirmTools confirm) and is unit-tested directly.
+                const floor = allowRuleFloorVerdict(event.toolName, input, modeAtEntry, effectivePolicy);
+                if (floor.kind === "block") {
+                    return { block: true, reason: floor.reason };
+                }
+                if (floor.kind === "confirm") {
+                    // Defer to the existing confirm flow via the ruleAskConfirm flag
+                    // (set below) — alwaysConfirmTools keeps its fresh-consent contract.
+                    ruleAskConfirm = true;
+                }
+                else if (floor.kind === "hold") {
+                    // Plan mode's no-mutation contract outranks the allow rule —
+                    // fall through to the normal plan-mode gate below.
+                }
+                else {
+                    return {};
+                }
+            }
             // YAG-506: PreToolUse hooks run BEFORE decideGate. They can short-circuit
             // (allow/deny/ask) or fall through to the normal gate logic. The result
             // is cached in preToolUseResult so the "ask" check below does NOT
@@ -439,6 +796,9 @@ export function registerPermissionGate(pi, deps = {}) {
                 try {
                     preToolUseResult = await hookRunner.preToolUse(event.toolName, input, cwd, ctx?.isProjectTrusted()) ?? undefined;
                     if (preToolUseResult) {
+                        if (preToolUseResult.decision === "allow" || preToolUseResult.decision === "deny") {
+                            slot.source = "hook";
+                        }
                         if (preToolUseResult.decision === "deny") {
                             return { block: true, reason: preToolUseResult.reason };
                         }
@@ -495,7 +855,7 @@ export function registerPermissionGate(pi, deps = {}) {
                 if (modeAtEntry === "auto" && command) {
                     const grant = matchesGrant(command, grants, resolveRepoKeyFor(cwd));
                     if (grant) {
-                        emitGateEvent({ ...eventBase, outcome: "prefix_allow", consulted: false });
+                        emitGateEvent(slot, { ...eventBase, outcome: "prefix_allow", consulted: false });
                         return {};
                     }
                 }
@@ -503,7 +863,20 @@ export function registerPermissionGate(pi, deps = {}) {
                 // Skipped in plan mode: a cached approval can cover a write command,
                 // and plan mode's contract is no mutations without Guardian review.
                 if (modeAtEntry !== "plan" && command && approvedCommands.has(cacheKey(cwd, command))) {
-                    emitGateEvent({ ...eventBase, outcome: "cached_allow", consulted: false });
+                    emitGateEvent(slot, { ...eventBase, outcome: "cached_allow", consulted: false });
+                    return {};
+                }
+                // 2b. Sandbox auto-allow (Claude's autoAllowBashIfSandboxed):
+                // the command will run inside the OS sandbox, so pre-approval is
+                // unnecessary. Positioned AFTER grants/cache (user intent outranks
+                // mechanism) and BEFORE the cap/breaker (a capped Guardian must not
+                // block a sandbox-safe command). Never active in plan mode — the
+                // session-side predicate is not consulted there at all, and even a
+                // true answer cannot widen plan's no-mutation contract.
+                if (modeAtEntry !== "plan" &&
+                    command &&
+                    deps.sandboxAutoAllow?.(event.toolName, input)) {
+                    emitGateEvent(slot, { ...eventBase, outcome: "sandbox_auto_allow", consulted: false });
                     return {};
                 }
                 const guardianAvailable = Boolean(guardianState && !guardianDisabled && guardianReview);
@@ -528,19 +901,19 @@ export function registerPermissionGate(pi, deps = {}) {
                         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);
+                            const resolution = await askUser(ctx, title, null, "breaker");
                             if (resolution === "yes") {
                                 guardianState.resetTurn();
                                 rememberApproved(cwd, command);
-                                emitGateEvent({ ...eventBase, outcome: "breaker_ask_approved", consulted: false });
+                                emitGateEvent(slot, { ...eventBase, outcome: "breaker_ask_approved", consulted: false });
                                 return {};
                             }
                             if (resolution === "aborted") {
-                                emitGateEvent({ ...eventBase, outcome: "aborted", consulted: false });
+                                emitGateEvent(slot, { ...eventBase, outcome: "aborted", consulted: false });
                                 return { block: true };
                             }
                         }
-                        emitGateEvent({ ...eventBase, outcome: "breaker_blocked", consulted: false });
+                        emitGateEvent(slot, { ...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 };
@@ -591,7 +964,7 @@ export function registerPermissionGate(pi, deps = {}) {
                         // telemetry can count salvage hits (the rawOutput is already
                         // scrubbed + capped at the source).
                         emitDiag("allow", verdict.rationale, reviewResult.repaired ? reviewResult.rawOutput : undefined);
-                        emitGateEvent({
+                        emitGateEvent(slot, {
                             ...eventBase,
                             outcome: "allow",
                             riskLevel: verdict.riskLevel,
@@ -605,7 +978,7 @@ export function registerPermissionGate(pi, deps = {}) {
                         guardianState.recordReview("deny");
                         const rationale = verdict.rationale;
                         emitDiag("deny", rationale, reviewResult.repaired ? reviewResult.rawOutput : undefined);
-                        emitGateEvent({
+                        emitGateEvent(slot, {
                             ...eventBase,
                             outcome: "deny",
                             riskLevel: verdict.riskLevel,
@@ -632,7 +1005,7 @@ export function registerPermissionGate(pi, deps = {}) {
                         emitDiag("ask", verdict.rationale, reviewResult.repaired ? reviewResult.rawOutput : undefined);
                         if (!ctx?.hasUI) {
                             // Headless (includes every /go child stage): fail closed.
-                            emitGateEvent({
+                            emitGateEvent(slot, {
                                 ...eventBase,
                                 outcome: "ask_headless_blocked",
                                 riskLevel: verdict.riskLevel,
@@ -653,7 +1026,7 @@ export function registerPermissionGate(pi, deps = {}) {
                                 if (hookResult) {
                                     if (hookResult.decision === "allow") {
                                         rememberApproved(cwd, command);
-                                        emitGateEvent({
+                                        emitGateEvent(slot, {
                                             ...eventBase,
                                             outcome: "ask_approved",
                                             riskLevel: verdict.riskLevel,
@@ -664,7 +1037,7 @@ export function registerPermissionGate(pi, deps = {}) {
                                         return {};
                                     }
                                     if (hookResult.decision === "deny") {
-                                        emitGateEvent({
+                                        emitGateEvent(slot, {
                                             ...eventBase,
                                             outcome: "ask_denied",
                                             riskLevel: verdict.riskLevel,
@@ -681,15 +1054,25 @@ export function registerPermissionGate(pi, deps = {}) {
                             }
                         }
                         // Offer "don't ask again" only when the grant would actually
-                        // cover this command (grant-time validation).
+                        // cover this command (grant-time validation). adds a
+                        // third option: persist a user-level permission rule (survives
+                        // across repos, unlike the repo-scoped grant) — offered only when
+                        // a grantCandidate also exists (the same prefix discipline; the
+                        // rule is the same pattern in settings form).
                         const grantCandidate = validateGrant(command, effectivePolicy.execPolicy ?? DEFAULT_EXEC_POLICY, resolveRepoKeyFor(cwd));
+                        const ruleCandidate = grantCandidate
+                            ? `Bash(${grantCandidate.pattern.join(" ")}:*)`
+                            : null;
                         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);
+                        const ruleLabel = grantCandidate && deps.persistUserRule
+                            ? `Yes, and always allow \`${grantCandidate.pattern.join(" ")}\` in this project's local settings`
+                            : null;
+                        const resolution = await askUserWithOptions(ctx, buildAskTitle(command, verdict.rationale, verdict.riskLevel), rememberLabel, ruleLabel, "guardian_verdict", "bash");
                         if (resolution === "yes") {
                             rememberApproved(cwd, command);
-                            emitGateEvent({
+                            emitGateEvent(slot, {
                                 ...eventBase,
                                 outcome: "ask_approved",
                                 riskLevel: verdict.riskLevel,
@@ -699,6 +1082,50 @@ export function registerPermissionGate(pi, deps = {}) {
                             });
                             return {};
                         }
+                        if (resolution === "rule" && ruleCandidate && deps.persistUserRule) {
+                            let persisted = false;
+                            try {
+                                deps.persistUserRule(ruleCandidate, cwd);
+                                persisted = true;
+                                // Also covers this session like a grant would:
+                                rememberApproved(cwd, command);
+                            }
+                            catch (err) {
+                                // Fail-soft: the in-memory approval covers ONLY this call —
+                                // rememberApproved sits after the throwing call, so a failed
+                                // persist does NOT remember the command for the session (a
+                                // narrower fallback than a grant, deliberately: the user's
+                                // durable choice did not land). But the user just made an
+                                // explicit durable choice in the dialog — a silent failure
+                                // would leave them believing a rule exists that will not
+                                // survive restart. Log the failure (rule string + the thrown
+                                // message — it is mutateConfigJson's own path/reason text,
+                                // never the raw parse error or file content) and tell the
+                                // user.
+                                logEvent({
+                                    source: "permission-rules",
+                                    level: "warn",
+                                    event: "rule_save_failed",
+                                    fields: {
+                                        rule: ruleCandidate,
+                                        destination: "local",
+                                        error: err instanceof Error ? err.message : String(err),
+                                    },
+                                });
+                                if (ctx?.hasUI) {
+                                    ctx.ui.notify(`Could not save the permission rule to your settings — it did not persist; you'll be asked again on the next identical command.`, "warning");
+                                }
+                            }
+                            emitGateEvent(slot, {
+                                ...eventBase,
+                                outcome: persisted ? "ask_approved_remembered" : "ask_approved",
+                                riskLevel: verdict.riskLevel,
+                                rationale: verdict.rationale,
+                                durationMs,
+                                consulted: true,
+                            });
+                            return {};
+                        }
                         if (resolution === "remember" && grantCandidate) {
                             const grantRecord = {
                                 ...grantCandidate,
@@ -712,7 +1139,7 @@ export function registerPermissionGate(pi, deps = {}) {
                             catch {
                                 // Fail-soft: the in-memory grant still applies this session.
                             }
-                            emitGateEvent({
+                            emitGateEvent(slot, {
                                 ...eventBase,
                                 outcome: "ask_approved_remembered",
                                 riskLevel: verdict.riskLevel,
@@ -725,10 +1152,10 @@ export function registerPermissionGate(pi, deps = {}) {
                         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 });
+                            emitGateEvent(slot, { ...eventBase, outcome: "aborted", durationMs, consulted: true });
                             return { block: true };
                         }
-                        emitGateEvent({
+                        emitGateEvent(slot, {
                             ...eventBase,
                             outcome: "ask_denied",
                             riskLevel: verdict.riskLevel,
@@ -742,7 +1169,10 @@ export function registerPermissionGate(pi, deps = {}) {
                                 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.
+                        // dismissed or UI-layer error — neutral reason, no "denied"
+                        // spin. (No timeout can land here anymore: the dialog waits
+                        // indefinitely, so this is only a real ESC/dismiss — or the
+                        // select itself failed, which fails closed the same way.)
                         return {
                             block: true,
                             reason: "The permission dialog was dismissed; the command was not run. Ask the user how to proceed.",
@@ -757,7 +1187,7 @@ export function registerPermissionGate(pi, deps = {}) {
                         // 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 });
+                        emitGateEvent(slot, { ...eventBase, outcome: "aborted", durationMs, consulted: false });
                         return { block: true };
                     }
                     if (modeAtEntry === "review" && decision.confirm) {
@@ -770,17 +1200,17 @@ export function registerPermissionGate(pi, deps = {}) {
                         // 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);
+                        const resolution = await askUser(ctx, `Guardian unavailable (${errorMsg}).\nRun this command anyway?\n$ ${boundedCommand(command)}`, null, "error_fallback");
                         if (resolution === "yes") {
                             rememberApproved(cwd, command);
-                            emitGateEvent({ ...eventBase, outcome: "ask_approved", guardianError: error, durationMs, consulted: false });
+                            emitGateEvent(slot, { ...eventBase, outcome: "ask_approved", guardianError: error, durationMs, consulted: false });
                             return {};
                         }
                         if (resolution === "aborted") {
-                            emitGateEvent({ ...eventBase, outcome: "aborted", durationMs, consulted: false });
+                            emitGateEvent(slot, { ...eventBase, outcome: "aborted", durationMs, consulted: false });
                             return { block: true };
                         }
-                        emitGateEvent({ ...eventBase, outcome: "ask_denied", guardianError: error, durationMs, consulted: false });
+                        emitGateEvent(slot, { ...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,
@@ -789,7 +1219,7 @@ export function registerPermissionGate(pi, deps = {}) {
                     }
                     else {
                         const errorMsg = guardianErrorMessage(error);
-                        emitGateEvent({ ...eventBase, outcome: error, durationMs, consulted: false });
+                        emitGateEvent(slot, { ...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." : "";
@@ -813,7 +1243,7 @@ export function registerPermissionGate(pi, deps = {}) {
                     // the Guardian to verify the command is non-mutating, the plan-mode
                     // contract (no changes) cannot be upheld. The user can switch to
                     // /mode auto or /mode review to proceed.
-                    emitGateEvent({ ...eventBase, outcome: "breaker_blocked", consulted: false });
+                    emitGateEvent(slot, { ...eventBase, outcome: "breaker_blocked", consulted: false });
                     return { block: true, reason: "Guardian unavailable in plan mode. Switch to /mode auto to run commands, or /mode review to approve manually." };
                 }
                 // review mode with Guardian disabled/capped: fall through to confirm.
@@ -823,6 +1253,11 @@ export function registerPermissionGate(pi, deps = {}) {
             if (preToolUseResult?.decision === "ask") {
                 decision = { block: false, confirm: true };
             }
+            // an allow-rule verdict on an alwaysConfirmTools tool forced
+            // the confirm flow (Floor 2 above) — same treatment as a hook "ask".
+            if (ruleAskConfirm) {
+                decision = { block: false, confirm: true };
+            }
             if (decision.confirm) {
                 // YAG-506: PermissionRequest hooks run before the confirm dialog.
                 if (hookRunner) {
@@ -830,6 +1265,8 @@ export function registerPermissionGate(pi, deps = {}) {
                         const cwd = ctx?.cwd ?? ".";
                         const hookResult = await hookRunner.permissionRequest(event.toolName, input, cwd, ctx?.isProjectTrusted());
                         if (hookResult) {
+                            if (hookResult.decision === "allow" || hookResult.decision === "deny")
+                                slot.source = "hook";
                             if (hookResult.decision === "allow")
                                 return {};
                             if (hookResult.decision === "deny") {
@@ -864,9 +1301,12 @@ export function registerPermissionGate(pi, deps = {}) {
                 const choice = await ctx.ui.select(effectivePolicy.alwaysConfirmTools?.includes(event.toolName)
                     ? externalTrackerPrompt(event.toolName, input)
                     : "YAGNI Code review mode", options);
-                if (choice === yes)
+                if (choice === yes) {
+                    slot.source = "user_temporary";
                     return {};
+                }
                 if (blessable && choice === remember) {
+                    slot.source = "user_permanent";
                     // Session-scoped bless, then a fire-and-forget decision capture so the
                     // approved tool call is never delayed by the capture prompt.
                     blessStore.add(event.toolName, input);
@@ -876,6 +1316,7 @@ export function registerPermissionGate(pi, deps = {}) {
                     return {};
                 }
                 // "No" or a dismissed dialog (undefined) → held.
+                slot.source = choice === undefined ? "user_abort" : "user_reject";
                 return { block: true, reason: `declined ${event.toolName} in review mode` };
             }
             return {};
@@ -889,7 +1330,8 @@ export function registerPermissionGate(pi, deps = {}) {
             }
             return {};
         }
-    });
+    };
+    wireToolCallGate(pi, gateToolCall, deps.onToolDecision);
     // 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
@@ -937,6 +1379,7 @@ export function registerPermissionGate(pi, deps = {}) {
                 // 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();
+                ruleAskApprovals.clear();
             }
             mode = arg;
             paintMode(ctx);