@oh-my-pi/pi-coding-agent 11.2.3 → 11.4.0

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

@@ -286,6 +286,15 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 			return Promise.resolve({ success: false, error: "Theme switching not supported in RPC mode" });
 		}
 
+		getToolsExpanded() {
+			// Tool expansion not supported in RPC mode - no TUI
+			return false;
+		}
+
+		setToolsExpanded(_expanded: boolean) {
+			// Tool expansion not supported in RPC mode - no TUI
+		}
+
 		setEditorComponent(): void {
 			// Custom editor components not supported in RPC mode
 		}
@@ -316,6 +325,7 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 				getActiveTools: () => session.getActiveToolNames(),
 				getAllTools: () => session.getAllToolNames(),
 				setActiveTools: (toolNames: string[]) => session.setActiveToolsByName(toolNames),
+				getCommands: () => [],
 				setModel: async model => {
 					const key = await session.modelRegistry.getApiKey(model);
 					if (!key) return false;
@@ -335,6 +345,7 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 					shutdownState.requested = true;
 				},
 				getContextUsage: () => session.getContextUsage(),
+				getSystemPrompt: () => session.systemPrompt,
 				compact: async instructionsOrOptions => {
 					const instructions = typeof instructionsOrOptions === "string" ? instructionsOrOptions : undefined;
 					const options =
@@ -364,6 +375,10 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 					const result = await session.navigateTree(targetId, { summarize: options?.summarize });
 					return { cancelled: result.cancelled };
 				},
+				switchSession: async sessionPath => {
+					const success = await session.switchSession(sessionPath);
+					return { cancelled: !success };
+				},
 				compact: async instructionsOrOptions => {
 					const instructions = typeof instructionsOrOptions === "string" ? instructionsOrOptions : undefined;
 					const options =
@@ -412,12 +427,12 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 			}
 
 			case "steer": {
-				await session.steer(command.message);
+				await session.steer(command.message, command.images);
 				return success(id, "steer");
 			}
 
 			case "follow_up": {
-				await session.followUp(command.message);
+				await session.followUp(command.message, command.images);
 				return success(id, "follow_up");
 			}
 

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

@@ -17,8 +17,8 @@ import type { CompactionResult } from "../../session/compaction";
 export type RpcCommand =
 	// Prompting
 	| { id?: string; type: "prompt"; message: string; images?: ImageContent[]; streamingBehavior?: "steer" | "followUp" }
-	| { id?: string; type: "steer"; message: string }
-	| { id?: string; type: "follow_up"; message: string }
+	| { id?: string; type: "steer"; message: string; images?: ImageContent[] }
+	| { id?: string; type: "follow_up"; message: string; images?: ImageContent[] }
 	| { id?: string; type: "abort" }
 	| { id?: string; type: "new_session"; parentSession?: string }
 

package/src/modes/types.ts

@@ -176,6 +176,7 @@ export interface InteractiveModeContext {
 	cycleThinkingLevel(): void;
 	cycleRoleModel(options?: { temporary?: boolean }): Promise<void>;
 	toggleToolOutputExpansion(): void;
+	setToolsExpanded(expanded: boolean): void;
 	toggleThinkingBlockVisibility(): void;
 	openExternalEditor(): void;
 	registerExtensionShortcuts(): void;

package/src/modes/utils/ui-helpers.ts

@@ -203,7 +203,9 @@ export class UiHelpers {
 
 				// Render tool call components
 				for (const content of message.content) {
-					if (content.type !== "toolCall") continue;
+					if (content.type !== "toolCall") {
+						continue;
+					}
 
 					if (content.name === "read") {
 						if (!readGroup) {

package/src/patch/applicator.ts

@@ -126,6 +126,8 @@ function adjustLinesIndentation(patternLines: string[], actualLines: string[], n
 
 	let patternTabOnly = true;
 	let actualSpaceOnly = true;
+	let patternSpaceOnly = true;
+	let actualTabOnly = true;
 	let patternMixed = false;
 	let actualMixed = false;
 
@@ -133,6 +135,7 @@ function adjustLinesIndentation(patternLines: string[], actualLines: string[], n
 		if (line.trim().length === 0) continue;
 		const ws = getLeadingWhitespace(line);
 		if (ws.includes(" ")) patternTabOnly = false;
+		if (ws.includes("\t")) patternSpaceOnly = false;
 		if (ws.includes(" ") && ws.includes("\t")) patternMixed = true;
 	}
 
@@ -140,6 +143,7 @@ function adjustLinesIndentation(patternLines: string[], actualLines: string[], n
 		if (line.trim().length === 0) continue;
 		const ws = getLeadingWhitespace(line);
 		if (ws.includes("\t")) actualSpaceOnly = false;
+		if (ws.includes(" ")) actualTabOnly = false;
 		if (ws.includes(" ") && ws.includes("\t")) actualMixed = true;
 	}
 
@@ -173,6 +177,88 @@ function adjustLinesIndentation(patternLines: string[], actualLines: string[], n
 		}
 	}
 
+	// Reverse: pattern uses spaces, actual uses tabs — infer spaces = tabs * width + offset
+	// Collect (tabs, spaces) pairs from matched lines to solve for the model's tab rendering.
+	// With one data point: spaces = tabs * width (offset=0).
+	// With two+: solve ax + b via pairs with distinct tab counts.
+	if (!patternMixed && !actualMixed && patternSpaceOnly && actualTabOnly) {
+		const samples = new Map<number, number>(); // tabs -> spaces
+		const lineCount = Math.min(patternLines.length, actualLines.length);
+		let consistent = true;
+		for (let i = 0; i < lineCount; i++) {
+			const patternLine = patternLines[i];
+			const actualLine = actualLines[i];
+			if (patternLine.trim().length === 0 || actualLine.trim().length === 0) continue;
+			const spaces = countLeadingWhitespace(patternLine);
+			const tabs = countLeadingWhitespace(actualLine);
+			if (tabs === 0) continue;
+			const existing = samples.get(tabs);
+			if (existing !== undefined && existing !== spaces) {
+				consistent = false;
+				break;
+			}
+			samples.set(tabs, spaces);
+		}
+
+		if (consistent && samples.size > 0) {
+			let tabWidth: number | undefined;
+			let offset = 0;
+
+			if (samples.size === 1) {
+				// One level: assume offset=0, width = spaces / tabs
+				const [[tabs, spaces]] = samples;
+				if (spaces % tabs === 0) {
+					tabWidth = spaces / tabs;
+				}
+			} else {
+				// Two+ levels: solve via any two distinct pairs
+				// spaces = tabs * width + offset  =>  width = (s2 - s1) / (t2 - t1)
+				const entries = [...samples.entries()];
+				const [t1, s1] = entries[0];
+				const [t2, s2] = entries[1];
+				if (t1 !== t2) {
+					const w = (s2 - s1) / (t2 - t1);
+					if (w > 0 && Number.isInteger(w)) {
+						const b = s1 - t1 * w;
+						// Validate all samples against this model
+						let valid = true;
+						for (const [t, s] of samples) {
+							if (t * w + b !== s) {
+								valid = false;
+								break;
+							}
+						}
+						if (valid) {
+							tabWidth = w;
+							offset = b;
+						}
+					}
+				}
+			}
+
+			if (tabWidth !== undefined && tabWidth > 0) {
+				const converted = newLines.map(line => {
+					if (line.trim().length === 0) return line;
+					const ws = countLeadingWhitespace(line);
+					if (ws === 0) return line;
+					// Reverse: tabs = (spaces - offset) / width
+					const adjusted = ws - offset;
+					if (adjusted >= 0 && adjusted % tabWidth! === 0) {
+						return "\t".repeat(adjusted / tabWidth!) + line.slice(ws);
+					}
+					// Partial tab — keep remainder as spaces
+					const tabCount = Math.floor(adjusted / tabWidth!);
+					const remainder = adjusted - tabCount * tabWidth!;
+					if (tabCount >= 0) {
+						return "\t".repeat(tabCount) + " ".repeat(remainder) + line.slice(ws);
+					}
+					return line;
+				});
+				return converted;
+			}
+		}
+	}
+
 	// Build a map from trimmed content to actual lines (by content, not position)
 	// This handles fuzzy matches where pattern and actual may not be positionally aligned
 	const contentToActualLines = new Map<string, string[]>();
@@ -434,8 +520,7 @@ function formatSequenceMatchPreview(lines: string[], startIdx: number): string {
 	return previewLines
 		.map((line, i) => {
 			const num = start + i + 1;
-			const truncated =
-				line.length > MATCH_PREVIEW_MAX_LEN ? `${line.slice(0, MATCH_PREVIEW_MAX_LEN - 3)}...` : line;
+			const truncated = line.length > MATCH_PREVIEW_MAX_LEN ? `${line.slice(0, MATCH_PREVIEW_MAX_LEN - 1)}…` : line;
 			return `  ${num} | ${truncated}`;
 		})
 		.join("\n");
@@ -1103,7 +1188,7 @@ function computeReplacements(
 					return lines
 						.map((line, i) => {
 							const num = start + i + 1;
-							const truncated = line.length > maxLineLength ? `${line.slice(0, maxLineLength - 3)}...` : line;
+							const truncated = line.length > maxLineLength ? `${line.slice(0, maxLineLength - 1)}…` : line;
 							return `  ${num} | ${truncated}`;
 						})
 						.join("\n");
@@ -1119,8 +1204,25 @@ function computeReplacements(
 
 		// Adjust indentation if needed (handles fuzzy matches where indentation differs)
 		const actualMatchedLines = originalLines.slice(found, found + pattern.length);
-		const adjustedNewLines = adjustLinesIndentation(pattern, actualMatchedLines, newSlice);
 
+		// Skip pure-context hunks (no +/- lines — oldLines === newLines).
+		// They serve only to advance lineIndex for subsequent hunks.
+		let isNoOp = pattern.length === newSlice.length;
+		if (isNoOp) {
+			for (let i = 0; i < pattern.length; i++) {
+				if (pattern[i] !== newSlice[i]) {
+					isNoOp = false;
+					break;
+				}
+			}
+		}
+
+		if (isNoOp) {
+			lineIndex = found + pattern.length;
+			continue;
+		}
+
+		const adjustedNewLines = adjustLinesIndentation(pattern, actualMatchedLines, newSlice);
 		replacements.push({ startIndex: found, oldLen: pattern.length, newLines: adjustedNewLines });
 		lineIndex = found + pattern.length;
 	}

package/src/patch/fuzzy.ts

@@ -241,7 +241,7 @@ export function findMatch(
 				const preview = previewLines
 					.map((line, idx) => {
 						const num = start + idx + 1;
-						return `  ${num} | ${line.length > OCCURRENCE_PREVIEW_MAX_LEN ? `${line.slice(0, OCCURRENCE_PREVIEW_MAX_LEN - 3)}...` : line}`;
+						return `  ${num} | ${line.length > OCCURRENCE_PREVIEW_MAX_LEN ? `${line.slice(0, OCCURRENCE_PREVIEW_MAX_LEN - 1)}…` : line}`;
 					})
 					.join("\n");
 				occurrencePreviews.push(preview);

package/src/patch/shared.ts

@@ -13,12 +13,14 @@ import {
 	formatExpandHint,
 	formatStatusIcon,
 	getDiffStats,
+	PREVIEW_LIMITS,
+	replaceTabs,
 	shortenPath,
 	ToolUIKit,
 	truncateDiffByHunk,
 } from "../tools/render-utils";
 import type { RenderCallOptions } from "../tools/renderers";
-import { renderStatusLine } from "../tui";
+import { Ellipsis, Hasher, type RenderCache, renderStatusLine, truncateToWidth } from "../tui";
 import type { DiffError, DiffResult, Operation } from "./types";
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -85,8 +87,6 @@ export interface EditRenderContext {
 	renderDiff?: (diffText: string, options?: { filePath?: string }) => string;
 }
 
-const EDIT_DIFF_PREVIEW_HUNKS = 2;
-const EDIT_DIFF_PREVIEW_LINES = 24;
 const EDIT_STREAMING_PREVIEW_LINES = 12;
 
 function countLines(text: string): number {
@@ -140,7 +140,7 @@ function renderDiffSection(
 		hiddenLines,
 	} = expanded
 		? { text: diff, hiddenHunks: 0, hiddenLines: 0 }
-		: truncateDiffByHunk(diff, EDIT_DIFF_PREVIEW_HUNKS, EDIT_DIFF_PREVIEW_LINES);
+		: truncateDiffByHunk(diff, PREVIEW_LIMITS.DIFF_COLLAPSED_HUNKS, PREVIEW_LIMITS.DIFF_COLLAPSED_LINES);
 
 	text += `\n\n${renderDiffFn(truncatedDiff, { filePath: rawPath })}`;
 	if (!expanded && (hiddenHunks > 0 || hiddenLines > 0)) {
@@ -182,7 +182,7 @@ export const editToolRenderer = {
 			const maxLines = 6;
 			text += "\n\n";
 			for (const line of previewLines.slice(0, maxLines)) {
-				text += `${uiTheme.fg("toolOutput", ui.truncate(line, 80))}\n`;
+				text += `${uiTheme.fg("toolOutput", ui.truncate(replaceTabs(line), 80))}\n`;
 			}
 			if (previewLines.length > maxLines) {
 				text += uiTheme.fg("dim", `… ${previewLines.length - maxLines} more lines`);
@@ -192,7 +192,7 @@ export const editToolRenderer = {
 			const maxLines = 6;
 			text += "\n\n";
 			for (const line of previewLines.slice(0, maxLines)) {
-				text += `${uiTheme.fg("toolOutput", ui.truncate(line, 80))}\n`;
+				text += `${uiTheme.fg("toolOutput", ui.truncate(replaceTabs(line), 80))}\n`;
 			}
 			if (previewLines.length > maxLines) {
 				text += uiTheme.fg("dim", `… ${previewLines.length - maxLines} more lines`);
@@ -209,75 +209,89 @@ export const editToolRenderer = {
 		args?: EditRenderArgs,
 	): Component {
 		const ui = new ToolUIKit(uiTheme);
-		const { expanded, renderContext } = options;
 		const rawPath = args?.file_path || args?.path || "";
 		const filePath = shortenPath(rawPath);
 		const editLanguage = getLanguageFromPath(rawPath) ?? "text";
 		const editIcon = uiTheme.fg("muted", uiTheme.getLangIcon(editLanguage));
-		const editDiffPreview = renderContext?.editDiffPreview;
-		const renderDiffFn = renderContext?.renderDiff ?? ((t: string) => t);
 
-		// Get op and rename from args or details
 		const op = args?.op || result.details?.op;
 		const rename = args?.rename || result.details?.rename;
+		const opTitle = op === "create" ? "Create" : op === "delete" ? "Delete" : "Edit";
 
-		// Build path display with line number if available
-		let pathDisplay = filePath ? uiTheme.fg("accent", filePath) : uiTheme.fg("toolOutput", "…");
-		const firstChangedLine =
-			(editDiffPreview && "firstChangedLine" in editDiffPreview ? editDiffPreview.firstChangedLine : undefined) ||
-			(result.details && !result.isError ? result.details.firstChangedLine : undefined);
-		if (firstChangedLine) {
-			pathDisplay += uiTheme.fg("warning", `:${firstChangedLine}`);
-		}
+		// Pre-compute metadata line (static across renders)
+		const metadataLine =
+			op !== "delete"
+				? `\n${formatMetadataLine(countLines(args?.newText ?? args?.oldText ?? args?.diff ?? args?.patch ?? ""), editLanguage, uiTheme)}`
+				: "";
 
-		// Add arrow for rename operations
-		if (rename) {
-			pathDisplay += ` ${uiTheme.fg("dim", "→")} ${uiTheme.fg("accent", shortenPath(rename))}`;
-		}
+		// Pre-compute error text (static)
+		const errorText = result.isError ? (result.content?.find(c => c.type === "text")?.text ?? "") : "";
 
-		// Show operation type for patch mode
-		const opTitle = op === "create" ? "Create" : op === "delete" ? "Delete" : "Edit";
-		const header = renderStatusLine(
-			{
-				icon: result.isError ? "error" : "success",
-				title: opTitle,
-				description: `${editIcon} ${pathDisplay}`,
-			},
-			uiTheme,
-		);
-		let text = header;
-
-		// Skip metadata line for delete operations
-		if (op !== "delete") {
-			const editLineCount = countLines(args?.newText ?? args?.oldText ?? args?.diff ?? args?.patch ?? "");
-			text += `\n${formatMetadataLine(editLineCount, editLanguage, uiTheme)}`;
-		}
+		let cached: RenderCache | undefined;
 
-		if (result.isError) {
-			// Show error from result
-			const errorText = result.content?.find(c => c.type === "text")?.text ?? "";
-			if (errorText) {
-				text += `\n\n${uiTheme.fg("error", errorText)}`;
-			}
-		} else if (result.details?.diff) {
-			// Prefer actual diff after execution
-			text += renderDiffSection(result.details.diff, rawPath, expanded, uiTheme, ui, renderDiffFn);
-		} else if (editDiffPreview) {
-			// Use cached diff preview when no actual diff is available
-			if ("error" in editDiffPreview) {
-				text += `\n\n${uiTheme.fg("error", editDiffPreview.error)}`;
-			} else if (editDiffPreview.diff) {
-				text += renderDiffSection(editDiffPreview.diff, rawPath, expanded, uiTheme, ui, renderDiffFn);
-			}
-		}
+		return {
+			render(width) {
+				const { expanded, renderContext } = options;
+				const editDiffPreview = renderContext?.editDiffPreview;
+				const renderDiffFn = renderContext?.renderDiff ?? ((t: string) => t);
+				const key = new Hasher().bool(expanded).u32(width).digest();
+				if (cached?.key === key) return cached.lines;
 
-		// Show LSP diagnostics if available
-		if (result.details?.diagnostics) {
-			text += ui.formatDiagnostics(result.details.diagnostics, expanded, (fp: string) =>
-				uiTheme.getLangIcon(getLanguageFromPath(fp)),
-			);
-		}
+				// Build path display with line number
+				let pathDisplay = filePath ? uiTheme.fg("accent", filePath) : uiTheme.fg("toolOutput", "…");
+				const firstChangedLine =
+					(editDiffPreview && "firstChangedLine" in editDiffPreview
+						? editDiffPreview.firstChangedLine
+						: undefined) || (result.details && !result.isError ? result.details.firstChangedLine : undefined);
+				if (firstChangedLine) {
+					pathDisplay += uiTheme.fg("warning", `:${firstChangedLine}`);
+				}
 
-		return new Text(text, 0, 0);
+				// Add arrow for rename operations
+				if (rename) {
+					pathDisplay += ` ${uiTheme.fg("dim", "→")} ${uiTheme.fg("accent", shortenPath(rename))}`;
+				}
+
+				const header = renderStatusLine(
+					{
+						icon: result.isError ? "error" : "success",
+						title: opTitle,
+						description: `${editIcon} ${pathDisplay}`,
+					},
+					uiTheme,
+				);
+				let text = header;
+				text += metadataLine;
+
+				if (result.isError) {
+					if (errorText) {
+						text += `\n\n${uiTheme.fg("error", errorText)}`;
+					}
+				} else if (result.details?.diff) {
+					text += renderDiffSection(result.details.diff, rawPath, expanded, uiTheme, ui, renderDiffFn);
+				} else if (editDiffPreview) {
+					if ("error" in editDiffPreview) {
+						text += `\n\n${uiTheme.fg("error", editDiffPreview.error)}`;
+					} else if (editDiffPreview.diff) {
+						text += renderDiffSection(editDiffPreview.diff, rawPath, expanded, uiTheme, ui, renderDiffFn);
+					}
+				}
+
+				// Show LSP diagnostics if available
+				if (result.details?.diagnostics) {
+					text += ui.formatDiagnostics(result.details.diagnostics, expanded, (fp: string) =>
+						uiTheme.getLangIcon(getLanguageFromPath(fp)),
+					);
+				}
+
+				const lines =
+					width > 0 ? text.split("\n").map(line => truncateToWidth(line, width, Ellipsis.Omit)) : text.split("\n");
+				cached = { key, lines };
+				return lines;
+			},
+			invalidate() {
+				cached = undefined;
+			},
+		};
 	},
 };

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

@@ -19,9 +19,9 @@ Create plan at `{{planFilePath}}`.
 
 Use `{{editToolName}}` incremental updates; `{{writeToolName}}` only create/full replace.
 
-<important>
+<caution>
 Plan execution runs in fresh context (session cleared). Make plan file self-contained: include requirements, decisions, key findings, remaining todos needed to continue without prior session history.
-</important>
+</caution>
 
 {{#if reentry}}
 ## Re-entry
@@ -56,7 +56,7 @@ Use `{{editToolName}}` update plan file as you learn; don't wait until end.
 - Smaller task → fewer or no questions
 </procedure>
 
-<important>
+<caution>
 ### Plan Structure
 
 Use clear markdown headers; include:
@@ -65,7 +65,7 @@ Use clear markdown headers; include:
 - Verification: how to test end-to-end
 
 Concise enough to scan. Detailed enough to execute.
-</important>
+</caution>
 
 {{else}}
 ## Planning Workflow
@@ -87,9 +87,9 @@ Update `{{planFilePath}}` (`{{editToolName}}` changes, `{{writeToolName}}` only
 - Verification section
 </procedure>
 
-<important>
+<caution>
 Ask questions throughout. Don't make large assumptions about user intent.
-</important>
+</caution>
 {{/if}}
 
 <directives>

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

@@ -4,7 +4,7 @@ XML tags prompt: system-level instructions, not suggestions.
 Tag hierarchy (enforcement):
 - `<critical>` — Inviolable; noncompliance = system failure.
 - `<prohibited>` — Forbidden; actions cause harm.
-- `<important>` — High priority; deviate only with justification.
+- `<caution>` — High priority; important to follow.
 - `<instruction>` — Operating rules; follow precisely.
 - `<conditions>` — When rules apply; check before acting.
 - `<avoid>` — Anti-patterns; prefer alternatives.
@@ -221,6 +221,7 @@ Main branch: {{git.mainBranch}}
 {{#if skills.length}}
 <skills>
 Scan descriptions vs domain. Skill covers output? Read `skill://<name>` first.
+When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.
 
 {{#list skills join="\n"}}
 <skill name="{{name}}">

package/src/prompts/tools/ask.md

@@ -16,9 +16,9 @@ Ask user when you need clarification or input during task execution.
 Returns selected option(s) as text. For multi-part questions, returns map of question IDs to selected values.
 </output>
 
-<important>
+<caution>
 - Provide 2-5 concise, distinct options
-</important>
+</caution>
 
 <critical>
 **Default to action. Do NOT ask unless you are genuinely blocked and user preference is required to avoid a wrong outcome.**

package/src/prompts/tools/gemini-image.md

@@ -14,10 +14,10 @@ When using multiple `input_images`, describe each image's role in `subject` or `
 Returns generated image saved to disk. Response includes file path where image was written.
 </output>
 
-<important>
+<caution>
 - For photoreal: add "ultra-detailed, realistic, natural skin texture" to style
 - For posters/cards: use 9:16 aspect ratio with negative space for text placement
 - For iteration: use `changes` for targeted adjustments rather than regenerating from scratch
 - For text: add "sharp, legible, correctly spelled" for important text; keep text short
 - For diagrams: include "scientifically accurate" in style and provide facts explicitly
-</important>
+</caution>

package/src/prompts/tools/lsp.md

@@ -22,7 +22,7 @@ Interact with Language Server Protocol servers for code intelligence.
 - `reload`: Confirmation of server restart
 </output>
 
-<important>
+<caution>
 - Requires running LSP server for target language
 - Some operations require file to be saved to disk
-</important>
+</caution>

package/src/prompts/tools/patch.md

@@ -48,7 +48,7 @@ Returns success/failure; on failure, error message indicates:
 - Never use anchors as comments (no line numbers, location labels, placeholders like `@@ @@`)
 - Do not place new lines outside intended block
 - If edit fails or breaks structure, re-read file and produce new patch from current content—do not retry same diff
-- If indentation/alignment wrong after editing, run formatter (`go fmt`, `cargo fmt`, `ruff format`, `biome`, etc.)—never make repeated edit attempts to fix whitespace
+- **NEVER** use edit to fix indentation or reformat code—run the project's formatter instead
 </critical>
 
 <example name="create">

package/src/prompts/tools/python.md

@@ -41,13 +41,13 @@ User sees output like Jupyter notebook; rich displays render fully:
 - `display(HTML(...))` → rendered HTML
 - `display(Markdown(...))` → formatted markdown
 - `plt.show()` → inline figures
-**You will see object repr** (e.g., `<IPython.core.display.JSON object>`). Trust `display()`; do not assume user sees only repr.
+  **You will see object repr** (e.g., `<IPython.core.display.JSON object>`). Trust `display()`; do not assume user sees only repr.
 </output>
 
-<important>
+<caution>
 - Per-call mode uses fresh kernel each call
 - Use `reset: true` to clear state when session mode active
-</important>
+</caution>
 
 <critical>
 - Use `run()` for shell commands; never raw `subprocess`

package/src/prompts/tools/task.md

@@ -70,6 +70,10 @@ Run in isolated git worktree; returns patches. Use when tasks edit overlapping f
 ### `schema` (optional — recommended for structured output)
 
 JTD schema defining expected response structure. Use typed properties. If you care about parsing result, define here — **never describe output format in `context` or `assignment`**.
+
+<caution>
+**Schema vs agent mismatch causes null output.** Agents with `output="structured"` (e.g., `explore`) have a built-in schema. If you also pass `schema`, yours takes precedence — but if you describe output format in `context`/`assignment` instead, the agent's built-in schema wins. The agent gets confused trying to fit your requested format into its schema shape and submits `null`. Either: (1) use `schema` to override the built-in one, (2) use `task` agent which has no built-in schema, or (3) match your instructions to the agent's expected output shape.
+</caution>
 ---
 
 ## Writing an assignment
@@ -115,9 +119,11 @@ Use structure every assignment:
 - "No WASM."
 
 If tempted to write above, expand using templates.
+**Output format in prose instead of `schema`** — agent returns null:
+Structured agents (`explore`, `reviewer`) have built-in output schemas. Describing a different output format in `context`/`assignment` without overriding via `schema` creates a mismatch — the agent can't reconcile your prose instructions with its schema and submits null data. Always use `schema` for output structure, or pick an agent whose built-in schema matches your needs.
 **Test/lint commands in parallel tasks** — edit wars:
 Parallel agents share working tree. If two agents run `bun check` or `bun test` concurrently, they see each other's half-finished edits, "fix" phantom errors, loop. **Never tell parallel tasks run project-wide build/test/lint commands.** Each task edits, stops. Caller verifies after all tasks complete.
-**If you can’t specify scope yet**, create **Discovery task** first: enumerate files, find callsites, list candidates. Then fan out with explicit paths.
+**If you can't specify scope yet**, create **Discovery task** first: enumerate files, find callsites, list candidates. Then fan out with explicit paths.
 
 ### Delegate intent, not keystrokes
 

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

@@ -36,9 +36,9 @@ Use proactively:
 Returns confirmation todo list updated.
 </output>
 
-<important>
+<caution>
 When in doubt, use this.
-</important>
+</caution>
 
 <example name="use-dark-mode">
 User: Add dark mode toggle to settings. Run tests when done.

package/src/prompts/tools/web-search.md

@@ -14,6 +14,6 @@ Returns search results formatted as blocks with:
 - Provider-dependent structure based on selected backend
 </output>
 
-<important>
+<caution>
 Searches are performed automatically within a single API call—no pagination or follow-up requests needed.
-</important>
+</caution>

package/src/prompts/tools/write.md

@@ -14,8 +14,5 @@ Confirmation of file creation/write with path. When LSP available, content may b
 <critical>
 - Prefer Edit tool for modifying existing files (more precise, preserves formatting)
 - Create documentation files (*.md, README) only when explicitly requested
-</critical>
-
-<important>
-- Include emojis only when explicitly requested
-</important>
+- No emojis unless requested
+</critical>