@oh-my-pi/pi-coding-agent 8.4.0 → 8.4.2

package/src/modes/components/status-line/presets.ts

@@ -3,7 +3,7 @@ import type { PresetDef, StatusLinePreset } from "./types";
 export const STATUS_LINE_PRESETS: Record<StatusLinePreset, PresetDef> = {
 	default: {
 		// Matches current behavior
-		leftSegments: ["pi", "model", "path", "git", "context_pct", "token_total", "cost"],
+		leftSegments: ["pi", "model", "plan_mode", "path", "git", "context_pct", "token_total", "cost"],
 		rightSegments: [],
 		separator: "powerline-thin",
 		segmentOptions: {
@@ -15,7 +15,7 @@ export const STATUS_LINE_PRESETS: Record<StatusLinePreset, PresetDef> = {
 
 	minimal: {
 		leftSegments: ["path", "git"],
-		rightSegments: ["context_pct"],
+		rightSegments: ["plan_mode", "context_pct"],
 		separator: "slash",
 		segmentOptions: {
 			path: { abbreviate: true, maxLength: 30 },
@@ -24,7 +24,7 @@ export const STATUS_LINE_PRESETS: Record<StatusLinePreset, PresetDef> = {
 	},
 
 	compact: {
-		leftSegments: ["model", "git"],
+		leftSegments: ["model", "plan_mode", "git"],
 		rightSegments: ["cost", "context_pct"],
 		separator: "powerline-thin",
 		segmentOptions: {
@@ -34,7 +34,7 @@ export const STATUS_LINE_PRESETS: Record<StatusLinePreset, PresetDef> = {
 	},
 
 	full: {
-		leftSegments: ["pi", "hostname", "model", "path", "git", "subagents"],
+		leftSegments: ["pi", "hostname", "model", "plan_mode", "path", "git", "subagents"],
 		rightSegments: ["token_in", "token_out", "cache_read", "cost", "context_pct", "time_spent", "time"],
 		separator: "powerline",
 		segmentOptions: {
@@ -47,7 +47,7 @@ export const STATUS_LINE_PRESETS: Record<StatusLinePreset, PresetDef> = {
 
 	nerd: {
 		// Full preset with all Nerd Font icons
-		leftSegments: ["pi", "hostname", "model", "path", "git", "session", "subagents"],
+		leftSegments: ["pi", "hostname", "model", "plan_mode", "path", "git", "session", "subagents"],
 		rightSegments: [
 			"token_in",
 			"token_out",
@@ -70,7 +70,7 @@ export const STATUS_LINE_PRESETS: Record<StatusLinePreset, PresetDef> = {
 
 	ascii: {
 		// No Nerd Font dependencies
-		leftSegments: ["model", "path", "git"],
+		leftSegments: ["model", "plan_mode", "path", "git"],
 		rightSegments: ["token_total", "cost", "context_pct"],
 		separator: "ascii",
 		segmentOptions: {
@@ -82,7 +82,7 @@ export const STATUS_LINE_PRESETS: Record<StatusLinePreset, PresetDef> = {
 
 	custom: {
 		// User-defined - these are just defaults that get overridden
-		leftSegments: ["model", "path", "git"],
+		leftSegments: ["model", "plan_mode", "path", "git"],
 		rightSegments: ["token_total", "cost", "context_pct"],
 		separator: "powerline-thin",
 		segmentOptions: {},

package/src/modes/components/status-line/segments.ts

@@ -71,6 +71,21 @@ const modelSegment: StatusLineSegment = {
 	},
 };
 
+const planModeSegment: StatusLineSegment = {
+	id: "plan_mode",
+	render(ctx) {
+		const status = ctx.planMode;
+		if (!status || (!status.enabled && !status.paused)) {
+			return { content: "", visible: false };
+		}
+
+		const label = status.paused ? "Plan ⏸" : "Plan";
+		const content = withIcon(theme.icon.plan, label);
+		const color = status.paused ? "warning" : "accent";
+		return { content: theme.fg(color, content), visible: true };
+	},
+};
+
 const pathSegment: StatusLineSegment = {
 	id: "path",
 	render(ctx) {
@@ -322,6 +337,7 @@ const cacheWriteSegment: StatusLineSegment = {
 export const SEGMENTS: Record<StatusLineSegmentId, StatusLineSegment> = {
 	pi: piSegment,
 	model: modelSegment,
+	plan_mode: planModeSegment,
 	path: pathSegment,
 	git: gitSegment,
 	subagents: subagentsSegment,

package/src/modes/components/status-line/types.ts

@@ -26,6 +26,10 @@ export interface SegmentContext {
 	session: AgentSession;
 	width: number;
 	options: StatusLineSegmentOptions;
+	planMode: {
+		enabled: boolean;
+		paused: boolean;
+	} | null;
 	// Cached values for performance (computed once per render)
 	usageStats: {
 		input: number;

package/src/modes/components/status-line-segment-editor.ts

@@ -17,6 +17,7 @@ import { ALL_SEGMENT_IDS } from "./status-line/segments";
 const SEGMENT_INFO: Record<StatusLineSegmentId, { label: string; short: string }> = {
 	pi: { label: "Pi", short: "π icon" },
 	model: { label: "Model", short: "model name" },
+	plan_mode: { label: "Plan Mode", short: "plan status" },
 	path: { label: "Path", short: "working dir" },
 	git: { label: "Git", short: "branch/status" },
 	subagents: { label: "Agents", short: "subagent count" },

package/src/modes/components/status-line.ts

@@ -52,6 +52,7 @@ export class StatusLineComponent implements Component {
 	private hookStatuses: Map<string, string> = new Map();
 	private subagentCount: number = 0;
 	private sessionStartTime: number = Date.now();
+	private planModeStatus: { enabled: boolean; paused: boolean } | null = null;
 
 	// Git status caching (1s TTL)
 	private cachedGitStatus: { staged: number; unstaged: number; untracked: number } | null = null;
@@ -79,6 +80,10 @@ export class StatusLineComponent implements Component {
 		this.sessionStartTime = time;
 	}
 
+	setPlanModeStatus(status: { enabled: boolean; paused: boolean } | undefined): void {
+		this.planModeStatus = status ?? null;
+	}
+
 	setHookStatus(key: string, text: string | undefined): void {
 		if (text === undefined) {
 			this.hookStatuses.delete(key);
@@ -237,6 +242,7 @@ export class StatusLineComponent implements Component {
 			session: this.session,
 			width,
 			options: this.resolveSettings().segmentOptions ?? {},
+			planMode: this.planModeStatus,
 			usageStats,
 			contextPercent,
 			contextWindow,
@@ -256,6 +262,7 @@ export class StatusLineComponent implements Component {
 		StatusLineSettings {
 		const preset = this.settings.preset ?? "default";
 		const presetDef = getPreset(preset);
+		const useCustomSegments = preset === "custom";
 		const mergedSegmentOptions: StatusLineSettings["segmentOptions"] = {};
 
 		for (const [segment, options] of Object.entries(presetDef.segmentOptions ?? {})) {
@@ -270,10 +277,17 @@ export class StatusLineComponent implements Component {
 			};
 		}
 
+		const leftSegments = useCustomSegments
+			? (this.settings.leftSegments ?? presetDef.leftSegments)
+			: presetDef.leftSegments;
+		const rightSegments = useCustomSegments
+			? (this.settings.rightSegments ?? presetDef.rightSegments)
+			: presetDef.rightSegments;
+
 		return {
 			...this.settings,
-			leftSegments: this.settings.leftSegments ?? presetDef.leftSegments,
-			rightSegments: this.settings.rightSegments ?? presetDef.rightSegments,
+			leftSegments,
+			rightSegments,
 			separator: this.settings.separator ?? presetDef.separator,
 			segmentOptions: mergedSegmentOptions,
 		};

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

@@ -339,6 +339,7 @@ export class CommandController {
 
 	handleHotkeysCommand(): void {
 		const expandToolsKey = this.ctx.keybindings.getDisplayString("expandTools") || "Ctrl+O";
+		const planModeKey = this.ctx.keybindings.getDisplayString("togglePlanMode") || "Alt+Shift+P";
 		const hotkeys = `
 **Navigation**
 | Key | Action |
@@ -370,6 +371,7 @@ export class CommandController {
 | \`Shift+Ctrl+P\` | Cycle role models (temporary) |
 | \`Alt+P\` | Select model (temporary) |
 | \`Ctrl+L\` | Select model (set roles) |
+| \`${planModeKey}\` | Toggle plan mode |
 | \`Ctrl+R\` | Search prompt history |
 | \`${expandToolsKey}\` | Toggle tool output expansion |
 | \`Ctrl+T\` | Toggle todo list expansion |
@@ -626,6 +628,46 @@ export class CommandController {
 		}
 		await this.ctx.flushCompactionQueue({ willRetry: false });
 	}
+
+	async handleHandoffCommand(customInstructions?: string): Promise<void> {
+		const entries = this.ctx.sessionManager.getEntries();
+		const messageCount = entries.filter(e => e.type === "message").length;
+
+		if (messageCount < 2) {
+			this.ctx.showWarning("Nothing to hand off (no messages yet)");
+			return;
+		}
+
+		try {
+			// The agent will visibly generate the handoff document in chat
+			const result = await this.ctx.session.handoff(customInstructions);
+
+			if (!result) {
+				this.ctx.showError("Handoff cancelled");
+				return;
+			}
+
+			// Rebuild chat from the new session (which now contains the handoff document)
+			this.ctx.rebuildChatFromMessages();
+
+			this.ctx.statusLine.invalidate();
+			this.ctx.updateEditorTopBorder();
+			await this.ctx.reloadTodos();
+
+			this.ctx.chatContainer.addChild(new Spacer(1));
+			this.ctx.chatContainer.addChild(
+				new Text(`${theme.fg("accent", `${theme.status.success} New session started with handoff context`)}`, 1, 1),
+			);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			if (message === "Handoff cancelled" || (error instanceof Error && error.name === "AbortError")) {
+				this.ctx.showError("Handoff cancelled");
+			} else {
+				this.ctx.showError(`Handoff failed: ${message}`);
+			}
+		}
+		this.ctx.ui.requestRender();
+	}
 }
 
 const BAR_WIDTH = 24;

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

@@ -7,6 +7,7 @@ import { TtsrNotificationComponent } from "../../modes/components/ttsr-notificat
 import { getSymbolTheme, theme } from "../../modes/theme/theme";
 import type { InteractiveModeContext, TodoItem } from "../../modes/types";
 import type { AgentSessionEvent } from "../../session/agent-session";
+import type { ExitPlanModeDetails } from "../../tools";
 import { detectNotificationProtocol, isNotificationSuppressed, sendNotification } from "../../utils/terminal-notify";
 
 export class EventController {
@@ -246,6 +247,18 @@ export class EventController {
 						this.ctx.setTodos(details.todos);
 					}
 				}
+				if (event.toolName === "enter_plan_mode" && !event.isError) {
+					const details = event.result.details as import("../../tools").EnterPlanModeDetails | undefined;
+					if (details) {
+						await this.ctx.handleEnterPlanModeTool(details);
+					}
+				}
+				if (event.toolName === "exit_plan_mode" && !event.isError) {
+					const details = event.result.details as ExitPlanModeDetails | undefined;
+					if (details) {
+						await this.ctx.handleExitPlanModeTool(details);
+					}
+				}
 				break;
 			}
 

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

@@ -88,6 +88,11 @@ export class InputController {
 			this.ctx.editor.setCustomKeyHandler(key, () => this.handleDequeue());
 		}
 
+		const planModeKeys = this.ctx.keybindings.getKeys("togglePlanMode");
+		for (const key of planModeKeys) {
+			this.ctx.editor.setCustomKeyHandler(key, () => void this.ctx.handlePlanModeCommand());
+		}
+
 		this.ctx.editor.onChange = (text: string) => {
 			const wasBashMode = this.ctx.isBashMode;
 			const wasPythonMode = this.ctx.isPythonMode;
@@ -180,6 +185,11 @@ export class InputController {
 				this.ctx.editor.setText("");
 				return;
 			}
+			if (text === "/plan") {
+				await this.ctx.handlePlanModeCommand();
+				this.ctx.editor.setText("");
+				return;
+			}
 			if (text === "/model" || text === "/models") {
 				this.ctx.showModelSelector();
 				this.ctx.editor.setText("");
@@ -265,6 +275,12 @@ export class InputController {
 				await this.ctx.handleCompactCommand(customInstructions);
 				return;
 			}
+			if (text === "/handoff" || text.startsWith("/handoff ")) {
+				const customInstructions = text.startsWith("/handoff ") ? text.slice(9).trim() : undefined;
+				this.ctx.editor.setText("");
+				await this.ctx.handleHandoffCommand(customInstructions);
+				return;
+			}
 			if (text === "/background" || text === "/bg") {
 				this.ctx.editor.setText("");
 				this.handleBackgroundCommand();

package/src/modes/interactive-mode.ts

@@ -4,7 +4,8 @@
  */
 import * as path from "node:path";
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
-import type { AssistantMessage, ImageContent, Message, UsageReport } from "@oh-my-pi/pi-ai";
+import type { AssistantMessage, ImageContent, Message, Model, UsageReport } from "@oh-my-pi/pi-ai";
+import { resolvePlanUrlToPath } from "@oh-my-pi/pi-coding-agent/internal-urls";
 import type { Component, Loader, SlashCommand } from "@oh-my-pi/pi-tui";
 import {
 	CombinedAutocompleteProvider,
@@ -18,14 +19,17 @@ import {
 import { isEnoent, logger, postmortem } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import { KeybindingsManager } from "../config/keybindings";
+import { renderPromptTemplate } from "../config/prompt-templates";
 import type { SettingsManager } from "../config/settings-manager";
 import type { ExtensionUIContext } from "../extensibility/extensions";
 import type { CompactOptions } from "../extensibility/extensions/types";
 import { loadSlashCommands } from "../extensibility/slash-commands";
+import planModeApprovedPrompt from "../prompts/system/plan-mode-approved.md" with { type: "text" };
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
 import { getRecentSessions } from "../session/session-manager";
+import type { EnterPlanModeDetails, ExitPlanModeDetails } from "../tools";
 import { setTerminalTitle } from "../utils/title-generator";
 import type { AssistantMessageComponent } from "./components/assistant-message";
 import type { BashExecutionComponent } from "./components/bash-execution";
@@ -87,6 +91,9 @@ export class InteractiveMode implements InteractiveModeContext {
 	public isBashMode = false;
 	public toolOutputExpanded = false;
 	public todoExpanded = false;
+	public planModeEnabled = false;
+	public planModePaused = false;
+	public planModePlanFilePath: string | undefined = undefined;
 	public todoItems: TodoItem[] = [];
 	public hideThinkingBlock = false;
 	public pendingImages: ImageContent[] = [];
@@ -124,6 +131,9 @@ export class InteractiveMode implements InteractiveModeContext {
 	private cleanupUnsubscribe?: () => void;
 	private readonly version: string;
 	private readonly changelogMarkdown: string | undefined;
+	private planModePreviousTools: string[] | undefined;
+	private planModePreviousModel: Model<any> | undefined;
+	private planModeHasEntered = false;
 	public readonly lspServers: Array<{ name: string; status: "ready" | "error"; fileTypes: string[] }> | undefined =
 		undefined;
 	public mcpManager?: import("@oh-my-pi/pi-coding-agent/mcp").MCPManager;
@@ -185,6 +195,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		// Define slash commands for autocomplete
 		const slashCommands: SlashCommand[] = [
 			{ name: "settings", description: "Open settings menu" },
+			{ name: "plan", description: "Toggle plan mode (agent plans before executing)" },
 			{ name: "model", description: "Select model (opens selector UI)" },
 			{ name: "export", description: "Export session to HTML file" },
 			{ name: "dump", description: "Copy session transcript to clipboard" },
@@ -202,6 +213,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			{ name: "logout", description: "Logout from OAuth provider" },
 			{ name: "new", description: "Start a new session" },
 			{ name: "compact", description: "Manually compact the session context" },
+			{ name: "handoff", description: "Hand off the session context to a new session" },
 			{ name: "background", description: "Detach UI and continue running in background" },
 			{ name: "bg", description: "Alias for /background" },
 			{ name: "resume", description: "Resume a different session" },
@@ -469,6 +481,208 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.renderTodoList();
 	}
 
+	private getPlanFilePath(): string {
+		const sessionId = this.sessionManager.getSessionId();
+		return `plan://${sessionId}/plan.md`;
+	}
+
+	private resolvePlanFilePath(planFilePath: string): string {
+		if (planFilePath.startsWith("plan://")) {
+			return resolvePlanUrlToPath(planFilePath, {
+				getPlansDirectory: this.settingsManager.getPlansDirectory.bind(this.settingsManager),
+				cwd: this.sessionManager.getCwd(),
+			});
+		}
+		return planFilePath;
+	}
+
+	private updatePlanModeStatus(): void {
+		const status =
+			this.planModeEnabled || this.planModePaused
+				? {
+						enabled: this.planModeEnabled,
+						paused: this.planModePaused,
+					}
+				: undefined;
+		this.statusLine.setPlanModeStatus(status);
+		this.updateEditorTopBorder();
+		this.ui.requestRender();
+	}
+
+	private async applyPlanModeModel(): Promise<void> {
+		const slowModel = this.session.resolveRoleModel("slow");
+		if (!slowModel) return;
+		const currentModel = this.session.model;
+		if (currentModel && currentModel.provider === slowModel.provider && currentModel.id === slowModel.id) {
+			return;
+		}
+		this.planModePreviousModel = currentModel;
+		try {
+			await this.session.setModelTemporary(slowModel);
+		} catch (error) {
+			this.showWarning(
+				`Failed to switch to slow model for plan mode: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+
+	private async enterPlanMode(options?: {
+		planFilePath?: string;
+		workflow?: "parallel" | "iterative";
+	}): Promise<void> {
+		if (this.planModeEnabled) {
+			return;
+		}
+
+		this.planModePaused = false;
+
+		const planFilePath = options?.planFilePath ?? this.getPlanFilePath();
+		const previousTools = this.session.getActiveToolNames();
+		const hasExitTool = this.session.getToolByName("exit_plan_mode") !== undefined;
+		const planTools = hasExitTool ? [...previousTools, "exit_plan_mode"] : previousTools;
+		const uniquePlanTools = [...new Set(planTools)];
+
+		this.planModePreviousTools = previousTools;
+		this.planModePlanFilePath = planFilePath;
+		this.planModeEnabled = true;
+
+		await this.session.setActiveToolsByName(uniquePlanTools);
+		this.session.setPlanModeState({
+			enabled: true,
+			planFilePath,
+			workflow: options?.workflow ?? "parallel",
+			reentry: this.planModeHasEntered,
+		});
+		this.planModeHasEntered = true;
+		await this.applyPlanModeModel();
+		this.updatePlanModeStatus();
+		this.showStatus(`Plan mode enabled. Plan file: ${planFilePath}`);
+	}
+
+	private async exitPlanMode(options?: { silent?: boolean; paused?: boolean }): Promise<void> {
+		if (!this.planModeEnabled) {
+			return;
+		}
+
+		const previousTools = this.planModePreviousTools;
+		if (previousTools && previousTools.length > 0) {
+			await this.session.setActiveToolsByName(previousTools);
+		}
+		if (this.planModePreviousModel) {
+			await this.session.setModelTemporary(this.planModePreviousModel);
+		}
+
+		this.session.setPlanModeState(undefined);
+		this.planModeEnabled = false;
+		this.planModePaused = options?.paused ?? false;
+		this.planModePlanFilePath = undefined;
+		this.planModePreviousTools = undefined;
+		this.planModePreviousModel = undefined;
+		this.updatePlanModeStatus();
+		if (!options?.silent) {
+			this.showStatus(this.planModePaused ? "Plan mode paused." : "Plan mode disabled.");
+		}
+	}
+
+	private async readPlanFile(planFilePath: string): Promise<string | null> {
+		const resolvedPath = this.resolvePlanFilePath(planFilePath);
+		try {
+			return await Bun.file(resolvedPath).text();
+		} catch (error) {
+			if (isEnoent(error)) {
+				return null;
+			}
+			throw error;
+		}
+	}
+
+	private renderPlanPreview(planContent: string): void {
+		this.chatContainer.addChild(new Spacer(1));
+		this.chatContainer.addChild(new DynamicBorder());
+		this.chatContainer.addChild(new Text(theme.bold(theme.fg("accent", "Plan Review")), 1, 1));
+		this.chatContainer.addChild(new Spacer(1));
+		this.chatContainer.addChild(new Markdown(planContent, 1, 1, getMarkdownTheme()));
+		this.chatContainer.addChild(new DynamicBorder());
+		this.ui.requestRender();
+	}
+
+	private async approvePlan(planContent: string): Promise<void> {
+		const previousTools = this.planModePreviousTools ?? this.session.getActiveToolNames();
+		await this.exitPlanMode({ silent: true, paused: false });
+		await this.handleClearCommand();
+		if (previousTools.length > 0) {
+			await this.session.setActiveToolsByName(previousTools);
+		}
+		this.session.markPlanReferenceSent();
+		const prompt = renderPromptTemplate(planModeApprovedPrompt, { planContent });
+		await this.session.prompt(prompt);
+	}
+
+	async handlePlanModeCommand(): Promise<void> {
+		if (this.planModeEnabled) {
+			const confirmed = await this.showHookConfirm(
+				"Exit plan mode?",
+				"This exits plan mode without approving a plan.",
+			);
+			if (!confirmed) return;
+			await this.exitPlanMode({ paused: true });
+			return;
+		}
+		await this.enterPlanMode();
+	}
+
+	async handleEnterPlanModeTool(details: EnterPlanModeDetails): Promise<void> {
+		if (this.planModeEnabled) {
+			this.showWarning("Plan mode is already active.");
+			return;
+		}
+
+		const confirmed = await this.showHookConfirm(
+			"Enter plan mode?",
+			"This enables read-only planning and creates a plan file for approval.",
+		);
+		if (!confirmed) {
+			return;
+		}
+
+		const planFilePath = details.planFilePath || this.getPlanFilePath();
+		this.planModePlanFilePath = planFilePath;
+		await this.enterPlanMode({ planFilePath, workflow: details.workflow });
+	}
+
+	async handleExitPlanModeTool(details: ExitPlanModeDetails): Promise<void> {
+		if (!this.planModeEnabled) {
+			this.showWarning("Plan mode is not active.");
+			return;
+		}
+
+		const planFilePath = details.planFilePath || this.planModePlanFilePath || this.getPlanFilePath();
+		this.planModePlanFilePath = planFilePath;
+		const planContent = await this.readPlanFile(planFilePath);
+		if (!planContent) {
+			this.showError(`Plan file not found at ${planFilePath}`);
+			return;
+		}
+
+		this.renderPlanPreview(planContent);
+		const choice = await this.showHookSelector("Plan mode - next step", [
+			"Approve and execute",
+			"Refine plan",
+			"Stay in plan mode",
+		]);
+
+		if (choice === "Approve and execute") {
+			await this.approvePlan(planContent);
+			return;
+		}
+		if (choice === "Refine plan") {
+			const refinement = await this.showHookInput("What should be refined?");
+			if (refinement) {
+				this.editor.setText(refinement);
+			}
+		}
+	}
+
 	stop(): void {
 		if (this.loadingAnimation) {
 			this.loadingAnimation.stop();
@@ -680,6 +894,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.commandController.handleCompactCommand(customInstructions);
 	}
 
+	handleHandoffCommand(customInstructions?: string): Promise<void> {
+		return this.commandController.handleHandoffCommand(customInstructions);
+	}
+
 	executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<void> {
 		return this.commandController.executeCompaction(customInstructionsOrOptions, isAuto);
 	}

package/src/modes/theme/theme.ts

@@ -81,6 +81,7 @@ export type SymbolKey =
 	| "sep.pipe"
 	// Icons
 	| "icon.model"
+	| "icon.plan"
 	| "icon.folder"
 	| "icon.file"
 	| "icon.git"
@@ -278,6 +279,8 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	// Icons
 	// pick: ◈ | alt: ◆ ⬢ ◇
 	"icon.model": "◈",
+	// pick: 📋 | alt: 🗒 📝
+	"icon.plan": "📋",
 	// pick: 📁 | alt: 📂 🗂 🗃
 	"icon.folder": "📁",
 	// pick: 📄 | alt: 📃 📝
@@ -517,6 +520,8 @@ const NERD_SYMBOLS: SymbolMap = {
 	// Icons - Nerd Font specific
 	// pick:  | alt:   ◆
 	"icon.model": "\uec19",
+	// pick:  | alt:  
+	"icon.plan": "\uf2d2",
 	// pick:  | alt:  
 	"icon.folder": "\uf115",
 	// pick:  | alt:  
@@ -705,6 +710,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"sep.pipe": " | ",
 	// Icons
 	"icon.model": "[M]",
+	"icon.plan": "plan",
 	"icon.folder": "[D]",
 	"icon.file": "[F]",
 	"icon.git": "git:",
@@ -1397,6 +1403,7 @@ export class Theme {
 	get icon() {
 		return {
 			model: this.symbols["icon.model"],
+			plan: this.symbols["icon.plan"],
 			folder: this.symbols["icon.folder"],
 			file: this.symbols["icon.file"],
 			git: this.symbols["icon.git"],

package/src/modes/types.ts

@@ -9,6 +9,7 @@ import type { MCPManager } from "../mcp";
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import type { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
+import type { ExitPlanModeDetails } from "../tools";
 import type { AssistantMessageComponent } from "./components/assistant-message";
 import type { BashExecutionComponent } from "./components/bash-execution";
 import type { CustomEditor } from "./components/custom-editor";
@@ -58,6 +59,8 @@ export interface InteractiveModeContext {
 	isBashMode: boolean;
 	toolOutputExpanded: boolean;
 	todoExpanded: boolean;
+	planModeEnabled: boolean;
+	planModePlanFilePath?: string;
 	hideThinkingBlock: boolean;
 	pendingImages: ImageContent[];
 	compactionQueuedMessages: CompactionQueuedMessage[];
@@ -145,6 +148,7 @@ export interface InteractiveModeContext {
 	handleBashCommand(command: string, excludeFromContext?: boolean): Promise<void>;
 	handlePythonCommand(code: string, excludeFromContext?: boolean): Promise<void>;
 	handleCompactCommand(customInstructions?: string): Promise<void>;
+	handleHandoffCommand(customInstructions?: string): Promise<void>;
 	executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<void>;
 	openInBrowser(urlOrPath: string): void;
 
@@ -173,6 +177,9 @@ export interface InteractiveModeContext {
 	toggleThinkingBlockVisibility(): void;
 	openExternalEditor(): void;
 	registerExtensionShortcuts(): void;
+	handlePlanModeCommand(): Promise<void>;
+	handleEnterPlanModeTool(details: import("../tools").EnterPlanModeDetails): Promise<void>;
+	handleExitPlanModeTool(details: ExitPlanModeDetails): Promise<void>;
 
 	// Hook UI methods
 	initHooksAndCustomTools(): Promise<void>;