@yagni-app/code-staging 0.3.0-staging.1067.1 → 0.3.0-staging.1073.1

package/dist/extension/guardian.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The Guardian — LLM auto-review of prompt-band bash commands (YAG-504).
+ *
+ * Pure half: verdict types, state tracking, circuit breaker, JSON parsing.
+ * I/O half: reviewCommand spawns a locked-down child pi (same runStage seam
+ * the advisor uses) on the efficient tier with read-only tools and a risk
+ * policy persona. The child returns a JSON verdict; the gate acts on it.
+ *
+ * Same pure/IO split as advisor.ts (decideConsult pure, askAdvisorTool I/O)
+ * and permission.ts (decideGate pure, registerPermissionGate I/O), for the
+ * same reason: the rules are what need exhaustive tests, and they must not
+ * require a child process to exercise.
+ *
+ * Trigger: the exec policy classifies a bash command as "prompt" (not clearly
+ * safe, not clearly forbidden). The Guardian reviews it instead of interrupting
+ * the user. On allow, the command runs. On deny, the agent sees the rationale
+ * and is told to find a safer alternative or ask the user. On timeout/error,
+ * auto mode fails closed (block); review mode falls back to the user prompt.
+ *
+ * Circuit breaker: 3 consecutive denials in one turn → turn interrupted.
+ */
+import { runStage as defaultRunStage } from "./pipeline/runner.js";
+import type { PipelineStage } from "./pipeline/types.js";
+export type GuardianOutcome = "allow" | "deny";
+export type GuardianRiskLevel = "low" | "medium" | "high" | "critical";
+export interface GuardianVerdict {
+    outcome: GuardianOutcome;
+    riskLevel: GuardianRiskLevel;
+    rationale: string;
+}
+export interface GuardianLimits {
+    /** Session cap on total Guardian reviews. */
+    maxReviews: number;
+    /** Consecutive denials per turn before the circuit breaker trips. */
+    maxConsecutiveDenials: number;
+    /** Hard timeout for the Guardian consult in ms. */
+    timeoutMs: number;
+}
+export declare const DEFAULT_GUARDIAN_LIMITS: GuardianLimits;
+/**
+ * Resolve Guardian limits from the environment. `YAGNI_GUARDIAN_MAX_REVIEWS`
+ * overrides the session review cap; anything non-numeric or < 1 falls back to
+ * the default (a bad value must never zero out the cap and lock the session).
+ */
+export declare function resolveGuardianLimits(env?: Record<string, string | undefined>): GuardianLimits;
+/** The model tier the Guardian runs on. Configurable via YAGNI_GUARDIAN_TIER. */
+export declare const GUARDIAN_MODEL_TIER = "efficient";
+/** Read-only tools — the Guardian can read files for context but cannot write or execute. */
+export declare const GUARDIAN_TOOLS: string[];
+export interface GuardianState {
+    reviews: number;
+    consecutiveDenials: number;
+}
+export interface GuardianStateHandle {
+    read(): GuardianState;
+    recordReview(outcome: GuardianOutcome): GuardianState;
+    resetTurn(): void;
+}
+export declare function makeGuardianState(): GuardianStateHandle;
+export interface CircuitBreakerResult {
+    tripped: boolean;
+    reason?: string;
+}
+export declare function checkCircuitBreaker(state: GuardianState, limits: GuardianLimits): CircuitBreakerResult;
+export declare function parseVerdict(raw: string): GuardianVerdict | null;
+export declare function formatGuardianSubtotal(state: GuardianState, limits: GuardianLimits): string;
+export type GuardianError = "timeout" | "malformed" | "network" | "empty";
+export interface ReviewResult {
+    verdict: GuardianVerdict | null;
+    error?: GuardianError;
+    cost: number;
+}
+export interface ReviewCommandDeps {
+    runStage?: typeof defaultRunStage;
+    cwd: string;
+    signal?: AbortSignal;
+    /** Override the model tier (default: efficient). */
+    modelTier?: string;
+}
+/**
+ * The synthetic stage a Guardian consult runs as. Borrows the `plan` StageId
+ * (same pattern as the advisor) so it doesn't ripple into feed/reducers. The
+ * agent name selects the guardian persona from PERSONA_BODIES.
+ */
+export declare function guardianStage(modelTier?: string): PipelineStage;
+/**
+ * Run a Guardian consult: spawn a locked-down child pi with the risk policy
+ * persona and the command as the task. Parse the JSON verdict from the output.
+ * Returns { verdict, cost } on success, { verdict: null, error, cost } on failure.
+ */
+export declare function reviewCommand(command: string, deps: ReviewCommandDeps): Promise<ReviewResult>;
+export interface GuardianDiagnosticEvent {
+    event: "guardian_review";
+    outcome: GuardianOutcome | GuardianError;
+    durationMs?: number;
+    tier?: string;
+    /** Debug-only: command hash for correlation (never the raw command). */
+    commandHash?: string;
+    /** Debug-only: the Guardian's rationale. */
+    rationale?: string;
+}
+/**
+ * Create a sanitized diagnostic event. Never includes the raw command text
+ * (could contain secrets). YAGNI_DEBUG=1 adds rationale and a command hash.
+ */
+export declare function buildDiagnosticEvent(outcome: GuardianOutcome | GuardianError, opts: {
+    durationMs?: number;
+    tier?: string;
+    rationale?: string;
+    commandHash?: string;
+    debug?: boolean;
+}): GuardianDiagnosticEvent;
+//# sourceMappingURL=guardian.d.ts.map

package/dist/extension/guardian.js

@@ -0,0 +1,186 @@
+/**
+ * The Guardian — LLM auto-review of prompt-band bash commands (YAG-504).
+ *
+ * Pure half: verdict types, state tracking, circuit breaker, JSON parsing.
+ * I/O half: reviewCommand spawns a locked-down child pi (same runStage seam
+ * the advisor uses) on the efficient tier with read-only tools and a risk
+ * policy persona. The child returns a JSON verdict; the gate acts on it.
+ *
+ * Same pure/IO split as advisor.ts (decideConsult pure, askAdvisorTool I/O)
+ * and permission.ts (decideGate pure, registerPermissionGate I/O), for the
+ * same reason: the rules are what need exhaustive tests, and they must not
+ * require a child process to exercise.
+ *
+ * Trigger: the exec policy classifies a bash command as "prompt" (not clearly
+ * safe, not clearly forbidden). The Guardian reviews it instead of interrupting
+ * the user. On allow, the command runs. On deny, the agent sees the rationale
+ * and is told to find a safer alternative or ask the user. On timeout/error,
+ * auto mode fails closed (block); review mode falls back to the user prompt.
+ *
+ * Circuit breaker: 3 consecutive denials in one turn → turn interrupted.
+ */
+import { runStage as defaultRunStage } from "./pipeline/runner.js";
+export const DEFAULT_GUARDIAN_LIMITS = {
+    maxReviews: 30,
+    maxConsecutiveDenials: 3,
+    timeoutMs: 15_000,
+};
+/**
+ * Resolve Guardian limits from the environment. `YAGNI_GUARDIAN_MAX_REVIEWS`
+ * overrides the session review cap; anything non-numeric or < 1 falls back to
+ * the default (a bad value must never zero out the cap and lock the session).
+ */
+export function resolveGuardianLimits(env = process.env) {
+    const raw = env.YAGNI_GUARDIAN_MAX_REVIEWS?.trim();
+    const parsed = raw ? Number.parseInt(raw, 10) : NaN;
+    const maxReviews = Number.isFinite(parsed) && parsed >= 1 ? parsed : DEFAULT_GUARDIAN_LIMITS.maxReviews;
+    return { ...DEFAULT_GUARDIAN_LIMITS, maxReviews };
+}
+/** The model tier the Guardian runs on. Configurable via YAGNI_GUARDIAN_TIER. */
+export const GUARDIAN_MODEL_TIER = "efficient";
+/** Read-only tools — the Guardian can read files for context but cannot write or execute. */
+export const GUARDIAN_TOOLS = ["read"];
+export function makeGuardianState() {
+    const state = { reviews: 0, consecutiveDenials: 0 };
+    return {
+        read: () => ({ ...state }),
+        recordReview(outcome) {
+            state.reviews += 1;
+            if (outcome === "deny") {
+                state.consecutiveDenials += 1;
+            }
+            else {
+                state.consecutiveDenials = 0;
+            }
+            return { ...state };
+        },
+        resetTurn() {
+            state.consecutiveDenials = 0;
+        },
+    };
+}
+export function checkCircuitBreaker(state, limits) {
+    if (state.consecutiveDenials >= limits.maxConsecutiveDenials) {
+        return {
+            tripped: true,
+            reason: `Guardian denied ${state.consecutiveDenials} consecutive actions this turn. Pausing for human review.`,
+        };
+    }
+    return { tripped: false };
+}
+// --- Verdict parsing (fail closed on malformed) ---
+export function parseVerdict(raw) {
+    try {
+        // Efficient-tier models may wrap JSON in markdown fences despite
+        // instructions to output raw JSON. Extract the first {...} block.
+        const jsonMatch = raw.match(/\{[\s\S]*\}/);
+        const jsonStr = jsonMatch ? jsonMatch[0] : raw;
+        const parsed = JSON.parse(jsonStr);
+        const outcome = parsed?.outcome;
+        if (outcome !== "allow" && outcome !== "deny")
+            return null;
+        const riskLevel = parsed.riskLevel;
+        const validLevels = ["low", "medium", "high", "critical"];
+        return {
+            outcome,
+            riskLevel: typeof riskLevel === "string" && validLevels.includes(riskLevel)
+                ? riskLevel
+                : "medium",
+            rationale: typeof parsed.rationale === "string" && parsed.rationale.trim().length > 0
+                ? parsed.rationale.trim()
+                : "No rationale provided.",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// --- /cost subtotal ---
+export function formatGuardianSubtotal(state, limits) {
+    if (state.reviews === 0)
+        return "";
+    const plural = state.reviews === 1 ? "review" : "reviews";
+    return `Guardian: ${state.reviews} ${plural}.`;
+}
+/**
+ * The synthetic stage a Guardian consult runs as. Borrows the `plan` StageId
+ * (same pattern as the advisor) so it doesn't ripple into feed/reducers. The
+ * agent name selects the guardian persona from PERSONA_BODIES.
+ */
+export function guardianStage(modelTier = GUARDIAN_MODEL_TIER) {
+    return {
+        id: "plan",
+        agent: "guardian",
+        model: modelTier,
+        tools: GUARDIAN_TOOLS,
+        taskTemplate: "{ticket}",
+    };
+}
+/**
+ * Run a Guardian consult: spawn a locked-down child pi with the risk policy
+ * persona and the command as the task. Parse the JSON verdict from the output.
+ * Returns { verdict, cost } on success, { verdict: null, error, cost } on failure.
+ */
+export async function reviewCommand(command, deps) {
+    const runStage = deps.runStage ?? defaultRunStage;
+    const stage = guardianStage(deps.modelTier);
+    // Build the abort signal with the Guardian timeout.
+    const timeoutMs = DEFAULT_GUARDIAN_LIMITS.timeoutMs;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    timer.unref?.();
+    // Chain with the caller's signal if present.
+    if (deps.signal) {
+        if (deps.signal.aborted)
+            controller.abort();
+        else
+            deps.signal.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+    try {
+        const result = await runStage(stage, { ticket: `Review this shell command for safety. Output only the JSON verdict.\n\nCommand:\n${command}` }, {
+            cwd: deps.cwd,
+            signal: controller.signal,
+            callerLabel: "guardian",
+        });
+        const cost = result.usage?.cost ?? 0;
+        const output = result.finalOutput.trim();
+        if (!output) {
+            return { verdict: null, error: "empty", cost };
+        }
+        const verdict = parseVerdict(output);
+        if (!verdict) {
+            return { verdict: null, error: "malformed", cost };
+        }
+        return { verdict, cost };
+    }
+    catch (err) {
+        // Distinguish timeout from network/process errors.
+        if (controller.signal.aborted && !deps.signal?.aborted) {
+            return { verdict: null, error: "timeout", cost: 0 };
+        }
+        return { verdict: null, error: "network", cost: 0 };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Create a sanitized diagnostic event. Never includes the raw command text
+ * (could contain secrets). YAGNI_DEBUG=1 adds rationale and a command hash.
+ */
+export function buildDiagnosticEvent(outcome, opts) {
+    const ev = {
+        event: "guardian_review",
+        outcome,
+        ...(opts.durationMs !== undefined ? { durationMs: opts.durationMs } : {}),
+        ...(opts.tier !== undefined ? { tier: opts.tier } : {}),
+    };
+    if (opts.debug) {
+        if (opts.rationale)
+            ev.rationale = opts.rationale;
+        if (opts.commandHash)
+            ev.commandHash = opts.commandHash;
+    }
+    return ev;
+}
+//# sourceMappingURL=guardian.js.map

package/dist/extension/index.d.ts

@@ -4,7 +4,7 @@ import { runInitPass as defaultRunInitPass } from "./initPass.js";
 import { fetchMcpServers as defaultFetchMcpServers } from "./mcpTools.js";
 import { type FlushOutcome, type SpoolClientOpts } from "./spool.js";
 import { type TokenProvider } from "./tokenProvider.js";
-import { type ContextBrief, type ModelEntry } from "./config.js";
+import { type CatalogResult, type ContextBrief } from "./config.js";
 /**
  * YAGNI Code extension entry point.
  *
@@ -31,7 +31,7 @@ export interface RegisterYagniDeps {
         baseUrl: string;
         getToken: () => string | undefined;
         fetchImpl?: typeof fetch;
-    }) => Promise<ModelEntry[]>;
+    }) => Promise<CatalogResult>;
     fetchContextBrief?: (opts: {
         baseUrl: string;
         getToken: () => string | undefined;
@@ -106,6 +106,8 @@ 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 type { GuardianOutcome, GuardianVerdict, GuardianState, GuardianStateHandle, GuardianLimits, ReviewResult, ReviewCommandDeps, } from "./guardian.js";
 export type { Citation, MakeAskYagniToolOptions } from "./askYagniTool.js";
 export { makeReviewBusinessMatchTool } from "./reviewTool.js";
 export type { MakeReviewToolOptions } from "./reviewTool.js";
@@ -122,7 +124,7 @@ export type { RunInitPassDeps, InitPassOutcome, RunTeamSetupDeps, TeamSetupOutco
 export { isInitDone, markInitDone, initDoneMarkerFile, _setInitDoneHomeForTest } from "./initDone.js";
 export { brandSystemPrompt, YAGNI_IDENTITY, YAGNI_IDENTITY_DRIVER, BRAND_NAME } from "./branding.js";
 export { attributionHeaders, isDriverCaller, fetchCatalog, getToken, getWorkspaceId, resolveBaseUrl, sanitizeCallerSegment, } from "./config.js";
-export type { FetchCatalogOptions, ModelEntry } from "./config.js";
+export type { CatalogResult, FetchCatalogOptions, ModelEntry } from "./config.js";
 export { buildYagniProvider } from "./provider.js";
 export { registerGoCommand } from "./pipeline/goCommand.js";
 export type { RegisterGoDeps } from "./pipeline/goCommand.js";
@@ -141,7 +143,9 @@ export { registerSubagents, makeSubagentTool, discoverSubagents, parseAgentMarkd
 export type { SubagentDef, SubagentSource } from "./subagents.js";
 export { registerTodos, makeTodoTool, normalizeTodos, reconstructTodos, renderTodoWidget, formatTodoList, todoSummary, TODO_TOOL_NAME, MAX_TODOS, } from "./todos.js";
 export type { TodoItem, TodoStatus, TodoTheme } from "./todos.js";
-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";
+export type { ExecDecision, ExecPolicy, PrefixRule, ExecClassification, } from "./execPolicy.js";
 export type { PermissionMode, PermissionPolicy, GateDecision, RegisterPermissionDeps, BlessRememberInfo, } from "./permission.js";
 export { makeBlessStore, blessPath } from "./bless.js";
 export type { BlessStore, BlessRule } from "./bless.js";

package/dist/extension/index.js

@@ -2,6 +2,7 @@ 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 { formatGuardianSubtotal, GUARDIAN_MODEL_TIER, makeGuardianState, resolveGuardianLimits, reviewCommand } from "./guardian.js";
 import { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
 import { makeAskYagniTool } from "./askYagniTool.js";
 import { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js";
@@ -126,7 +127,7 @@ export async function registerYagni(pi, deps = {}) {
     // 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 fullCatalog = await fetchCatalog({ baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+    const { models: fullCatalog, guardianEnabled: workspaceGuardianEnabled } = 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
@@ -234,8 +235,33 @@ export async function registerYagni(pi, deps = {}) {
     // 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);
     registerPermissionGate(pi, {
         modeHolder,
+        guardianState,
+        guardianLimits,
+        guardianTier,
+        guardianDisabled,
+        guardianReview: (command, deps) => reviewCommand(command, { ...deps, modelTier: guardianTier }),
+        onGuardianReview: (ev) => {
+            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(), ...ev }) + "\n", "utf8");
+            }
+            catch { /* logging must never break the session */ }
+        },
         ...(mcpMutatingTools.length > 0
             ? {
                 policy: {
@@ -271,7 +297,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),
+        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 } });
@@ -651,6 +681,7 @@ 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";
@@ -681,7 +712,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

@@ -28,6 +28,7 @@
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type BlessStore } from "./bless.js";
+import { type ExecPolicy } from "./execPolicy.js";
 export type PermissionMode = "auto" | "plan" | "review";
 /**
  * A shared, mutable holder for the current permission mode. Both
@@ -54,6 +55,12 @@ export interface PermissionPolicy {
      * 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. */
@@ -62,6 +69,13 @@ 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";
 }
 /**
  * Pure permission decision for one tool call under a mode + policy. Auto allows
@@ -89,16 +103,44 @@ export interface RegisterPermissionDeps {
     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;
 }
-/** 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.