@yagni-app/code-staging 0.0.0 → 0.1.0-staging.997.1

package/dist/extension/initPass.js

@@ -0,0 +1,394 @@
+/**
+ * The CLI init pass (Onramp Door B, spec §5B/§7).
+ *
+ * On a FRESH workspace, the first `yagni` run in a repo should not drop the
+ * user into a bare prompt. Instead it runs a one-time init pass:
+ *   1. detect a fresh workspace (an empty/thin grounding corpus, via the existing
+ *      `GET /api/yagni-code/context` brief),
+ *   2. read the repo (README, AGENTS.md/CLAUDE.md, package.json scripts, ADRs),
+ *   3. draft the ENGINEERING HALF of the company brief + a proposed Engineering
+ *      Team, and record the salient ADRs/conventions as decisions so the corpus
+ *      is non-empty for the very first `/go`,
+ *   4. present the draft for approve/edit in-terminal (mirrored to the app via the
+ *      recorded decisions), NEVER auto-committing the Team, and
+ *   5. offer the ONE default next action (`suggest_next_work`) with escape hatches.
+ *
+ * Honesty rails (non-negotiable, spec §9): when a repo has no README/AGENTS/ADRs
+ * the engineering half stays THIN and SAYS SO — nothing is fabricated, and no
+ * decision is seeded from thin air. The proposed Team is only ever a DRAFT; it is
+ * never created/committed automatically.
+ *
+ * No new backend transport: the only writes are through the existing token-scoped
+ * `record_decision` endpoint (reused via {@link recordDecision}). Every seam is
+ * injectable so the whole pass is unit-testable without a network or a filesystem.
+ */
+import { readFile as fsReadFile, readdir as fsReaddir } from "node:fs/promises";
+import path from "node:path";
+import { fetchContextBrief as defaultFetchContextBrief, } from "./config.js";
+import { defaultNextAction } from "./nextWorkTool.js";
+import { recordDecision as defaultRecordDecision, } from "./recordDecisionTool.js";
+// ---------------------------------------------------------------------------
+// Fresh-workspace detection
+// ---------------------------------------------------------------------------
+/**
+ * Below this many non-whitespace characters (and with no sources), a returned
+ * context brief is treated as thin/empty — i.e. the corpus has not been seeded
+ * yet, so this is a fresh workspace that should run the init pass.
+ */
+export const FRESH_BRIEF_MIN_CHARS = 40;
+/**
+ * Is this a fresh workspace (an empty/thin grounding corpus)? A `null` brief, or
+ * a brief with only a stub of text and no sources, means nothing has grounded the
+ * workspace yet. A brief with real text OR any sources means it is already
+ * populated and the init pass must be skipped.
+ */
+export function isFreshWorkspace(brief) {
+    if (!brief)
+        return true;
+    const text = (brief.brief ?? "").trim();
+    const hasSources = Array.isArray(brief.sources) && brief.sources.length > 0;
+    return text.length < FRESH_BRIEF_MIN_CHARS && !hasSources;
+}
+/** The default fs seam: node:fs/promises, resolving to empty on any error. */
+const nodeIntakeFs = {
+    async readFile(p) {
+        try {
+            return await fsReadFile(p, "utf8");
+        }
+        catch {
+            return "";
+        }
+    },
+    async readdir(p) {
+        try {
+            return await fsReaddir(p);
+        }
+        catch {
+            return [];
+        }
+    },
+};
+/** Candidate filenames, tried in order; the first that reads non-empty wins. */
+const README_CANDIDATES = ["README.md", "README", "readme.md", "README.markdown"];
+const AGENTS_CANDIDATES = ["AGENTS.md", "CLAUDE.md"];
+const ADR_DIRS = ["docs/adr", "docs/adrs", "docs/decisions"];
+/** Cap the amount of prose we lift so a large README never bloats the brief. */
+const MAX_DOC_CHARS = 4000;
+const MAX_SUMMARY_CHARS = 280;
+const MAX_ADRS = 25;
+async function firstNonEmpty(fs, cwd, names) {
+    for (const name of names) {
+        const body = (await fs.readFile(path.join(cwd, name))).trim();
+        if (body)
+            return body.slice(0, MAX_DOC_CHARS);
+    }
+    return undefined;
+}
+/** Parse the `scripts` map out of a package.json body; {} on any problem. */
+function parseScripts(raw) {
+    if (!raw.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        const scripts = parsed.scripts;
+        if (!scripts || typeof scripts !== "object")
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(scripts)) {
+            if (typeof v === "string")
+                out[k] = v;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** The first `# heading` (or the filename) as a title; first paragraph as summary. */
+function extractAdr(relPath, content) {
+    const heading = content.match(/^#{1,3}\s+(.+)$/m);
+    const title = heading?.[1]?.trim() || path.basename(relPath).replace(/\.[^.]+$/, "");
+    // First non-heading, non-empty paragraph.
+    const paragraphs = content
+        .split(/\n\s*\n/)
+        .map((p) => p.trim())
+        .filter((p) => p && !p.startsWith("#"));
+    const summary = paragraphs[0]?.replace(/\s+/g, " ").slice(0, MAX_SUMMARY_CHARS);
+    return { path: relPath, title, summary: summary || undefined };
+}
+async function readAdrs(fs, cwd) {
+    const adrs = [];
+    for (const dir of ADR_DIRS) {
+        const entries = await fs.readdir(path.join(cwd, dir));
+        for (const entry of entries.filter((e) => /\.m(d|arkdown)$/i.test(e)).sort()) {
+            if (adrs.length >= MAX_ADRS)
+                return adrs;
+            const rel = `${dir}/${entry}`;
+            const content = await fs.readFile(path.join(cwd, rel));
+            if (content.trim())
+                adrs.push(extractAdr(rel, content));
+        }
+    }
+    return adrs;
+}
+/**
+ * Read the repo at `cwd` for the signals that seed the engineering half of the
+ * brief. Every read is best-effort; a missing file simply drops that signal.
+ */
+export async function readRepoIntake(cwd, fs = nodeIntakeFs) {
+    const [readme, agents, pkgRaw, adrs] = await Promise.all([
+        firstNonEmpty(fs, cwd, README_CANDIDATES),
+        firstNonEmpty(fs, cwd, AGENTS_CANDIDATES),
+        fs.readFile(path.join(cwd, "package.json")),
+        readAdrs(fs, cwd),
+    ]);
+    const packageScripts = parseScripts(pkgRaw);
+    return {
+        readme,
+        agents,
+        packageScripts,
+        adrs,
+        testCommand: packageScripts.test || undefined,
+        buildCommand: packageScripts.build || undefined,
+    };
+}
+const THIN_BRIEF = "I couldn't find a README, AGENTS.md/CLAUDE.md, or ADRs in this repo, so I don't " +
+    "know much about how you build yet. Tell me in a line what this repo is and how " +
+    "you build it, and I'll fill in the engineering brief.";
+const TEAM_MISSION = "Owns how we build: conventions, reviews, test/build, and risk areas.";
+/** The README's first real paragraph (heading-stripped), capped. */
+function firstParagraph(readme) {
+    if (!readme)
+        return undefined;
+    const para = readme
+        .split(/\n\s*\n/)
+        .map((p) => p.trim())
+        .find((p) => p && !p.startsWith("#") && !/^[!\[]/.test(p));
+    return para?.replace(/\s+/g, " ").slice(0, MAX_SUMMARY_CHARS);
+}
+/**
+ * Draft the engineering half of the brief from repo intake. PURE. Honest-when-thin:
+ * with no README/AGENTS/ADRs the brief says so and NO decision is seeded.
+ */
+export function draftEngineering(intake) {
+    const hasSubstance = Boolean(intake.readme || intake.agents || intake.adrs.length);
+    const thin = !hasSubstance;
+    const team = {
+        name: "Engineering",
+        mission: TEAM_MISSION,
+        responsibilities: [],
+        playbookRules: [],
+        testCommand: intake.testCommand,
+        buildCommand: intake.buildCommand,
+        riskAreas: intake.adrs
+            .filter((a) => /risk|security|migration|billing|auth/i.test(a.title))
+            .map((a) => a.title),
+    };
+    if (intake.testCommand)
+        team.playbookRules.push(`Run \`${intake.testCommand}\` before handing off a change.`);
+    if (intake.buildCommand)
+        team.playbookRules.push(`Run \`${intake.buildCommand}\` to verify the change builds.`);
+    team.playbookRules.push("Ask @yagni before guessing on anything org- or codebase-specific; record product-intent decisions as you make them.");
+    if (thin) {
+        team.responsibilities.push("Define how this team builds software (not documented yet).");
+        return { brief: THIN_BRIEF, thin: true, decisions: [], team };
+    }
+    if (intake.agents)
+        team.responsibilities.push("Uphold the conventions documented in AGENTS.md/CLAUDE.md.");
+    if (intake.testCommand || intake.buildCommand)
+        team.responsibilities.push("Keep the build and tests green.");
+    if (intake.adrs.length)
+        team.responsibilities.push("Steward the architecture decisions in docs/adr.");
+    if (team.responsibilities.length === 0)
+        team.responsibilities.push("Own how this team builds software.");
+    const lines = ["How this team builds software (drafted from repo intake — a draft, editable):"];
+    const whatItIs = firstParagraph(intake.readme);
+    if (whatItIs)
+        lines.push(`- What this is: ${whatItIs}`);
+    if (intake.agents)
+        lines.push("- Conventions: documented in AGENTS.md/CLAUDE.md.");
+    if (intake.testCommand)
+        lines.push(`- Tests: \`${intake.testCommand}\``);
+    if (intake.buildCommand)
+        lines.push(`- Build: \`${intake.buildCommand}\``);
+    if (intake.adrs.length)
+        lines.push(`- Decisions on record: ${intake.adrs.map((a) => a.title).join("; ")}`);
+    const brief = lines.join("\n");
+    // Seed the corpus so the very first /go has real ground to cite. The brief
+    // itself is banked as one grounding entry, then each ADR/convention as a
+    // decision. All are DRAFTS (editable), never treated as immutable fact.
+    const decisions = [
+        {
+            question: "How does this team build software?",
+            decision: brief,
+            rationale: "Drafted from repo intake (README/AGENTS/ADRs) during the first YAGNI Code run; a draft, editable.",
+        },
+        ...intake.adrs.map((adr) => ({
+            question: `What does "${adr.title}" decide?`,
+            decision: adr.summary || adr.title,
+            rationale: `Recorded from ${adr.path} during repo intake.`,
+        })),
+    ];
+    return { brief, thin: false, decisions, team };
+}
+/**
+ * Compact one-screen PREVIEW of the draft for the approve/edit dialog.
+ *
+ * Approval-gated (spec §5B/§9, F2/F13): NOTHING is written to the corpus until
+ * the human approves or corrects the draft, so this is a preview of INTENT — it
+ * states what will be recorded ON APPROVAL, and never claims a corpus was
+ * already seeded. When thin there is nothing to record (honest — nothing to
+ * fabricate). The ACTUAL recorded count is reported after the write runs (see
+ * `runInitPass`).
+ */
+export function summarizeDraft(draft) {
+    const parts = [draft.brief, "", `Proposed Team: ${draft.team.name} — ${draft.team.mission}`];
+    if (draft.team.responsibilities.length) {
+        parts.push("Responsibilities:", ...draft.team.responsibilities.map((r) => `  - ${r}`));
+    }
+    if (draft.thin) {
+        parts.push("", "(Engineering context is thin — nothing to record yet; I never fabricate one.)");
+    }
+    else if (draft.decisions.length > 0) {
+        parts.push("", `On approval I'll record ${draft.decisions.length} decision(s) into your grounding corpus.`);
+    }
+    parts.push("", "This Team is a draft — it is never created automatically. You can edit it first.");
+    return parts.join("\n");
+}
+/**
+ * Run the init pass. Guards on fresh-workspace detection (defensive — the caller
+ * also guards), reads the repo, drafts the engineering half, presents it for
+ * approve/edit, and ONLY THEN seeds the corpus (approval-gated: an approve banks
+ * the drafted decisions, an edit banks the correction, a decline writes nothing),
+ * before offering the one default next action. Fully fail-soft: a UI or network
+ * hiccup never throws (it must never break session start).
+ */
+export async function runInitPass(pi, ctx, deps) {
+    const recordDecisionFn = deps.recordDecision ?? defaultRecordDecision;
+    const readIntake = deps.readRepoIntake ?? ((cwd) => readRepoIntake(cwd));
+    const decisionOpts = {
+        baseUrl: deps.baseUrl,
+        getToken: deps.getToken,
+        fetchImpl: deps.fetchImpl,
+    };
+    // 1. Fresh-workspace guard (skip when already grounded).
+    const brief = deps.brief !== undefined
+        ? deps.brief
+        : await (deps.fetchContextBrief ?? defaultFetchContextBrief)({
+            baseUrl: deps.baseUrl,
+            getToken: deps.getToken,
+            fetchImpl: deps.fetchImpl,
+        }).catch(() => null);
+    if (!isFreshWorkspace(brief))
+        return { ran: false, reason: "not_fresh" };
+    const ui = (ctx.hasUI ? ctx.ui : undefined);
+    // 1b. Approval-gated writes (spec §5B/§9 — captured-judgment beat): the init
+    // pass records decisions into the corpus, but a decision only earns its place
+    // when a human can see and approve/edit the draft. In non-interactive / print
+    // (`-p`) / no-UI mode there is no one to approve, so we NEVER write — we skip
+    // the pass entirely (returning ran:false so the caller does NOT mark the
+    // workspace init-done, leaving the seed for the first interactive run).
+    if (!ui)
+        return { ran: false, reason: "non_interactive" };
+    const notify = (message, type) => {
+        try {
+            ui?.notify?.(message, type);
+        }
+        catch {
+            /* a notice must never disrupt the pass */
+        }
+    };
+    notify("YAGNI Code — first run in this repo. Reading it to seed your engineering brief…", "info");
+    // 2. Read the repo + draft the engineering half.
+    let intake;
+    try {
+        intake = await readIntake(ctx.cwd);
+    }
+    catch {
+        intake = { packageScripts: {}, adrs: [] };
+    }
+    const draft = draftEngineering(intake);
+    // 3. Present the draft for approve/edit BEFORE any durable write (spec §5B/§9,
+    //    F2/F13 — approval-gated writes). A decision earns its place in the corpus
+    //    only once the human has APPROVED the draft or CORRECTED it; nothing is
+    //    written before the dialog. The Team itself is never auto-committed. In a
+    //    UI without a `confirm` capability there is no way to obtain approval, so
+    //    (consistent with the no-UI guard above) we write nothing.
+    let decisionsRecorded = 0;
+    let chosenAction;
+    try {
+        let approved = false;
+        let correctedBrief;
+        if (ui && typeof ui.confirm === "function") {
+            approved = await ui.confirm("Your draft Engineering Team", summarizeDraft(draft));
+            if (!approved && typeof ui.editor === "function") {
+                const edited = await ui.editor("Edit the engineering brief", draft.brief);
+                if (edited && edited.trim() && edited.trim() !== draft.brief.trim()) {
+                    correctedBrief = edited.trim();
+                }
+            }
+        }
+        // 4. Approval-gated corpus writes. APPROVE → bank the drafted decisions.
+        //    REJECT-then-correct → bank ONLY the correction (the rejected auto-draft
+        //    is never written). REJECT without an edit (or no approval UI) → write
+        //    NOTHING. Best-effort throughout: a failed write is swallowed and the
+        //    recorded count stays honest (F13).
+        if (approved) {
+            for (const decision of draft.decisions) {
+                try {
+                    const result = await recordDecisionFn(decisionOpts, decision, ctx.signal);
+                    if (!result.spooled)
+                        decisionsRecorded += 1;
+                }
+                catch {
+                    /* fail-soft: recording is best-effort */
+                }
+            }
+        }
+        else if (correctedBrief) {
+            // The edit is a captured-judgment beat: bank the correction so the next
+            // run inherits the steer.
+            try {
+                const result = await recordDecisionFn(decisionOpts, {
+                    question: "How does this team build software?",
+                    decision: correctedBrief,
+                    rationale: "The user edited the drafted engineering brief during the init pass.",
+                }, ctx.signal);
+                if (!result.spooled)
+                    decisionsRecorded += 1;
+            }
+            catch {
+                /* fail-soft */
+            }
+        }
+        // Report the ACTUAL recorded count once the write has run (never the
+        // intended count) so the receipt is honest even on a partial/failed write.
+        if (decisionsRecorded > 0) {
+            notify(`Recorded ${decisionsRecorded} decision(s) into your grounding corpus.`, "info");
+        }
+        // 5. Offer the ONE default next action (not a four-option chooser).
+        const next = defaultNextAction();
+        if (ui && typeof ui.select === "function") {
+            const labels = [next.primary.label, ...next.escapeHatches.map((h) => h.label)];
+            const picked = await ui.select("What next?", labels);
+            const chosen = [next.primary, ...next.escapeHatches].find((o) => o.label === picked) ?? next.primary;
+            chosenAction = chosen.id;
+            ui.setEditorText?.(chosen.prompt);
+        }
+        else {
+            notify(`Next: ${next.primary.prompt}`, "info");
+        }
+    }
+    catch {
+        /* the presentation is best-effort; the corpus is already seeded */
+    }
+    return {
+        ran: true,
+        thin: draft.thin,
+        decisionsRecorded,
+        teamDrafted: true,
+        teamCommitted: false,
+        chosenAction,
+    };
+}
+//# sourceMappingURL=initPass.js.map

package/dist/extension/nextWorkTool.d.ts

@@ -0,0 +1,51 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { Citation } from "./askYagniTool.js";
+/** Options for {@link makeSuggestNextWorkTool}. */
+export interface MakeNextWorkToolOptions {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+}
+/** A single offered next action: its id, the label shown, and the editor prompt it prefills. */
+export interface NextActionOption {
+    id: "suggest_next_work" | "bootstrap" | "review";
+    /** Short label shown in the selector. */
+    label: string;
+    /** The message prefilled into the editor when this action is chosen. */
+    prompt: string;
+}
+/**
+ * The one default next action plus its escape hatches. `primary` is the single
+ * most-likely thing to do (ask @yagni what to work on next); `escapeHatches` are
+ * the two alternatives (bootstrap a first ticket, or review the working diff).
+ * This is deliberately a ONE-default-plus-hatches shape, NOT a flat four-option
+ * chooser — defaults over choices (spec §7.3).
+ */
+export interface DefaultNextAction {
+    primary: NextActionOption;
+    escapeHatches: NextActionOption[];
+}
+/**
+ * Build the default next action offered after the init pass. The recommended
+ * default is `suggest_next_work` ("ask @yagni what to work on next"); the escape
+ * hatches are "bootstrap a first ticket and /go" and "review this diff". Pure so
+ * the presenter can render it without a network.
+ */
+export declare function defaultNextAction(): DefaultNextAction;
+declare const parameters: Type.TObject<{
+    context: Type.TOptional<Type.TString>;
+}>;
+/**
+ * Build the `suggest_next_work` tool.
+ *
+ * Asks the YAGNI app for the highest-value next thing to work on, RANKED BY
+ * BUSINESS PRIORITY across open work-items and desk next-moves (not by ticket
+ * order), with the business case for the top pick. Returns a ranked
+ * recommendation plus citations.
+ */
+export declare function makeSuggestNextWorkTool(opts: MakeNextWorkToolOptions): ToolDefinition<typeof parameters, {
+    citations: Citation[];
+}>;
+export {};
+//# sourceMappingURL=nextWorkTool.d.ts.map

package/dist/extension/nextWorkTool.js

@@ -0,0 +1,80 @@
+import { Type } from "typebox";
+import { friendlyFetchError, METERED_POST_FETCH_POLICY, resilientFetch } from "./resilientFetch.js";
+/**
+ * Build the default next action offered after the init pass. The recommended
+ * default is `suggest_next_work` ("ask @yagni what to work on next"); the escape
+ * hatches are "bootstrap a first ticket and /go" and "review this diff". Pure so
+ * the presenter can render it without a network.
+ */
+export function defaultNextAction() {
+    return {
+        primary: {
+            id: "suggest_next_work",
+            label: "Ask @yagni what to work on next (recommended)",
+            prompt: "What should I work on next?",
+        },
+        escapeHatches: [
+            {
+                id: "bootstrap",
+                label: "Bootstrap: pick a first ticket and /go",
+                prompt: "Pick a good first ticket to bootstrap on, then run /go on it.",
+            },
+            {
+                id: "review",
+                label: "Review this diff",
+                prompt: "Review the current working-tree diff for business fit and correctness.",
+            },
+        ],
+    };
+}
+const parameters = Type.Object({
+    context: Type.Optional(Type.String()),
+});
+/**
+ * Build the `suggest_next_work` tool.
+ *
+ * Asks the YAGNI app for the highest-value next thing to work on, RANKED BY
+ * BUSINESS PRIORITY across open work-items and desk next-moves (not by ticket
+ * order), with the business case for the top pick. Returns a ranked
+ * recommendation plus citations.
+ */
+export function makeSuggestNextWorkTool(opts) {
+    return {
+        name: "suggest_next_work",
+        label: "Suggest next work",
+        description: "Ask YAGNI what to work on next, ranked by BUSINESS priority across open work-items " +
+            "and desk next-moves (not just ticket order), with the business case for the top " +
+            "pick and a concrete first step. Optionally pass a `context` to focus the ranking " +
+            "(e.g. 'revenue this week'). Use when deciding what to pick up.",
+        promptSnippet: "suggest_next_work: ask YAGNI for the highest-value next task, ranked by business priority.",
+        promptGuidelines: [
+            "Call suggest_next_work when the user asks what to do next or when you've finished and need the next task.",
+            "Pass a `context` if the user has a focus (a goal, a deadline, an area) so the ranking reflects it.",
+            "Present the recommendation with its business case; let the user confirm before starting.",
+        ],
+        parameters,
+        async execute(_toolCallId, params, signal, onUpdate, ctx) {
+            onUpdate?.({
+                content: [{ type: "text", text: "Ranking the highest-value next work…" }],
+                details: { citations: [] },
+            });
+            const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/next-action`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${opts.getToken() ?? ""}`,
+                },
+                body: JSON.stringify({ context: params.context, cwd: ctx?.cwd }),
+            }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
+            if (!res.ok) {
+                throw new Error(await friendlyFetchError("suggest_next_work", res));
+            }
+            const data = (await res.json());
+            return {
+                content: [{ type: "text", text: data.suggestion }],
+                details: { citations: data.citations ?? [] },
+            };
+        },
+    };
+}
+//# sourceMappingURL=nextWorkTool.js.map

package/dist/extension/permission.d.ts

@@ -0,0 +1,91 @@
+/**
+ * P3 - interactive permission tiers + plan mode, wired to pi's tool-call gate.
+ *
+ * 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.
+ *   - 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
+ *              session bless (policy.isBlessed) auto-approves an action the user
+ *              already OK'd for this tool + directory, so only novel actions
+ *              prompt. Picking "Yes, and don't ask again for <tool> in <dir>"
+ *              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
+ * 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).
+ *
+ * Plan mode is a full mode, not just a blocker: while active, every agent turn
+ * carries a hidden [PLAN MODE ACTIVE] context message so the model plans
+ * instead of flailing against held writes, and a footer chip shows the mode.
+ * When the mode leaves plan, stale plan-context messages are filtered out of
+ * the context so the model doesn't keep believing it is restricted.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type BlessStore } from "./bless.js";
+export type PermissionMode = "auto" | "plan" | "review";
+/** 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[];
+    /**
+     * 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;
+}
+export declare const DEFAULT_PERMISSION_POLICY: PermissionPolicy;
+/** A pure gate verdict: block outright, ask to confirm, or allow. */
+export interface GateDecision {
+    block: boolean;
+    reason?: string;
+    /** review mode only: the caller should ctx.ui.confirm before allowing. */
+    confirm?: boolean;
+}
+/**
+ * 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
+ * unless a recorded decision blesses them.
+ */
+export declare function decideGate(toolName: string, params: Record<string, unknown>, mode: PermissionMode, policy: PermissionPolicy): GateDecision;
+/** What was blessed with "don't ask again", handed to the capture hook. */
+export interface BlessRememberInfo {
+    tool: string;
+    /** A human-readable directory label (cwd-relative when inside the tree). */
+    dir: string;
+}
+export interface RegisterPermissionDeps {
+    policy?: PermissionPolicy;
+    /** Initial mode (default auto). */
+    mode?: PermissionMode;
+    /** Session bless store factory (needs the cwd from the first tool_call). */
+    makeBlessStore?: (cwd: string) => BlessStore;
+    /**
+     * Called (fire-and-forget) when the user picks "Yes, and don't ask again".
+     * The judgment-capture hook: draft a decision so YAGNI remembers. Fail-soft;
+     * never blocks the approved tool call.
+     */
+    onBlessRemember?: (ctx: ExtensionContext, info: BlessRememberInfo) => void | Promise<void>;
+}
+/** The customType tag on injected plan-mode context (filterable later). */
+export declare const PLAN_CONTEXT_TYPE = "yagni-plan-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.";
+/**
+ * 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.
+ */
+export declare function filterStalePlanContext<T>(messages: T[]): T[];
+/**
+ * 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.
+ */
+export declare function registerPermissionGate(pi: ExtensionAPI, deps?: RegisterPermissionDeps): void;
+//# sourceMappingURL=permission.d.ts.map