@oh-my-pi/pi-coding-agent 12.19.3 → 13.0.1

package/src/session/agent-session.ts

@@ -75,7 +75,7 @@ import { ExtensionToolWrapper } from "../extensibility/extensions/wrapper";
 import type { HookCommandContext } from "../extensibility/hooks/types";
 import type { Skill, SkillWarning } from "../extensibility/skills";
 import { expandSlashCommand, type FileSlashCommand } from "../extensibility/slash-commands";
-import { resolvePlanUrlToPath } from "../internal-urls";
+import { resolveLocalUrlToPath } from "../internal-urls";
 import { executePython as executePythonCommand, type PythonResult } from "../ipy/executor";
 import { getCurrentThemeName, theme } from "../modes/theme/theme";
 import { normalizeDiff, normalizeToLF, ParseError, previewPatch, stripBom } from "../patch";
@@ -88,7 +88,7 @@ import { closeAllConnections } from "../ssh/connection-manager";
 import { unmountAll } from "../ssh/sshfs-mount";
 import { outputMeta } from "../tools/output-meta";
 import { resolveToCwd } from "../tools/path-utils";
-import type { TodoItem } from "../tools/todo-write";
+import { getLatestTodoPhasesFromEntries, type TodoItem, type TodoPhase } from "../tools/todo-write";
 import { parseCommandArgs } from "../utils/command-args";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import { extractFileMentions, generateFileMentionMessages } from "../utils/file-mentions";
@@ -135,7 +135,6 @@ export type AgentSessionEvent =
 
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
-
 export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime">;
 
 export interface AsyncJobSnapshot {
@@ -192,7 +191,7 @@ export interface PromptOptions {
 	streamingBehavior?: "steer" | "followUp";
 	/** Optional tool choice override for the next LLM call. */
 	toolChoice?: ToolChoice;
-	/** Mark the user message as synthetic (system-injected). */
+	/** Send as developer/system message instead of user. Providers that support it use the developer role; others fall back to user. */
 	synthetic?: boolean;
 }
 
@@ -310,6 +309,7 @@ export class AgentSession {
 	#pendingNextTurnMessages: CustomMessage[] = [];
 	#planModeState: PlanModeState | undefined;
 	#planReferenceSent = false;
+	#planReferencePath = "local://PLAN.md";
 
 	// Compaction state
 	#compactionAbortController: AbortController | undefined = undefined;
@@ -330,6 +330,7 @@ export class AgentSession {
 
 	// Todo completion reminder state
 	#todoReminderCount = 0;
+	#todoPhases: TodoPhase[] = [];
 
 	// Bash execution state
 	#bashAbortController: AbortController | undefined = undefined;
@@ -395,6 +396,7 @@ export class AgentSession {
 		this.#forceCopilotAgentInitiator = config.forceCopilotAgentInitiator ?? false;
 		this.#obfuscator = config.obfuscator;
 		this.agent.providerSessionState = this.#providerSessionState;
+		this.#syncTodoPhasesFromBranch();
 
 		// Always subscribe to agent events for internal handling
 		// (session persistence, hooks, auto-compaction, retry logic)
@@ -602,6 +604,7 @@ export class AgentSession {
 				}
 			} else if (
 				event.message.role === "user" ||
+				event.message.role === "developer" ||
 				event.message.role === "assistant" ||
 				event.message.role === "toolResult" ||
 				event.message.role === "fileMention"
@@ -638,7 +641,7 @@ export class AgentSession {
 				const { toolName, $normative, toolCallId, details, isError, content } = event.message as {
 					toolName?: string;
 					toolCallId?: string;
-					details?: { path?: string };
+					details?: { path?: string; phases?: TodoPhase[] };
 					$normative?: Record<string, unknown>;
 					isError?: boolean;
 					content?: Array<TextContent | ImageContent>;
@@ -650,14 +653,17 @@ export class AgentSession {
 				if (toolName === "edit" && details?.path) {
 					this.#invalidateFileCacheForPath(details.path);
 				}
+				if (toolName === "todo_write" && !isError && Array.isArray(details?.phases)) {
+					this.setTodoPhases(details.phases);
+				}
 				if (toolName === "todo_write" && isError) {
 					const errorText = content?.find(part => part.type === "text")?.text;
 					const reminderText = [
-						"<system_reminder>",
+						"<system-reminder>",
 						"todo_write failed, so todo progress is not visible to the user.",
 						errorText ? `Failure: ${errorText}` : "Failure: todo_write returned an error.",
 						"Fix the todo payload and call todo_write again before continuing.",
-						"</system_reminder>",
+						"</system-reminder>",
 					].join("\n");
 					await this.sendCustomMessage(
 						{
@@ -1491,6 +1497,7 @@ export class AgentSession {
 		this.#planModeState = state;
 		if (state?.enabled) {
 			this.#planReferenceSent = false;
+			this.#planReferencePath = state.planFilePath;
 		}
 	}
 
@@ -1498,6 +1505,10 @@ export class AgentSession {
 		this.#planReferenceSent = true;
 	}
 
+	setPlanReferencePath(path: string): void {
+		this.#planReferencePath = path;
+	}
+
 	/**
 	 * Inject the plan mode context message into the conversation history.
 	 */
@@ -1546,10 +1557,10 @@ export class AgentSession {
 		if (this.#planModeState?.enabled) return null;
 		if (this.#planReferenceSent) return null;
 
-		const planFilePath = `plan://${this.sessionManager.getSessionId()}/plan.md`;
-		const resolvedPlanPath = resolvePlanUrlToPath(planFilePath, {
-			getPlansDirectory: () => this.settings.getPlansDirectory(),
-			cwd: this.sessionManager.getCwd(),
+		const planFilePath = this.#planReferencePath;
+		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
+			getArtifactsDir: () => this.sessionManager.getArtifactsDir(),
+			getSessionId: () => this.sessionManager.getSessionId(),
 		});
 		let planContent: string;
 		try {
@@ -1580,19 +1591,19 @@ export class AgentSession {
 	async #buildPlanModeMessage(): Promise<CustomMessage | null> {
 		const state = this.#planModeState;
 		if (!state?.enabled) return null;
-		const sessionPlanUrl = `plan://${this.sessionManager.getSessionId()}/plan.md`;
-		const resolvedPlanPath = state.planFilePath.startsWith("plan://")
-			? resolvePlanUrlToPath(state.planFilePath, {
-					getPlansDirectory: () => this.settings.getPlansDirectory(),
-					cwd: this.sessionManager.getCwd(),
+		const sessionPlanUrl = "local://PLAN.md";
+		const resolvedPlanPath = state.planFilePath.startsWith("local://")
+			? resolveLocalUrlToPath(state.planFilePath, {
+					getArtifactsDir: () => this.sessionManager.getArtifactsDir(),
+					getSessionId: () => this.sessionManager.getSessionId(),
 				})
 			: resolveToCwd(state.planFilePath, this.sessionManager.getCwd());
-		const resolvedSessionPlan = resolvePlanUrlToPath(sessionPlanUrl, {
-			getPlansDirectory: () => this.settings.getPlansDirectory(),
-			cwd: this.sessionManager.getCwd(),
+		const resolvedSessionPlan = resolveLocalUrlToPath(sessionPlanUrl, {
+			getArtifactsDir: () => this.sessionManager.getArtifactsDir(),
+			getSessionId: () => this.sessionManager.getSessionId(),
 		});
 		const displayPlanPath =
-			state.planFilePath.startsWith("plan://") || resolvedPlanPath !== resolvedSessionPlan
+			state.planFilePath.startsWith("local://") || resolvedPlanPath !== resolvedSessionPlan
 				? state.planFilePath
 				: sessionPlanUrl;
 
@@ -1673,16 +1684,11 @@ export class AgentSession {
 			userContent.push(...options.images);
 		}
 
-		await this.#promptWithMessage(
-			{
-				role: "user",
-				content: userContent,
-				synthetic: options?.synthetic,
-				timestamp: Date.now(),
-			},
-			expandedText,
-			options,
-		);
+		const message = options?.synthetic
+			? { role: "developer" as const, content: userContent, timestamp: Date.now() }
+			: { role: "user" as const, content: userContent, timestamp: Date.now() };
+
+		await this.#promptWithMessage(message, expandedText, options);
 	}
 
 	async promptCustomMessage<T = unknown>(
@@ -2185,6 +2191,31 @@ export class AgentSession {
 		return this.#skillWarnings;
 	}
 
+	getTodoPhases(): TodoPhase[] {
+		return this.#cloneTodoPhases(this.#todoPhases);
+	}
+
+	setTodoPhases(phases: TodoPhase[]): void {
+		this.#todoPhases = this.#cloneTodoPhases(phases);
+	}
+
+	#syncTodoPhasesFromBranch(): void {
+		this.setTodoPhases(getLatestTodoPhasesFromEntries(this.sessionManager.getBranch()));
+	}
+
+	#cloneTodoPhases(phases: TodoPhase[]): TodoPhase[] {
+		return phases.map(phase => ({
+			id: phase.id,
+			name: phase.name,
+			tasks: phase.tasks.map(task => ({
+				id: task.id,
+				content: task.content,
+				status: task.status,
+				notes: task.notes,
+			})),
+		}));
+	}
+
 	/**
 	 * Abort current operation and wait for agent to become idle.
 	 */
@@ -2228,6 +2259,7 @@ export class AgentSession {
 		this.agent.reset();
 		await this.sessionManager.flush();
 		await this.sessionManager.newSession(options);
+		this.setTodoPhases([]);
 		this.agent.sessionId = this.sessionManager.getSessionId();
 		this.#steeringMessages = [];
 		this.#followUpMessages = [];
@@ -2237,6 +2269,7 @@ export class AgentSession {
 
 		this.#todoReminderCount = 0;
 		this.#planReferenceSent = false;
+		this.#planReferencePath = "local://PLAN.md";
 		this.#reconnectToAgent();
 
 		// Emit session_switch event with reason "new" to hooks
@@ -2645,6 +2678,7 @@ export class AgentSession {
 		await this.sessionManager.rewriteEntries();
 		const sessionContext = this.sessionManager.buildSessionContext();
 		this.agent.replaceMessages(sessionContext.messages);
+		this.#syncTodoPhasesFromBranch();
 		this.#closeCodexProviderSessionsForHistoryRewrite();
 		return result;
 	}
@@ -2769,6 +2803,7 @@ export class AgentSession {
 			const newEntries = this.sessionManager.getEntries();
 			const sessionContext = this.sessionManager.buildSessionContext();
 			this.agent.replaceMessages(sessionContext.messages);
+			this.#syncTodoPhasesFromBranch();
 			this.#closeCodexProviderSessionsForHistoryRewrite();
 
 			// Get the saved compaction entry for the hook
@@ -2925,7 +2960,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 
 		try {
 			// Send the prompt and wait for completion
-			await this.prompt(handoffPrompt, { expandPromptTemplates: false });
+			await this.prompt(handoffPrompt, { expandPromptTemplates: false, synthetic: true });
 			await completionPromise;
 
 			if (!handoffText || this.#handoffAbortController.signal.aborted) {
@@ -2950,6 +2985,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			// Rebuild agent messages from session
 			const sessionContext = this.sessionManager.buildSessionContext();
 			this.agent.replaceMessages(sessionContext.messages);
+			this.#syncTodoPhasesFromBranch();
 
 			return { document: handoffText };
 		} finally {
@@ -3047,25 +3083,24 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			return;
 		}
 
-		// Load current todos from artifacts
-		const sessionFile = this.sessionManager.getSessionFile();
-		if (!sessionFile) return;
-
-		const todoPath = `${sessionFile.slice(0, -6)}/todos.json`;
-
-		let todos: TodoItem[];
-		try {
-			const data = await Bun.file(todoPath).json();
-			todos = data?.todos ?? [];
-		} catch (err) {
-			if (isEnoent(err)) {
-				this.#todoReminderCount = 0;
-			}
+		const phases = this.getTodoPhases();
+		if (phases.length === 0) {
+			this.#todoReminderCount = 0;
 			return;
 		}
 
-		// Check for incomplete todos
-		const incomplete = todos.filter(t => t.status !== "completed");
+		const incompleteByPhase = phases
+			.map(phase => ({
+				name: phase.name,
+				tasks: phase.tasks
+					.filter(
+						(task): task is TodoItem & { status: "pending" | "in_progress" } =>
+							task.status === "pending" || task.status === "in_progress",
+					)
+					.map(task => ({ id: task.id, content: task.content, status: task.status })),
+			}))
+			.filter(phase => phase.tasks.length > 0);
+		const incomplete = incompleteByPhase.flatMap(phase => phase.tasks);
 		if (incomplete.length === 0) {
 			this.#todoReminderCount = 0;
 			return;
@@ -3073,13 +3108,15 @@ Be thorough - include exact file paths, function names, error messages, and tech
 
 		// Build reminder message
 		this.#todoReminderCount++;
-		const todoList = incomplete.map(t => `- ${t.content}`).join("\n");
+		const todoList = incompleteByPhase
+			.map(phase => `- ${phase.name}\n${phase.tasks.map(task => `  - ${task.content}`).join("\n")}`)
+			.join("\n");
 		const reminder =
-			`<system_reminder>\n` +
+			`<system-reminder>\n` +
 			`You stopped with ${incomplete.length} incomplete todo item(s):\n${todoList}\n\n` +
 			`Please continue working on these tasks or mark them complete if finished.\n` +
 			`(Reminder ${this.#todoReminderCount}/${remindersMax})\n` +
-			`</system_reminder>`;
+			`</system-reminder>`;
 
 		logger.debug("Todo completion: sending reminder", {
 			incomplete: incomplete.length,
@@ -3096,7 +3133,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 
 		// Inject reminder and continue the conversation
 		this.agent.appendMessage({
-			role: "user",
+			role: "developer",
 			content: [{ type: "text", text: reminder }],
 			timestamp: Date.now(),
 		});
@@ -3482,6 +3519,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			const newEntries = this.sessionManager.getEntries();
 			const sessionContext = this.sessionManager.buildSessionContext();
 			this.agent.replaceMessages(sessionContext.messages);
+			this.#syncTodoPhasesFromBranch();
 			this.#closeCodexProviderSessionsForHistoryRewrite();
 
 			// Get the saved compaction entry for the hook
@@ -4054,6 +4092,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 		}
 
 		this.agent.replaceMessages(sessionContext.messages);
+		this.#syncTodoPhasesFromBranch();
 
 		// Restore model if saved
 		const defaultModelStr = sessionContext.models.default;
@@ -4135,6 +4174,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 		} else {
 			this.sessionManager.createBranchedSession(selectedEntry.parentId);
 		}
+		this.#syncTodoPhasesFromBranch();
 		this.agent.sessionId = this.sessionManager.getSessionId();
 
 		// Reload messages from entries (works for both file and in-memory mode)
@@ -4303,6 +4343,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 		// Update agent state
 		const sessionContext = this.sessionManager.buildSessionContext();
 		this.agent.replaceMessages(sessionContext.messages);
+		this.#syncTodoPhasesFromBranch();
 
 		// Emit session_tree event
 		if (this.#extensionRunner) {

package/src/session/artifacts.ts

@@ -2,7 +2,7 @@
  * Session-scoped artifact storage for truncated tool outputs.
  *
  * Artifacts are stored in a directory alongside the session file,
- * accessible via artifact:// URLs or the $ARTIFACTS environment variable.
+ * accessible via artifact:// URLs.
  */
 import * as fs from "node:fs/promises";
 import * as path from "node:path";

package/src/session/messages.ts

@@ -300,6 +300,7 @@ export function convertToLlm(messages: AgentMessage[]): Message[] {
 					};
 				}
 				case "user":
+				case "developer":
 				case "assistant":
 					return m;
 				case "toolResult":

package/src/task/agents.ts

@@ -22,6 +22,7 @@ interface AgentFrontmatter {
 	spawns?: string;
 	model?: string | string[];
 	thinkingLevel?: string;
+	blocking?: boolean;
 }
 
 interface EmbeddedAgentDef {

package/src/task/index.ts

@@ -179,7 +179,8 @@ export class TaskTool implements AgentTool<TaskSchema, TaskToolDetails, Theme> {
 		onUpdate?: AgentToolUpdateCallback<TaskToolDetails>,
 	): Promise<AgentToolResult<TaskToolDetails>> {
 		const asyncEnabled = this.session.settings.get("async.enabled");
-		if (!asyncEnabled) {
+		const selectedAgent = this.#discoveredAgents.find(agent => agent.name === params.agent);
+		if (!asyncEnabled || selectedAgent?.blocking === true) {
 			return this.#executeSync(_toolCallId, params, signal, onUpdate);
 		}
 

package/src/task/render.ts

@@ -366,9 +366,9 @@ function renderTaskSection(
 	const trimmed = task.trimEnd();
 	if (!expanded || !trimmed) return lines;
 
-	// Strip the shared <swarm_context>...</swarm_context> block — it's the same
+	// Strip the shared <context>...</context> block — it's the same
 	// across all tasks and just adds noise when expanded.
-	const stripped = trimmed.replace(/<swarm_context>[\s\S]*?<\/swarm_context>\s*/, "").trimStart();
+	const stripped = trimmed.replace(/<context>[\s\S]*?<\/context>\s*/, "").trimStart();
 	if (!stripped) return lines;
 
 	lines.push(`${continuePrefix}${theme.fg("dim", "Task")}`);

package/src/task/types.ts

@@ -127,6 +127,7 @@ export interface AgentDefinition {
 	model?: string[];
 	thinkingLevel?: ThinkingLevel;
 	output?: unknown;
+	blocking?: boolean;
 	source: AgentSource;
 	filePath?: string;
 }

package/src/tools/bash-interactive.ts

@@ -275,7 +275,7 @@ class BashInteractiveOverlayComponent implements Component {
 	}
 }
 
-const NO_PAGER_ENV = {
+export const NO_PAGER_ENV = {
 	// Disable pagers so commands don't block on interactive views.
 	PAGER: "cat",
 	GIT_PAGER: "cat",

package/src/tools/bash-skill-urls.ts

@@ -22,6 +22,7 @@ interface InternalUrlResolver {
 
 export interface InternalUrlExpansionOptions {
 	skills: readonly Skill[];
+	noEscape?: boolean;
 	internalRouter?: InternalUrlResolver;
 }
 
@@ -152,7 +153,7 @@ export function expandSkillUrls(command: string, skills: readonly Skill[]): stri
 
 /**
  * Expand supported internal URLs in a bash command string to shell-escaped absolute paths.
- * Supported schemes: skill://, agent://, artifact://, plan://, memory://, rule://
+ * Supported schemes: skill://, agent://, artifact://, memory://, rule://, local://
  */
 export async function expandInternalUrls(command: string, options: InternalUrlExpansionOptions): Promise<string> {
 	if (!command.includes("://")) return command;
@@ -169,7 +170,7 @@ export async function expandInternalUrls(command: string, options: InternalUrlEx
 
 		const url = unquoteToken(token);
 		const resolvedPath = await resolveInternalUrlToPath(url, options.skills, options.internalRouter);
-		const replacement = shellEscape(resolvedPath);
+		const replacement = options.noEscape ? resolvedPath : shellEscape(resolvedPath);
 		expanded = `${expanded.slice(0, index)}${replacement}${expanded.slice(index + token.length)}`;
 	}
 

package/src/tools/bash.ts

@@ -16,10 +16,10 @@ import { DEFAULT_MAX_BYTES, TailBuffer } from "../session/streaming-output";
 import { renderStatusLine } from "../tui";
 import { CachedOutputBlock } from "../tui/output-block";
 import type { ToolSession } from ".";
-import { type BashInteractiveResult, runInteractiveBashPty } from "./bash-interactive";
+import { type BashInteractiveResult, NO_PAGER_ENV, runInteractiveBashPty } from "./bash-interactive";
 import { checkBashInterception } from "./bash-interceptor";
 import { applyHeadTail } from "./bash-normalize";
-import { expandInternalUrls } from "./bash-skill-urls";
+import { expandInternalUrls, type InternalUrlExpansionOptions } from "./bash-skill-urls";
 import { formatStyledTruncationWarning, type OutputMeta } from "./output-meta";
 import { resolveToCwd } from "./path-utils";
 import { replaceTabs } from "./render-utils";
@@ -144,6 +144,14 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 	): Promise<AgentToolResult<BashToolDetails>> {
 		let command = rawCommand;
 
+		// Extract leading `cd <path> && ...` into cwd when the model ignores the cwd parameter.
+		if (!cwd) {
+			const cdMatch = command.match(/^cd\s+((?:[^&\\]|\\.)+?)\s*&&\s*/);
+			if (cdMatch) {
+				cwd = cdMatch[1].trim().replace(/^["']|["']$/g, "");
+				command = command.slice(cdMatch[0].length);
+			}
+		}
 		if (asyncRequested && !this.#asyncEnabled) {
 			throw new ToolError("Async bash execution is disabled. Enable async.enabled to use async mode.");
 		}
@@ -161,10 +169,16 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			}
 		}
 
-		command = await expandInternalUrls(command, {
+		const internalUrlOptions: InternalUrlExpansionOptions = {
 			skills: this.session.skills ?? [],
 			internalRouter: this.session.internalRouter,
-		});
+		};
+		command = await expandInternalUrls(command, internalUrlOptions);
+
+		// Resolve protocol URLs (skill://, agent://, etc.) in extracted cwd.
+		if (cwd?.includes("://")) {
+			cwd = await expandInternalUrls(cwd, { ...internalUrlOptions, noEscape: true });
+		}
 
 		const commandCwd = cwd ? resolveToCwd(cwd, this.session.cwd) : this.session.cwd;
 		let cwdStat: fs.Stats;
@@ -195,8 +209,6 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				"bash",
 				label,
 				async ({ jobId, signal: runSignal, reportProgress }) => {
-					const artifactsDir = this.session.getArtifactsDir?.();
-					const extraEnv = artifactsDir ? { ARTIFACTS: artifactsDir } : undefined;
 					const { path: artifactPath, id: artifactId } =
 						(await this.session.allocateOutputArtifact?.("bash")) ?? {};
 					try {
@@ -205,7 +217,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 							sessionKey: `${this.session.getSessionId?.() ?? ""}:async:${jobId}`,
 							timeout: timeoutMs,
 							signal: runSignal,
-							env: extraEnv,
+							env: NO_PAGER_ENV,
 							artifactPath,
 							artifactId,
 							onChunk: chunk => {
@@ -238,9 +250,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		// Track output for streaming updates (tail only)
 		const tailBuffer = new TailBuffer(DEFAULT_MAX_BYTES);
 
-		// Set up artifacts environment and allocation
-		const artifactsDir = this.session.getArtifactsDir?.();
-		const extraEnv = artifactsDir ? { ARTIFACTS: artifactsDir } : undefined;
+		// Allocate artifact for truncated output storage
 		const { path: artifactPath, id: artifactId } = (await this.session.allocateOutputArtifact?.("bash")) ?? {};
 
 		const usePty = pty && $env.PI_NO_PTY !== "1" && ctx?.hasUI === true && ctx.ui !== undefined;
@@ -250,7 +260,6 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					cwd: commandCwd,
 					timeoutMs,
 					signal,
-					env: extraEnv,
 					artifactPath,
 					artifactId,
 				})
@@ -259,7 +268,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					sessionKey: this.session.getSessionId?.() ?? undefined,
 					timeout: timeoutMs,
 					signal,
-					env: extraEnv,
+					env: NO_PAGER_ENV,
 					artifactPath,
 					artifactId,
 					onChunk: chunk => {

package/src/tools/exit-plan-mode.ts

@@ -8,13 +8,36 @@ import type { ToolSession } from ".";
 import { resolvePlanPath } from "./plan-mode-guard";
 import { ToolError } from "./tool-errors";
 
-const exitPlanModeSchema = Type.Object({});
+const exitPlanModeSchema = Type.Object({
+	title: Type.String({ description: "Final plan title, e.g. WP_MIGRATION_PLAN" }),
+});
 
 type ExitPlanModeParams = Static<typeof exitPlanModeSchema>;
 
+function normalizePlanTitle(title: string): { title: string; fileName: string } {
+	const trimmed = title.trim();
+	if (!trimmed) {
+		throw new ToolError("Title is required and must not be empty.");
+	}
+
+	if (trimmed.includes("/") || trimmed.includes("\\") || trimmed.includes("..")) {
+		throw new ToolError("Title must not contain path separators or '..'.");
+	}
+
+	const withExtension = trimmed.toLowerCase().endsWith(".md") ? trimmed : `${trimmed}.md`;
+	if (!/^[A-Za-z0-9_-]+\.md$/.test(withExtension)) {
+		throw new ToolError("Title may only contain letters, numbers, underscores, or hyphens.");
+	}
+
+	const normalizedTitle = withExtension.slice(0, -3);
+	return { title: normalizedTitle, fileName: withExtension };
+}
+
 export interface ExitPlanModeDetails {
 	planFilePath: string;
 	planExists: boolean;
+	title: string;
+	finalPlanFilePath: string;
 }
 
 export class ExitPlanModeTool implements AgentTool<typeof exitPlanModeSchema, ExitPlanModeDetails> {
@@ -29,7 +52,7 @@ export class ExitPlanModeTool implements AgentTool<typeof exitPlanModeSchema, Ex
 
 	async execute(
 		_toolCallId: string,
-		_params: ExitPlanModeParams,
+		params: ExitPlanModeParams,
 		_signal?: AbortSignal,
 		_onUpdate?: AgentToolUpdateCallback<ExitPlanModeDetails>,
 		_context?: AgentToolContext,
@@ -39,7 +62,10 @@ export class ExitPlanModeTool implements AgentTool<typeof exitPlanModeSchema, Ex
 			throw new ToolError("Plan mode is not active.");
 		}
 
+		const normalized = normalizePlanTitle(params.title);
+		const finalPlanFilePath = `local://${normalized.fileName}`;
 		const resolvedPlanPath = resolvePlanPath(this.session, state.planFilePath);
+		resolvePlanPath(this.session, finalPlanFilePath);
 		let planExists = false;
 		try {
 			const stat = await fs.stat(resolvedPlanPath);
@@ -55,6 +81,8 @@ export class ExitPlanModeTool implements AgentTool<typeof exitPlanModeSchema, Ex
 			details: {
 				planFilePath: state.planFilePath,
 				planExists,
+				title: normalized.title,
+				finalPlanFilePath,
 			},
 		};
 	}