@oh-my-pi/pi-coding-agent 12.3.0 → 12.5.0

package/src/modes/interactive-mode.ts

@@ -15,7 +15,7 @@ import {
 	Text,
 	TUI,
 } from "@oh-my-pi/pi-tui";
-import { $env, isEnoent, logger, postmortem } from "@oh-my-pi/pi-utils";
+import { $env, hsvToRgb, isEnoent, logger, postmortem } from "@oh-my-pi/pi-utils";
 import { APP_NAME, getProjectDir } from "@oh-my-pi/pi-utils/dirs";
 import chalk from "chalk";
 import { KeybindingsManager } from "../config/keybindings";
@@ -30,6 +30,7 @@ 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 { STTController, type SttState } from "../stt";
 import type { ExitPlanModeDetails } from "../tools";
 import { setTerminalTitle } from "../utils/title-generator";
 import type { AssistantMessageComponent } from "./components/assistant-message";
@@ -152,6 +153,11 @@ export class InteractiveMode implements InteractiveModeContext {
 	readonly #inputController: InputController;
 	readonly #selectorController: SelectorController;
 	readonly #uiHelpers: UiHelpers;
+	#sttController: STTController | undefined;
+	#voiceAnimationInterval: NodeJS.Timeout | undefined;
+	#voiceHue = 0;
+	#voicePreviousShowHardwareCursor: boolean | null = null;
+	#voicePreviousUseTerminalCursor: boolean | null = null;
 
 	constructor(
 		session: AgentSession,
@@ -709,6 +715,11 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.loadingAnimation.stop();
 			this.loadingAnimation = undefined;
 		}
+		this.#cleanupMicAnimation();
+		if (this.#sttController) {
+			this.#sttController.dispose();
+			this.#sttController = undefined;
+		}
 		this.statusLine.dispose();
 		if (this.unsubscribe) {
 			this.unsubscribe();
@@ -923,6 +934,78 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.#commandController.handleMemoryCommand(text);
 	}
 
+	async handleSTTToggle(): Promise<void> {
+		if (!settings.get("stt.enabled")) {
+			this.showWarning("Speech-to-text is disabled. Enable it in settings: stt.enabled");
+			return;
+		}
+		if (!this.#sttController) {
+			this.#sttController = new STTController();
+		}
+		await this.#sttController.toggle(this.editor, {
+			showWarning: (msg: string) => this.showWarning(msg),
+			showStatus: (msg: string) => this.showStatus(msg),
+			onStateChange: (state: SttState) => {
+				if (state === "recording") {
+					this.#voicePreviousShowHardwareCursor = this.ui.getShowHardwareCursor();
+					this.#voicePreviousUseTerminalCursor = this.editor.getUseTerminalCursor();
+					this.ui.setShowHardwareCursor(false);
+					this.editor.setUseTerminalCursor(false);
+					this.#startMicAnimation();
+				} else if (state === "transcribing") {
+					this.#stopMicAnimation();
+					this.editor.cursorOverride = `\x1b[38;2;200;200;200m${theme.icon.mic}\x1b[0m`;
+					this.editor.cursorOverrideWidth = 1;
+				} else {
+					this.#cleanupMicAnimation();
+				}
+				this.updateEditorTopBorder();
+				this.ui.requestRender();
+			},
+		});
+	}
+
+	#updateMicIcon(): void {
+		const { r, g, b } = hsvToRgb({ h: this.#voiceHue, s: 0.9, v: 1.0 });
+		this.editor.cursorOverride = `\x1b[38;2;${r};${g};${b}m${theme.icon.mic}\x1b[0m`;
+		this.editor.cursorOverrideWidth = 1;
+	}
+
+	#startMicAnimation(): void {
+		if (this.#voiceAnimationInterval) return;
+		this.#voiceHue = 0;
+		this.#updateMicIcon();
+		this.#voiceAnimationInterval = setInterval(() => {
+			this.#voiceHue = (this.#voiceHue + 8) % 360;
+			this.#updateMicIcon();
+			this.ui.requestRender();
+		}, 60);
+	}
+
+	#stopMicAnimation(): void {
+		if (this.#voiceAnimationInterval) {
+			clearInterval(this.#voiceAnimationInterval);
+			this.#voiceAnimationInterval = undefined;
+		}
+	}
+
+	#cleanupMicAnimation(): void {
+		if (this.#voiceAnimationInterval) {
+			clearInterval(this.#voiceAnimationInterval);
+			this.#voiceAnimationInterval = undefined;
+		}
+		this.editor.cursorOverride = undefined;
+		this.editor.cursorOverrideWidth = undefined;
+		if (this.#voicePreviousShowHardwareCursor !== null) {
+			this.ui.setShowHardwareCursor(this.#voicePreviousShowHardwareCursor);
+			this.#voicePreviousShowHardwareCursor = null;
+		}
+		if (this.#voicePreviousUseTerminalCursor !== null) {
+			this.editor.setUseTerminalCursor(this.#voicePreviousUseTerminalCursor);
+			this.#voicePreviousUseTerminalCursor = null;
+		}
+	}
+
 	showDebugSelector(): void {
 		this.#selectorController.showDebugSelector();
 	}

package/src/modes/rpc/rpc-client.ts

@@ -207,6 +207,13 @@ export class RpcClient {
 		await this.#send({ type: "abort" });
 	}
 
+	/**
+	 * Abort current operation and immediately start a new turn with the given message.
+	 */
+	async abortAndPrompt(message: string, images?: ImageContent[]): Promise<void> {
+		await this.#send({ type: "abort_and_prompt", message, images });
+	}
+
 	/**
 	 * Start a new session, optionally with parent tracking.
 	 * @param parentSession - Optional parent session path for lineage tracking

package/src/modes/rpc/rpc-mode.ts

@@ -449,6 +449,14 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 				return success(id, "abort");
 			}
 
+			case "abort_and_prompt": {
+				await session.abort();
+				session
+					.prompt(command.message, { images: command.images })
+					.catch(e => output(error(id, "abort_and_prompt", e.message)));
+				return success(id, "abort_and_prompt");
+			}
+
 			case "new_session": {
 				const options = command.parentSession ? { parentSession: command.parentSession } : undefined;
 				const cancelled = !(await session.newSession(options));

package/src/modes/rpc/rpc-types.ts

@@ -20,6 +20,7 @@ export type RpcCommand =
 	| { id?: string; type: "steer"; message: string; images?: ImageContent[] }
 	| { id?: string; type: "follow_up"; message: string; images?: ImageContent[] }
 	| { id?: string; type: "abort" }
+	| { id?: string; type: "abort_and_prompt"; message: string; images?: ImageContent[] }
 	| { id?: string; type: "new_session"; parentSession?: string }
 
 	// State
@@ -94,6 +95,7 @@ export type RpcResponse =
 	| { id?: string; type: "response"; command: "steer"; success: true }
 	| { id?: string; type: "response"; command: "follow_up"; success: true }
 	| { id?: string; type: "response"; command: "abort"; success: true }
+	| { id?: string; type: "response"; command: "abort_and_prompt"; success: true }
 	| { id?: string; type: "response"; command: "new_session"; success: true; data: { cancelled: boolean } }
 
 	// State

package/src/modes/theme/theme.ts

@@ -114,6 +114,8 @@ export type SymbolKey =
 	| "icon.extensionPrompt"
 	| "icon.extensionContextFile"
 	| "icon.extensionInstruction"
+	// STT
+	| "icon.mic"
 	// Thinking Levels
 	| "thinking.minimal"
 	| "thinking.low"
@@ -271,6 +273,8 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"icon.extensionPrompt": "✎",
 	"icon.extensionContextFile": "📎",
 	"icon.extensionInstruction": "📘",
+	// STT
+	"icon.mic": "🎤",
 	// Thinking levels
 	"thinking.minimal": "◔ min",
 	"thinking.low": "◑ low",
@@ -507,6 +511,8 @@ const NERD_SYMBOLS: SymbolMap = {
 	"icon.extensionContextFile": "\uf0f6",
 	// pick:  | alt:  
 	"icon.extensionInstruction": "\uf02d",
+	// STT - fa-microphone
+	"icon.mic": "\uf130",
 	// Thinking Levels - emoji labels
 	// pick: 🤨 min | alt:  min  min
 	"thinking.minimal": "\u{F0E7} min",
@@ -676,6 +682,8 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.extensionPrompt": "PR",
 	"icon.extensionContextFile": "CF",
 	"icon.extensionInstruction": "IN",
+	// STT
+	"icon.mic": "MIC",
 	// Thinking Levels
 	"thinking.minimal": "[min]",
 	"thinking.low": "[low]",
@@ -1374,6 +1382,7 @@ export class Theme {
 			extensionPrompt: this.#symbols["icon.extensionPrompt"],
 			extensionContextFile: this.#symbols["icon.extensionContextFile"],
 			extensionInstruction: this.#symbols["icon.extensionInstruction"],
+			mic: this.#symbols["icon.mic"],
 		};
 	}
 
@@ -1624,7 +1633,8 @@ function detectTerminalBackground(): "dark" | "light" {
 }
 
 function getDefaultTheme(): string {
-	return detectTerminalBackground();
+	const bg = detectTerminalBackground();
+	return bg === "light" ? autoLightTheme : autoDarkTheme;
 }
 
 // ============================================================================
@@ -1633,10 +1643,20 @@ function getDefaultTheme(): string {
 
 export var theme: Theme;
 var currentThemeName: string | undefined;
+
+/** Get the name of the currently active theme. */
+export function getCurrentThemeName(): string | undefined {
+	return currentThemeName;
+}
 var currentSymbolPresetOverride: SymbolPreset | undefined;
 var currentColorBlindMode: boolean = false;
 var themeWatcher: fs.FSWatcher | undefined;
+var sigwinchHandler: (() => void) | undefined;
+var autoDetectedTheme: boolean = false;
+var autoDarkTheme: string = "dark";
+var autoLightTheme: string = "light";
 var onThemeChangeCallback: (() => void) | undefined;
+var themeLoadRequestId: number = 0;
 
 function getCurrentThemeOptions(): CreateThemeOptions {
 	return {
@@ -1646,12 +1666,16 @@ function getCurrentThemeOptions(): CreateThemeOptions {
 }
 
 export async function initTheme(
-	themeName?: string,
 	enableWatcher: boolean = false,
 	symbolPreset?: SymbolPreset,
 	colorBlindMode?: boolean,
+	darkTheme?: string,
+	lightTheme?: string,
 ): Promise<void> {
-	const name = themeName ?? getDefaultTheme();
+	autoDetectedTheme = true;
+	autoDarkTheme = darkTheme ?? "dark";
+	autoLightTheme = lightTheme ?? "light";
+	const name = getDefaultTheme();
 	currentThemeName = name;
 	currentSymbolPresetOverride = symbolPreset;
 	currentColorBlindMode = colorBlindMode ?? false;
@@ -1659,6 +1683,7 @@ export async function initTheme(
 		theme = await loadTheme(name, getCurrentThemeOptions());
 		if (enableWatcher) {
 			await startThemeWatcher();
+			startSigwinchListener();
 		}
 	} catch (err) {
 		logger.debug("Theme loading failed, falling back to dark theme", { error: String(err) });
@@ -1672,9 +1697,15 @@ export async function setTheme(
 	name: string,
 	enableWatcher: boolean = false,
 ): Promise<{ success: boolean; error?: string }> {
+	autoDetectedTheme = false;
 	currentThemeName = name;
+	const requestId = ++themeLoadRequestId;
 	try {
-		theme = await loadTheme(name, getCurrentThemeOptions());
+		const loadedTheme = await loadTheme(name, getCurrentThemeOptions());
+		if (requestId !== themeLoadRequestId) {
+			return { success: false, error: "Theme change superseded by a newer request" };
+		}
+		theme = loadedTheme;
 		if (enableWatcher) {
 			await startThemeWatcher();
 		}
@@ -1683,6 +1714,9 @@ export async function setTheme(
 		}
 		return { success: true };
 	} catch (error) {
+		if (requestId !== themeLoadRequestId) {
+			return { success: false, error: "Theme change superseded by a newer request" };
+		}
 		// Theme is invalid - fall back to dark theme
 		currentThemeName = "dark";
 		theme = await loadTheme("dark", getCurrentThemeOptions());
@@ -1694,7 +1728,74 @@ export async function setTheme(
 	}
 }
 
+export async function previewTheme(name: string): Promise<{ success: boolean; error?: string }> {
+	const requestId = ++themeLoadRequestId;
+	try {
+		const loadedTheme = await loadTheme(name, getCurrentThemeOptions());
+		if (requestId !== themeLoadRequestId) {
+			return { success: false, error: "Theme preview superseded by a newer request" };
+		}
+		theme = loadedTheme;
+		if (onThemeChangeCallback) {
+			onThemeChangeCallback();
+		}
+		return { success: true };
+	} catch (error) {
+		if (requestId !== themeLoadRequestId) {
+			return { success: false, error: "Theme preview superseded by a newer request" };
+		}
+		return {
+			success: false,
+			error: error instanceof Error ? error.message : String(error),
+		};
+	}
+}
+
+/**
+ * Enable auto-detection mode, switching to the appropriate dark/light theme.
+ */
+export function enableAutoTheme(): void {
+	autoDetectedTheme = true;
+	const resolved = getDefaultTheme();
+	if (resolved === currentThemeName) return;
+	currentThemeName = resolved;
+	loadTheme(resolved, getCurrentThemeOptions())
+		.then(loadedTheme => {
+			theme = loadedTheme;
+			if (onThemeChangeCallback) {
+				onThemeChangeCallback();
+			}
+		})
+		.catch(err => {
+			logger.debug("Auto theme switch failed", { error: String(err) });
+		});
+}
+
+/**
+ * Update the theme mappings for auto-detection mode.
+ * When a dark/light mapping changes and auto-detection is active, re-evaluate the theme.
+ */
+export function setAutoThemeMapping(mode: "dark" | "light", themeName: string): void {
+	if (mode === "dark") autoDarkTheme = themeName;
+	else autoLightTheme = themeName;
+	if (!autoDetectedTheme) return;
+	const resolved = getDefaultTheme();
+	if (resolved === currentThemeName) return;
+	currentThemeName = resolved;
+	loadTheme(resolved, getCurrentThemeOptions())
+		.then(loadedTheme => {
+			theme = loadedTheme;
+			if (onThemeChangeCallback) {
+				onThemeChangeCallback();
+			}
+		})
+		.catch(err => {
+			logger.debug("Auto theme mapping switch failed", { error: String(err) });
+		});
+}
+
 export function setThemeInstance(themeInstance: Theme): void {
+	autoDetectedTheme = false;
 	theme = themeInstance;
 	currentThemeName = "<in-memory>";
 	stopThemeWatcher();
@@ -1836,11 +1937,41 @@ async function startThemeWatcher(): Promise<void> {
 	}
 }
 
+/** Re-check COLORFGBG on SIGWINCH and switch dark/light when using auto-detected theme. */
+function startSigwinchListener(): void {
+	stopSigwinchListener();
+	sigwinchHandler = () => {
+		if (!autoDetectedTheme) return;
+		const resolved = getDefaultTheme();
+		if (resolved === currentThemeName) return;
+		currentThemeName = resolved;
+		loadTheme(resolved, getCurrentThemeOptions())
+			.then(loadedTheme => {
+				theme = loadedTheme;
+				if (onThemeChangeCallback) {
+					onThemeChangeCallback();
+				}
+			})
+			.catch(err => {
+				logger.debug("Theme switch on SIGWINCH failed", { error: String(err) });
+			});
+	};
+	process.on("SIGWINCH", sigwinchHandler);
+}
+
+function stopSigwinchListener(): void {
+	if (sigwinchHandler) {
+		process.removeListener("SIGWINCH", sigwinchHandler);
+		sigwinchHandler = undefined;
+	}
+}
+
 export function stopThemeWatcher(): void {
 	if (themeWatcher) {
 		themeWatcher.close();
 		themeWatcher = undefined;
 	}
+	stopSigwinchListener();
 }
 
 // ============================================================================
@@ -1921,11 +2052,36 @@ export async function getResolvedThemeColors(themeName?: string): Promise<Record
 }
 
 /**
- * Check if a theme is a "light" theme (for CSS that needs light/dark variants).
+ * Check if a theme is a "light" theme by analyzing its background color luminance.
+ * Loads theme JSON synchronously (built-in or custom file) and resolves userMessageBg.
  */
 export function isLightTheme(themeName?: string): boolean {
-	// Currently just check the name - could be extended to analyze colors
-	return themeName === "light";
+	const name = themeName ?? "dark";
+	const builtinThemes = getBuiltinThemes();
+	let themeJson: ThemeJson | undefined;
+	if (name in builtinThemes) {
+		themeJson = builtinThemes[name];
+	} else {
+		try {
+			const customPath = path.join(getCustomThemesDir(), `${name}.json`);
+			const content = fs.readFileSync(customPath, "utf-8");
+			themeJson = JSON.parse(content) as ThemeJson;
+		} catch {
+			return false;
+		}
+	}
+	try {
+		const resolved = resolveVarRefs(themeJson.colors.userMessageBg, themeJson.vars ?? {});
+		if (typeof resolved !== "string" || !resolved.startsWith("#") || resolved.length !== 7) return false;
+		const r = parseInt(resolved.slice(1, 3), 16) / 255;
+		const g = parseInt(resolved.slice(3, 5), 16) / 255;
+		const b = parseInt(resolved.slice(5, 7), 16) / 255;
+		// Relative luminance (ITU-R BT.709)
+		const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+		return luminance > 0.5;
+	} catch {
+		return false;
+	}
 }
 
 /**

package/src/modes/types.ts

@@ -152,6 +152,7 @@ export interface InteractiveModeContext {
 	handleHandoffCommand(customInstructions?: string): Promise<void>;
 	handleMoveCommand(targetPath: string): Promise<void>;
 	handleMemoryCommand(text: string): Promise<void>;
+	handleSTTToggle(): Promise<void>;
 	executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<void>;
 	openInBrowser(urlOrPath: string): void;
 	refreshSlashCommandState(cwd?: string): Promise<void>;

package/src/patch/hashline.ts

@@ -56,7 +56,7 @@ function splitDstLines(dst: string): string[] {
 }
 
 /** Pattern matching hashline display format: `LINE:HASH|CONTENT` */
-const HASHLINE_PREFIX_RE = /^\d+:[0-9a-zA-Z]{1,16}\|/;
+const HASHLINE_PREFIX_RE = /^\s*(?:>>>|>>)?\s*\d+:[0-9a-zA-Z]{1,16}\|/;
 
 /** Pattern matching a unified-diff `+` prefix (but not `++`) */
 const DIFF_PLUS_RE = /^\+(?!\+)/;
@@ -508,6 +508,7 @@ export function parseLineRef(ref: string): { line: number; hash: string } {
 	const cleaned = ref
 		.replace(/\|.*$/, "")
 		.replace(/ {2}.*$/, "")
+		.replace(/^>+\s*/, "")
 		.trim();
 	const normalized = cleaned.replace(/\s*:\s*/, ":");
 	const strictMatch = normalized.match(/^(\d+):([0-9a-zA-Z]{1,16})$/);

package/src/patch/shared.ts

@@ -121,7 +121,7 @@ function formatStreamingDiff(diff: string, rawPath: string, uiTheme: Theme, labe
 	return text;
 }
 
-function formatStreamingHashlineEdits(edits: HashlineEditPreview[], uiTheme: Theme, ui: ToolUIKit): string {
+function formatStreamingHashlineEdits(edits: unknown[], uiTheme: Theme, ui: ToolUIKit): string {
 	const MAX_EDITS = 4;
 	const MAX_DST_LINES = 8;
 	let text = "\n\n";
@@ -156,28 +156,59 @@ function formatStreamingHashlineEdits(edits: HashlineEditPreview[], uiTheme: The
 	}
 
 	return text.trimEnd();
-	function formatHashlineEdit(edit: HashlineEditPreview): { srcLabel: string; dst: string } {
-		if ("set_line" in edit) {
+	function formatHashlineEdit(edit: unknown): { srcLabel: string; dst: string } {
+		const asRecord = (value: unknown): Record<string, unknown> | undefined => {
+			if (typeof value === "object" && value !== null) return value as Record<string, unknown>;
+			return undefined;
+		};
+		const editRecord = asRecord(edit);
+		if (!editRecord) {
+			return {
+				srcLabel: "• (incomplete edit)",
+				dst: "",
+			};
+		}
+		if ("set_line" in editRecord) {
+			const setLine = asRecord(editRecord.set_line);
+			return {
+				srcLabel: `• set_line ${typeof setLine?.anchor === "string" ? setLine.anchor : "…"}`,
+				dst: typeof setLine?.new_text === "string" ? setLine.new_text : "",
+			};
+		}
+		if ("replace_lines" in editRecord) {
+			const replaceLines = asRecord(editRecord.replace_lines);
+			const start = typeof replaceLines?.start_anchor === "string" ? replaceLines.start_anchor : "…";
+			const end = typeof replaceLines?.end_anchor === "string" ? replaceLines.end_anchor : "…";
 			return {
-				srcLabel: `• set_line ${edit.set_line.anchor}`,
-				dst: edit.set_line.new_text,
+				srcLabel: `• replace_lines ${start}..${end}`,
+				dst: typeof replaceLines?.new_text === "string" ? replaceLines.new_text : "",
 			};
 		}
-		if ("replace_lines" in edit) {
+		if ("replace" in editRecord) {
+			const replace = asRecord(editRecord.replace);
+			const all = typeof replace?.all === "boolean" ? replace.all : false;
 			return {
-				srcLabel: `• replace_lines ${edit.replace_lines.start_anchor}..${edit.replace_lines.end_anchor}`,
-				dst: edit.replace_lines.new_text,
+				srcLabel: `• replace old_text→new_text${all ? " (all)" : ""}`,
+				dst: typeof replace?.new_text === "string" ? replace.new_text : "",
 			};
 		}
-		if ("replace" in edit) {
+		if ("insert_after" in editRecord) {
+			const insertAfter = asRecord(editRecord.insert_after);
+			const anchor = typeof insertAfter?.anchor === "string" ? insertAfter.anchor : "…";
+			const text =
+				typeof insertAfter?.text === "string"
+					? insertAfter.text
+					: typeof insertAfter?.content === "string"
+						? insertAfter.content
+						: "";
 			return {
-				srcLabel: `• replace old_text→new_text${edit.replace.all ? " (all)" : ""}`,
-				dst: edit.replace.new_text,
+				srcLabel: `• insert_after ${anchor}..`,
+				dst: text,
 			};
 		}
 		return {
-			srcLabel: `• insert_after ${edit.insert_after.anchor}..`,
-			dst: edit.insert_after.text,
+			srcLabel: "• (incomplete edit)",
+			dst: "",
 		};
 	}
 }

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

@@ -9,6 +9,11 @@ Plan approved. Execute it now.
 <instruction>
 Execute this plan step by step. You have full tool access.
 Verify each step before proceeding to the next.
+{{#has tools "todo_write"}}
+Before execution, initialize todo tracking for this plan with `todo_write`.
+After each completed step, immediately update `todo_write` so progress stays visible.
+If a `todo_write` call fails, fix the todo payload and retry before continuing silently.
+{{/has}}
 </instruction>
 
 <critical>

package/src/prompts/system/subagent-system-prompt.md

@@ -15,6 +15,7 @@ For additional parent conversation context, check {{contextFile}} (`tail -100` o
 - MUST work under working tree: {{worktree}}. Do not modify original repository.
 {{/if}}
 - MUST call `submit_result` exactly once when finished. No JSON in text. No plain-text summary. Pass result via `data` parameter.
+- Todo tracking is parent-owned. Do not create or maintain a separate todo list in this subagent.
 {{#if outputSchema}}
 - If cannot complete, call `submit_result` with `status="aborted"` and error message. Do not provide success result or pretend completion.
 {{else}}

package/src/prompts/system/system-prompt.md

@@ -123,6 +123,16 @@ Don't open a file hoping. Hope is not a strategy.
 **If blocked**: exhaust tools/context/files first. Only then ask — minimum viable question.
 **If requested change includes refactor**: remove now-unused elements. Note removals.
 
+{{#has tools "todo_write"}}
+### Task Tracking
+- Use `todo_write` proactively for non-trivial, multi-step work so progress stays visible.
+- Initialize todos before implementation for complex tasks, then keep them current while working.
+- Mark todo items complete immediately after finishing them; do not batch completion updates.
+- Keep todo items as focused logical units (one coherent outcome per item); split broad work into smaller items.
+- Keep exactly one item `in_progress` at a time and complete in order unless requirements change.
+- Skip `todo_write` for single trivial or purely informational requests.
+{{/has}}
+
 ### Verification
 - Prefer external proof: tests, linters, type checks, repro steps.
 - If unverified: state what to run and expected result.

package/src/prompts/tools/todo-write.md

@@ -20,14 +20,16 @@ Use proactively:
 2. **Task Management**:
    - Update status in real time
    - Mark complete IMMEDIATELY after finishing (no batching)
-   - Multiple tasks may be in_progress in parallel
+   - Keep exactly ONE task in_progress at a time
    - Remove tasks no longer relevant
+   - Complete tasks in list order (do not mark later tasks completed while earlier tasks remain incomplete)
 3. **Task Completion Requirements**:
    - ONLY mark completed when FULLY accomplished
    - On errors/blockers/inability to finish, keep in_progress
    - When blocked, create task describing what needs resolving
 4. **Task Breakdown**:
 	 - Create specific, actionable items
+	 - Keep each todo scoped to one logical unit of work; split unrelated work into separate items
 	 - Break complex tasks into smaller steps
 	 - Use clear, descriptive names
 </protocol>