@oh-my-pi/pi-coding-agent 14.2.1 → 14.4.0

package/src/modes/components/tool-execution.ts

@@ -14,14 +14,7 @@ import {
 	type TUI,
 } from "@oh-my-pi/pi-tui";
 import { getProjectDir, logger } from "@oh-my-pi/pi-utils";
-import {
-	computeEditDiff,
-	computeHashlineDiff,
-	computePatchDiff,
-	type DiffError,
-	type DiffResult,
-	expandApplyPatchToEntries,
-} from "../../edit";
+import { EDIT_MODE_STRATEGIES, type EditMode, type PerFileDiffPreview } from "../../edit";
 import type { Theme } from "../../modes/theme/theme";
 import { theme } from "../../modes/theme/theme";
 import { BASH_DEFAULT_PREVIEW_LINES } from "../../tools/bash";
@@ -34,7 +27,6 @@ import {
 	JSON_TREE_SCALAR_LEN_COLLAPSED,
 	JSON_TREE_SCALAR_LEN_EXPANDED,
 	renderJsonTreeLines,
-	stripInternalArgs,
 } from "../../tools/json-tree";
 import { PYTHON_DEFAULT_PREVIEW_LINES } from "../../tools/python";
 import { formatExpandHint, replaceTabs, resolveImageOptions, truncateToWidth } from "../../tools/render-utils";
@@ -65,6 +57,12 @@ function isEditLikeToolName(toolName: string): boolean {
 	return toolName === "edit" || toolName === "apply_patch";
 }
 
+function resolveEditModeForTool(toolName: string, tool: AgentTool | undefined): EditMode | undefined {
+	if (toolName === "apply_patch") return "apply_patch";
+	if (toolName !== "edit") return undefined;
+	return (tool as { mode?: EditMode } | undefined)?.mode;
+}
+
 export interface ToolExecutionOptions {
 	showImages?: boolean; // default: true (only used if terminal supports images)
 	editFuzzyThreshold?: number;
@@ -111,9 +109,12 @@ export class ToolExecutionComponent extends Container {
 		isError?: boolean;
 		details?: any;
 	};
-	// Cached edit diff preview (computed when args arrive, before tool executes)
-	#editDiffPreview?: DiffResult | DiffError;
-	#editDiffArgsKey?: string; // Track which args the preview is for
+	// Edit preview state (single-file for legacy modes, multi-file for chunk)
+	#editMode?: EditMode;
+	#editDiffPreview?: PerFileDiffPreview[];
+	#editDiffScheduleTimer?: NodeJS.Timeout;
+	#editDiffAbort?: AbortController;
+	#editDiffLastArgsKey?: string;
 	// Cached converted images for Kitty protocol (which requires PNG), keyed by index
 	#convertedImages: Map<number, { data: string; mimeType: string }> = new Map();
 	// Spinner animation for partial task results
@@ -166,116 +167,98 @@ export class ToolExecutionComponent extends Container {
 			this.addChild(this.#contentText);
 		}
 
+		this.#editMode = resolveEditModeForTool(toolName, tool);
+
 		this.#updateDisplay();
+		this.#schedulePreviewDiff(0);
 	}
 
 	updateArgs(args: any, _toolCallId?: string): void {
 		this.#args = cloneToolArgs(args);
 		this.#updateSpinnerAnimation();
+		this.#schedulePreviewDiff();
 		this.#updateDisplay();
 	}
 
 	/**
 	 * Signal that args are complete (tool is about to execute).
-	 * This triggers diff computation for edit-like tools.
+	 * This triggers an immediate final diff computation for edit-like tools.
 	 */
 	setArgsComplete(_toolCallId?: string): void {
 		this.#argsComplete = true;
 		this.#updateSpinnerAnimation();
-		this.#maybeComputeEditDiff();
+		this.#schedulePreviewDiff(0);
 	}
 
 	/**
-	 * Compute edit diff preview when we have complete args.
-	 * This runs async and updates display when done.
+	 * Schedule a debounced compute of the streaming edit-diff preview.
+	 * `delayMs === 0` runs immediately (used on construction and on
+	 * `setArgsComplete`). All other calls coalesce to a trailing-edge timer.
 	 */
-	#maybeComputeEditDiff(): void {
-		if (!isEditLikeToolName(this.#toolName)) return;
-
-		const edits = this.#args?.edits;
-		if (!Array.isArray(edits) || edits.length === 0) {
-			if (this.#toolName !== "apply_patch" || typeof this.#args?.input !== "string") {
-				return;
-			}
-
-			const input = this.#args.input;
-			const argsKey = JSON.stringify({ input });
-			if (this.#editDiffArgsKey === argsKey) return;
-			this.#editDiffArgsKey = argsKey;
-
-			try {
-				const first = expandApplyPatchToEntries({ input })[0];
-				if (!first?.path) return;
-				computePatchDiff({ ...first, op: first.op ?? "update" }, this.#cwd, {
-					fuzzyThreshold: this.#editFuzzyThreshold,
-					allowFuzzy: this.#editAllowFuzzy,
-				}).then(result => {
-					if (this.#editDiffArgsKey === argsKey) {
-						this.#editDiffPreview = result;
-						this.#updateDisplay();
-						this.#ui.requestRender();
-					}
-				});
-			} catch (err) {
-				this.#editDiffPreview = { error: err instanceof Error ? err.message : String(err) };
-				this.#updateDisplay();
-				this.#ui.requestRender();
-			}
+	#schedulePreviewDiff(delayMs = 80): void {
+		if (!this.#editMode) return;
+		if (this.#editDiffScheduleTimer) {
+			clearTimeout(this.#editDiffScheduleTimer);
+			this.#editDiffScheduleTimer = undefined;
+		}
+		if (delayMs === 0) {
+			void this.#runPreviewDiff();
 			return;
 		}
+		this.#editDiffScheduleTimer = setTimeout(() => {
+			this.#editDiffScheduleTimer = undefined;
+			void this.#runPreviewDiff();
+		}, delayMs);
+	}
 
-		const first = edits[0];
-		if (!first || typeof first !== "object") return;
-
-		// Detect mode from first edit entry shape and compute preview for first file
-		if ("old_text" in first && "new_text" in first) {
-			// Replace mode
-			const { path, old_text: oldText, new_text: newText, all } = first;
-			if (!path || oldText === undefined || newText === undefined) return;
-
-			const argsKey = JSON.stringify({ path, oldText, newText, all });
-			if (this.#editDiffArgsKey === argsKey) return;
-			this.#editDiffArgsKey = argsKey;
+	async #runPreviewDiff(): Promise<void> {
+		const editMode = this.#editMode;
+		if (!editMode) return;
+		const strategy = EDIT_MODE_STRATEGIES[editMode];
+		if (!strategy) return;
+
+		const args = this.#args;
+		if (args == null || typeof args !== "object") return;
+
+		const partialJson = (args as { __partialJson?: string }).__partialJson;
+		let effectiveArgs: unknown;
+		try {
+			effectiveArgs = strategy.extractCompleteEdits(args, partialJson);
+		} catch {
+			effectiveArgs = args;
+		}
 
-			computeEditDiff(path, oldText, newText, this.#cwd, true, all, this.#editFuzzyThreshold).then(result =>
-				this.#applyEditDiffResult(argsKey, result),
-			);
-		} else if ("path" in first && ("diff" in first || ("op" in first && !("content" in first)))) {
-			// Patch mode (has diff or op without content — chunk edits always have content)
-			const { path, op, rename, diff } = first;
-			if (!path) return;
+		// Coalesce duplicate computes for identical args.
+		let argsKey: string;
+		try {
+			argsKey = JSON.stringify(effectiveArgs);
+		} catch {
+			argsKey = String(Date.now());
+		}
+		if (argsKey === this.#editDiffLastArgsKey) return;
+		this.#editDiffLastArgsKey = argsKey;
 
-			const argsKey = JSON.stringify({ path, op, rename, diff });
-			if (this.#editDiffArgsKey === argsKey) return;
-			this.#editDiffArgsKey = argsKey;
+		this.#editDiffAbort?.abort();
+		const controller = new AbortController();
+		this.#editDiffAbort = controller;
 
-			computePatchDiff({ path, op, rename, diff }, this.#cwd, {
+		try {
+			const previews = await strategy.computeDiffPreview(effectiveArgs, {
+				cwd: this.#cwd,
+				signal: controller.signal,
 				fuzzyThreshold: this.#editFuzzyThreshold,
 				allowFuzzy: this.#editAllowFuzzy,
-			}).then(result => this.#applyEditDiffResult(argsKey, result));
-		} else if ("loc" in first && "path" in first) {
-			// Hashline mode — group edits by path, preview first file
-			const path = first.path;
-			if (!path) return;
-			const fileEdits = edits.filter((e: any) => e.path === path);
-			const move = this.#args?.move;
-
-			const argsKey = JSON.stringify({ path, edits: fileEdits, move });
-			if (this.#editDiffArgsKey === argsKey) return;
-			this.#editDiffArgsKey = argsKey;
-
-			computeHashlineDiff({ path, edits: fileEdits, move }, this.#cwd).then(result =>
-				this.#applyEditDiffResult(argsKey, result),
-			);
+			});
+			if (controller.signal.aborted) return;
+			if (previews) {
+				this.#editDiffPreview = previews;
+				this.#updateDisplay();
+				this.#ui.requestRender();
+			}
+		} catch (err) {
+			if (controller.signal.aborted) return;
+			logger.warn("Edit preview diff failed", { tool: this.#toolName, error: String(err) });
 		}
-		// Chunk mode edits don't have a pre-execution diff preview
-	}
-
-	#applyEditDiffResult(argsKey: string, result: DiffResult | DiffError): void {
-		if (this.#editDiffArgsKey !== argsKey) return;
-		this.#editDiffPreview = result;
-		this.#updateDisplay();
-		this.#ui.requestRender();
 	}
 
 	updateResult(
@@ -378,6 +361,12 @@ export class ToolExecutionComponent extends Container {
 			this.#spinnerInterval = undefined;
 			this.#spinnerFrame = undefined;
 		}
+		if (this.#editDiffScheduleTimer) {
+			clearTimeout(this.#editDiffScheduleTimer);
+			this.#editDiffScheduleTimer = undefined;
+		}
+		this.#editDiffAbort?.abort();
+		this.#editDiffAbort = undefined;
 	}
 
 	setExpanded(expanded: boolean): void {
@@ -549,6 +538,9 @@ export class ToolExecutionComponent extends Container {
 				this.#contentBox.setBgFn(renderer.inline ? undefined : bgFn);
 				this.#contentBox.clear();
 
+				const renderContext = this.#buildRenderContext();
+				this.#renderState.renderContext = renderContext;
+
 				const shouldRenderCall = !this.#result || !renderer.mergeCallAndResult;
 				if (shouldRenderCall) {
 					// Render call component
@@ -567,10 +559,6 @@ export class ToolExecutionComponent extends Container {
 				// Render result component if we have a result
 				if (this.#result) {
 					try {
-						// Build render context for tools that need extra state
-						const renderContext = this.#buildRenderContext();
-						this.#renderState.renderContext = renderContext;
-
 						const resultComponent = renderer.renderResult(
 							{
 								content: this.#result.content as any,
@@ -646,10 +634,20 @@ export class ToolExecutionComponent extends Container {
 		if (!isEditLikeToolName(this.#toolName)) {
 			return this.#args;
 		}
-		if (!this.#editDiffPreview || !("diff" in this.#editDiffPreview) || !this.#editDiffPreview.diff) {
+		const previews = this.#editDiffPreview;
+		if (!previews || previews.length === 0) {
 			return this.#args;
 		}
-		return { ...(this.#args as Record<string, unknown>), previewDiff: this.#editDiffPreview.diff };
+		// Single-file previews feed the existing `previewDiff` channel consumed
+		// by `formatStreamingDiff` in the renderer. Multi-file previews are
+		// piped via `renderContext.perFileDiffPreview`, so the args we hand to
+		// `renderCall` only need the first file's diff to preserve prior
+		// single-file behavior.
+		const first = previews[0];
+		if (!first?.diff) {
+			return this.#args;
+		}
+		return { ...(this.#args as Record<string, unknown>), previewDiff: first.diff };
 	}
 
 	/**
@@ -680,8 +678,19 @@ export class ToolExecutionComponent extends Container {
 			context.previewLines = PYTHON_DEFAULT_PREVIEW_LINES;
 			context.timeout = normalizeTimeoutSeconds(this.#args?.timeout, 600);
 		} else if (isEditLikeToolName(this.#toolName)) {
-			// Edit needs diff preview and renderDiff function
-			context.editDiffPreview = this.#editDiffPreview;
+			context.editMode = this.#editMode;
+			const previews = this.#editDiffPreview;
+			if (previews && previews.length > 0) {
+				const first = previews[0];
+				if (first?.diff || first?.error) {
+					context.editDiffPreview = first.error
+						? { error: first.error }
+						: { diff: first.diff ?? "", firstChangedLine: first.firstChangedLine };
+				}
+				if (previews.length > 1) {
+					context.perFileDiffPreview = previews;
+				}
+			}
 			context.renderDiff = renderDiff;
 		}
 
@@ -733,9 +742,7 @@ export class ToolExecutionComponent extends Container {
 			lines.push("");
 			lines.push(theme.fg("dim", "Args"));
 			const tree = renderJsonTreeLines(
-				this.#args && typeof this.#args === "object" && !Array.isArray(this.#args)
-					? stripInternalArgs(this.#args as Record<string, unknown>)
-					: this.#args,
+				this.#args,
 				theme,
 				JSON_TREE_MAX_DEPTH_EXPANDED,
 				JSON_TREE_MAX_LINES_EXPANDED,

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

@@ -715,7 +715,7 @@ export class InputController {
 			return;
 		}
 
-		const currentText = this.ctx.editor.getText();
+		const currentText = this.ctx.editor.getExpandedText?.() ?? this.ctx.editor.getText();
 
 		let ttyHandle: fs.FileHandle | null = null;
 		try {

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

@@ -362,7 +362,7 @@ export class SelectorController {
 				}
 				break;
 			case "providers.image":
-				if (value === "auto" || value === "gemini" || value === "openrouter") {
+				if (value === "auto" || value === "openai" || value === "gemini" || value === "openrouter") {
 					setPreferredImageProvider(value);
 				}
 				break;

package/src/modes/interactive-mode.ts

@@ -63,7 +63,6 @@ import { SelectorController } from "./controllers/selector-controller";
 import { SSHCommandController } from "./controllers/ssh-command-controller";
 import { OAuthManualInputManager } from "./oauth-manual-input";
 import { SessionObserverRegistry } from "./session-observer-registry";
-import { setMermaidRenderCallback } from "./theme/mermaid-cache";
 import type { Theme } from "./theme/theme";
 import {
 	getEditorTheme,
@@ -220,7 +219,6 @@ export class InteractiveMode implements InteractiveModeContext {
 
 		this.ui = new TUI(new ProcessTerminal(), settings.get("showHardwareCursor"));
 		this.ui.setClearOnShrink(settings.get("clearOnShrink"));
-		setMermaidRenderCallback(() => this.ui.requestRender());
 		this.chatContainer = new Container();
 		this.pendingMessagesContainer = new Container();
 		this.statusContainer = new Container();

package/src/modes/print-mode.ts

@@ -161,6 +161,14 @@ export async function runPrintMode(session: AgentSession, options: PrintModeOpti
 				}
 			}
 
+			if (
+				assistantMsg.errorMessage &&
+				assistantMsg.stopReason !== "error" &&
+				assistantMsg.stopReason !== "aborted"
+			) {
+				process.stderr.write(`${sanitizeText(assistantMsg.errorMessage)}\n`);
+			}
+
 			// Output text content
 			for (const content of assistantMsg.content) {
 				if (content.type === "text") {

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

@@ -1,63 +1,24 @@
-import { extractMermaidBlocks, logger, renderMermaidAsciiSafe } from "@oh-my-pi/pi-utils";
+import { renderMermaidAsciiSafe } from "@oh-my-pi/pi-utils";
 
-const cache = new Map<bigint | number, string | null>();
+const cache = new Map<string, string | null>();
 
-let onRenderNeeded: (() => void) | null = null;
-
-/**
- * Set callback to trigger TUI re-render when mermaid ASCII renders become available.
- */
-export function setMermaidRenderCallback(callback: (() => void) | null): void {
-	onRenderNeeded = callback;
-}
-
-/**
- * Get a pre-rendered mermaid ASCII diagram by hash.
- * Returns null if not cached or rendering failed.
- */
-export function getMermaidAscii(hash: bigint | number): string | null {
-	return cache.get(hash) ?? null;
+function normalizeMermaidSource(source: string): string {
+	return source.replace(/\r\n?/g, "\n").trim();
 }
 
 /**
- * Render all mermaid blocks in markdown text.
- * Caches results and calls render callback when new diagrams are available.
+ * Resolve mermaid ASCII from fenced block source text.
+ * Returns null when rendering fails, while memoizing failures to avoid repeated work.
  */
-export function prerenderMermaid(markdown: string): void {
-	const blocks = extractMermaidBlocks(markdown);
-	if (blocks.length === 0) return;
-
-	let hasNew = false;
-
-	for (const { source, hash } of blocks) {
-		if (cache.has(hash)) continue;
-
-		const ascii = renderMermaidAsciiSafe(source);
-		if (ascii) {
-			cache.set(hash, ascii);
-			hasNew = true;
-		} else {
-			cache.set(hash, null);
-		}
+export function resolveMermaidAscii(source: string): string | null {
+	const normalizedSource = normalizeMermaidSource(source);
+	if (cache.has(normalizedSource)) {
+		return cache.get(normalizedSource) ?? null;
 	}
 
-	if (hasNew && onRenderNeeded) {
-		try {
-			onRenderNeeded();
-		} catch (error) {
-			logger.warn("Mermaid render callback failed", {
-				error: error instanceof Error ? error.message : String(error),
-			});
-		}
-	}
-}
-
-/**
- * Check if markdown contains mermaid blocks that aren't cached yet.
- */
-export function hasPendingMermaid(markdown: string): boolean {
-	const blocks = extractMermaidBlocks(markdown);
-	return blocks.some(({ hash }) => !cache.has(hash));
+	const ascii = normalizedSource ? renderMermaidAsciiSafe(normalizedSource) : null;
+	cache.set(normalizedSource, ascii);
+	return ascii;
 }
 
 /**

package/src/modes/theme/theme.ts

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

package/src/prompts/agents/librarian.md

@@ -98,7 +98,7 @@ Before acting, determine what kind of question this is:
 - For API signatures: copy verbatim from source. You **MUST NOT** paraphrase or reconstruct from memory.
 
 ## 5. Report
-- Call `submit_result` with structured findings.
+- Call `yield` with structured findings.
 - Every `sources` entry **MUST** include a verbatim excerpt.
 - The `api` array **MUST** contain exact signatures copied from source.
 - Clean up cloned repos: `rm -rf /tmp/librarian-*`.

package/src/prompts/agents/reviewer.md

@@ -44,7 +44,7 @@ output:
             type: number
           file_path:
             metadata:
-              description: Absolute path to affected file
+              description: Path to affected file
             type: string
           line_start:
             metadata:
@@ -63,7 +63,7 @@ Your goal is to identify bugs the author would want fixed before merge.
 1. Run `git diff` (or `gh pr diff <number>`) to view patch
 2. Read modified files for full context
 3. Call `report_finding` per issue
-4. Call `submit_result` with verdict
+4. Call `yield` with verdict
 
 Bash is read-only: `git diff`, `git log`, `git show`, `gh pr diff`. You **MUST NOT** make file edits or trigger builds.
 </procedure>
@@ -108,10 +108,10 @@ Each `report_finding` requires:
 - `body`: One paragraph
 - `priority`: 0-3
 - `confidence`: 0.0-1.0
-- `file_path`: Absolute path
+- `file_path`: Path to affected file
 - `line_start`, `line_end`: Range ≤10 lines, must overlap diff
 
-Final `submit_result` call (payload under `result.data`):
+Final `yield` call (payload under `result.data`):
 - `result.data.overall_correctness`: "correct" (no bugs/blockers) or "incorrect"
 - `result.data.explanation`: Plain text, 1-3 sentences summarizing verdict. Don't repeat findings (captured via `report_finding`).
 - `result.data.confidence`: 0.0-1.0

package/src/prompts/ci-green-request.md

@@ -4,7 +4,7 @@ Do not stop after a single fix attempt.
 </critical>
 
 <instruction>
-- Prefer `gh_run_watch` with no arguments if that tool is available.
+- Prefer the `github` tool with `op: run_watch` and no other arguments if that tool is available.
 - Otherwise use `gh` cli.
 - Use the workflow runs for the current HEAD commit as the source of truth after each push.
 </instruction>

package/src/prompts/review-request.md

@@ -40,7 +40,7 @@ Reviewer **MUST**:
 2. {{#if skipDiff}}**MUST** run `git diff`/`git show` for assigned files{{else}}**MUST** use diff hunks below (**MUST NOT** re-run git diff){{/if}}
 3. **MAY** read full file context as needed via `read`
 4. Call `report_finding` per issue
-5. Call `submit_result` with verdict when done
+5. Call `yield` with verdict when done
 
 {{#if skipDiff}}
 ### Diff Previews

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

@@ -15,9 +15,9 @@ If you need additional information, you can find your conversation with the user
 {{/if}}
 
 {{SECTION_SEPARATOR "Closure"}}
-No TODO tracking, no progress updates. Execute, call `submit_result`, done.
+No TODO tracking, no progress updates. Execute, call `yield`, done.
 
-When finished, you **MUST** call `submit_result` exactly once. This is like writing to a ticket, provide what is required, and close it.
+When finished, you **MUST** call `yield` exactly once. This is like writing to a ticket, provide what is required, and close it.
 
 This is your only way to return a result. You **MUST NOT** put JSON in plain text, and you **MUST NOT** substitute a text summary for the structured `result.data` parameter.
 
@@ -29,7 +29,7 @@ Your result **MUST** match this TypeScript interface:
 {{/if}}
 
 {{SECTION_SEPARATOR "Giving Up"}}
-Giving up is a last resort. If truly blocked, you **MUST** call `submit_result` exactly once with `result.error` describing what you tried and the exact blocker.
+Giving up is a last resort. If truly blocked, you **MUST** call `yield` exactly once with `result.error` describing what you tried and the exact blocker.
 You **MUST NOT** give up due to uncertainty, missing information obtainable via tools or repo context, or needing a design decision you can derive yourself.
 
 You **MUST** keep going until this ticket is closed. This matters.

package/src/prompts/system/subagent-yield-reminder.md

@@ -0,0 +1,11 @@
+<system-reminder>
+You stopped without calling yield. This is reminder {{retryCount}} of {{maxRetries}}.
+
+You **MUST** call yield as your only action now. Choose one:
+- If task is complete: call yield with your result in `result.data`
+- If task failed: call yield with `result.error` describing what happened
+
+You **MUST NOT** give up if you can still complete the task through exploration (using available tools or repo context). If you submit an error, you **MUST** include what you tried and the exact blocker.
+
+You **MUST NOT** output text without a tool call. You **MUST** call yield to finish.
+</system-reminder>

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

@@ -187,13 +187,16 @@ You **MUST NOT** use Python or Bash when a specialized tool exists.
 {{/ifAny}}
 
 {{#ifAny (includes tools "read") (includes tools "write") (includes tools "grep") (includes tools "find") (includes tools "edit")}}
-{{#has tools "read"}}- Use `read`, not `cat` or `open`.{{/has}}
+{{#has tools "read"}}- Use `read`, not `cat`.{{/has}}
 {{#has tools "write"}}- Use `write`, not shell redirection.{{/has}}
 {{#has tools "grep"}}- Use `grep`, not shell regex search.{{/has}}
 {{#has tools "find"}}- Use `find`, not shell file globbing.{{/has}}
 {{#has tools "edit"}}- Use `edit` for surgical text changes, not `sed`.{{/has}}
 {{/ifAny}}
 
+### Paths
+- For tools that take a `path` (or path-like field), prefer cwd-relative paths for files inside the cwd. Use absolute paths only when targeting files outside the cwd or when expanding `~`.
+
 {{#has tools "lsp"}}
 ### LSP guidance
 Use semantic tools for semantic questions:

package/src/prompts/tools/ask.md

@@ -21,8 +21,9 @@ Asks user when you need clarification or input during task execution.
 - **Do NOT include "Other" option** — UI automatically adds "Other (type your own)" to every question.
 </critical>
 
-<example name="single">
+<examples>
+# Single question
 question: "Which authentication method should this API use?"
 options: [{"label": "JWT"}, {"label": "OAuth2"}, {"label": "Session cookies"}]
 recommended: 0
-</example>
+</examples>