@yagni-app/code 0.2.1 → 0.3.0

package/dist/extension/index.js

@@ -1,34 +1,40 @@
+import { createHash } from "node:crypto";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { Text } from "@earendil-works/pi-tui";
 import { DEFAULT_ADVISOR_LIMITS, formatAdvisorSubtotal, makeAdvisorState } from "./advisor.js";
+import { appendGrant, loadGrants, resolveRepoKey, storagePrefix } from "./approvedPrefixes.js";
+import { redactCommand } from "./redact.js";
+import { formatGuardianSubtotal, GUARDIAN_MODEL_TIER, makeGuardianState, resolveGuardianLimits, reviewCommand } from "./guardian.js";
 import { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
-import { registerBoostCommand } from "./boostCommand.js";
 import { makeAskYagniTool } from "./askYagniTool.js";
+import { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js";
 import { makeReviewBusinessMatchTool } from "./reviewTool.js";
+import { registerCmuxBridge } from "./cmux/index.js";
 import { makeRecordEngineeringContextTool } from "./recordContextTool.js";
 import { makeRecordDecisionTool } from "./recordDecisionTool.js";
 import { makeSuggestNextWorkTool } from "./nextWorkTool.js";
 import { BRAND_NAME, brandSystemPrompt, brandingDisabled, buildMastheadString, YAGNI_IDENTITY_DRIVER } from "./branding.js";
-import { appendClaudeRules, claudeRulesSection } from "./claudeRules.js";
+import { claudeRulesSection } from "./claudeRules.js";
 import { registerCostCommand } from "./costHud.js";
 import { isDebug } from "./diagnostics.js";
 import { droppedSessionRuns, sessionRunIds } from "./sessionRuns.js";
 import { codeStateHome } from "./stateHome.js";
+import { createYagniFooterFactory, formatCwd } from "./footer.js";
 import { RerouteNotifier } from "./rerouteNotice.js";
 import { isFreshWorkspace, registerTeamSetupCommand, runInitPass as defaultRunInitPass } from "./initPass.js";
 import { isInitDone as defaultIsInitDone, markInitDone as defaultMarkInitDone } from "./initDone.js";
 import { fetchMcpServers as defaultFetchMcpServers, registerMcpCommand, registerMcpTools, } from "./mcpTools.js";
 import { registerGoCommand } from "./pipeline/goCommand.js";
 import { registerGoCompareCommand } from "./pipeline/goCompareCommand.js";
-import { DEFAULT_PERMISSION_POLICY, registerPermissionGate } from "./permission.js";
+import { DEFAULT_PERMISSION_POLICY, createModeHolder, registerPermissionGate } from "./permission.js";
 import { registerSubagents } from "./subagents.js";
 import { registerTodos } from "./todos.js";
 import { registerDecisionCommands } from "./decisions.js";
 import { makeDecisionCapture } from "./decisionCapture.js";
 import { registerAmbientRecall } from "./recall.js";
 import { resilientFetch } from "./resilientFetch.js";
-import { installUncaughtExceptionMonitor } from "./crashReport.js";
+import { installUncaughtExceptionMonitor, makeCrashReporter } from "./crashReport.js";
 import { flushSpool as defaultFlushSpool } from "./spool.js";
 import { makeAuthedFetch, makeTokenProvider } from "./tokenProvider.js";
 import { attributionHeaders, fetchCatalog as defaultFetchCatalog, fetchContextBrief as defaultFetchContextBrief, getToken, getTokenExpiresAt as defaultGetTokenExpiresAt, getWorkspaceId as defaultGetWorkspaceId, isDriverCaller, resolveBaseUrl, tokenExpiryNotice, } from "./config.js";
@@ -111,7 +117,26 @@ export async function registerYagni(pi, deps = {}) {
     if (!evalMode) {
         installUncaughtExceptionMonitor({ baseUrl, getToken: getTokenFn, env: deps.env });
     }
-    const catalog = await fetchCatalog({ baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+    // YAG-500 Fix E: non-fatal auth-event reporter for 401s on the model path.
+    // Reuses the crash endpoint (/api/yagni-code/crash) with a distinct context
+    // so auth failures are visible in Sentry/backend logs. Gated on !evalMode
+    // like every other external side effect; injectable for tests.
+    const authReporter = deps.authReporter ??
+        (!evalMode
+            ? makeCrashReporter({ baseUrl, getToken: getTokenFn, fetchImpl: deps.fetchImpl, env: deps.env })
+            : async () => { });
+    // YAG-500 Fix A+C: the model-path 401 recovery outcome, set by the
+    // message_end handler so it can produce the right user-facing message. The
+    // after_provider_response event does NOT fire on a 401 (the OpenAI SDK throws
+    // before onResponse is reached), so message_end is the only seam.
+    let lastAuthRecovery = null;
+    const { models: fullCatalog, guardianEnabled: workspaceGuardianEnabled, guardianStorage: guardianStorageTier, } = await fetchCatalog({ baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+    // Lock the interactive session to the `advanced` tier only. The backend
+    // catalog returns all tiers, but only `advanced` is registered with the
+    // `yagni` provider, so /model and Ctrl+P show a single entry. Child
+    // processes (/go, subagents, advisor) fetch their own catalog and register
+    // their own provider, so they are unaffected by this filter.
+    const catalog = fullCatalog.filter((m) => m.id === "advanced");
     // YAG-471: the driver's own completions carry attribution headers read from
     // this process's env (YAGNI_SESSION_ID minted by the launcher; YAGNI_CALLER
     // defaults to "driver" when unset, i.e. every session that is not a /go
@@ -119,11 +144,17 @@ export async function registerYagni(pi, deps = {}) {
     pi.registerProvider("yagni", buildYagniProvider(catalog, baseUrl, attributionHeaders(deps.env)));
     const toolOpts = { baseUrl, getToken: getTokenFn, fetchImpl: authedFetch };
     pi.registerTool(makeAskYagniTool(toolOpts));
-    // The peak-tier escalation for Balanced sessions (YAG-380). Registered
+    // Ticket write-back (spec 2026-08-09): explicit user-intent writes to the
+    // workspace tracker, attributed to the developer via per-user credentials.
+    if (!evalMode) {
+        pi.registerTool(makeFileTicketTool(toolOpts));
+        pi.registerTool(makeUpdateTicketStatusTool(toolOpts));
+    }
+    // The peak-tier escalation for Advanced sessions (YAG-380). Registered
     // UNCONDITIONALLY and gated at execute time on the live session model: pi's
     // picker can switch the model after activation, so a registration-time tier
-    // check would both leave the tool live after switching away from Balanced and
-    // hide it forever from a session that switched TO Balanced. One state handle
+    // check would both leave the tool live after switching away from Advanced and
+    // hide it forever from a session that switched TO Advanced. One state handle
     // per session, shared with /advise so they draw on the same cap.
     const advisorState = makeAdvisorState();
     const askAdvisorTool = makeAskAdvisorTool({ state: advisorState });
@@ -131,12 +162,6 @@ export async function registerYagni(pi, deps = {}) {
     // /advise runs the SAME tool, sharing the state handle, so a manual consult
     // draws on the same cap rather than opening a side channel around it.
     registerAdviseCommand(pi, askAdvisorTool);
-    // /boost — the sanctioned session-scoped escalation to Peak (spec §7,
-    // YAG-380 follow-on). Unlike /advise's per-call consult, this flips the
-    // DRIVER's own live model to peak until /boost off or the session ends.
-    // The returned handle threads isBoosted() into /cost below, the same way
-    // advisorState threads into advisorSubtotal.
-    const boostCommand = registerBoostCommand(pi, { env });
     // The differentiated business-grounded tools (loop bricks): review a change
     // for business fit, rank the next work by business priority, and record the
     // engineering rationale back onto the work-item.
@@ -212,7 +237,98 @@ export async function registerYagni(pi, deps = {}) {
     // drafts a decision on "don't ask again". Default auto, so still additive.
     // Mutating MCP tools join write/edit/bash in the gate policy: plan mode
     // holds them, review mode confirms them.
+    const modeHolder = createModeHolder();
+    const guardianState = makeGuardianState();
+    // Disabled by the local env override OR the workspace kill switch
+    // (yagni_code.guardian, read from the catalog response at launch). The env
+    // var wins for a single developer's debugging; the flag turns it off for
+    // every session in the workspace.
+    const guardianDisabled = env.YAGNI_DISABLE_GUARDIAN === "1" ||
+        env.YAGNI_DISABLE_GUARDIAN === "true" ||
+        !workspaceGuardianEnabled;
+    const guardianTier = env.YAGNI_GUARDIAN_TIER ?? GUARDIAN_MODEL_TIER;
+    const guardianLimits = resolveGuardianLimits(env);
+    // YAG-510: guardian.log stays the sanitized local debug sink (hash-only,
+    // never the command). The remote guardian-events stream below is the
+    // separate, opt-in, per-workspace analytics sink; the two are independent.
+    const guardianLogSink = (payload) => {
+        try {
+            if (process.env.NODE_TEST_CONTEXT)
+                return;
+            const logPath = join(codeStateHome(null), "logs", "guardian.log");
+            mkdirSync(dirname(logPath), { recursive: true });
+            appendFileSync(logPath, JSON.stringify({ ts: new Date().toISOString(), ...payload }) + "\n", "utf8");
+        }
+        catch { /* logging must never break the session */ }
+    };
+    // YAG-510: persisted "don't ask again" grants, per-repo keyed. Loaded once
+    // at startup (grants added by other concurrent sessions appear next launch).
+    const sessionGrants = evalMode ? [] : loadGrants();
+    const GUARDIAN_EVENT_TIMEOUT_MS = 5_000;
     registerPermissionGate(pi, {
+        modeHolder,
+        guardianState,
+        guardianLimits,
+        guardianTier,
+        guardianDisabled,
+        guardianReview: (command, deps) => reviewCommand(command, { ...deps, modelTier: guardianTier }),
+        onGuardianReview: (ev) => guardianLogSink(ev),
+        grants: sessionGrants,
+        resolveRepoKey,
+        persistGrant: (grant) => {
+            if (!evalMode)
+                appendGrant(grant);
+        },
+        // Opt-in storage stream (YAG-510). Tier decides what leaves the machine:
+        // "off" → nothing (not even sent); "hash" → sha256 + family prefix +
+        // metadata, no command content; "raw" → adds client-REDACTED command and
+        // rationale. Fire-and-forget: one attempt, short timeout, failures logged
+        // fail-soft to guardian.log — a storage outage never touches the session.
+        onGuardianEvent: guardianStorageTier === "off" || evalMode
+            ? undefined
+            : (ev) => {
+                void (async () => {
+                    try {
+                        const body = {
+                            sessionId: env.YAGNI_SESSION_ID ?? null,
+                            commandHash: createHash("sha256").update(ev.command).digest("hex"),
+                            commandPrefix: storagePrefix(ev.command),
+                            outcome: ev.outcome,
+                            mode: ev.mode,
+                            ...(ev.execJustification ? { execJustification: ev.execJustification } : {}),
+                            ...(ev.riskLevel ? { riskLevel: ev.riskLevel } : {}),
+                            ...(ev.tier ? { tier: ev.tier } : {}),
+                            ...(ev.durationMs !== undefined ? { durationMs: ev.durationMs } : {}),
+                        };
+                        if (guardianStorageTier === "raw") {
+                            body.command = redactCommand(ev.command);
+                            if (ev.rationale)
+                                body.rationale = redactCommand(ev.rationale);
+                        }
+                        const res = await resilientFetch(`${baseUrl}/api/yagni-code/guardian-events`, {
+                            method: "POST",
+                            headers: {
+                                "content-type": "application/json",
+                                authorization: `Bearer ${getTokenFn() ?? ""}`,
+                                ...attributionHeaders(deps.env),
+                            },
+                            body: JSON.stringify(body),
+                        }, {
+                            fetchImpl: authedFetch,
+                            policy: { maxAttempts: 1, backoffBaseMs: 0, backoffMaxMs: 0, timeoutMs: GUARDIAN_EVENT_TIMEOUT_MS, jitterRatio: 0 },
+                        });
+                        if (!res.ok) {
+                            guardianLogSink({ event: "guardian_event_post_failed", status: res.status });
+                        }
+                    }
+                    catch (err) {
+                        guardianLogSink({
+                            event: "guardian_event_post_failed",
+                            error: err instanceof Error ? err.message : "unknown",
+                        });
+                    }
+                })();
+            },
         ...(mcpMutatingTools.length > 0
             ? {
                 policy: {
@@ -224,6 +340,7 @@ export async function registerYagni(pi, deps = {}) {
                         ...DEFAULT_PERMISSION_POLICY.reviewConfirmTools,
                         ...mcpMutatingTools,
                     ],
+                    alwaysConfirmTools: DEFAULT_PERMISSION_POLICY.alwaysConfirmTools,
                 },
             }
             : {}),
@@ -247,12 +364,11 @@ export async function registerYagni(pi, deps = {}) {
         // turn_end accumulator. Thread the subtotal in explicitly for the local
         // fallback line; the server-authoritative line already counts advisor
         // spend as an ordinary caller row.
-        advisorSubtotal: () => formatAdvisorSubtotal(advisorState.read(), DEFAULT_ADVISOR_LIMITS),
-        // YAG-380 follow-on: a boosted session that only chats never produces a
-        // server-side boosted row (see boostCommand.ts's KNOWN-asymmetry
-        // docblock), so /cost needs the live client-side toggle on top of
-        // whatever the server rows show.
-        isBoosted: () => boostCommand.isBoosted(),
+        advisorSubtotal: () => {
+            const advisor = formatAdvisorSubtotal(advisorState.read(), DEFAULT_ADVISOR_LIMITS);
+            const guardian = formatGuardianSubtotal(guardianState.read(), guardianLimits);
+            return [advisor, guardian].filter(Boolean).join(" ");
+        },
         fetchHeadroom: async (signal) => {
             try {
                 const res = await resilientFetch(`${baseUrl}/api/yagni-code/credits`, { method: "GET", headers: { authorization: `Bearer ${getTokenFn() ?? ""}` } }, { fetchImpl: authedFetch, signal, policy: { maxAttempts: 1, backoffBaseMs: 0, backoffMaxMs: 0, timeoutMs: COST_FETCH_TIMEOUT_MS, jitterRatio: 0 } });
@@ -405,7 +521,11 @@ export async function registerYagni(pi, deps = {}) {
     pi.on("before_agent_start", (event) => noBranding
         ? undefined
         : {
-            systemPrompt: appendClaudeRules(brandSystemPrompt(event.systemPrompt, { contextBrief, identity }), rulesSection),
+            systemPrompt: brandSystemPrompt(event.systemPrompt, {
+                contextBrief,
+                identity,
+                rulesSection,
+            }),
         });
     // Two finalized-message guards share this handler (their conditions are
     // mutually exclusive: YAG-460 takes error-stopped messages, YAG-466 takes
@@ -425,7 +545,7 @@ export async function registerYagni(pi, deps = {}) {
     // renders. The message text deliberately matches neither pi's overflow nor
     // retryable-error patterns: a deterministic empty response should not burn
     // auto-retries or trigger compaction — the user decides what to do next.
-    pi.on("message_end", (event, ctx) => {
+    pi.on("message_end", async (event, ctx) => {
         const msg = event.message;
         if (msg.role !== "assistant")
             return;
@@ -440,6 +560,71 @@ export async function registerYagni(pi, deps = {}) {
         // post-replacement message, and dropping the marker would defeat the very
         // recovery this error exists to trigger.
         if (msg.stopReason === "error" && msg.errorMessage) {
+            // YAG-500: a 401 from the model proxy means the session token expired
+            // (or was revoked). Unlike tool 401s (handled by makeAuthedFetch), the
+            // model completion path has no 401-retry seam — pi's retryProviderRequest
+            // treats 401 as non-retryable, and after_provider_response never fires
+            // (the SDK throws before onResponse is reached). So message_end is the
+            // only place to detect it and trigger recovery. The regex matches
+            // "yagni login" (the backend's auth-error message) but NOT
+            // "request_too_large" (YAG-460's overflow marker).
+            const isAuthError = /yagni login/i.test(msg.errorMessage)
+                && !/request_too_large|context_too_large/i.test(msg.errorMessage);
+            if (isAuthError) {
+                lastAuthRecovery = null;
+                let rotated = false;
+                try {
+                    rotated = await tokenProvider.refresh();
+                }
+                catch {
+                    rotated = false;
+                }
+                lastAuthRecovery = rotated ? "refreshed" : "failed";
+                const explanation = rotated
+                    ? "Your session token expired but was refreshed automatically. Re-send your prompt to continue."
+                    : "Your session token expired and could not be refreshed. Run `yagni login`, then re-send your prompt. If the issue persists, restart YAGNI Code.";
+                if (ctx.hasUI) {
+                    try {
+                        ctx.ui.notify(explanation, rotated ? "info" : "error");
+                    }
+                    catch {
+                        // Surfacing the problem must never break the session itself.
+                    }
+                }
+                // YAG-500 Fix E: fire a non-fatal crash report so auth failures are
+                // visible in Sentry/backend logs. Reuses the crash endpoint with a
+                // distinct context. Fire-and-forget, fail-soft. The crash endpoint is
+                // now public (no token required), so the report lands even when the
+                // session token is expired and refresh failed — the most critical
+                // failure signal is no longer silently dropped.
+                void authReporter(new Error(`auth_401 on model path; refresh=${rotated ? "succeeded" : "failed"}`), "auth-failure").catch(() => { });
+                // YAG-500 Fix F: local diagnostics log under YAGNI_DEBUG.
+                if (isDebug(env)) {
+                    try {
+                        const logPath = join(codeStateHome(null, env), "logs", "auth-events.log");
+                        mkdirSync(dirname(logPath), { recursive: true });
+                        appendFileSync(logPath, JSON.stringify({
+                            ts: new Date().toISOString(),
+                            status: 401,
+                            refresh: rotated ? "succeeded" : "failed",
+                        }) + "\n", "utf8");
+                    }
+                    catch {
+                        // A diagnostic must never break the session.
+                    }
+                }
+                return { message: { ...msg, errorMessage: explanation } };
+            }
+            // YAG-460: the backend proxy answers an oversized conversation with an
+            // OpenAI-format 413 whose type is `request_too_large`. pi's own overflow
+            // detection matches that marker and runs full recovery — compact, then
+            // auto-retry the failed turn — so this branch must NOT call ctx.compact()
+            // (it would race the built-in recovery and lose the retry). Its only job
+            // is UX: replace the raw `413: {"error":{...}}` JSON with a readable
+            // message and tell the user what is happening. The rewritten text KEEPS
+            // the `request_too_large` marker verbatim: pi's _checkCompaction reads the
+            // post-replacement message, and dropping the marker would defeat the very
+            // recovery this error exists to trigger.
             const isContextTooLarge = /request_too_large|context_too_large/i.test(msg.errorMessage);
             if (!isContextTooLarge)
                 return;
@@ -486,7 +671,39 @@ export async function registerYagni(pi, deps = {}) {
             ctx.ui?.setStatus?.("brand", BRAND_NAME);
             // setHeader replaces the built-in header in place (verified against pi
             // 0.80.2 setExtensionHeader); the factory returns a simple Text component.
-            ctx.ui?.setHeader?.((_tui, theme) => new Text(buildMastheadString(theme)));
+            // Pass the launcher-forwarded CLI version (YAGNI_CODE_VERSION) and the
+            // home-collapsed cwd so the masthead shows them like the reference.
+            const mastheadVersion = process.env.YAGNI_CODE_VERSION?.trim() || undefined;
+            const mastheadCwd = formatCwd(process.cwd(), process.env.HOME);
+            ctx.ui?.setHeader?.((_tui, theme) => new Text(buildMastheadString(theme, { version: mastheadVersion, cwd: mastheadCwd })));
+            // Replace the built-in footer with the YAGNI status bar: folder +
+            // [worktree] + branch on line 1, model + token/cost stats + integer
+            // context % on line 2, and extension statuses (brand, todos, mode) on
+            // line 3. The factory captures ctx so the footer can read session data
+            // (token stats, context usage) that isn't on the footerData provider.
+            ctx.ui?.setFooter?.((tui, theme, footerData) => createYagniFooterFactory(ctx, modeHolder)(tui, theme, footerData));
+            // Label the collapsed chain-of-thought line so users know it is reasoning
+            // and how to reveal the full trace. Harmless when reasoning is expanded
+            // (the label only shows on hidden thinking blocks). Fails closed to pi's
+            // default "Thinking..." label.
+            try {
+                ctx.ui?.setHiddenThinkingLabel?.("Reasoning — Ctrl+T to expand");
+            }
+            catch {
+                // A label must never disrupt session start.
+            }
+            // One-time hint naming what changed now that reasoning is collapsed by
+            // default (option 2). Gated on the launcher's YAGNI_HIDE_THINKING_SEEDED
+            // marker so it fires only on the launch that actually seeded the key — it
+            // never re-nags on subsequent runs, even though the label above persists.
+            if (env.YAGNI_HIDE_THINKING_SEEDED === "1") {
+                try {
+                    ctx.ui?.notify("Reasoning is collapsed by default — Ctrl+T shows the full trace at any time.", "info");
+                }
+                catch {
+                    // A hint must never disrupt session start.
+                }
+            }
         }
         // Best-effort, once at session start: if the token is at or near expiry, say
         // so via a single notice so a long session does not silently start 401-ing
@@ -542,10 +759,18 @@ export async function registerYagni(pi, deps = {}) {
 }
 export default async function (pi) {
     await registerYagni(pi);
+    // cmux session bridge: report lifecycle state (running/idle), workspace
+    // naming, and resume bindings to cmux when running inside it. Complete
+    // no-op outside cmux — guarded by CMUX_SURFACE_ID. Registered in the
+    // default export (not registerYagni) so tests that call registerYagni
+    // directly don't get the bridge's handlers.
+    registerCmuxBridge(pi);
 }
 export { makeAskYagniTool } from "./askYagniTool.js";
+export { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js";
 export { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
 export { ADVISOR_TIER, DEFAULT_ADVISOR_LIMITS, decideConsult, formatAdvisorSubtotal, makeAdvisorState, } from "./advisor.js";
+export { DEFAULT_GUARDIAN_LIMITS, GUARDIAN_MODEL_TIER, formatGuardianSubtotal, makeGuardianState, resolveGuardianLimits, reviewCommand, } from "./guardian.js";
 export { makeReviewBusinessMatchTool } from "./reviewTool.js";
 export { makeRecordEngineeringContextTool } from "./recordContextTool.js";
 export { makeRecordDecisionTool } from "./recordDecisionTool.js";
@@ -576,7 +801,8 @@ export { registerSubagents, makeSubagentTool, discoverSubagents, parseAgentMarkd
 export { registerTodos, makeTodoTool, normalizeTodos, reconstructTodos, renderTodoWidget, formatTodoList, todoSummary, TODO_TOOL_NAME, MAX_TODOS, } from "./todos.js";
 // P3 + W4: the permission gate seam (decideGate is pure; policy injectable) plus
 // the session bless-with-remember capture hook.
-export { decideGate, registerPermissionGate, filterStalePlanContext, DEFAULT_PERMISSION_POLICY, PLAN_CONTEXT_TYPE, PLAN_CONTEXT_MESSAGE, } from "./permission.js";
+export { decideGate, registerPermissionGate, filterStaleModeContext, filterStalePlanContext, buildModeContextMessage, DEFAULT_PERMISSION_POLICY, MODE_CONTEXT_TYPE, PLAN_CONTEXT_TYPE, PLAN_CONTEXT_MESSAGE, } from "./permission.js";
+export { classifyCommand, DEFAULT_EXEC_POLICY, } from "./execPolicy.js";
 // W4 judgment loop: the session bless store (tool + path-prefix, session-only).
 export { makeBlessStore, blessPath } from "./bless.js";
 // W4 judgment loop: the decisions surface (/decide + /decisions) + shared bank.

package/dist/extension/permission.d.ts

@@ -4,7 +4,8 @@
  * YAGNI Code registers no tool_call handler today, so the interactive session has
  * no plan/approval surface. P3 adds one on pi's documented `tool_call` block seam
  * plus a `/mode` command:
- *   - auto   (default): never blocks. Byte-identical to today, so this is additive.
+ *   - auto   (default): ordinary coding tools run directly; external tracker
+ *              changes still require fresh human confirmation.
  *   - plan   : blocks write/edit/bash so the agent can explore + propose without
  *              touching the tree.
  *   - review : surfaces a three-way ctx.ui.select before a write/edit/bash; a
@@ -14,7 +15,7 @@
  *              adds a session-scoped bless rule AND drafts a decision capture.
  *
  * `decideGate` is PURE; the live wiring holds the mode in a small closure (no
- * module-global state). The default auto mode remains fail-open, but stricter
+ * module-global state). The default auto mode remains direct for coding tools, but stricter
  * modes fail closed for side-effect tools if the gate itself errors. Bless rules
  * are session-scoped, path-prefix-bound, never persisted, and never consulted in
  * plan mode (plan blocks outright before isBlessed is reached).
@@ -26,20 +27,42 @@
  * the context so the model doesn't keep believing it is restricted.
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type ApprovedPrefixGrant } from "./approvedPrefixes.js";
 import { type BlessStore } from "./bless.js";
+import { type ExecPolicy } from "./execPolicy.js";
+import { type GuardianError, type GuardianRiskLevel } from "./guardian.js";
 export type PermissionMode = "auto" | "plan" | "review";
+/**
+ * A shared, mutable holder for the current permission mode. Both
+ * `registerPermissionGate` (which writes on /mode) and the footer factory
+ * (which reads on every render) hold a reference, so mode changes appear
+ * immediately in the footer's line 2.
+ */
+export interface ModeHolder {
+    get(): PermissionMode;
+    set(m: PermissionMode): void;
+}
+export declare function createModeHolder(initial?: PermissionMode): ModeHolder;
 /** Which tools each tier acts on, plus the optional grounding-bless predicate. */
 export interface PermissionPolicy {
     /** Tools blocked outright in plan mode (write/exec). */
     planBlockTools: string[];
     /** Tools that prompt for confirmation in review mode. */
     reviewConfirmTools: string[];
+    /** Consequential external writes that require fresh consent in every mode. */
+    alwaysConfirmTools?: string[];
     /**
      * Optional: a recorded decision already blesses this action, so it auto-runs in
      * review mode instead of prompting. The hook for tying the gate to captured
      * judgment; default undefined (nothing pre-blessed).
      */
     isBlessed?: (toolName: string, params: Record<string, unknown>) => boolean;
+    /**
+     * Exec policy for bash command classification. When present, bash commands are
+     * classified by the exec policy engine before the tool-granular logic runs.
+     * Defaults to DEFAULT_EXEC_POLICY when absent.
+     */
+    execPolicy?: ExecPolicy;
 }
 export declare const DEFAULT_PERMISSION_POLICY: PermissionPolicy;
 /** A pure gate verdict: block outright, ask to confirm, or allow. */
@@ -48,13 +71,55 @@ export interface GateDecision {
     reason?: string;
     /** review mode only: the caller should ctx.ui.confirm before allowing. */
     confirm?: boolean;
+    /**
+     * Exec policy classification result for bash commands. When present, the
+     * tool_call handler should run the Guardian for "prompt" before falling
+     * through to the user confirm. Absent for non-bash tools or when no
+     * command string is available.
+     */
+    classify?: "allow" | "prompt" | "forbidden";
+    /**
+     * The exec policy's justification for a "prompt" classification — why the
+     * command was routed to the Guardian. Threaded into the consult prompt and
+     * the storage event (it is the layer-tuning signal, YAG-510).
+     */
+    classifyJustification?: string;
 }
 /**
- * Pure permission decision for one tool call under a mode + policy. auto always
- * allows; plan blocks the write/exec set; review marks writes for confirmation
+ * Pure permission decision for one tool call under a mode + policy. Auto allows
+ * ordinary tools; plan blocks the write/exec set; review marks writes for confirmation
  * unless a recorded decision blesses them.
  */
 export declare function decideGate(toolName: string, params: Record<string, unknown>, mode: PermissionMode, policy: PermissionPolicy): GateDecision;
+/**
+ * Terminal outcome of one prompt-band decision (YAG-510). One storage event
+ * is emitted per terminal outcome; `consulted` says whether a Guardian LLM
+ * call actually happened (grants/cache hits skip it).
+ */
+export type GuardianGateOutcome = "prefix_allow" | "cached_allow" | "allow" | "deny" | "ask_approved" | "ask_approved_remembered" | "ask_denied" | "ask_headless_blocked" | "breaker_ask_approved" | "breaker_blocked" | GuardianError;
+/**
+ * Rich per-decision event for opt-in storage (YAG-510). Carries the RAW
+ * command — the wiring layer (index.ts) hashes/redacts per the workspace's
+ * storage tier before anything leaves the machine. Distinct from the
+ * sanitized GuardianDiagnosticEvent (local debug log), which never carries
+ * the command.
+ */
+export interface GuardianGateEvent {
+    command: string;
+    outcome: GuardianGateOutcome;
+    /** Why the exec policy routed this command to the Guardian. */
+    execJustification?: string;
+    riskLevel?: GuardianRiskLevel;
+    rationale?: string;
+    mode: PermissionMode;
+    tier?: string;
+    durationMs?: number;
+    /** Whether a Guardian LLM consult actually ran for this decision. */
+    consulted: boolean;
+    /** Present when the terminal outcome followed a Guardian error (e.g. an
+     * error-fallback ask that the user then approved). */
+    guardianError?: GuardianError;
+}
 /** What was blessed with "don't ask again", handed to the capture hook. */
 export interface BlessRememberInfo {
     tool: string;
@@ -73,16 +138,64 @@ export interface RegisterPermissionDeps {
      * never blocks the approved tool call.
      */
     onBlessRemember?: (ctx: ExtensionContext, info: BlessRememberInfo) => void | Promise<void>;
+    /** Shared holder so the footer can read the live mode on every render. */
+    modeHolder?: ModeHolder;
+    /**
+     * Guardian state handle for the session. When present, prompt-band bash
+     * commands are auto-reviewed by the Guardian LLM instead of interrupting
+     * the user. When absent, prompt-band commands fall through to the existing
+     * tool-granular behavior (review: user prompt, auto: allow).
+     */
+    guardianState?: import("./guardian.js").GuardianStateHandle;
+    /** Guardian limits (timeouts, circuit breaker). Defaults to DEFAULT_GUARDIAN_LIMITS. */
+    guardianLimits?: import("./guardian.js").GuardianLimits;
+    /** Override the Guardian model tier (default: efficient). */
+    guardianTier?: string;
+    /** Injectable Guardian review function (tests pass a stub). */
+    guardianReview?: (command: string, deps: import("./guardian.js").ReviewCommandDeps) => Promise<import("./guardian.js").ReviewResult>;
+    /**
+     * Called (fire-and-forget) after each Guardian review with a sanitized
+     * diagnostic event. Fail-soft; never blocks.
+     */
+    onGuardianReview?: (event: import("./guardian.js").GuardianDiagnosticEvent) => void;
+    /** Disable the Guardian entirely (env var YAGNI_DISABLE_GUARDIAN). */
+    guardianDisabled?: boolean;
+    /**
+     * Persisted "don't ask again" grants for this session's repo (YAG-510).
+     * Consulted ONLY after the exec policy classified a command as "prompt" —
+     * a grant can never override the forbidden band. Suppressed in review mode.
+     */
+    grants?: readonly ApprovedPrefixGrant[];
+    /** Resolve the grant scope key for a cwd (git remote origin URL fallback
+     * realpath). Lazily invoked on the first prompt-band bash call. */
+    resolveRepoKey?: (cwd: string) => string;
+    /** Persist a new grant (fire-and-forget; the in-memory list is updated
+     * either way). index.ts wires approvedPrefixes.appendGrant. */
+    persistGrant?: (grant: ApprovedPrefixGrant) => void;
+    /**
+     * Called (fire-and-forget) at every terminal prompt-band outcome with the
+     * rich storage event (raw command — the wiring layer redacts/hashes).
+     * Fail-soft; never blocks.
+     */
+    onGuardianEvent?: (event: GuardianGateEvent) => void;
 }
-/** The customType tag on injected plan-mode context (filterable later). */
-export declare const PLAN_CONTEXT_TYPE = "yagni-plan-context";
+/** The customType tag on injected mode-context messages (filterable later). */
+export declare const MODE_CONTEXT_TYPE = "yagni-mode-context";
+/** Legacy alias — the original plan-mode tag, kept for backward compat. */
+export declare const PLAN_CONTEXT_TYPE = "yagni-mode-context";
 export declare const PLAN_CONTEXT_MESSAGE = "[PLAN MODE ACTIVE]\nYou are in plan mode: explore and design, change nothing.\n- write, edit, and bash are held by the permission gate; do not attempt them.\n- Read, search, and ask_yagni freely to ground the plan in how this company works.\n- Produce a concrete numbered plan of the steps you would take, with the files involved.\n- End by asking the user to review the plan; they run /mode auto (or /mode review) to execute it.\n- Once executing, track the plan's steps with todo_write.";
+/** Build the mode-awareness context message for the current permission mode. */
+export declare function buildModeContextMessage(mode: PermissionMode): string;
 /**
- * Drop previously injected plan-mode context once plan mode is off, so the
- * model stops believing writes are held. Pure; returns the SAME array when
- * nothing needs filtering so callers can cheaply detect a no-op.
+ * Drop previously injected mode-context messages from a DIFFERENT mode so the
+ * model does not keep believing it is in a prior mode. Messages matching the
+ * current mode are kept (the fresh injection from before_agent_start should
+ * survive). Pure; returns the SAME array when nothing needs filtering so callers
+ * can cheaply detect a no-op.
  */
-export declare function filterStalePlanContext<T>(messages: T[]): T[];
+export declare function filterStaleModeContext<T>(messages: T[], currentMode?: PermissionMode): T[];
+/** Legacy alias — the original plan-mode filter name. */
+export declare const filterStalePlanContext: typeof filterStaleModeContext;
 /**
  * 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.