@cruxy/cli 0.4.0 → 0.7.0

package/dist/onboarding/steps.js

@@ -0,0 +1,100 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import pc from "picocolors";
+import { CREATE_KEY_URL } from "../constants.js";
+import { loadProjectInstructions } from "../config/index.js";
+/**
+ * The individual onboarding steps (U.6). Each returns a {@link StepResult} and
+ * never throws across its boundary; the secret is read masked and is never echoed
+ * or logged. Rendering is gated on `io.color` so output respects NO_COLOR / pipes.
+ */
+const MAX_KEY_ATTEMPTS = 3;
+const c = (io) => pc.createColors(io.color);
+/**
+ * Acquire and persist a provider key: print the create-key URL, read it masked,
+ * validate it live, and **only then** write it to the credentials store. Loops on
+ * a rejected key (up to 3 tries); a network failure or an empty entry stops.
+ */
+export async function acquireKeyStep(io, deps, provider) {
+    const col = c(io);
+    io.write(`\nYou'll need a Cruxy API key. Create one at ${col.cyan(CREATE_KEY_URL)}\n`);
+    for (let attempt = 1; attempt <= MAX_KEY_ATTEMPTS; attempt++) {
+        io.write(col.bold("Paste your API key: "));
+        const key = (await io.readSecret()).trim();
+        if (key === "") {
+            // Empty / Ctrl-C / EOF — treat as an abort of the mandatory step.
+            return { status: "aborted" };
+        }
+        io.write(col.dim("validating…\n"));
+        const outcome = await deps.validateKey(provider, key);
+        if (outcome === "valid") {
+            deps.writeCredential(provider, key);
+            io.write(`${col.green("✓")} key validated and saved to ~/.cruxy\n`);
+            return { status: "ok", apiKey: key };
+        }
+        if (outcome === "unreachable") {
+            io.write(`${col.red("✗")} couldn't reach the gateway to validate the key.\n`);
+            return {
+                status: "failed",
+                message: "network unreachable — try again with `cruxy login`",
+            };
+        }
+        // invalid
+        const left = MAX_KEY_ATTEMPTS - attempt;
+        io.write(`${col.red("✗")} that key was rejected${left > 0 ? ` (${left} ${left === 1 ? "try" : "tries"} left)` : ""}.\n`);
+    }
+    return { status: "failed", message: "key rejected after 3 attempts" };
+}
+const CRUXY_MD_TEMPLATE = `# Project instructions for cruxy
+
+These notes are loaded into cruxy's context on every run. Keep them short and
+high-signal — conventions, where things live, how to build and test.
+
+## Conventions
+
+- (e.g. language, style, naming rules the agent should follow)
+
+## Build & test
+
+- (e.g. how to install deps, run the app, run the test suite)
+
+## Gotchas
+
+- (e.g. anything non-obvious about this codebase)
+`;
+/**
+ * Offer to scaffold a project `CRUXY.md`. Skipped silently when one already
+ * exists (or `AGENTS.md`); otherwise a `y` confirmation writes the template.
+ */
+export async function scaffoldStep(io, cwd) {
+    const col = c(io);
+    if (loadProjectInstructions(cwd) !== null) {
+        return { status: "skipped" };
+    }
+    io.write(`\nScaffold a ${col.bold("CRUXY.md")} to guide cruxy in this project? ${col.dim("[y/N]")} `);
+    const key = (await io.readKey()).toLowerCase();
+    io.write("\n");
+    if (key !== "y")
+        return { status: "skipped" };
+    const file = join(cwd, "CRUXY.md");
+    writeFileSync(file, CRUXY_MD_TEMPLATE, "utf8");
+    io.write(`${col.green("✓")} wrote ${col.bold("CRUXY.md")}\n`);
+    return { status: "ok" };
+}
+const FIRST_WIN_PROMPT = "Give me a concise 3-sentence summary of what this repository does, based on its README and structure.";
+/**
+ * Offer the first-win demo run. Skipped when no runner is wired or the user
+ * declines; otherwise runs one real task so they see value immediately.
+ */
+export async function firstWinStep(io, deps) {
+    const col = c(io);
+    if (!deps.runTask)
+        return { status: "skipped" };
+    io.write(`\nRun a quick demo now — let cruxy summarize this repo? ${col.dim("[Y/n]")} `);
+    const key = (await io.readKey()).toLowerCase();
+    io.write("\n");
+    if (key === "n")
+        return { status: "skipped" };
+    await deps.runTask(FIRST_WIN_PROMPT);
+    return { status: "ok" };
+}

package/dist/onboarding/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Types for the first-run onboarding flow (U.6). The flow is built from injected
+ * dependencies (validation, persistence, the first-win runner) so every step is
+ * unit-testable with scripted IO and no real network or filesystem.
+ */
+/** Outcome of validating a candidate key against the gateway. */
+export type ValidationOutcome = "valid" | "invalid" | "unreachable";
+/** Why a step ended. `aborted` is reserved for the mandatory key step. */
+export type StepStatus = "ok" | "skipped" | "aborted" | "failed";
+export interface StepResult {
+    readonly status: StepStatus;
+    /** The validated key, when a key step succeeds. */
+    readonly apiKey?: string;
+    /** A short human note (e.g. why a step failed) for the caller to surface. */
+    readonly message?: string;
+}
+/** Persisted onboarding state / completion marker (`~/.cruxy/onboarding.json`). */
+export interface OnboardingState {
+    readonly version: number;
+    /** ISO timestamp; **its presence is the completion marker**. */
+    readonly completedAt?: string;
+    /** Whether a key has been successfully configured at least once. */
+    readonly keyConfigured?: boolean;
+}
+export interface OnboardingResult {
+    /** True once the flow ran to completion and wrote the marker. */
+    readonly completed: boolean;
+    /** True when the user aborted (Ctrl-C / EOF) before a key was saved. */
+    readonly aborted: boolean;
+    /** The key in effect after onboarding, if any. */
+    readonly apiKey?: string;
+}
+/**
+ * IO surface for onboarding — a superset of the approval `PromptIO` with a
+ * **masked** `readSecret()`. Injectable so tests script keystrokes and capture
+ * every write (to assert the secret is never echoed).
+ */
+export interface OnboardingIO {
+    /** Emit prompt text (to stderr in the default impl). */
+    write(text: string): void;
+    /** Read one line in cooked mode; "" on EOF. */
+    readLine(): Promise<string>;
+    /** Read a single keypress (y/n prompts); "" on EOF / Ctrl-C. */
+    readKey(): Promise<string>;
+    /** Read a secret with no echo (each char shown as `*`); "" on Ctrl-C / EOF. */
+    readSecret(): Promise<string>;
+    /** Whether to emit ANSI color. */
+    color: boolean;
+}
+/** Injected dependencies — the seams for testing and for the default wiring. */
+export interface OnboardingDeps {
+    /** Validate a candidate key with one cheap live call. */
+    validateKey(provider: string, apiKey: string): Promise<ValidationOutcome>;
+    /** Persist a validated key to the credentials store (`0600`). */
+    writeCredential(provider: string, key: string): void;
+    /** Resolve the currently effective key (env → store). */
+    resolveApiKey(provider: string): string | undefined;
+    /** Read persisted onboarding state, or `null`. */
+    readState(): OnboardingState | null;
+    /** Persist onboarding state. */
+    writeState(state: OnboardingState): void;
+    /** Run the first-win task; absent ⇒ the first-win step is skipped. */
+    runTask?: (prompt: string) => Promise<void>;
+    /** Project root (for the scaffold step). */
+    cwd: string;
+    /** ISO timestamp source (injectable for deterministic tests). */
+    now: () => string;
+}
+export type OnboardingMode = "first-run" | "login" | "init";
+export interface OnboardingOptions {
+    readonly provider: string;
+    readonly mode: OnboardingMode;
+    /** Run the key step even if a key already resolves (re-key, `cruxy login`). */
+    readonly forceKey?: boolean;
+    /** Offer the first-win demo run (only when there's no real task queued). */
+    readonly offerFirstWin?: boolean;
+    /** Offer to scaffold a project `CRUXY.md` (init). */
+    readonly offerScaffold?: boolean;
+    readonly io: OnboardingIO;
+    readonly deps: OnboardingDeps;
+}

package/dist/onboarding/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for the first-run onboarding flow (U.6). The flow is built from injected
+ * dependencies (validation, persistence, the first-win runner) so every step is
+ * unit-testable with scripted IO and no real network or filesystem.
+ */
+export {};

package/dist/plan/approve.d.ts

@@ -0,0 +1,16 @@
+import type { PromptIO } from "../approval/index.js";
+import type { Plan, PlanDecision } from "./types.js";
+/**
+ * The plan-approval prompt (C.31). Renders the plan and reads a single-key,
+ * 3-way decision, reusing the U.3 {@link PromptIO} (so it's testable with the
+ * same scripted-IO helper and honors NO_COLOR / non-TTY). The copy is explicit
+ * that "allow safe steps" never covers destructive or irreversible actions.
+ *
+ * Default-deny: EOF / Ctrl-C / any unrecognized key → `abort`.
+ */
+export declare function promptPlanDecision(plan: Plan, io: PromptIO): Promise<PlanDecision>;
+/**
+ * After a failed step, ask whether to continue with the remaining steps or abort
+ * the run. Default-deny → abort (the safe choice: stop on failure).
+ */
+export declare function promptContinueAfterFailure(io: PromptIO): Promise<boolean>;

package/dist/plan/approve.js

@@ -0,0 +1,46 @@
+import pc from "picocolors";
+import { renderPlan } from "./render.js";
+/**
+ * The plan-approval prompt (C.31). Renders the plan and reads a single-key,
+ * 3-way decision, reusing the U.3 {@link PromptIO} (so it's testable with the
+ * same scripted-IO helper and honors NO_COLOR / non-TTY). The copy is explicit
+ * that "allow safe steps" never covers destructive or irreversible actions.
+ *
+ * Default-deny: EOF / Ctrl-C / any unrecognized key → `abort`.
+ */
+export async function promptPlanDecision(plan, io) {
+    const c = pc.createColors(io.color);
+    io.write(renderPlan(plan, io.color));
+    io.write("\n\n");
+    io.write(`  ${c.dim("Approving consents to the shape of the work — every action still asks before it runs.")}\n`);
+    io.write(`  ${c.dim("[a] approve ·")} [g] approve ${c.bold("+ allow the read/mutate steps")} this run ${c.dim("(destructive still confirms)")} ${c.dim("· [e] reject & revise")} `);
+    const key = (await io.readKey()).toLowerCase();
+    io.write("\n");
+    switch (key) {
+        case "a":
+            return { kind: "approve" };
+        case "g":
+            return { kind: "approve-grant" };
+        case "e":
+        case "n": {
+            io.write("  what should change about the plan? ");
+            const feedback = (await io.readLine()).trim();
+            // No feedback ⇒ treat as an abort, not an empty revision request.
+            return feedback ? { kind: "revise", feedback } : { kind: "abort" };
+        }
+        default:
+            // Unrecognized key, empty, EOF, Ctrl-C → default-deny.
+            return { kind: "abort" };
+    }
+}
+/**
+ * After a failed step, ask whether to continue with the remaining steps or abort
+ * the run. Default-deny → abort (the safe choice: stop on failure).
+ */
+export async function promptContinueAfterFailure(io) {
+    const c = pc.createColors(io.color);
+    io.write(`  ${c.red("step failed.")} ${c.dim("[c] continue with the remaining steps · [any other key] abort")} `);
+    const key = (await io.readKey()).toLowerCase();
+    io.write("\n");
+    return key === "c";
+}

package/dist/plan/execute.d.ts

@@ -0,0 +1,20 @@
+import type { PromptIO } from "../approval/index.js";
+import type { Plan, PlanExecutionResult, PlanStep } from "./types.js";
+/**
+ * Execute an approved plan step-by-step (C.31): mark each step `running`, run it,
+ * mark `done` / `failed`, rendering live status. Fail-loud — a failed step
+ * **halts** by default (no silent skip); the user chooses continue or abort.
+ *
+ * The per-step runner is injected (`runStep`) so ordering, status, and
+ * halt-on-failure are testable without a real model. In production it drives one
+ * agent turn scoped to the step, with per-action U.3 gating still applying.
+ */
+export interface ExecuteDeps {
+    /**
+     * Run one step. Resolve normally on success; **throw** (ideally a
+     * {@link CruxyError}) to signal failure — that halts the run.
+     */
+    runStep: (step: PlanStep) => Promise<void>;
+    io: PromptIO;
+}
+export declare function executePlan(plan: Plan, deps: ExecuteDeps): Promise<PlanExecutionResult>;

package/dist/plan/execute.js

@@ -0,0 +1,31 @@
+import { CruxyError } from "../errors/index.js";
+import { promptContinueAfterFailure } from "./approve.js";
+import { renderStepStatus } from "./render.js";
+export async function executePlan(plan, deps) {
+    const { runStep, io } = deps;
+    for (const step of plan.steps) {
+        step.status = "running";
+        io.write(renderStepStatus(step, io.color) + "\n");
+        try {
+            await runStep(step);
+            step.status = "done";
+            io.write(renderStepStatus(step, io.color) + "\n");
+        }
+        catch (err) {
+            step.status = "failed";
+            io.write(renderStepStatus(step, io.color) + "\n");
+            // Surface the failure via the U.5 shape when we have it.
+            const detail = err instanceof CruxyError
+                ? `${err.title}${err.cause ? ` — ${err.cause}` : ""}`
+                : err.message;
+            io.write(`  ${detail}\n`);
+            const cont = await promptContinueAfterFailure(io);
+            if (!cont) {
+                return { completed: false, halted: true, failedStepId: step.id };
+            }
+            // User chose to continue despite the failure; move to the next step.
+        }
+    }
+    const completed = plan.steps.every((s) => s.status === "done");
+    return { completed, halted: false };
+}

package/dist/plan/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./submit-plan.js";
+export * from "./policy.js";
+export * from "./render.js";
+export * from "./approve.js";
+export * from "./execute.js";
+export * from "./service.js";

package/dist/plan/index.js

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./submit-plan.js";
+export * from "./policy.js";
+export * from "./render.js";
+export * from "./approve.js";
+export * from "./execute.js";
+export * from "./service.js";

package/dist/plan/policy.d.ts

@@ -0,0 +1,26 @@
+import type { ApprovalDecision, ApprovalPolicy, ApprovalRequest, SessionAllowlist } from "../approval/index.js";
+/**
+ * The execution-phase approval policy for plan mode (C.31). It wraps the base
+ * (interactive) policy and adds exactly one behavior, gated behind the user's
+ * "approve + allow safe steps" choice: auto-allow **grantable mutate** actions
+ * for the rest of the run, recording the real scope in the shared
+ * {@link SessionAllowlist} so U.3's own scoping (`scopeCovers`) governs reuse.
+ *
+ * What it deliberately does NOT do — the two-tier boundary:
+ *   • **destructive** actions always fall through to the base policy (prompt);
+ *   • **ungrantable** actions (`scope:"none"`) always fall through (prompt),
+ *     even if the tier is `mutate` — because `SessionAllowlist.grant` is a no-op
+ *     on `none`, an ungrantable action can never be pre-approved.
+ *
+ * So approving a plan (even with "allow safe steps") never consents to a
+ * destructive or irreversible action; those re-confirm at execution time.
+ */
+export declare class PlanExecutionPolicy implements ApprovalPolicy {
+    private readonly allowlist;
+    private readonly base;
+    private safeStepGrants;
+    constructor(allowlist: SessionAllowlist, base: ApprovalPolicy);
+    /** Turn on auto-allow for safe (grantable mutate) steps — the `[g]` choice. */
+    enableSafeStepGrants(): void;
+    decide(request: ApprovalRequest): Promise<ApprovalDecision>;
+}

package/dist/plan/policy.js

@@ -0,0 +1,45 @@
+/**
+ * The execution-phase approval policy for plan mode (C.31). It wraps the base
+ * (interactive) policy and adds exactly one behavior, gated behind the user's
+ * "approve + allow safe steps" choice: auto-allow **grantable mutate** actions
+ * for the rest of the run, recording the real scope in the shared
+ * {@link SessionAllowlist} so U.3's own scoping (`scopeCovers`) governs reuse.
+ *
+ * What it deliberately does NOT do — the two-tier boundary:
+ *   • **destructive** actions always fall through to the base policy (prompt);
+ *   • **ungrantable** actions (`scope:"none"`) always fall through (prompt),
+ *     even if the tier is `mutate` — because `SessionAllowlist.grant` is a no-op
+ *     on `none`, an ungrantable action can never be pre-approved.
+ *
+ * So approving a plan (even with "allow safe steps") never consents to a
+ * destructive or irreversible action; those re-confirm at execution time.
+ */
+export class PlanExecutionPolicy {
+    allowlist;
+    base;
+    safeStepGrants = false;
+    constructor(allowlist, base) {
+        this.allowlist = allowlist;
+        this.base = base;
+    }
+    /** Turn on auto-allow for safe (grantable mutate) steps — the `[g]` choice. */
+    enableSafeStepGrants() {
+        this.safeStepGrants = true;
+    }
+    async decide(request) {
+        // Already covered by a prior session grant (scoped, tier-keyed) → allow.
+        if (this.allowlist.allows(request))
+            return { allow: true };
+        // The one plan-mode shortcut: a grantable mutate action, pre-consented by
+        // the "allow safe steps" choice. Record its concrete scope, then allow.
+        if (this.safeStepGrants &&
+            request.tier === "mutate" &&
+            request.scope.kind !== "none") {
+            this.allowlist.grant(request);
+            return { allow: true };
+        }
+        // Everything else (destructive, ungrantable, or a non-consented mutate) is
+        // decided by the base policy — i.e. the user is prompted.
+        return this.base.decide(request);
+    }
+}

package/dist/plan/render.d.ts

@@ -0,0 +1,5 @@
+import type { Plan, PlanStep } from "./types.js";
+/** Render the whole plan as a block (header + one line per step + rationale). */
+export declare function renderPlan(plan: Plan, color: boolean): string;
+/** A one-line status update for a single step (used during execution). */
+export declare function renderStepStatus(step: PlanStep, color: boolean): string;

package/dist/plan/render.js

@@ -0,0 +1,47 @@
+import pc from "picocolors";
+/** Status glyph, colored when enabled. */
+function statusMark(status, c) {
+    switch (status) {
+        case "pending":
+            return c.dim("○");
+        case "running":
+            return c.cyan("◐");
+        case "done":
+            return c.green("✓");
+        case "failed":
+            return c.red("✗");
+    }
+}
+/** A short tag for the step's risk estimate. */
+function kindTag(kind, c) {
+    switch (kind) {
+        case "read":
+            return c.dim("[read]");
+        case "mutate":
+            return c.yellow("[mutate]");
+        case "destructive":
+            return c.red(c.bold("[destructive]"));
+    }
+}
+function renderStep(step, c) {
+    const head = `  ${statusMark(step.status, c)} ${c.bold(step.id + ".")} ${step.title} ${kindTag(step.kind, c)}`;
+    const why = step.rationale.trim()
+        ? `\n      ${c.dim(step.rationale.trim())}`
+        : "";
+    return head + why;
+}
+/** Render the whole plan as a block (header + one line per step + rationale). */
+export function renderPlan(plan, color) {
+    const c = pc.createColors(color);
+    const lines = [
+        c.bold(`Plan — ${plan.steps.length} step${plan.steps.length === 1 ? "" : "s"}:`),
+    ];
+    for (const step of plan.steps)
+        lines.push(renderStep(step, c));
+    return lines.join("\n");
+}
+/** A one-line status update for a single step (used during execution). */
+export function renderStepStatus(step, color) {
+    const c = pc.createColors(color);
+    return `${statusMark(step.status, c)} ${c.bold(step.id + ".")} ${step.title}`;
+}

package/dist/plan/service.d.ts

@@ -0,0 +1,39 @@
+import type { Message, Provider } from "@cruxy/sdk";
+import type { CruxyConfig } from "../config/index.js";
+import type { PromptIO } from "../approval/index.js";
+import { ToolRegistry, type ToolContext } from "../tools/index.js";
+import { type AgentResult } from "../agent/loop.js";
+import { PlanExecutionPolicy } from "./policy.js";
+/**
+ * Orchestrates a plan-mode turn (C.31): propose → approve/revise (capped) →
+ * execute, all on the ordinary agent loop. The propose phase runs with a
+ * read-only + `submit_plan` registry so the agent cannot act before approval;
+ * execution runs with the full registry, one step at a time, per-action U.3
+ * gating intact.
+ */
+/** Default cap on plan revisions before failing loud. */
+export declare const MAX_PLAN_REVISIONS = 3;
+export interface PlanSessionArgs {
+    provider: Provider;
+    config: CruxyConfig;
+    ctx: ToolContext;
+    /** The full (execution-phase) tool registry. */
+    execRegistry: ToolRegistry;
+    /** The plan-mode approval policy (flipped on the `[g]` choice). */
+    planPolicy: PlanExecutionPolicy;
+    /** Prompt IO for plan approval + status (reuses U.3's PromptIO). */
+    io: PromptIO;
+    /** Whether we can actually prompt (a TTY). Non-interactive → fail loud. */
+    interactive: boolean;
+    /** The running conversation (with the user turn already appended). */
+    messages: Message[];
+    git?: {
+        branch: string;
+        dirty: boolean;
+    } | null;
+    projectInstructions?: string | null;
+    onText?: (delta: string) => void;
+    /** Revision cap (defaults to {@link MAX_PLAN_REVISIONS}). */
+    maxRevisions?: number;
+}
+export declare function runPlanSession(args: PlanSessionArgs): Promise<AgentResult>;

package/dist/plan/service.js

@@ -0,0 +1,118 @@
+import { planApprovalRequired, planInvalid, planRevisionLimit, } from "../errors/index.js";
+import { ToolRegistry } from "../tools/index.js";
+import { runAgent } from "../agent/loop.js";
+import { promptPlanDecision } from "./approve.js";
+import { executePlan } from "./execute.js";
+import { makeSubmitPlanTool } from "./submit-plan.js";
+/**
+ * Orchestrates a plan-mode turn (C.31): propose → approve/revise (capped) →
+ * execute, all on the ordinary agent loop. The propose phase runs with a
+ * read-only + `submit_plan` registry so the agent cannot act before approval;
+ * execution runs with the full registry, one step at a time, per-action U.3
+ * gating intact.
+ */
+/** Default cap on plan revisions before failing loud. */
+export const MAX_PLAN_REVISIONS = 3;
+/** Tools available during the propose phase (read-only) — plus `submit_plan`. */
+const PLAN_PHASE_TOOLS = new Set([
+    "list_files",
+    "read_file",
+    "glob",
+    "grep_files",
+    "git_status",
+    "search_codebase",
+    "list_skills",
+    "load_skill",
+]);
+/** Build the read-only + `submit_plan` registry for the propose phase. */
+function buildPlanPhaseRegistry(execRegistry, holder) {
+    const registry = new ToolRegistry();
+    for (const tool of execRegistry.list()) {
+        if (PLAN_PHASE_TOOLS.has(tool.name))
+            registry.register(tool);
+    }
+    registry.register(makeSubmitPlanTool(holder));
+    return registry;
+}
+export async function runPlanSession(args) {
+    // Fail loud before proposing — a plan is never auto-approved (U.3 discipline).
+    if (!args.interactive)
+        throw planApprovalRequired();
+    const maxRevisions = args.maxRevisions ?? MAX_PLAN_REVISIONS;
+    const usage = { input_tokens: 0, output_tokens: 0 };
+    let messages = args.messages;
+    let iterations = 0;
+    const accumulate = (r) => {
+        messages = r.messages;
+        usage.input_tokens += r.usage.input_tokens;
+        usage.output_tokens += r.usage.output_tokens;
+        iterations += r.iterations;
+    };
+    const finish = () => ({
+        messages,
+        iterations,
+        stop: "completed",
+        usage,
+    });
+    // ── propose / revise loop (capped) ─────────────────────────────────────────
+    let feedback = null;
+    for (let rev = 0; rev <= maxRevisions; rev++) {
+        if (feedback !== null) {
+            messages.push({
+                role: "user",
+                content: `Revise the plan based on this feedback, then call submit_plan again with the updated steps:\n\n${feedback}`,
+            });
+        }
+        const holder = { plan: null };
+        const planRegistry = buildPlanPhaseRegistry(args.execRegistry, holder);
+        accumulate(await runAgent({
+            messages,
+            provider: args.provider,
+            registry: planRegistry,
+            config: args.config,
+            ctx: args.ctx,
+            git: args.git,
+            projectInstructions: args.projectInstructions,
+            onText: args.onText,
+            planMode: true,
+        }));
+        if (!holder.plan) {
+            throw planInvalid("the model ended its turn without calling submit_plan");
+        }
+        const plan = holder.plan;
+        const decision = await promptPlanDecision(plan, args.io);
+        if (decision.kind === "abort") {
+            args.io.write("plan aborted — nothing was executed.\n");
+            return finish();
+        }
+        if (decision.kind !== "revise") {
+            if (decision.kind === "approve-grant") {
+                args.planPolicy.enableSafeStepGrants();
+            }
+            // Execute step-by-step, driving one agent turn per step against the full
+            // registry. Each step's actions still pass through the U.3 gate.
+            const runStep = async (step) => {
+                messages.push({
+                    role: "user",
+                    content: `The plan is approved. Do ONLY step ${step.id}: ${step.title}. ${step.rationale} ` +
+                        "Do not start any other step. When this step is complete, stop.",
+                });
+                accumulate(await runAgent({
+                    messages,
+                    provider: args.provider,
+                    registry: args.execRegistry,
+                    config: args.config,
+                    ctx: args.ctx,
+                    git: args.git,
+                    projectInstructions: args.projectInstructions,
+                    onText: args.onText,
+                }));
+            };
+            await executePlan(plan, { runStep, io: args.io });
+            return finish();
+        }
+        feedback = decision.feedback;
+    }
+    // Rejected past the cap without converging.
+    throw planRevisionLimit(maxRevisions);
+}

package/dist/plan/submit-plan.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import type { Tool } from "../tools/index.js";
+import type { PlanHolder } from "./types.js";
+declare const parameters: z.ZodObject<{
+    steps: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        rationale: z.ZodString;
+        kind: z.ZodEnum<["read", "mutate", "destructive"]>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        kind: "read" | "mutate" | "destructive";
+        rationale: string;
+    }, {
+        title: string;
+        kind: "read" | "mutate" | "destructive";
+        rationale: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    steps: {
+        title: string;
+        kind: "read" | "mutate" | "destructive";
+        rationale: string;
+    }[];
+}, {
+    steps: {
+        title: string;
+        kind: "read" | "mutate" | "destructive";
+        rationale: string;
+    }[];
+}>;
+/** Build a `submit_plan` tool bound to `holder`, which captures the last plan. */
+export declare function makeSubmitPlanTool(holder: PlanHolder): Tool<typeof parameters>;
+export {};