howtofixcli 0.7.24 → 0.7.26

package/dist/permissions.js

@@ -0,0 +1,298 @@
+import { noteToolCall, repeatRefusal } from "./loop-guard.js";
+import { isReadOnlyCommand } from "./read-only-commands.js";
+export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
+export const APPROVAL_LABELS = {
+    suggest: "suggest: ask before every edit and command",
+    "auto-edit": "auto-edit: edits run, commands ask",
+    "full-auto": "full-auto: nothing asks",
+};
+export function isApprovalMode(value) {
+    return APPROVAL_MODES.includes(value);
+}
+/** Ordering of capability tiers, least to most privileged. */
+export const TIER_RANK = { read: 0, write: 1, exec: 2 };
+/** The highest tier a mode runs without asking. */
+export const MODE_MAX_TIER = {
+    suggest: "read",
+    "auto-edit": "write",
+    "full-auto": "exec",
+};
+/**
+ * The SDK's built-in tools, by tier. It declares no approval metadata of its own, so
+ * the built-ins have to be listed here; everything else falls back to a tier
+ * chosen by {@link resolveTier}.
+ */
+const BUILTIN_TIERS = {
+    read: "read",
+    grep: "read",
+    find: "read",
+    ls: "read",
+    think: "read",
+    ask: "read",
+    todo: "read",
+    context: "read",
+    // Lookup only: the URL policy in `web.ts` refuses private targets before the
+    // network is touched, so neither tool prompts in `suggest`.
+    web_search: "read",
+    web_fetch: "read",
+    // A language-server query reads a file and answers; it has no write verb.
+    lsp: "read",
+    quality: "read",
+    // A workflow runs agents, which run tools — including shell. Its own tier is
+    // the strongest one so a run cannot start in a mode that would silently allow
+    // what the child agents then do.
+    workflow: "exec",
+    // The goal tool only writes session state; it runs nothing.
+    goal: "read",
+    // Plan mode tools only flip session state and read the plan file. The real
+    // enforcement is the plan gate, which is registered ahead of this one.
+    enter_plan_mode: "read",
+    exit_plan_mode: "read",
+    edit: "write",
+    write: "write",
+    bash: "exec",
+    powershell: "exec",
+    task: "exec",
+};
+/**
+ * Tiers for the tools this project registers as custom tools. `task` spawns
+ * headless agents, so it sits at `exec`; `think` and `ask` only produce text.
+ */
+export function resolveTier(toolName) {
+    const builtin = BUILTIN_TIERS[toolName];
+    if (builtin)
+        return builtin;
+    // An MCP server tool can do anything its server exposes, and its own
+    // annotations are unverified. Every MCP tool is pinned to `write`; a
+    // tool that turns out to be read-only costs one extra prompt.
+    if (toolName.startsWith("mcp__"))
+        return "write";
+    // Safe default for unknown custom tools: `exec`.
+    return "exec";
+}
+/**
+ * Commands that only read. They never ask, in any mode.
+ *
+ * The decision lives in `read-only-commands.ts`, which ports Claude Code's
+ * classifier: a compound command is read-only only if *every* segment is, and a
+ * segment only if its flags are all in a per-subcommand allowlist. The old
+ * single regex got both directions wrong — it prompted on `ls | head`, which is
+ * how you read a codebase, and it auto-allowed `git branch -D`.
+ */
+export { isReadOnlyCommand } from "./read-only-commands.js";
+/**
+ * Commands that are refused in every mode, including `full-auto`. These are the
+ * patterns treated as "critical": an approval prompt is the wrong
+ * answer when the command is a fork bomb or a wipe of the root filesystem.
+ */
+const CRITICAL_COMMANDS = [
+    { pattern: /\brm\s+(?:-[a-zA-Z]+\s+)*(?:\/|\/\*|~|\$HOME)(?:\s|$)/, reason: "recursive delete of the filesystem root or home" },
+    { pattern: /\bmkfs(?:\.[a-z0-9]+)?\b/, reason: "filesystem format" },
+    { pattern: /\bdd\b[^|;]*\bof=\/dev\/(?:sd|nvme|hd|vd)/, reason: "raw write to a block device" },
+    { pattern: /:\s*\(\s*\)\s*\{.*\}\s*;\s*:/, reason: "fork bomb" },
+    { pattern: />\s*\/etc\/(?:passwd|shadow|sudoers)/, reason: "overwrite of a system account file" },
+    { pattern: /\b(?:shutdown|reboot|halt|poweroff)\b/, reason: "host shutdown" },
+];
+/**
+ * The critical pattern a command matches, if any.
+ *
+ * Only the **command being run** is matched, never the whole line. A line-wide
+ * regex made every mention of the word fatal: `grep -rn shutdown src/`,
+ * `cat reboot-notes.md`, `git log --grep=reboot` and `echo "reboot later"` were
+ * all refused as "host shutdown", so an agent could not even search its own
+ * codebase for the word. The list exists to stop the action, not the noun, so
+ * the head of the command is the only part that counts.
+ *
+ * `sudo shutdown` and `env reboot` are still caught: any leading word that is
+ * itself a launcher (`sudo`, `env`, `nohup`, `time`, `exec`, …) is skipped
+ * before the match, so the check reads the command that will actually run.
+ */
+const LAUNCHER_WORDS = new Set(["sudo", "doas", "env", "nohup", "time", "exec", "command", "nice", "setsid", "stdbuf"]);
+/** Launcher flags that consume the token after them, so `sudo -u root shutdown`
+ *  does not leave `root` looking like the command. */
+const LAUNCHER_VALUE_FLAGS = new Set(["-u", "-g", "-p", "-C", "-S", "-U", "--user", "--group", "--prompt", "--close-from", "--chdir", "--setenv", "--unset"]);
+export function criticalCommand(command) {
+    // Quote-aware tokenization: `grep -rn shutdown src/` splits into words, and
+    // the argument is simply not the first one.
+    const words = (command.match(/"[^"]*"|'[^']*'|\S+/g) ?? []).map((word) => word.replace(/^['"]|['"]$/g, ""));
+    let head = 0;
+    // Skip leading `VAR=value` assignments, then the launcher prefix — both the
+    // launcher word and its own flags, so `sudo -n reboot` still reads as
+    // `reboot`. A value-taking launcher flag takes the next token with it.
+    while (head < words.length) {
+        const current = words[head] ?? "";
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(current) || LAUNCHER_WORDS.has(current)) {
+            head++;
+            continue;
+        }
+        if (current.startsWith("-")) {
+            head += LAUNCHER_VALUE_FLAGS.has(current) ? 2 : 1;
+            continue;
+        }
+        break;
+    }
+    const token = words[head];
+    if (token === undefined)
+        return undefined;
+    // The command word, without its directory: `/sbin/shutdown` is `shutdown`.
+    const word = token.split("/").pop() ?? token;
+    // `rm` is only critical when it is recursive *and* aimed at the root, home or
+    // a wildcard — `rm -rf build/` and `rm -rf /tmp/x` are ordinary work.
+    if (word === "rm") {
+        const args = words.slice(head + 1);
+        const recursive = args.some((arg) => /^-[a-zA-Z]*r[a-zA-Z]*$/i.test(arg) || arg === "--recursive");
+        const target = args.find((arg) => !arg.startsWith("-"));
+        if (recursive && (target === undefined || /^(?:\/|\/\*|~|~\/\*|\$HOME|\$HOME\/\*|\*)$/.test(target))) {
+            return "recursive delete of the filesystem root or home";
+        }
+        return undefined;
+    }
+    // `dd … of=/dev/sdX` is the raw-device write; a bare `dd` is not.
+    if (word === "dd") {
+        return words.slice(head + 1).some((arg) => /^of=\/dev\/(?:sd|nvme|hd|vd)/.test(arg)) ? "raw write to a block device" : undefined;
+    }
+    if (/^mkfs(?:\.[a-z0-9]+)?$/.test(word))
+        return "filesystem format";
+    if (/:\(\)\s*\{.*\}\s*;:/.test(command))
+        return "fork bomb";
+    if (/^(?:shutdown|reboot|halt|poweroff)$/.test(word))
+        return "host shutdown";
+    // The redirect target is not the command word, so it is checked separately.
+    if (/>\s*\/etc\/(?:passwd|shadow|sudoers)/.test(command))
+        return "overwrite of a system account file";
+    return undefined;
+}
+let currentMode = "full-auto";
+let currentPrompt = async () => false;
+/**
+ * When set, a tool call runs without consulting the mode, the critical-command
+ * list, or the loop guard. `--dangerously-skip-permissions` sets it for print
+ * mode, where a refusal has no human to answer it.
+ *
+ * What it does NOT turn off: an extension's own `tool_call` handler (this gate
+ * is one of several), and the provider's own limits. It is the same trade
+ * Claude Code makes with `--dangerously-skip-permissions`, and it is named the
+ * same way on purpose — the name is the warning.
+ */
+let dangerousBypass = false;
+/** Change the policy. Read at tool-call time, so it applies immediately. */
+export function setApprovalMode(mode) {
+    currentMode = mode;
+}
+export function getApprovalMode() {
+    return currentMode;
+}
+export function setDangerousBypass(on) {
+    dangerousBypass = on;
+}
+export function isDangerousBypass() {
+    return dangerousBypass;
+}
+/** Install the dialog used when a call needs approval. Print mode leaves the deny default. */
+export function setApprovalPrompt(prompt) {
+    currentPrompt = prompt;
+}
+/**
+ * The whole policy in one place, so it can be exercised without a session.
+ *
+ * `full-auto` runs everything except a critical command; `auto-edit` adds the
+ * `write` tier (file edits); `suggest` runs only `read`. Read-only shell
+ * commands run in every mode, as the README promises.
+ */
+export function decideToolCall(mode, toolName, input) {
+    // The bypass short-circuits the whole policy, including the critical list:
+    // that is the point of the flag, and it is why the flag is named the way it is.
+    if (dangerousBypass)
+        return { action: "run" };
+    const command = typeof input?.command === "string" ? input.command : "";
+    if (toolName === "bash" || toolName === "powershell") {
+        const critical = criticalCommand(command);
+        if (critical)
+            return { action: "deny", reason: `Refused in every mode: ${critical}.` };
+        if (isReadOnlyCommand(command))
+            return { action: "run" };
+    }
+    const tier = resolveTier(toolName);
+    if (TIER_RANK[tier] <= TIER_RANK[MODE_MAX_TIER[mode]])
+        return { action: "run" };
+    return { action: "prompt", reason: `this is a ${tier}-tier tool` };
+}
+/** Human summary of a tool call, used in the approval dialog. */
+export function describeToolCall(toolName, input) {
+    if (input && typeof input === "object") {
+        const record = input;
+        if ((toolName === "bash" || toolName === "powershell") && typeof record.command === "string")
+            return record.command;
+        if ((toolName === "edit" || toolName === "write") && typeof record.path === "string") {
+            const edits = Array.isArray(record.edits) ? ` (${record.edits.length} edits)` : "";
+            return `${record.path}${edits}`;
+        }
+        // A tool we do not know by name (MCP, another extension): show its
+        // arguments, so the choice is informed instead of a bare tool name.
+        try {
+            const args = JSON.stringify(record);
+            if (args && args !== "{}")
+                return args.length > 300 ? `${args.slice(0, 297)}...` : args;
+        }
+        catch {
+            // Unserializable input falls through to the tool name.
+        }
+    }
+    return toolName;
+}
+/**
+ * The approval prompt body: the tool, where it came
+ * from, why it needs approval, then the concrete arguments.
+ */
+export function formatApprovalPrompt(toolName, input, reason) {
+    const lines = [`Allow tool: ${toolName}`];
+    if (toolName.startsWith("mcp__"))
+        lines.push("Origin: MCP server tool");
+    lines.push(`Reason: ${reason}`);
+    const details = describeToolCall(toolName, input);
+    if (details !== toolName)
+        lines.push(details);
+    return lines.join("\n");
+}
+/**
+ * Gate tool calls behind user approval, by declared capability tier. With no
+ * interactive prompt installed (print mode), anything above the mode's tier is
+ * denied; a critical command is denied outright.
+ *
+ * The loop guard runs before the approval check, because a call the model has
+ * already issued identically three times needs no human decision — approving it
+ * again would just spend the budget on the same non-progress. It blocks in every
+ * mode, `full-auto` included.
+ */
+export function createPermissionExtension(options = {}) {
+    // A subagent has no UI, so it must never reach for the shared approval dialog:
+    // the dialog belongs to the parent's screen, and a child that awaits it while
+    // the parent is mid-turn deadlocks both — measured, the child's prompt never
+    // even reached the provider. A non-interactive gate decides with the same
+    // policy and denies what it cannot run, which is the fail-closed behaviour the
+    // parent's print mode already has.
+    return (hxf) => {
+        hxf.on("tool_call", async (event) => {
+            // The bypass skips the loop guard too: it exists to stop a model spinning
+            // on a call a human would have to approve, and there is no human here.
+            if (dangerousBypass)
+                return undefined;
+            const repeat = noteToolCall(event.toolName, event.input);
+            if (repeat)
+                return { block: true, reason: repeatRefusal(event.toolName, repeat.repeats) };
+            const mode = currentMode;
+            const decision = decideToolCall(mode, event.toolName, event.input);
+            if (decision.action === "run")
+                return undefined;
+            if (decision.action === "deny")
+                return { block: true, reason: decision.reason };
+            if (options.interactive === false) {
+                return { block: true, reason: `Blocked: this is a ${resolveTier(event.toolName)}-tier tool and no UI can approve it here (approval mode: ${mode}).` };
+            }
+            const allowed = await currentPrompt(`${event.toolName} wants to run`, formatApprovalPrompt(event.toolName, event.input, decision.reason));
+            if (allowed)
+                return undefined;
+            return { block: true, reason: `Blocked by the user (approval mode: ${mode}).` };
+        });
+    };
+}

package/dist/plan-mode.js

@@ -0,0 +1,363 @@
+/**
+ * Plan mode: a read-only planning phase, ported from xAI's Grok Build.
+ *
+ * Why this exists: planning is a phase, not a message. Both Grok Build
+ * (`crates/codegen/xai-grok-shell/src/session/plan_mode.rs`) and Claude Code
+ * ship it as a first-class mode, and the reason is the same in both — an agent
+ * that starts editing before the approach is agreed wastes the whole task when
+ * the approach is wrong. The mode is the harness enforcing "design first",
+ * rather than asking the model nicely in a prompt it can forget after a
+ * compaction.
+ *
+ * Three properties are load-bearing, and all three are copied from the
+ * reference rather than invented:
+ *
+ *   1. **Plan mode blocks edits to everything except the plan file, in every
+ *      approval mode.** Grok documents this explicitly: "This holds in every
+ *      permission mode, including always-approve." The edit gate is registered
+ *      *before* the approval gate, and the SDK returns on the first `block`, so
+ *      `full-auto` cannot punch through it.
+ *   2. **The plan is read from disk, not from the model.** `exit_plan_mode`
+ *      takes no plan content as input; it reads the plan file and presents what
+ *      is actually on disk. Grok's own comment is the justification: it prevents
+ *      "divergence between the model's in-context plan and the actual file
+ *      content" — the user reviews what will be built, not a summary of it.
+ *   3. **The state machine is pure.** Every transition is a function over a
+ *      small snapshot, so the whole lifecycle is testable with no session, no
+ *      model, and no terminal. Grok's tracker is built the same way.
+ *
+ * One deliberate divergence from the reference: Grok alternates between a full
+ * reminder and a one-line sparse one, to save tokens. That is a cache hazard
+ * here. Our reminder is appended to the system message, which is the cacheable
+ * prefix of every request, so alternating the text would invalidate the prefix
+ * on every other turn — the same class of mistake that cost Claude Code 10.2% of
+ * fleet-wide cache-creation tokens. A single stable block costs ~80 tokens a
+ * turn and never invalidates anything, so the alternation is dropped and the
+ * state machine carries only what it needs.
+ *
+ * Honest limits, both inherited from the reference and stated here so nobody
+ * assumes more isolation than exists:
+ *   - Shell commands are not inspected for writes. Plan mode blocks the edit
+ *     tools, not `bash > file`. Grok documents the same gap.
+ *   - A subagent starts with its own tracker (inactive), so a write-capable
+ *     subagent is not covered by the parent's gate. Grok documents this too.
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { defineTool } from "@netrodev/hxf-coding-agent";
+import { Type } from "typebox";
+import { writeFileAtomicSync } from "./fs-atomic.js";
+export function emptyPlanSnapshot() {
+    return { state: "inactive", wasActive: false };
+}
+/** Collapse transient state, the way a restore must. */
+export function restorePlanSnapshot(snapshot) {
+    if (!snapshot)
+        return emptyPlanSnapshot();
+    if (snapshot.state === "pending")
+        return { ...snapshot, state: "inactive" };
+    return { ...snapshot };
+}
+/** User toggled the mode on. */
+export function enterPending(snapshot) {
+    if (snapshot.state !== "inactive")
+        return snapshot;
+    return { ...snapshot, state: "pending" };
+}
+/** The first prompt while pending activates the mode. */
+export function activate(snapshot) {
+    if (snapshot.state !== "pending")
+        return snapshot;
+    return { state: "active", wasActive: true };
+}
+/** The agent asked to enter and the user approved: straight to active. */
+export function activateFromTool(snapshot) {
+    if (snapshot.state !== "inactive")
+        return snapshot;
+    return { state: "active", wasActive: true };
+}
+/** The plan was approved, so the mode ends. */
+export function deactivateApproved(snapshot) {
+    if (snapshot.state !== "active")
+        return snapshot;
+    return { ...snapshot, state: "inactive" };
+}
+/** The user toggled the mode off. */
+export function userExit(snapshot) {
+    if (snapshot.state === "inactive")
+        return snapshot;
+    return { ...snapshot, state: "inactive" };
+}
+export function isPlanActive(snapshot) {
+    return snapshot.state === "active";
+}
+/** Whether a write target is the plan file. Exact match, as in the reference. */
+export function isPlanFileWrite(target, planFile) {
+    return target === planFile;
+}
+/**
+ * The per-turn reminder, appended to the system message.
+ *
+ * Stable on purpose: it changes only when the plan file gains its first content,
+ * which happens once per planning session. Nothing volatile may enter it, or the
+ * cached prefix is lost on every turn.
+ */
+export function planReminder(planFile, hasContent) {
+    const where = hasContent ? `A plan file exists at ${planFile}. Read it and refine it with the \`edit\` tool.` : `No plan is written yet. Write yours to ${planFile} with the \`write\` tool.`;
+    return [
+        "<plan-mode>",
+        "Plan mode is active. Do not make any edits or writes to the system.",
+        where,
+        "That file is the only path you may edit.",
+        "Explore first: read, search, and run read-only commands until the approach is clear.",
+        "End your turn with either `ask` to clarify a requirement, or `exit_plan_mode` to present",
+        "the plan for approval. Do not start implementing before the plan is approved.",
+        "</plan-mode>",
+    ].join("\n");
+}
+/** What the model is told when it tries to edit outside the plan file. */
+export function planEditRefusal(planFile) {
+    return `Rejected: file edits are not allowed in plan mode. The only editable file is the plan file (${planFile}). Present the plan with exit_plan_mode first.`;
+}
+/** The plan file for the current session, or undefined before one is known. */
+let planFilePath;
+let snapshot = emptyPlanSnapshot();
+let sessionDir;
+export function currentPlanSnapshot() {
+    return snapshot;
+}
+export function currentPlanFile() {
+    return planFilePath;
+}
+export function planActive() {
+    return isPlanActive(snapshot);
+}
+/** Read the plan from disk. Empty or missing reads as absent. */
+export function readPlan() {
+    if (!planFilePath || !existsSync(planFilePath))
+        return undefined;
+    try {
+        const text = readFileSync(planFilePath, "utf8");
+        return text.trim() ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function planHasContent() {
+    return readPlan() !== undefined;
+}
+/** The short form for the HUD. Empty when the mode is off. */
+export function planSegment() {
+    if (snapshot.state === "inactive")
+        return "";
+    if (snapshot.state === "pending")
+        return "plan pending";
+    return planHasContent() ? "plan ● ready" : "plan ● planning";
+}
+/** Path of the small state file that survives a resume, beside the plan. */
+function statePath() {
+    return sessionDir ? join(sessionDir, "plan_mode.json") : undefined;
+}
+function persistSnapshot() {
+    const path = statePath();
+    if (!path)
+        return;
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileAtomicSync(path, JSON.stringify(snapshot));
+    }
+    catch {
+        // A session directory that cannot be written is not worth failing a turn
+        // over: the mode still works for this process.
+    }
+}
+function loadSnapshot() {
+    const path = statePath();
+    if (!path || !existsSync(path))
+        return emptyPlanSnapshot();
+    try {
+        return restorePlanSnapshot(JSON.parse(readFileSync(path, "utf8")));
+    }
+    catch {
+        return emptyPlanSnapshot();
+    }
+}
+/**
+ * Point the mode at this session's directory and restore what a previous run
+ * left there. Plan mode is session state, so a resume must not silently drop it.
+ */
+export function openPlanSession(dir) {
+    sessionDir = dir;
+    planFilePath = join(dir, "plan.md");
+    snapshot = loadSnapshot();
+}
+/** Apply a transition and persist it. Every mutation goes through here. */
+export function transition(next) {
+    snapshot = next;
+    persistSnapshot();
+    return snapshot;
+}
+/** Test seam: forget the session, the mode, and the file. Test-only; see check-wiring.mjs. */
+export function resetPlanMode() {
+    planFilePath = undefined;
+    sessionDir = undefined;
+    snapshot = emptyPlanSnapshot();
+}
+/**
+ * The edit gate. Registered before the approval gate, and it blocks in every
+ * approval mode — the SDK returns on the first `block`, so `full-auto` cannot
+ * override it. `bash` is deliberately not inspected: see the module comment.
+ */
+export function createPlanGateExtension() {
+    return (hxf) => {
+        hxf.on("tool_call", async (event) => {
+            if (!isPlanActive(snapshot))
+                return undefined;
+            if (event.toolName !== "edit" && event.toolName !== "write")
+                return undefined;
+            const path = event.input?.path;
+            if (typeof path !== "string")
+                return undefined;
+            if (!planFilePath || isPlanFileWrite(path, planFilePath))
+                return undefined;
+            return { block: true, reason: planEditRefusal(planFilePath) };
+        });
+    };
+}
+/**
+ * Keeps the reminder in front of the model, and the mode alive across a resume.
+ *
+ * The reminder is appended to the system message, following the pattern the
+ * shared-notes extension already proved in this codebase: it is the leading
+ * message the provider reads the prompt from, and it is the only place a
+ * per-request instruction can live without becoming a fake user turn.
+ */
+export function createPlanPromptExtension() {
+    return (hxf) => {
+        hxf.on("session_start", async (_event, ctx) => {
+            openPlanSession(ctx.sessionManager.getSessionDir());
+        });
+        // The first prompt after `/plan` is what activates the mode: the model must
+        // not be told about plan mode until it is about to run under it.
+        hxf.on("before_agent_start", async () => {
+            if (snapshot.state === "pending")
+                transition(activate(snapshot));
+        });
+        hxf.on("context_with_system", async (event) => {
+            if (!isPlanActive(snapshot) || !planFilePath)
+                return undefined;
+            const head = event.messages[0];
+            if (!head || head.role !== "system")
+                return undefined;
+            const reminder = planReminder(planFilePath, planHasContent());
+            const combined = `${typeof head.content === "string" ? head.content : ""}\n\n${reminder}`;
+            const messages = event.messages.map((message) => (message === head ? { ...head, content: combined } : message));
+            return { messages };
+        });
+    };
+}
+/** Longest plan the exit tool will present, so a runaway file cannot flood the UI. */
+export const MAX_PLAN_CHARS = 20_000;
+function ensurePlanFile() {
+    if (!planFilePath)
+        return undefined;
+    try {
+        mkdirSync(dirname(planFilePath), { recursive: true });
+        if (!existsSync(planFilePath))
+            writeFileAtomicSync(planFilePath, "");
+    }
+    catch {
+        return undefined;
+    }
+    return planFilePath;
+}
+export const enterPlanModeTool = defineTool({
+    name: "enter_plan_mode",
+    label: "enter_plan_mode",
+    description: "Enter plan mode to design an approach before writing code. Use it when a task has genuine ambiguity; several reasonable designs, or a restructuring where the wrong approach wastes significant effort. Do not use it for a clear fix, a rename, or a task that follows existing conventions. The user must approve entering.",
+    promptSnippet: "enter_plan_mode: design first when the approach is genuinely ambiguous",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+        if (snapshot.state !== "inactive") {
+            return { content: [{ type: "text", text: `Plan mode is already ${snapshot.state}.` }], details: {} };
+        }
+        if (!ctx.hasUI) {
+            return {
+                content: [{ type: "text", text: "Plan mode needs an interactive session: there is no one to approve the plan. Proceed normally." }],
+                details: {},
+                isError: true,
+            };
+        }
+        const approved = await ctx.ui.confirm("Enter plan mode?", "The agent will explore and design an approach before editing anything.");
+        if (!approved) {
+            return { content: [{ type: "text", text: "The user declined plan mode. Proceed normally." }], details: {} };
+        }
+        transition(activateFromTool(snapshot));
+        const file = ensurePlanFile();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: ["Plan mode is active. Edits are blocked except for the plan file.", file ? `Write your plan to ${file}.` : "Write your plan to the session plan file."].join("\n"),
+                },
+            ],
+            details: { planFile: file },
+        };
+    },
+});
+export const exitPlanModeTool = defineTool({
+    name: "exit_plan_mode",
+    label: "exit_plan_mode",
+    description: "Present your plan for approval when you have finished planning. The plan is read from the plan file on disk, so write the file first. If the user asks for changes, stay in plan mode and revise it.",
+    promptSnippet: "exit_plan_mode: present the written plan for approval",
+    parameters: Type.Object({}),
+    // Sequential: the plan is read from disk, so a `write` to the plan file issued
+    // in the same batch must have finished first. Run in parallel, this tool reads
+    // the file before the write lands and reports an empty plan — observed in a
+    // real run. A tool that depends on a sibling's file effect must not race it.
+    executionMode: "sequential",
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+        if (!isPlanActive(snapshot)) {
+            return { content: [{ type: "text", text: "Plan mode is not active." }], details: {}, isError: true };
+        }
+        const plan = readPlan();
+        if (!plan) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No plan has been written yet. Write it to ${planFilePath ?? "the plan file"} before exiting plan mode.`,
+                    },
+                ],
+                details: {},
+                isError: true,
+            };
+        }
+        if (!ctx.hasUI) {
+            return {
+                content: [{ type: "text", text: "Plan approval needs an interactive session." }],
+                details: {},
+                isError: true,
+            };
+        }
+        const shown = plan.length > MAX_PLAN_CHARS ? `${plan.slice(0, MAX_PLAN_CHARS)}\n… (${plan.length - MAX_PLAN_CHARS} more characters)` : plan;
+        const approved = await ctx.ui.confirm("Approve this plan?", shown);
+        if (!approved) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "The user did not approve the plan. Stay in plan mode, revise the plan file with the feedback, and present it again.",
+                    },
+                ],
+                details: { approved: false },
+            };
+        }
+        transition(deactivateApproved(snapshot));
+        return {
+            content: [{ type: "text", text: "Plan approved. You may now implement it." }],
+            details: { approved: true, planFile: planFilePath },
+        };
+    },
+});