@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/tools/edit-apply.js

@@ -0,0 +1,274 @@
+import { isSensitivePath } from "./sensitive-paths.js";
+export class EditApplyError extends Error {
+    status;
+    constructor(message, status = "no_match") {
+        super(message);
+        this.status = status;
+        this.name = "EditApplyError";
+    }
+}
+const CANDIDATE_EXCERPT_CONTEXT_LINES = 3;
+const CANDIDATE_EXCERPT_MAX_LINES = 8;
+const CANDIDATE_EXCERPT_MAX_CHARS = 1200;
+function detectLineEnding(content) {
+    const crlf = content.indexOf("\r\n");
+    const lf = content.indexOf("\n");
+    return crlf !== -1 && crlf === lf - 1 ? "\r\n" : "\n";
+}
+function stripBom(content) {
+    return content.startsWith("\uFEFF") ? { bom: "\uFEFF", text: content.slice(1) } : { bom: "", text: content };
+}
+function normalizeToLF(text) {
+    return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+function buildOriginalOffsets(text) {
+    const offsets = [];
+    for (let i = 0; i < text.length; i++) {
+        offsets.push(i);
+        if (text[i] === "\r" && text[i + 1] === "\n")
+            i++;
+    }
+    offsets.push(text.length);
+    return offsets;
+}
+function lineEndingAt(text, offset, fallback) {
+    const after = text.slice(offset).match(/\r\n|\r|\n/);
+    if (after)
+        return after[0];
+    const before = text.slice(0, offset).match(/(\r\n|\r|\n)[^\r\n]*$/);
+    return before ? before[1] : fallback;
+}
+// Splices replacements into the original text so untouched lines keep their own
+// terminators; inserted text uses the terminator of the line being edited.
+function spliceOriginal(text, matches, edits, fallbackEnding) {
+    const offsets = buildOriginalOffsets(text);
+    let out = "";
+    let cursor = 0;
+    for (const match of [...matches].sort((a, b) => a.start - b.start)) {
+        const start = offsets[match.start];
+        const ending = lineEndingAt(text, start, fallbackEnding);
+        out += text.slice(cursor, start) + edits[match.editIndex].newText.replace(/\n/g, ending);
+        cursor = offsets[match.end];
+    }
+    return out + text.slice(cursor);
+}
+function normalizeLineForMatch(line) {
+    return line
+        .normalize("NFKC")
+        .trimEnd()
+        .replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+        .replace(/[\u201C\u201D\u201E\u201F]/g, '"')
+        .replace(/[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/g, "-")
+        .replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g, " ");
+}
+function findAllOccurrences(content, needle) {
+    const indexes = [];
+    if (needle.length === 0)
+        return indexes;
+    let index = content.indexOf(needle);
+    while (index !== -1) {
+        indexes.push(index);
+        index = content.indexOf(needle, index + needle.length);
+    }
+    return indexes;
+}
+function splitLines(content) {
+    const lines = [];
+    let start = 0;
+    for (let i = 0; i < content.length; i++) {
+        if (content[i] === "\n") {
+            lines.push({ text: content.slice(start, i), start, endNoNewline: i });
+            start = i + 1;
+        }
+    }
+    lines.push({ text: content.slice(start), start, endNoNewline: content.length });
+    return lines;
+}
+function nonBlankLines(lines) {
+    const result = [];
+    for (let i = 0; i < lines.length; i++) {
+        const normalized = normalizeLineForMatch(lines[i].text);
+        if (normalized.trim().length > 0) {
+            result.push({ lineIndex: i, normalized });
+        }
+    }
+    return result;
+}
+function normalizedOldNonBlankLines(oldText) {
+    return splitLines(oldText)
+        .map((line) => normalizeLineForMatch(line.text))
+        .filter((line) => line.trim().length > 0);
+}
+function summarizeOldText(oldText) {
+    const firstLine = normalizeToLF(oldText).split("\n").find((line) => line.trim().length > 0) ?? oldText;
+    return firstLine.length > 80 ? `${firstLine.slice(0, 80)}...` : firstLine;
+}
+function findBestLineHint(content, oldText) {
+    const oldLines = normalizedOldNonBlankLines(oldText);
+    if (oldLines.length === 0)
+        return undefined;
+    const contentLines = nonBlankLines(splitLines(content));
+    let best;
+    let tieCount = 0;
+    for (let i = 0; i < contentLines.length; i++) {
+        let score = 0;
+        for (let j = 0; j < oldLines.length && i + j < contentLines.length; j++) {
+            if (contentLines[i + j].normalized === oldLines[j])
+                score++;
+        }
+        if (!best || score > best.score) {
+            best = { index: i, score };
+            tieCount = 1;
+        }
+        else if (score === best.score) {
+            tieCount++;
+        }
+    }
+    if (!best || best.score === 0)
+        return undefined;
+    const startLine = contentLines[best.index].lineIndex + 1;
+    return {
+        startLine,
+        score: best.score,
+        total: oldLines.length,
+        lineIndex: contentLines[best.index].lineIndex,
+        tieCount,
+    };
+}
+function isHighConfidenceLineHint(hint) {
+    return hint.score >= 2 && hint.score / hint.total >= 0.5 && hint.tieCount === 1;
+}
+function formatLineHint(hint) {
+    if (hint.tieCount > 1) {
+        return `Closest ambiguous line-based candidate starts near line ${hint.startLine} and matched ${hint.score}/${hint.total} non-blank lines, but ${hint.tieCount} candidates tied. Current bytes were not included because the candidate may be unrelated.`;
+    }
+    if (!isHighConfidenceLineHint(hint)) {
+        return `Closest low-confidence line-based candidate starts near line ${hint.startLine} and matched ${hint.score}/${hint.total} non-blank lines. Current bytes were not included because the candidate may be unrelated.`;
+    }
+    return `Closest line-based candidate starts near line ${hint.startLine} and matched ${hint.score}/${hint.total} non-blank lines.`;
+}
+function formatFence(content) {
+    let fence = "```";
+    while (content.includes(fence))
+        fence += "`";
+    return `${fence}\n${content}\n${fence}`;
+}
+function truncateExcerpt(excerpt) {
+    if (excerpt.length <= CANDIDATE_EXCERPT_MAX_CHARS)
+        return excerpt;
+    const marker = "\n...[truncated current candidate excerpt]";
+    return excerpt.slice(0, Math.max(0, CANDIDATE_EXCERPT_MAX_CHARS - marker.length)) + marker;
+}
+function formatCandidateExcerpt(content, hint) {
+    const lines = splitLines(content);
+    const startLineIndex = Math.max(0, hint.lineIndex - CANDIDATE_EXCERPT_CONTEXT_LINES);
+    const requestedEnd = Math.min(lines.length, hint.lineIndex + CANDIDATE_EXCERPT_CONTEXT_LINES + 1);
+    const endLineIndex = Math.min(requestedEnd, startLineIndex + CANDIDATE_EXCERPT_MAX_LINES);
+    const excerpt = truncateExcerpt(lines.slice(startLineIndex, endLineIndex).map((line) => line.text).join("\n"));
+    return [
+        `Current candidate excerpt (high confidence, current file lines ${startLineIndex + 1}-${endLineIndex}, not guaranteed target):`,
+        formatFence(excerpt),
+    ].join("\n");
+}
+function formatBestLineHint(content, hint, options) {
+    const lineHint = formatLineHint(hint);
+    if (!isHighConfidenceLineHint(hint))
+        return lineHint;
+    if (options?.path && isSensitivePath(options.path)) {
+        return `${lineHint}\nCurrent bytes were not included because this path is blocked by the sensitive-path read policy.`;
+    }
+    return `${lineHint}\n\n${formatCandidateExcerpt(content, hint)}`;
+}
+function matchEdit(content, edit, index, total, options) {
+    if (edit.oldText.length === 0) {
+        throw new EditApplyError(total === 1 ? "Error: oldText must not be empty." : `Error: edits[${index}].oldText must not be empty.`);
+    }
+    if (edit.oldText === edit.newText) {
+        const header = total === 1
+            ? "Error: This edit is a no-op because oldText and newText are byte-identical."
+            : `Error: edits[${index}] is a no-op because oldText and newText are byte-identical.`;
+        throw new EditApplyError([
+            header,
+            "",
+            "Common causes and how to escape:",
+            "- Your tokenizer may be folding repeated characters into a single token (hex colors like '#ec489' vs '#ec4899', repeated digits, etc.). The two strings feel different in your head but serialize to identical bytes.",
+            "- Use the write tool with the full new content for full-file replacements that hinge on a single repeated character or trailing digit.",
+            "- Or re-read the file with the read tool, then copy the exact bytes you want to replace before retrying.",
+        ].join("\n"));
+    }
+    const oldText = normalizeToLF(edit.oldText);
+    const occurrences = findAllOccurrences(content, oldText);
+    if (occurrences.length === 1) {
+        return { editIndex: index, start: occurrences[0], end: occurrences[0] + oldText.length };
+    }
+    if (occurrences.length > 1) {
+        const recovery = [
+            "",
+            "Extend oldText with more surrounding context (the lines immediately before/after) until it uniquely identifies the intended span.",
+        ].join("\n");
+        throw new EditApplyError(total === 1
+            ? `Error: oldText appears ${occurrences.length} times in file. Must be unique: "${summarizeOldText(oldText)}"${recovery}`
+            : `Error: edits[${index}].oldText appears ${occurrences.length} times in file. Must be unique: "${summarizeOldText(oldText)}"${recovery}`);
+    }
+    const hint = findBestLineHint(content, oldText);
+    const hintSuffix = hint ? `\n${formatBestLineHint(content, hint, options)}` : "";
+    const recovery = [
+        "",
+        "How to recover:",
+        "- Re-read the file with the read tool to see its current bytes; the file may have been changed by a prior edit this turn.",
+        "- Shorten oldText to a smaller unique anchor and try again. Long multi-line anchors are fragile to whitespace and indentation.",
+        "- If many lines need to change, use the write tool with the full new content instead of stacking edits.",
+    ].join("\n");
+    throw new EditApplyError(total === 1
+        ? `Error: oldText not found in file: "${summarizeOldText(oldText)}"${hintSuffix}${recovery}`
+        : `Error: edits[${index}].oldText not found in file: "${summarizeOldText(oldText)}"${hintSuffix}${recovery}`);
+}
+function assertNoOverlaps(matches) {
+    const sorted = [...matches].sort((a, b) => a.start - b.start);
+    for (let i = 1; i < sorted.length; i++) {
+        const previous = sorted[i - 1];
+        const current = sorted[i];
+        if (previous.end > current.start) {
+            throw new EditApplyError(`Error: edits[${previous.editIndex}] and edits[${current.editIndex}] overlap in file. Merge them into one edit or target disjoint regions.`, "blocked");
+        }
+    }
+}
+export function applyEditsToContent(rawContent, edits, options) {
+    if (!Array.isArray(edits) || edits.length === 0) {
+        throw new EditApplyError("Error: No edits provided");
+    }
+    const { bom, text } = stripBom(rawContent);
+    const lineEnding = detectLineEnding(text);
+    const normalizedOriginal = normalizeToLF(text);
+    const dropCopiedBom = (value) => (bom ? stripBom(value).text : value);
+    const normalizedEdits = edits.map((edit) => ({
+        oldText: normalizeToLF(dropCopiedBom(edit.oldText)),
+        newText: normalizeToLF(dropCopiedBom(edit.newText)),
+    }));
+    const matches = normalizedEdits.map((edit, index) => matchEdit(normalizedOriginal, edit, index, normalizedEdits.length, options));
+    assertNoOverlaps(matches);
+    const byDescendingStart = [...matches].sort((a, b) => b.start - a.start);
+    let normalizedNext = normalizedOriginal;
+    for (const match of byDescendingStart) {
+        const edit = normalizedEdits[match.editIndex];
+        normalizedNext = normalizedNext.slice(0, match.start) + edit.newText + normalizedNext.slice(match.end);
+    }
+    if (normalizedNext === normalizedOriginal) {
+        throw new EditApplyError([
+            "Error: No changes made. The replacement produced identical content.",
+            "",
+            "Common causes and how to escape:",
+            "- oldText and newText are byte-identical. Verify newText actually contains the intended change (a missing trailing char like turning '#ec489' into '#ec4899' is a frequent culprit).",
+            "- The file already contains newText. Re-read the file to confirm the current state before editing again.",
+            "- For wholesale rewrites, use the write tool with the full new content instead.",
+        ].join("\n"));
+    }
+    return {
+        content: bom + spliceOriginal(text, matches, normalizedEdits, lineEnding),
+        normalizedOriginal,
+        normalizedNext,
+        bom,
+        lineEnding,
+        matches,
+    };
+}

package/dist/tools/edit.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Edit tool - targeted string replacements with diff validation.
+ *
+ * This is the safest way to edit files: old_string must exist exactly once.
+ */
+import type { ApprovalController } from "../approval/types.js";
+import type { CheckpointStore } from "../checkpoints.js";
+import type { ToolRegistryEntry } from "../types.js";
+import { type LspService } from "../lsp/index.js";
+import { type FileStateTracker } from "./file-state.js";
+export interface EditArgs {
+    path: string;
+    edits: Array<{
+        oldText: string;
+        newText: string;
+    }>;
+}
+export declare function createEditTool(cwd: string, approval?: ApprovalController, lsp?: LspService, fileState?: FileStateTracker, checkpoints?: () => CheckpointStore | undefined): ToolRegistryEntry;

package/dist/tools/edit.js

@@ -0,0 +1,200 @@
+/**
+ * Edit tool - targeted string replacements with diff validation.
+ *
+ * This is the safest way to edit files: old_string must exist exactly once.
+ */
+import { constants } from "node:fs";
+import { access, readFile, writeFile } from "node:fs/promises";
+import { createTwoFilesPatch } from "diff";
+import { gateToolAction } from "../approval/tool-helper.js";
+import { countUnifiedDiffChanges } from "../diff-stats.js";
+import { formatDiagnosticBlocks } from "../lsp/index.js";
+import { applyEditsToContent, EditApplyError } from "./edit-apply.js";
+import { withFileMutationQueue } from "./file-mutation-queue.js";
+import { isWithinWorkspace } from "./file-state.js";
+import { resolveToolPath } from "./path-utils.js";
+function prepareEditArguments(input) {
+    if (!input || typeof input !== "object")
+        return input;
+    const args = { ...input };
+    if (typeof args.file_path === "string" && typeof args.path !== "string") {
+        args.path = args.file_path;
+    }
+    if (typeof args.edits === "string") {
+        try {
+            const parsed = JSON.parse(args.edits);
+            if (Array.isArray(parsed))
+                args.edits = parsed;
+        }
+        catch {
+            // Keep the original value so validation surfaces the problem.
+        }
+    }
+    if (Array.isArray(args.edits)) {
+        args.edits = args.edits.map((edit) => {
+            if (!edit || typeof edit !== "object")
+                return edit;
+            const normalized = { ...edit };
+            if (typeof normalized.oldText !== "string") {
+                normalized.oldText = firstString(edit.old_text, edit.oldString, edit.old_string);
+            }
+            if (typeof normalized.newText !== "string") {
+                normalized.newText = firstString(edit.new_text, edit.newString, edit.new_string);
+            }
+            return normalized;
+        });
+    }
+    if (!Array.isArray(args.edits)) {
+        const oldText = firstString(args.oldText, args.old_text, args.oldString, args.old_string);
+        const newText = firstString(args.newText, args.new_text, args.newString, args.new_string);
+        if (typeof oldText === "string" && typeof newText === "string") {
+            args.edits = [{ oldText, newText }];
+        }
+    }
+    return args;
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === "string")
+            return value;
+    }
+    return undefined;
+}
+export function createEditTool(cwd, approval, lsp, fileState, checkpoints) {
+    return {
+        name: "edit",
+        effect: "write_direct",
+        requiresApproval: true,
+        description: "Edit a single file using targeted text replacements. Every edits[].oldText must match a unique, non-overlapping region of the original file. If two changes overlap or one replacement is nested inside another, merge them into one edit. Do not include large unchanged regions just to connect distant changes. Matching is exact; a UTF-8 BOM and CRLF line endings are handled automatically and preserved, so write oldText/newText with plain \\n line breaks.",
+        promptSnippet: "Make precise file edits with exact text replacement, including multiple disjoint edits in one call",
+        promptGuidelines: [
+            "Use edit for precise changes; each edits[].oldText must be copied verbatim from a fresh read of the current exact target block and must identify a unique target. Do not reconstruct oldText from memory, stale reads, or similar code elsewhere.",
+            "When changing multiple small, clearly disjoint locations copied from the same fresh read, you may use one edit call with multiple entries in edits[]. Use separate smaller edit calls after re-reading when anchors are uncertain, stale, or likely to drift.",
+            "Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits; merge only truly overlapping targets.",
+            "Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions.",
+        ],
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file" },
+                edits: {
+                    type: "array",
+                    description: "List of replacements. Each oldText must be unique in the file.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            oldText: { type: "string", description: "Exact text to replace" },
+                            newText: { type: "string", description: "Replacement text" },
+                        },
+                        required: ["oldText", "newText"],
+                    },
+                },
+            },
+            required: ["path", "edits"],
+        },
+        prepareArguments: prepareEditArguments,
+        async execute(args) {
+            if (!Array.isArray(args.edits)) {
+                return {
+                    content: "Error: edit requires edits to be an array of { oldText, newText } replacements.",
+                    isError: true,
+                    status: "blocked",
+                    metadata: { kind: "edit", reason: "invalid_args" },
+                };
+            }
+            for (let index = 0; index < args.edits.length; index++) {
+                const edit = args.edits[index];
+                if (!edit || typeof edit !== "object" || typeof edit.oldText !== "string" || typeof edit.newText !== "string") {
+                    return {
+                        content: `Error: edit requires edits[${index}] to contain string oldText and newText fields.`,
+                        isError: true,
+                        status: "blocked",
+                        metadata: { kind: "edit", reason: "invalid_args", index },
+                    };
+                }
+            }
+            const filePath = resolveToolPath(cwd, args.path);
+            // Outside-workspace paths escalate the approval request instead of
+            // being blocked outright — see the matching note in write.ts.
+            const outsideWorkspace = !isWithinWorkspace(cwd, filePath);
+            return withFileMutationQueue(filePath, async () => {
+                try {
+                    await access(filePath, constants.R_OK | constants.W_OK);
+                }
+                catch {
+                    return { content: `Error: Cannot read/write file: ${filePath}`, isError: true };
+                }
+                const original = await readFile(filePath, "utf-8");
+                let applied;
+                try {
+                    applied = applyEditsToContent(original, args.edits, { path: filePath });
+                }
+                catch (err) {
+                    if (err instanceof EditApplyError) {
+                        return {
+                            content: err.message,
+                            isError: true,
+                            status: err.status,
+                            metadata: {
+                                kind: "edit",
+                                path: filePath,
+                                reason: err.status,
+                            },
+                        };
+                    }
+                    throw err;
+                }
+                const diff = createTwoFilesPatch(filePath, filePath, original, applied.content, "original", "modified", { context: 3 });
+                const diffStats = countUnifiedDiffChanges(diff);
+                // Gate on the approval controller BEFORE persisting the change.
+                const gate = await gateToolAction(approval, {
+                    type: "edit",
+                    path: filePath,
+                    diff,
+                    fileExists: true,
+                    outsideWorkspace,
+                });
+                if (!gate.approved)
+                    return gate.result;
+                const latest = await readFile(filePath, "utf-8");
+                if (latest !== original) {
+                    return {
+                        content: `Error: Cannot safely edit ${filePath} because it changed while approval was pending.\n\n`
+                            + "Re-read the file and retry the edit against the latest content.",
+                        isError: true,
+                        status: "blocked",
+                        metadata: {
+                            kind: "security",
+                            path: filePath,
+                            reason: "changed",
+                        },
+                    };
+                }
+                await checkpoints?.()?.captureBefore(filePath, original);
+                await writeFile(filePath, applied.content, "utf-8");
+                await fileState?.observe(filePath, "edit", applied.content).catch(() => undefined);
+                let output = `Edited ${filePath}\n\nDiff:\n${diff}`;
+                if (lsp) {
+                    try {
+                        await lsp.touchFile(filePath, "document");
+                        output += formatDiagnosticBlocks(cwd, filePath, lsp.diagnostics());
+                    }
+                    catch {
+                        // LSP diagnostics should not turn a successful edit into a failed tool call.
+                    }
+                }
+                return {
+                    content: output,
+                    status: "success",
+                    metadata: {
+                        kind: "edit",
+                        path: filePath,
+                        diff,
+                        addedLines: diffStats.added,
+                        removedLines: diffStats.removed,
+                    },
+                };
+            });
+        },
+    };
+}

package/dist/tools/exa-mcp.d.ts

@@ -0,0 +1,3 @@
+import type { ToolResult } from "../types.js";
+export declare function resolveExaMcpUrl(): string;
+export declare function callExaMcpTool(name: string, args: Record<string, unknown>): Promise<ToolResult>;

package/dist/tools/exa-mcp.js

@@ -0,0 +1,74 @@
+const DEFAULT_BASE_URL = "https://mcp.exa.ai/mcp";
+export function resolveExaMcpUrl() {
+    const baseUrl = (process.env.BUBBLE_WEB_SEARCH_URL || DEFAULT_BASE_URL).trim();
+    const url = new URL(baseUrl);
+    const enabledTools = new Set((url.searchParams.get("tools") || "web_search_exa,crawling_exa")
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean));
+    enabledTools.add("web_search_exa");
+    enabledTools.add("crawling_exa");
+    url.searchParams.set("tools", [...enabledTools].join(","));
+    const apiKey = process.env.BUBBLE_EXA_API_KEY?.trim();
+    if (apiKey && !url.searchParams.get("exaApiKey")) {
+        url.searchParams.set("exaApiKey", apiKey);
+    }
+    return url.toString();
+}
+export async function callExaMcpTool(name, args) {
+    const response = await fetch(resolveExaMcpUrl(), {
+        method: "POST",
+        headers: {
+            Accept: "application/json, text/event-stream",
+            "Content-Type": "application/json",
+            "User-Agent": "bubble",
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "tools/call",
+            params: {
+                name,
+                arguments: args,
+            },
+        }),
+    }).catch((error) => {
+        throw new Error(error instanceof Error ? error.message : String(error));
+    });
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => "");
+        return {
+            content: `Error: Remote MCP request failed with status ${response.status}${errorText ? `: ${errorText}` : ""}`,
+            isError: true,
+        };
+    }
+    const text = await response.text();
+    const result = parseMcpResponse(text);
+    if (!result) {
+        return { content: "No results found." };
+    }
+    return { content: result };
+}
+function parseMcpResponse(body) {
+    const lines = body.split("\n");
+    for (const line of lines) {
+        if (!line.startsWith("data: "))
+            continue;
+        try {
+            const parsed = JSON.parse(line.slice(6));
+            const text = parsed.result?.content?.find((item) => item.type === "text")?.text;
+            if (text)
+                return text;
+        }
+        catch {
+            // Ignore malformed SSE lines.
+        }
+    }
+    try {
+        const parsed = JSON.parse(body);
+        return parsed.result?.content?.find((item) => item.type === "text")?.text;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/tools/exit-plan-mode.d.ts

@@ -0,0 +1,22 @@
+/**
+ * exit_plan_mode tool - proposes a plan, awaits user approval, and (on approve) flips the
+ * agent out of plan mode so subsequent turns may execute it.
+ *
+ * The tool is read-only from the agent's perspective; the side effects (prompting the user,
+ * flipping mode) happen via the injected PlanController.
+ */
+import type { PermissionMode, PlanDecision, ToolRegistryEntry } from "../types.js";
+export interface PlanController {
+    /** Reads the current permission mode (used to gate the tool). */
+    getMode: () => PermissionMode;
+    /** Ask the user to approve/reject/edit the proposed plan. */
+    requestApproval(plan: string): Promise<PlanDecision>;
+    /** Switch the agent's mode. Called after an approval so the next turn runs unconstrained. */
+    setMode(mode: PermissionMode): void;
+    /**
+     * Mode to switch to once the plan is approved — the mode the user was in
+     * before entering plan mode. Defaults to "default" when omitted.
+     */
+    getExitMode?: () => Exclude<PermissionMode, "plan">;
+}
+export declare function createExitPlanModeTool(controller: PlanController): ToolRegistryEntry;

package/dist/tools/exit-plan-mode.js

@@ -0,0 +1,79 @@
+/**
+ * exit_plan_mode tool - proposes a plan, awaits user approval, and (on approve) flips the
+ * agent out of plan mode so subsequent turns may execute it.
+ *
+ * The tool is read-only from the agent's perspective; the side effects (prompting the user,
+ * flipping mode) happen via the injected PlanController.
+ */
+export function createExitPlanModeTool(controller) {
+    return {
+        name: "exit_plan_mode",
+        readOnly: true,
+        effect: "read",
+        requiresApproval: true,
+        // Outside plan mode the tool is not just useless, it is bait: models call
+        // it to "wrap up" an ordinary turn despite the description below saying
+        // not to (same failure seen with update_goal — wording loses to the
+        // trained close-out prior). Gating it out of the provider's function list
+        // removes the affordance; the predicate re-runs every model call, so
+        // entering plan mode surfaces it immediately. The runtime no-op in
+        // agent.ts stays as a backstop for a mode flip mid-turn.
+        enabled: () => controller.getMode() === "plan",
+        description: "ONLY call this tool when the harness has told you via a runtime reminder that plan mode is ACTIVE. " +
+            "Do NOT call it during ordinary work — in default mode you should just use the regular tools directly. " +
+            "In plan mode: after investigating, call this with a concrete step-by-step plan so the user can approve, edit, or reject. " +
+            "Approval automatically switches the agent out of plan mode.",
+        parameters: {
+            type: "object",
+            properties: {
+                plan: {
+                    type: "string",
+                    description: "The plan to present to the user. Should be concrete, step-by-step, and cover all changes you intend to make.",
+                },
+            },
+            required: ["plan"],
+        },
+        async execute(args) {
+            // Hard gate: this tool is a no-op outside plan mode. Without this check some
+            // models call it during normal work (misled by the word "plan" in the schema),
+            // which pops a confusing approval dialog to the user.
+            if (controller.getMode() !== "plan") {
+                return {
+                    content: "Error: exit_plan_mode is only valid while plan mode is active. " +
+                        "You are currently NOT in plan mode — proceed with the user's request directly using the regular tools.",
+                    isError: true,
+                };
+            }
+            const plan = typeof args.plan === "string" ? args.plan.trim() : "";
+            if (!plan) {
+                return { content: "Error: plan is required and must be a non-empty string", isError: true };
+            }
+            let decision;
+            try {
+                decision = await controller.requestApproval(plan);
+            }
+            catch (err) {
+                return {
+                    content: `Error requesting plan approval: ${err?.message || String(err)}`,
+                    isError: true,
+                };
+            }
+            if (decision.action === "approve") {
+                const exitMode = controller.getExitMode?.() ?? "default";
+                controller.setMode(exitMode);
+                const finalPlan = decision.plan.trim() || plan;
+                const edited = finalPlan !== plan;
+                return {
+                    content: `User approved the plan${edited ? " (with edits)" : ""}. ` +
+                        `Agent mode has been switched to ${exitMode} — you may now execute the plan using any tools. ` +
+                        `Approved plan:\n\n${finalPlan}`,
+                };
+            }
+            const reason = decision.reason?.trim();
+            return {
+                content: `User rejected the plan. Remain in plan mode and revise your approach. ` +
+                    (reason ? `Reason: ${reason}` : "No reason provided; ask for clarification or gather more context."),
+            };
+        },
+    };
+}