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

package/dist/extension/execPolicy.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Exec policy engine — classifies bash commands via prefix rules + lightweight
+ * shell tokenization (YAG-504).
+ *
+ * Pure: no I/O, no network, no model. Loads at startup and classifies
+ * synchronously. The curated default set auto-allows read-only commands
+ * (ls, cat, rg, git status/log/diff), forbids destructive ones (rm -rf,
+ * git reset --hard, git push --force, pipe-to-shell), and prompts for the
+ * ambiguous middle band (npm install, git commit, curl, …).
+ *
+ * The `prompt` band is what the Guardian arbitrates — see guardian.ts.
+ *
+ * Tokenization is a lightweight inline parser — not shell-quote — because the
+ * extension is bundled into @yagni-app/code's dist (a file copy, not a real
+ * bundler), and external dependencies aren't resolvable from the bundled path.
+ * We only need: split on whitespace (respecting single/double quotes), detect
+ * control operators (|, &&, ||, ;), and flag shell constructs ($(...),
+ * backticks, redirects) that we can't statically analyze.
+ */
+export type TokenEntry = string | {
+    op: "pipe" | "and" | "or" | "semi" | "redirect" | "substitution";
+};
+/**
+ * Parse a shell command string into tokens and control operators.
+ *
+ * Handles:
+ * - Single and double quoted strings (preserves spaces inside)
+ * - Control operators: |, &&, ||, ;
+ * - Shell constructs we flag as unanalyzable: $(), backticks, >, <
+ *
+ * Does NOT handle: variable expansion, glob patterns, heredocs, nested
+ * subshells beyond the first level. Commands using those are classified
+ * as "prompt" (let the Guardian review).
+ */
+export declare function shellParse(command: string): TokenEntry[];
+export type ExecDecision = "allow" | "prompt" | "forbidden";
+export interface PrefixRule {
+    /** Ordered tokens; a string[] element means alternatives (any match). */
+    pattern: (string | string[])[];
+    decision: ExecDecision;
+    justification: string;
+    /** Positive test invocations (validated at load if present). */
+    match?: string[][];
+    /** Negative test invocations (validated at load if present). */
+    notMatch?: string[][];
+}
+export interface ExecPolicy {
+    rules: PrefixRule[];
+}
+export interface ExecClassification {
+    decision: ExecDecision;
+    justification: string;
+    matchedRule?: PrefixRule;
+}
+/**
+ * Parse a command string into tokens using our lightweight tokenizer. Returns
+ * string tokens only (control operators and constructs are filtered out —
+ * detected separately).
+ */
+export declare function tokenize(command: string): string[];
+/**
+ * Classify a full bash command string against the exec policy.
+ *
+ * Compound commands (pipes, &&, ||, ;) are split into segments and each is
+ * classified independently. The strictest decision wins (forbidden > prompt >
+ * allow). Commands with shell constructs we can't parse (command substitution,
+ * redirects beyond pipe) are classified as prompt. Pipe-to-shell is always
+ * forbidden.
+ */
+export declare function classifyCommand(command: string, policy: ExecPolicy): ExecClassification;
+/** Curated default rules — the shipped safety floor. */
+export declare const DEFAULT_EXEC_POLICY: ExecPolicy;
+//# sourceMappingURL=execPolicy.d.ts.map

package/dist/extension/execPolicy.js

@@ -0,0 +1,399 @@
+/**
+ * Exec policy engine — classifies bash commands via prefix rules + lightweight
+ * shell tokenization (YAG-504).
+ *
+ * Pure: no I/O, no network, no model. Loads at startup and classifies
+ * synchronously. The curated default set auto-allows read-only commands
+ * (ls, cat, rg, git status/log/diff), forbids destructive ones (rm -rf,
+ * git reset --hard, git push --force, pipe-to-shell), and prompts for the
+ * ambiguous middle band (npm install, git commit, curl, …).
+ *
+ * The `prompt` band is what the Guardian arbitrates — see guardian.ts.
+ *
+ * Tokenization is a lightweight inline parser — not shell-quote — because the
+ * extension is bundled into @yagni-app/code's dist (a file copy, not a real
+ * bundler), and external dependencies aren't resolvable from the bundled path.
+ * We only need: split on whitespace (respecting single/double quotes), detect
+ * control operators (|, &&, ||, ;), and flag shell constructs ($(...),
+ * backticks, redirects) that we can't statically analyze.
+ */
+/**
+ * Parse a shell command string into tokens and control operators.
+ *
+ * Handles:
+ * - Single and double quoted strings (preserves spaces inside)
+ * - Control operators: |, &&, ||, ;
+ * - Shell constructs we flag as unanalyzable: $(), backticks, >, <
+ *
+ * Does NOT handle: variable expansion, glob patterns, heredocs, nested
+ * subshells beyond the first level. Commands using those are classified
+ * as "prompt" (let the Guardian review).
+ */
+export function shellParse(command) {
+    const tokens = [];
+    let i = 0;
+    let current = "";
+    let inSingle = false;
+    let inDouble = false;
+    let hasConstruct = false;
+    const pushCurrent = () => {
+        if (current.length > 0) {
+            tokens.push(current);
+            current = "";
+        }
+    };
+    while (i < command.length) {
+        const ch = command[i];
+        if (inSingle) {
+            if (ch === "'") {
+                inSingle = false;
+            }
+            else {
+                current += ch;
+            }
+            i++;
+            continue;
+        }
+        if (inDouble) {
+            if (ch === '"') {
+                inDouble = false;
+            }
+            else {
+                current += ch;
+            }
+            i++;
+            continue;
+        }
+        switch (ch) {
+            case "'":
+                inSingle = true;
+                i++;
+                continue;
+            case '"':
+                inDouble = true;
+                i++;
+                continue;
+            case " ":
+            case "\t":
+            case "\n":
+                pushCurrent();
+                i++;
+                continue;
+            case "|":
+                if (command[i + 1] === "|") {
+                    pushCurrent();
+                    tokens.push({ op: "or" });
+                    i += 2;
+                }
+                else {
+                    pushCurrent();
+                    tokens.push({ op: "pipe" });
+                    i++;
+                }
+                continue;
+            case "&":
+                if (command[i + 1] === "&") {
+                    pushCurrent();
+                    tokens.push({ op: "and" });
+                    i += 2;
+                }
+                else {
+                    // Single & — background operator, treat as construct
+                    hasConstruct = true;
+                    current += ch;
+                    i++;
+                }
+                continue;
+            case ";":
+                pushCurrent();
+                tokens.push({ op: "semi" });
+                i++;
+                continue;
+            case ">":
+            case "<":
+                pushCurrent();
+                tokens.push({ op: "redirect" });
+                hasConstruct = true;
+                // Skip the operator char(s) and any following space
+                i++;
+                if (command[i] === ch)
+                    i++; // >> or <<
+                while (command[i] === " " || command[i] === "\t")
+                    i++;
+                continue;
+            case "$":
+                if (command[i + 1] === "(") {
+                    pushCurrent();
+                    tokens.push({ op: "substitution" });
+                    hasConstruct = true;
+                    // Skip until matching )
+                    i += 2;
+                    let depth = 1;
+                    while (i < command.length && depth > 0) {
+                        if (command[i] === "(")
+                            depth++;
+                        if (command[i] === ")")
+                            depth--;
+                        i++;
+                    }
+                    continue;
+                }
+                current += ch;
+                i++;
+                continue;
+            case "`":
+                pushCurrent();
+                tokens.push({ op: "substitution" });
+                hasConstruct = true;
+                i++;
+                while (i < command.length && command[i] !== "`")
+                    i++;
+                if (i < command.length)
+                    i++;
+                continue;
+            default:
+                current += ch;
+                i++;
+                continue;
+        }
+    }
+    pushCurrent();
+    // If we detected constructs but didn't emit them as operator tokens
+    // (e.g. background &), surface that via a substitution token.
+    if (hasConstruct && !tokens.some((t) => typeof t === "object")) {
+        tokens.push({ op: "substitution" });
+    }
+    return tokens;
+}
+/** Interpreters that, when piped into, indicate code execution — always forbidden. */
+const PIPE_TO_SHELL = new Set([
+    "sh", "bash", "zsh", "fish", "nc", "ncat", "socat",
+    "python", "python3", "perl", "ruby", "node",
+]);
+/**
+ * Parse a command string into tokens using our lightweight tokenizer. Returns
+ * string tokens only (control operators and constructs are filtered out —
+ * detected separately).
+ */
+export function tokenize(command) {
+    return shellParse(command).filter((t) => typeof t === "string");
+}
+/** Operator tokens we can safely split on (compound command segments). */
+const SPLIT_OPS = new Set(["pipe", "and", "or", "semi"]);
+/**
+ * Detect whether the command uses shell constructs we can't statically classify
+ * (command substitution, redirects, etc.) — anything that is NOT a splittable
+ * operator (pipe, and, or, semi).
+ */
+function hasUnhandledConstructs(command) {
+    return shellParse(command).some((t) => typeof t === "object" && "op" in t && !SPLIT_OPS.has(t.op));
+}
+/**
+ * Split a command into segments at control operators (|, &&, ||, ;).
+ * Returns the raw string of each segment.
+ */
+function splitSegments(command) {
+    const tokens = shellParse(command);
+    const segments = [];
+    let current = [];
+    for (const t of tokens) {
+        if (typeof t === "object") {
+            if (SPLIT_OPS.has(t.op)) {
+                if (current.length > 0)
+                    segments.push(current.join(" "));
+                current = [];
+            }
+            // Non-splittable operators (redirect, substitution) are already
+            // handled by hasUnhandledConstructs above — we won't reach splitSegments.
+        }
+        else {
+            current.push(t);
+        }
+    }
+    if (current.length > 0)
+        segments.push(current.join(" "));
+    return segments;
+}
+/** Check if any segment pipes into a known shell/network interpreter. */
+function isPipeToShell(command) {
+    const tokens = shellParse(command);
+    for (let i = 0; i < tokens.length - 1; i++) {
+        const t = tokens[i];
+        if (typeof t === "object" && t.op === "pipe") {
+            const next = tokens[i + 1];
+            if (typeof next === "string" && PIPE_TO_SHELL.has(next))
+                return true;
+        }
+    }
+    return false;
+}
+/** Match a token array against a prefix rule's pattern. */
+function matchRule(tokens, rule) {
+    if (tokens.length < rule.pattern.length)
+        return false;
+    for (let i = 0; i < rule.pattern.length; i++) {
+        const pat = rule.pattern[i];
+        const tok = tokens[i];
+        if (typeof pat === "string") {
+            if (pat !== tok)
+                return false;
+        }
+        else {
+            if (!pat.includes(tok))
+                return false;
+        }
+    }
+    return true;
+}
+/** Classify a single command segment (no shell constructs). */
+function classifySegment(segment, rules) {
+    const tokens = tokenize(segment);
+    if (tokens.length === 0) {
+        return { decision: "prompt", justification: "empty command segment" };
+    }
+    // First match wins (rules are ordered; more specific rules come first).
+    for (const rule of rules) {
+        if (matchRule(tokens, rule)) {
+            return { decision: rule.decision, justification: rule.justification, matchedRule: rule };
+        }
+    }
+    // No rule matched → prompt (fail toward review, not toward allow)
+    return { decision: "prompt", justification: `no policy rule matched for "${tokens[0]}"` };
+}
+/** Decision severity: forbidden > prompt > allow. */
+const SEVERITY = { allow: 0, prompt: 1, forbidden: 2 };
+/**
+ * Classify a full bash command string against the exec policy.
+ *
+ * Compound commands (pipes, &&, ||, ;) are split into segments and each is
+ * classified independently. The strictest decision wins (forbidden > prompt >
+ * allow). Commands with shell constructs we can't parse (command substitution,
+ * redirects beyond pipe) are classified as prompt. Pipe-to-shell is always
+ * forbidden.
+ */
+export function classifyCommand(command, policy) {
+    // Pipe-to-shell is always forbidden regardless of other rules.
+    if (isPipeToShell(command)) {
+        return {
+            decision: "forbidden",
+            justification: "piping into a shell or network interpreter is forbidden",
+        };
+    }
+    // Command substitution, redirects, and other constructs we can't statically
+    // analyze → prompt (let the Guardian review). Only checked for constructs
+    // that are NOT splittable (|, &&, ||, ;) — those are handled below.
+    if (hasUnhandledConstructs(command)) {
+        return {
+            decision: "prompt",
+            justification: "command uses shell constructs (substitution/redirect) that cannot be statically analyzed",
+        };
+    }
+    const segments = splitSegments(command);
+    if (segments.length <= 1) {
+        return classifySegment(command, policy.rules);
+    }
+    // Compound command: classify each segment, take the strictest.
+    let result = { decision: "allow", justification: "all segments allowed" };
+    for (const seg of segments) {
+        const segResult = classifySegment(seg, policy.rules);
+        if (SEVERITY[segResult.decision] > SEVERITY[result.decision]) {
+            result = segResult;
+        }
+    }
+    return result;
+}
+/** Curated default rules — the shipped safety floor. */
+export const DEFAULT_EXEC_POLICY = {
+    rules: [
+        // --- forbidden: destructive commands (highest priority) ---
+        {
+            pattern: ["rm", ["-rf", "-fr", "-r", "-f", "--recursive", "--force"]],
+            decision: "forbidden",
+            justification: "recursive/forced deletion is destructive and irreversible",
+        },
+        { pattern: ["rm", "-r"], decision: "forbidden", justification: "recursive deletion is destructive" },
+        { pattern: ["rm", "-f"], decision: "forbidden", justification: "forced deletion bypasses prompts" },
+        { pattern: ["rm", "--recursive"], decision: "forbidden", justification: "recursive deletion is destructive" },
+        { pattern: ["rm", "--force"], decision: "forbidden", justification: "forced deletion bypasses prompts" },
+        { pattern: ["git", "reset", "--hard"], decision: "forbidden", justification: "hard reset discards uncommitted changes irreversibly" },
+        { pattern: ["git", "push", ["--force", "-f"]], decision: "forbidden", justification: "force-push rewrites shared history" },
+        { pattern: ["git", "clean", ["-fd", "-df", "-f", "-d"]], decision: "forbidden", justification: "git clean removes untracked files irreversibly" },
+        { pattern: ["git", "checkout", "--"], decision: "forbidden", justification: "discards working tree changes" },
+        { pattern: ["chmod", "-R", "777"], decision: "forbidden", justification: "recursive world-writable permission change weakens security" },
+        { pattern: ["chown", "-R"], decision: "forbidden", justification: "recursive ownership change" },
+        { pattern: ["dd"], decision: "forbidden", justification: "low-level disk operations are destructive" },
+        { pattern: ["mkfs"], decision: "forbidden", justification: "filesystem formatting is destructive" },
+        { pattern: ["shutdown"], decision: "forbidden", justification: "system shutdown" },
+        { pattern: ["reboot"], decision: "forbidden", justification: "system reboot" },
+        { pattern: ["kill", "-9"], decision: "forbidden", justification: "force kill is destructive" },
+        { pattern: ["kill", "-KILL"], decision: "forbidden", justification: "force kill is destructive" },
+        { pattern: ["truncate"], decision: "forbidden", justification: "truncates files destructively" },
+        // --- allow: read-only commands ---
+        { pattern: ["ls"], decision: "allow", justification: "list directory contents" },
+        { pattern: ["cat"], decision: "allow", justification: "read file contents" },
+        { pattern: ["head"], decision: "allow", justification: "read file head" },
+        { pattern: ["tail"], decision: "allow", justification: "read file tail" },
+        { pattern: ["wc"], decision: "allow", justification: "count lines/words" },
+        { pattern: ["pwd"], decision: "allow", justification: "print working directory" },
+        { pattern: ["which"], decision: "allow", justification: "locate a command" },
+        { pattern: ["echo"], decision: "allow", justification: "print text" },
+        { pattern: ["true"], decision: "allow", justification: "no-op success" },
+        { pattern: ["false"], decision: "allow", justification: "no-op failure" },
+        { pattern: ["test"], decision: "allow", justification: "test condition" },
+        { pattern: ["find", ".", "-name"], decision: "allow", justification: "search for files by name" },
+        { pattern: ["find", ".", "-type"], decision: "allow", justification: "search for files by type" },
+        { pattern: ["grep"], decision: "allow", justification: "search text" },
+        { pattern: ["rg"], decision: "allow", justification: "search text (ripgrep)" },
+        { pattern: ["ag"], decision: "allow", justification: "search text (silver searcher)" },
+        { pattern: ["git", "status"], decision: "allow", justification: "show working tree status" },
+        { pattern: ["git", "log"], decision: "allow", justification: "show commit log" },
+        { pattern: ["git", "diff"], decision: "allow", justification: "show changes" },
+        { pattern: ["git", "branch"], decision: "allow", justification: "list branches" },
+        { pattern: ["git", "show"], decision: "allow", justification: "show a commit" },
+        { pattern: ["git", "remote"], decision: "allow", justification: "list remotes" },
+        { pattern: ["git", "rev-parse"], decision: "allow", justification: "resolve git refs" },
+        { pattern: ["git", "worktree", "list"], decision: "allow", justification: "list worktrees" },
+        { pattern: ["node", "--version"], decision: "allow", justification: "check node version" },
+        { pattern: ["node", "-v"], decision: "allow", justification: "check node version" },
+        { pattern: ["npm", "ls"], decision: "allow", justification: "list installed packages" },
+        { pattern: ["pnpm", "ls"], decision: "allow", justification: "list installed packages" },
+        { pattern: ["pnpm", "--version"], decision: "allow", justification: "check pnpm version" },
+        { pattern: ["tsc", "--version"], decision: "allow", justification: "check typescript version" },
+        // --- prompt: potentially destructive but context-dependent ---
+        { pattern: ["rm"], decision: "prompt", justification: "file deletion — review the target" },
+        { pattern: ["git", "commit"], decision: "prompt", justification: "creates a commit — confirm intent" },
+        { pattern: ["git", "push"], decision: "prompt", justification: "pushes to remote — confirm intent" },
+        { pattern: ["git", "merge"], decision: "prompt", justification: "merges branches — may conflict" },
+        { pattern: ["git", "rebase"], decision: "prompt", justification: "rebases — rewrites history" },
+        { pattern: ["git", "stash"], decision: "prompt", justification: "stashes working changes" },
+        { pattern: ["git", "checkout"], decision: "prompt", justification: "switches branch or restores files" },
+        { pattern: ["git", "switch"], decision: "prompt", justification: "switches branch" },
+        { pattern: ["git", "reset"], decision: "prompt", justification: "resets HEAD — may discard changes" },
+        { pattern: ["git", "revert"], decision: "prompt", justification: "creates a revert commit" },
+        { pattern: ["git", "cherry-pick"], decision: "prompt", justification: "applies a specific commit" },
+        { pattern: ["npm", "install"], decision: "prompt", justification: "installs packages — modifies node_modules" },
+        { pattern: ["npm", "ci"], decision: "prompt", justification: "clean install — modifies node_modules" },
+        { pattern: ["pnpm", "install"], decision: "prompt", justification: "installs packages — modifies node_modules" },
+        { pattern: ["pnpm", "add"], decision: "prompt", justification: "adds a dependency" },
+        { pattern: ["pnpm", "remove"], decision: "prompt", justification: "removes a dependency" },
+        { pattern: ["npm", "run"], decision: "prompt", justification: "runs a script — may have side effects" },
+        { pattern: ["pnpm", ["run", "exec"]], decision: "prompt", justification: "runs a script or binary — may have side effects" },
+        { pattern: ["npx"], decision: "prompt", justification: "executes a package — may have side effects" },
+        { pattern: ["curl"], decision: "prompt", justification: "network request — review the URL" },
+        { pattern: ["wget"], decision: "prompt", justification: "network download — review the URL" },
+        { pattern: ["docker"], decision: "prompt", justification: "docker command — may have side effects" },
+        { pattern: ["psql"], decision: "prompt", justification: "database command — may modify data" },
+        { pattern: ["fly"], decision: "prompt", justification: "Fly.io command — may affect production" },
+        { pattern: ["kubectl"], decision: "prompt", justification: "Kubernetes command — may affect production" },
+        { pattern: ["mv"], decision: "prompt", justification: "moves files — may overwrite" },
+        { pattern: ["cp"], decision: "prompt", justification: "copies files" },
+        { pattern: ["mkdir"], decision: "prompt", justification: "creates directories" },
+        { pattern: ["touch"], decision: "prompt", justification: "creates or updates file timestamps" },
+        { pattern: ["tar"], decision: "prompt", justification: "archive operation" },
+        { pattern: ["zip"], decision: "prompt", justification: "archive operation" },
+        { pattern: ["unzip"], decision: "prompt", justification: "archive operation" },
+        { pattern: ["ps"], decision: "prompt", justification: "lists processes" },
+        { pattern: ["kill"], decision: "prompt", justification: "sends a signal to a process" },
+    ],
+};
+//# sourceMappingURL=execPolicy.js.map

package/dist/extension/guardian.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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;
+/** 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