@yagni-app/code 1.0.5 → 1.0.7

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
@@ -92,7 +140,7 @@ export function decideGate(toolName, params, mode, policy) {
             }
             return { block: false };
         }
-        if (policy.planBlockTools.includes(toolName)) {
+        if (policy.planBlockTools.includes(toolName) || policy.isMutating?.(toolName)) {
             return {
                 block: true,
                 reason: `plan mode: ${toolName} is a write or exec action and is held. Switch to /mode auto to apply changes.`,
@@ -142,7 +190,7 @@ export function decideGate(toolName, params, mode, policy) {
     if (mode === "auto")
         return { block: false };
     // review
-    if (policy.reviewConfirmTools.includes(toolName)) {
+    if (policy.reviewConfirmTools.includes(toolName) || policy.isMutating?.(toolName)) {
         if (policy.isBlessed?.(toolName, params))
             return { block: false };
         return { block: false, confirm: true };
@@ -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
@@ -314,6 +414,8 @@ export function registerPermissionGate(pi, deps = {}) {
         // and dropping it here silently reverts every custom policy to the
         // default (round-2 review blocker).
         execPolicy: basePolicy.execPolicy,
+        // Same carry-through for the mutating-tool predicate (dynamic mcp__* tools).
+        isMutating: basePolicy.isMutating,
         isBlessed: basePolicy.isBlessed ?? ((tool, params) => blessStore?.isBlessed(tool, params) ?? false),
     };
     const sideEffects = sideEffectTools(effectivePolicy);
@@ -347,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);
@@ -370,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 {
@@ -417,16 +545,162 @@ export function registerPermissionGate(pi, deps = {}) {
             return "no";
         return ctx.signal?.aborted ? "aborted" : "dismissed";
     };
+    /**
+     * variant: the Guardian ask dialog with an optional third option
+     * (persist a user-level permission rule). Same semantics as askUser.
+     */
+    const askUserWithOptions = async (ctx, title, rememberLabel, ruleLabel) => {
+        if (ctx.signal?.aborted)
+            return "aborted";
+        const options = [
+            ASK_YES,
+            ...(rememberLabel ? [rememberLabel] : []),
+            ...(ruleLabel ? [ruleLabel] : []),
+            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 (ruleLabel !== null && choice === ruleLabel)
+            return "rule";
+        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) => {
+    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 === "project" ? "the project's settings" : "your user 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 === "project" ? "the project's settings" : "your user settings";
+                    const choice = await askUser(ctx, `Permission rule (ask) in ${origin}:\n${ruleVerdict.rule.raw}\nAllow ${event.toolName}?`, null);
+                    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
@@ -437,6 +711,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 };
                         }
@@ -493,7 +770,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 {};
                     }
                 }
@@ -501,7 +778,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);
@@ -530,15 +820,15 @@ export function registerPermissionGate(pi, deps = {}) {
                             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 };
@@ -575,6 +865,7 @@ export function registerPermissionGate(pi, deps = {}) {
                         void Promise.resolve(deps.onGuardianReview(buildDiagnosticEvent(outcome, {
                             durationMs,
                             tier: guardianTier,
+                            ...(reviewResult.repaired ? { repaired: true } : {}),
                             ...(rationale ? { rationale } : {}),
                             ...(rawOutput ? { rawOutput } : {}),
                             debug: isDebug(),
@@ -583,8 +874,12 @@ export function registerPermissionGate(pi, deps = {}) {
                     const verdict = reviewResult.verdict;
                     if (verdict?.outcome === "allow") {
                         guardianState.recordReview("allow");
-                        emitDiag("allow", verdict.rationale);
-                        emitGateEvent({
+                        // A repaired verdict is a REAL allow: it flows through the normal
+                        // path; the diag event carries `repaired` + the pre-repair shape so
+                        // telemetry can count salvage hits (the rawOutput is already
+                        // scrubbed + capped at the source).
+                        emitDiag("allow", verdict.rationale, reviewResult.repaired ? reviewResult.rawOutput : undefined);
+                        emitGateEvent(slot, {
                             ...eventBase,
                             outcome: "allow",
                             riskLevel: verdict.riskLevel,
@@ -597,8 +892,8 @@ export function registerPermissionGate(pi, deps = {}) {
                     if (verdict?.outcome === "deny") {
                         guardianState.recordReview("deny");
                         const rationale = verdict.rationale;
-                        emitDiag("deny", rationale);
-                        emitGateEvent({
+                        emitDiag("deny", rationale, reviewResult.repaired ? reviewResult.rawOutput : undefined);
+                        emitGateEvent(slot, {
                             ...eventBase,
                             outcome: "deny",
                             riskLevel: verdict.riskLevel,
@@ -622,10 +917,10 @@ export function registerPermissionGate(pi, deps = {}) {
                     }
                     if (verdict?.outcome === "ask") {
                         guardianState.recordReview("ask");
-                        emitDiag("ask", verdict.rationale);
+                        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,
@@ -646,7 +941,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,
@@ -657,7 +952,7 @@ export function registerPermissionGate(pi, deps = {}) {
                                         return {};
                                     }
                                     if (hookResult.decision === "deny") {
-                                        emitGateEvent({
+                                        emitGateEvent(slot, {
                                             ...eventBase,
                                             outcome: "ask_denied",
                                             riskLevel: verdict.riskLevel,
@@ -674,15 +969,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 my user settings`
+                            : null;
+                        const resolution = await askUserWithOptions(ctx, buildAskTitle(command, verdict.rationale, verdict.riskLevel), rememberLabel, ruleLabel);
                         if (resolution === "yes") {
                             rememberApproved(cwd, command);
-                            emitGateEvent({
+                            emitGateEvent(slot, {
                                 ...eventBase,
                                 outcome: "ask_approved",
                                 riskLevel: verdict.riskLevel,
@@ -692,6 +997,44 @@ export function registerPermissionGate(pi, deps = {}) {
                             });
                             return {};
                         }
+                        if (resolution === "rule" && ruleCandidate && deps.persistUserRule) {
+                            let persisted = false;
+                            try {
+                                deps.persistUserRule(ruleCandidate);
+                                persisted = true;
+                                // Also covers this session like a grant would:
+                                rememberApproved(cwd, command);
+                            }
+                            catch (err) {
+                                // Fail-soft: the in-memory approval still applies THIS
+                                // session. 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 only, it is user-configured text, plus
+                                // error class — never the thrown message) and tell the user.
+                                logEvent({
+                                    source: "permission-rules",
+                                    level: "warn",
+                                    event: "user_rule_save_failed",
+                                    fields: {
+                                        rule: ruleCandidate,
+                                        error: err instanceof Error ? err.constructor.name : typeof err,
+                                    },
+                                });
+                                if (ctx?.hasUI) {
+                                    ctx.ui.notify(`Could not save the permission rule to your settings — it applies to this session only.`, "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,
@@ -705,7 +1048,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,
@@ -718,10 +1061,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,
@@ -750,7 +1093,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) {
@@ -766,14 +1109,14 @@ export function registerPermissionGate(pi, deps = {}) {
                         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 });
+                            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,
@@ -782,7 +1125,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." : "";
@@ -806,7 +1149,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.
@@ -816,6 +1159,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) {
@@ -823,6 +1171,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") {
@@ -857,9 +1207,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);
@@ -869,6 +1222,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 {};
@@ -882,7 +1236,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
@@ -930,6 +1285,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);