@oh-my-pi/pi-coding-agent 13.5.1 → 13.5.3

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## [Unreleased]
 
+## [13.5.3] - 2026-03-01
+
+### Added
+
+- Auto-include `ast_grep` and `ast_edit` tools when their text-based counterparts (`grep`, `edit`) are requested and the AST tools are enabled
+- Enforced tool decision in plan mode—agent now requires calling either `ask` or `exit_plan_mode` when a turn ends without a required tool call
+- Auto-correction of escaped tab indentation in edits (enabled by default, controllable via `PI_HASHLINE_AUTOCORRECT_ESCAPED_TABS` environment variable)
+- Warning when suspicious Unicode escape placeholder `\uDDDD` is detected in edit content
+
+### Changed
+
+- Updated bash tool description to conditionally show `ast_grep` and `ast_edit` guidance based on tool availability in the session
+- Replaced timeout-based cancellation with AbortSignal-based cancellation in the `ask` tool for more reliable user interaction handling
+- Updated `ask` tool to distinguish between user-initiated cancellation and timeout-driven auto-selection, with only user cancellation aborting the turn
+- Updated hashline documentation to clarify that `\t` in JSON represents a real tab character, not a literal backslash-t sequence
+
+### Fixed
+
+- Fixed race condition in dialog overlay handling where multiple concurrent resolutions could occur
+- Cancelling the `ask` tool now aborts the current turn instead of returning a normal cancelled selection, while timeout-driven auto-cancel still returns without aborting
+
+## [13.5.2] - 2026-03-01
+
+### Added
+
+- Added `checkpoint` tool to create context checkpoints before exploratory work, allowing you to investigate with many intermediate tool calls and minimize context cost afterward
+- Added `rewind` tool to end an active checkpoint and replace intermediate exploration messages with a concise investigation report
+- Added `checkpoint.enabled` setting to control availability of the checkpoint and rewind tools
+- Added `render_mermaid` tool to convert Mermaid graph source into ASCII diagram output
+- Added `renderMermaid.enabled` setting to control availability of the render_mermaid tool
+
+### Changed
+
+- Changed Mermaid rendering from PNG images to ASCII diagrams in theme rendering
+- Changed `prerenderMermaid()` function to synchronously render ASCII instead of asynchronously rendering PNG
+
 ## [13.5.0] - 2026-03-01
 
 ### Added

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "13.5.1",
+	"version": "13.5.3",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -41,12 +41,12 @@
 	},
 	"dependencies": {
 		"@mozilla/readability": "^0.6",
-		"@oh-my-pi/omp-stats": "13.5.1",
-		"@oh-my-pi/pi-agent-core": "13.5.1",
-		"@oh-my-pi/pi-ai": "13.5.1",
-		"@oh-my-pi/pi-natives": "13.5.1",
-		"@oh-my-pi/pi-tui": "13.5.1",
-		"@oh-my-pi/pi-utils": "13.5.1",
+		"@oh-my-pi/omp-stats": "13.5.3",
+		"@oh-my-pi/pi-agent-core": "13.5.3",
+		"@oh-my-pi/pi-ai": "13.5.3",
+		"@oh-my-pi/pi-natives": "13.5.3",
+		"@oh-my-pi/pi-tui": "13.5.3",
+		"@oh-my-pi/pi-utils": "13.5.3",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/config/prompt-templates.ts

@@ -255,7 +255,8 @@ handlebars.registerHelper("SECTION_SEPERATOR", (name: unknown): string => sectio
  */
 function formatHashlineRef(lineNum: unknown, content: unknown): { num: number; text: string; ref: string } {
 	const num = typeof lineNum === "number" ? lineNum : Number.parseInt(String(lineNum), 10);
-	const text = typeof content === "string" ? content : String(content ?? "");
+	const raw = typeof content === "string" ? content : String(content ?? "");
+	const text = raw.replace(/\\t/g, "\t").replace(/\\n/g, "\n").replace(/\\r/g, "\r");
 	const ref = `${num}#${computeLineHash(num, text)}`;
 	return { num, text, ref };
 }

package/src/config/settings-schema.ts

@@ -460,11 +460,29 @@ export const SETTINGS_SCHEMA = {
 			description: "Enable the ast_edit tool for structural AST rewrites",
 		},
 	},
+	"renderMermaid.enabled": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "tools",
+			label: "Enable Render Mermaid",
+			description: "Enable the render_mermaid tool for Mermaid-to-ASCII rendering",
+		},
+	},
 	"notebook.enabled": {
 		type: "boolean",
 		default: true,
 		ui: { tab: "tools", label: "Enable Notebook", description: "Enable the notebook tool for notebook editing" },
 	},
+	"checkpoint.enabled": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "tools",
+			label: "Enable Checkpoint/Rewind",
+			description: "Enable the checkpoint and rewind tools for context checkpointing",
+		},
+	},
 	"fetch.enabled": {
 		type: "boolean",
 		default: true,

package/src/debug/index.ts

@@ -27,6 +27,11 @@ const DEBUG_MENU_ITEMS: SelectItem[] = [
 	{ value: "memory", label: "Report: memory issue", description: "Heap snapshot + bundle" },
 	{ value: "logs", label: "View: recent logs", description: "Show last 50 log entries" },
 	{ value: "system", label: "View: system info", description: "Show environment details" },
+	{
+		value: "transcript",
+		label: "Export: TUI transcript",
+		description: "Write visible TUI conversation to a temp txt",
+	},
 	{ value: "clear-cache", label: "Clear: artifact cache", description: "Remove old session artifacts" },
 ];
 
@@ -95,6 +100,9 @@ export class DebugSelectorComponent extends Container {
 			case "system":
 				await this.#handleViewSystemInfo();
 				break;
+			case "transcript":
+				await this.#handleTranscriptExport();
+				break;
 			case "clear-cache":
 				await this.#handleClearCache();
 				break;
@@ -323,6 +331,9 @@ export class DebugSelectorComponent extends Container {
 		this.ctx.ui.requestRender();
 	}
 
+	async #handleTranscriptExport(): Promise<void> {
+		await this.ctx.handleDebugTranscriptCommand();
+	}
 	async #handleOpenArtifacts(): Promise<void> {
 		const sessionFile = this.ctx.sessionManager.getSessionFile();
 		if (!sessionFile) {

package/src/exa/mcp-client.ts

@@ -16,6 +16,61 @@ export function findApiKey(): string | null {
 	return $env.EXA_API_KEY;
 }
 
+function asRecord(value: unknown): Record<string, unknown> | null {
+	if (typeof value !== "object" || value === null) return null;
+	return value as Record<string, unknown>;
+}
+
+function parseJsonContent(text: string): unknown | null {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Normalize tools/call payloads across MCP servers.
+ *
+ * Exa currently returns different shapes depending on deployment/environment:
+ * - direct payload in result
+ * - structured payload under result.structuredContent / result.data / result.result
+ * - JSON payload embedded as text in result.content[]
+ */
+function normalizeMcpToolPayload(payload: unknown): unknown {
+	const candidates: unknown[] = [];
+	const root = asRecord(payload);
+
+	if (root) {
+		if (root.structuredContent !== undefined) candidates.push(root.structuredContent);
+		if (root.data !== undefined) candidates.push(root.data);
+		if (root.result !== undefined) candidates.push(root.result);
+		candidates.push(root);
+
+		const content = root.content;
+		if (Array.isArray(content)) {
+			for (const item of content) {
+				const part = asRecord(item);
+				if (!part) continue;
+				const text = part.text;
+				if (typeof text !== "string" || text.trim().length === 0) continue;
+				const parsed = parseJsonContent(text);
+				if (parsed !== null) candidates.push(parsed);
+			}
+		}
+	} else {
+		candidates.push(payload);
+	}
+
+	for (const candidate of candidates) {
+		if (isSearchResponse(candidate)) {
+			return candidate;
+		}
+	}
+
+	return payload;
+}
+
 /** Fetch available tools from Exa MCP */
 export async function fetchExaTools(apiKey: string | null, toolNames: string[]): Promise<MCPTool[]> {
 	const params = new URLSearchParams();
@@ -65,7 +120,7 @@ export async function callExaTool(
 		throw new Error(`MCP error: ${response.error.message}`);
 	}
 
-	return response.result;
+	return normalizeMcpToolPayload(response.result);
 }
 
 /** Call a tool on Websets MCP */
@@ -85,7 +140,7 @@ export async function callWebsetsTool(
 		throw new Error(`MCP error: ${response.error.message}`);
 	}
 
-	return response.result;
+	return normalizeMcpToolPayload(response.result);
 }
 
 /** Format search results for LLM */

package/src/modes/controllers/command-controller.ts

@@ -28,6 +28,7 @@ import type { AuthStorage } from "../../session/auth-storage";
 import { createCompactionSummaryMessage } from "../../session/messages";
 import { outputMeta } from "../../tools/output-meta";
 import { resolveToCwd } from "../../tools/path-utils";
+import { replaceTabs } from "../../tools/render-utils";
 import { getChangelogPath, parseChangelog } from "../../utils/changelog";
 import { openPath } from "../../utils/open";
 
@@ -70,6 +71,25 @@ export class CommandController {
 		}
 	}
 
+	async handleDebugTranscriptCommand(): Promise<void> {
+		try {
+			const width = Math.max(1, this.ctx.ui.terminal.columns);
+			const renderedLines = this.ctx.chatContainer.render(width).map(line => replaceTabs(Bun.stripANSI(line)));
+			const rendered = renderedLines.join("\n").trimEnd();
+			if (!rendered) {
+				this.ctx.showError("No messages to dump yet.");
+				return;
+			}
+			const tmpPath = path.join(os.tmpdir(), `${Snowflake.next()}-tmp.txt`);
+			await Bun.write(tmpPath, `${rendered}\n`);
+			this.ctx.showStatus(`Debug transcript written to:\n${tmpPath}`);
+		} catch (error: unknown) {
+			this.ctx.showError(
+				`Failed to write debug transcript: ${error instanceof Error ? error.message : "Unknown error"}`,
+			);
+		}
+	}
+
 	async handleShareCommand(): Promise<void> {
 		const tmpFile = path.join(os.tmpdir(), `${Snowflake.next()}.html`);
 		const cleanupTempFile = async () => {

package/src/modes/controllers/extension-ui-controller.ts

@@ -41,7 +41,7 @@ export class ExtensionUiController {
 		const uiContext: ExtensionUIContext = {
 			select: (title, options, dialogOptions) => this.showHookSelector(title, options, dialogOptions),
 			confirm: (title, message, _dialogOptions) => this.showHookConfirm(title, message),
-			input: (title, placeholder, _dialogOptions) => this.showHookInput(title, placeholder),
+			input: (title, placeholder, dialogOptions) => this.showHookInput(title, placeholder, dialogOptions),
 			notify: (message, type) => this.showHookNotify(message, type),
 			onTerminalInput: handler => this.addExtensionTerminalInputListener(handler),
 			setStatus: (key, text) => this.setHookStatus(key, text),
@@ -561,6 +561,20 @@ export class ExtensionUiController {
 		dialogOptions?: ExtensionUIDialogOptions,
 	): Promise<string | undefined> {
 		const { promise, resolve } = Promise.withResolvers<string | undefined>();
+		let settled = false;
+		const onAbort = () => {
+			this.hideHookSelector();
+			if (!settled) {
+				settled = true;
+				resolve(undefined);
+			}
+		};
+		const finish = (value: string | undefined) => {
+			if (settled) return;
+			settled = true;
+			dialogOptions?.signal?.removeEventListener("abort", onAbort);
+			resolve(value);
+		};
 		this.#hookSelectorOverlay?.hide();
 		this.#hookSelectorOverlay = undefined;
 		const maxVisible = Math.max(4, Math.min(15, this.ctx.ui.terminal.rows - 12));
@@ -569,11 +583,11 @@ export class ExtensionUiController {
 			options,
 			option => {
 				this.hideHookSelector();
-				resolve(option);
+				finish(option);
 			},
 			() => {
 				this.hideHookSelector();
-				resolve(undefined);
+				finish(undefined);
 			},
 			{
 				initialIndex: dialogOptions?.initialIndex,
@@ -584,9 +598,15 @@ export class ExtensionUiController {
 			},
 		);
 		this.#hookSelectorOverlay = this.ctx.ui.showOverlay(this.ctx.hookSelector, this.#dialogOverlayOptions);
+		if (dialogOptions?.signal) {
+			if (dialogOptions.signal.aborted) {
+				onAbort();
+			} else {
+				dialogOptions.signal.addEventListener("abort", onAbort, { once: true });
+			}
+		}
 		return promise;
 	}
-
 	/**
 	 * Hide the hook selector.
 	 */
@@ -610,8 +630,26 @@ export class ExtensionUiController {
 	/**
 	 * Show a text input for hooks.
 	 */
-	showHookInput(title: string, placeholder?: string): Promise<string | undefined> {
+	showHookInput(
+		title: string,
+		placeholder?: string,
+		dialogOptions?: ExtensionUIDialogOptions,
+	): Promise<string | undefined> {
 		const { promise, resolve } = Promise.withResolvers<string | undefined>();
+		let settled = false;
+		const onAbort = () => {
+			this.hideHookInput();
+			if (!settled) {
+				settled = true;
+				resolve(undefined);
+			}
+		};
+		const finish = (value: string | undefined) => {
+			if (settled) return;
+			settled = true;
+			dialogOptions?.signal?.removeEventListener("abort", onAbort);
+			resolve(value);
+		};
 		this.#hookInputOverlay?.hide();
 		this.#hookInputOverlay = undefined;
 		this.ctx.hookInput = new HookInputComponent(
@@ -619,14 +657,21 @@ export class ExtensionUiController {
 			placeholder,
 			value => {
 				this.hideHookInput();
-				resolve(value);
+				finish(value);
 			},
 			() => {
 				this.hideHookInput();
-				resolve(undefined);
+				finish(undefined);
 			},
 		);
 		this.#hookInputOverlay = this.ctx.ui.showOverlay(this.ctx.hookInput, this.#dialogOverlayOptions);
+		if (dialogOptions?.signal) {
+			if (dialogOptions.signal.aborted) {
+				onAbort();
+			} else {
+				dialogOptions.signal.addEventListener("abort", onAbort, { once: true });
+			}
+		}
 		return promise;
 	}
 

package/src/modes/interactive-mode.ts

@@ -947,6 +947,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.#commandController.handleDumpCommand();
 	}
 
+	handleDebugTranscriptCommand(): Promise<void> {
+		return this.#commandController.handleDebugTranscriptCommand();
+	}
+
 	handleShareCommand(): Promise<void> {
 		return this.#commandController.handleShareCommand();
 	}

package/src/modes/theme/mermaid-cache.ts

@@ -1,88 +1,48 @@
-import {
-	extractMermaidBlocks,
-	type MermaidImage,
-	type MermaidRenderOptions,
-	renderMermaidToPng,
-} from "@oh-my-pi/pi-tui";
-import { logger } from "@oh-my-pi/pi-utils";
+import { extractMermaidBlocks, logger, renderMermaidAsciiSafe } from "@oh-my-pi/pi-utils";
 
-const cache = new Map<bigint, MermaidImage>();
-const pending = new Map<bigint, Promise<MermaidImage | null>>();
+const cache = new Map<bigint, string>();
 const failed = new Set<bigint>();
 
-const defaultOptions: MermaidRenderOptions = {
-	theme: "dark",
-	backgroundColor: "transparent",
-};
-
 let onRenderNeeded: (() => void) | null = null;
 
 /**
- * Set callback to trigger TUI re-render when mermaid images become available.
+ * Set callback to trigger TUI re-render when mermaid ASCII renders become available.
  */
 export function setMermaidRenderCallback(callback: (() => void) | null): void {
 	onRenderNeeded = callback;
 }
 
 /**
- * Get a pre-rendered mermaid image by hash.
+ * Get a pre-rendered mermaid ASCII diagram by hash.
  * Returns null if not cached or rendering failed.
  */
-export function getMermaidImage(hash: bigint): MermaidImage | null {
+export function getMermaidAscii(hash: bigint): string | null {
 	return cache.get(hash) ?? null;
 }
 
 /**
- * Pre-render all mermaid blocks in markdown text.
- * Renders in parallel, deduplicates concurrent requests.
- * Calls render callback when new images are cached.
+ * Render all mermaid blocks in markdown text.
+ * Caches results and calls render callback when new diagrams are available.
  */
-export async function prerenderMermaid(
-	markdown: string,
-	options: MermaidRenderOptions = defaultOptions,
-): Promise<void> {
+export function prerenderMermaid(markdown: string): void {
 	const blocks = extractMermaidBlocks(markdown);
 	if (blocks.length === 0) return;
 
-	const promises: Promise<boolean>[] = [];
+	let hasNew = false;
 
 	for (const { source, hash } of blocks) {
 		if (cache.has(hash) || failed.has(hash)) continue;
 
-		let promise = pending.get(hash);
-		if (!promise) {
-			promise = renderMermaidToPng(source, options);
-			pending.set(hash, promise);
+		const ascii = renderMermaidAsciiSafe(source);
+		if (ascii) {
+			cache.set(hash, ascii);
+			hasNew = true;
+		} else {
+			failed.add(hash);
 		}
-
-		promises.push(
-			promise
-				.then(image => {
-					pending.delete(hash);
-					if (image) {
-						cache.set(hash, image);
-						failed.delete(hash);
-						return true;
-					}
-					failed.add(hash);
-					return false;
-				})
-				.catch(error => {
-					pending.delete(hash);
-					failed.add(hash);
-					logger.warn("Mermaid render failed", {
-						hash,
-						error: error instanceof Error ? error.message : String(error),
-					});
-					return false;
-				}),
-		);
 	}
 
-	const results = await Promise.all(promises);
-	const newImages = results.some(added => added);
-
-	if (newImages && onRenderNeeded) {
+	if (hasNew && onRenderNeeded) {
 		try {
 			onRenderNeeded();
 		} catch (error) {
@@ -107,5 +67,4 @@ export function hasPendingMermaid(markdown: string): boolean {
 export function clearMermaidCache(): void {
 	cache.clear();
 	failed.clear();
-	pending.clear();
 }

package/src/modes/theme/theme.ts

@@ -16,7 +16,7 @@ import chalk from "chalk";
 import darkThemeJson from "./dark.json" with { type: "json" };
 import { defaultThemes } from "./defaults";
 import lightThemeJson from "./light.json" with { type: "json" };
-import { getMermaidImage } from "./mermaid-cache";
+import { getMermaidAscii } from "./mermaid-cache";
 
 // ============================================================================
 // Symbol Presets
@@ -2340,7 +2340,7 @@ export function getMarkdownTheme(): MarkdownTheme {
 		underline: (text: string) => theme.underline(text),
 		strikethrough: (text: string) => chalk.strikethrough(text),
 		symbols: getSymbolTheme(),
-		getMermaidImage,
+		getMermaidAscii,
 		highlightCode: (code: string, lang?: string): string[] => {
 			const validLang = lang && nativeSupportsLanguage(lang) ? lang : undefined;
 			try {

package/src/modes/types.ts

@@ -154,6 +154,7 @@ export interface InteractiveModeContext {
 	handleChangelogCommand(showFull?: boolean): Promise<void>;
 	handleHotkeysCommand(): void;
 	handleDumpCommand(): Promise<void>;
+	handleDebugTranscriptCommand(): Promise<void>;
 	handleClearCommand(): Promise<void>;
 	handleForkCommand(): Promise<void>;
 	handleBashCommand(command: string, excludeFromContext?: boolean): Promise<void>;

package/src/patch/hashline.ts

@@ -411,6 +411,45 @@ export function validateLineRef(ref: { line: number; hash: string }, fileLines:
 	}
 }
 
+function isEscapedTabAutocorrectEnabled(): boolean {
+	const value = Bun.env.PI_HASHLINE_AUTOCORRECT_ESCAPED_TABS;
+	if (value === "0") return false;
+	if (value === "1") return true;
+	return true;
+}
+
+function maybeAutocorrectEscapedTabIndentation(edits: HashlineEdit[], warnings: string[]): void {
+	if (!isEscapedTabAutocorrectEnabled()) return;
+	for (const edit of edits) {
+		if (edit.lines.length === 0) continue;
+		const hasEscapedTabs = edit.lines.some(line => line.includes("\\t"));
+		if (!hasEscapedTabs) continue;
+		const hasRealTabs = edit.lines.some(line => line.includes("\t"));
+		if (hasRealTabs) continue;
+		let correctedCount = 0;
+		const corrected = edit.lines.map(line =>
+			line.replace(/^((?:\\t)+)/, escaped => {
+				correctedCount += escaped.length / 2;
+				return "\t".repeat(escaped.length / 2);
+			}),
+		);
+		if (correctedCount === 0) continue;
+		edit.lines = corrected;
+		warnings.push(
+			`Auto-corrected escaped tab indentation in edit: converted leading \\t sequence(s) to real tab characters`,
+		);
+	}
+}
+
+function maybeWarnSuspiciousUnicodeEscapePlaceholder(edits: HashlineEdit[], warnings: string[]): void {
+	for (const edit of edits) {
+		if (edit.lines.length === 0) continue;
+		if (!edit.lines.some(line => /\\uDDDD/i.test(line))) continue;
+		warnings.push(
+			`Detected literal \\uDDDD in edit content; no autocorrection applied. Verify whether this should be a real Unicode escape or plain text.`,
+		);
+	}
+}
 // ═══════════════════════════════════════════════════════════════════════════
 // Edit Application
 // ═══════════════════════════════════════════════════════════════════════════
@@ -493,6 +532,8 @@ export function applyHashlineEdits(
 	if (mismatches.length > 0) {
 		throw new HashlineMismatchError(mismatches, fileLines);
 	}
+	maybeAutocorrectEscapedTabIndentation(edits, warnings);
+	maybeWarnSuspiciousUnicodeEscapePlaceholder(edits, warnings);
 	// Deduplicate identical edits targeting the same line(s)
 	const seenEditKeys = new Map<string, number>();
 	const dedupIndices = new Set<number>();

package/src/prompts/system/plan-mode-active.md

@@ -2,11 +2,12 @@
 Plan mode active. You **MUST** perform READ-ONLY operations only.
 
 You **MUST NOT**:
-- Creating/editing/deleting files (except plan file below)
-- Running state-changing commands (git commit, npm install, etc.)
-- Making any system changes
+- Create, edit, or delete files (except plan file below)
+- Run state-changing commands (git commit, npm install, etc.)
+- Make any system changes
 
-Supersedes all other instructions.
+To implement: call `{{exitToolName}}` → user approves → new session starts with full write access to execute the plan.
+You **MUST NOT** ask the user to exit plan mode for you; you **MUST** call `{{exitToolName}}` yourself.
 </critical>
 
 ## Plan File
@@ -32,7 +33,7 @@ Plan execution runs in fresh context (session cleared). You **MUST** make the pl
 3. Decide:
    - **Different task** → Overwrite plan
    - **Same task, continuing** → Update and clean outdated sections
-4. Call `exit_plan_mode` when complete
+4. Call `{{exitToolName}}` when complete
 </procedure>
 {{/if}}
 
@@ -43,7 +44,7 @@ Plan execution runs in fresh context (session cleared). You **MUST** make the pl
 ### 1. Explore
 You **MUST** use `find`, `grep`, `read`, `ls` to understand the codebase.
 ### 2. Interview
-You **MUST** use `ask` to clarify:
+You **MUST** use `{{askToolName}}` to clarify:
 - Ambiguous requirements
 - Technical decisions and tradeoffs
 - Preferences: UI/UX, performance, edge cases
@@ -78,7 +79,7 @@ You **MUST** focus on the request and associated code. You **SHOULD** launch par
 You **MUST** draft an approach based on exploration. You **MUST** consider trade-offs briefly, then choose.
 
 ### Phase 3: Review
-You **MUST** read critical files. You **MUST** verify plan matches original request. You **SHOULD** use `ask` to clarify remaining questions.
+You **MUST** read critical files. You **MUST** verify plan matches original request. You **SHOULD** use `{{askToolName}}` to clarify remaining questions.
 
 ### Phase 4: Update Plan
 You **MUST** update `{{planFilePath}}` (`{{editToolName}}` for changes, `{{writeToolName}}` only if creating from scratch):
@@ -93,14 +94,14 @@ You **MUST** ask questions throughout. You **MUST NOT** make large assumptions a
 {{/if}}
 
 <directives>
-- You **MUST** use `ask` only for clarifying requirements or choosing approaches
+- You **MUST** use `{{askToolName}}` only for clarifying requirements or choosing approaches
 </directives>
 
 <critical>
 Your turn ends ONLY by:
-1. Using `ask` gather information, OR
-2. Calling `exit_plan_mode` when ready
+1. Using `{{askToolName}}` to gather information, OR
+2. Calling `{{exitToolName}}` when ready — this triggers user approval, then a new implementation session with full tool access
 
-You **MUST NOT** ask plan approval via text or `ask`; you **MUST** use `exit_plan_mode`.
+You **MUST NOT** ask plan approval via text or `{{askToolName}}`; you **MUST** use `{{exitToolName}}`.
 You **MUST** keep going until complete.
 </critical>

package/src/prompts/system/plan-mode-subagent.md

@@ -2,11 +2,9 @@
 Plan mode active. You **MUST** perform READ-ONLY operations only.
 
 You **MUST NOT**:
-- Creating, editing, deleting, moving, or copying files
-- Running state-changing commands
-- Making any changes to system
-
-Supersedes all other instructions.
+- Create, edit, delete, move, or copy files
+- Run state-changing commands
+- Make any changes to the system
 </critical>
 
 <role>

package/src/prompts/system/plan-mode-tool-decision-reminder.md

@@ -0,0 +1,9 @@
+<system-reminder>
+Plan mode turn ended without a required tool call.
+
+You **MUST** choose exactly one next action now:
+1. Call `{{askToolName}}` to gather required clarification, OR
+2. Call `{{exitToolName}}` to finish planning and request approval
+
+You **MUST NOT** output plain text in this turn.
+</system-reminder>