@oh-my-pi/pi-coding-agent 14.2.0 → 14.3.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";
@@ -65,6 +58,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 +110,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 +168,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 +362,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 +539,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 +560,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 +635,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 +679,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;
 		}
 

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/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/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/system/system-prompt.md

@@ -187,7 +187,7 @@ 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}}

package/src/prompts/tools/ast-grep.md

@@ -10,6 +10,7 @@ Performs structural code search using AST matching via native ast-grep.
 - Metavariable names are UPPERCASE and must be the whole AST node — partial-text like `prefix$VAR`, `"hello $NAME"`, or `a $OP b` does NOT work; match the whole node instead
 - When the same metavariable appears twice, both occurrences **MUST** match identical code (`$A == $A` matches `x == x`, not `x == y`)
 - Patterns **MUST** parse as a single valid AST node for the target language. For method fragments or body snippets that don't parse standalone, wrap in valid context (e.g. `class $_ { … }`) and set `sel` to target the inner node — results return for the selected node, not the outer wrapper. If ast-grep reports `Multiple AST nodes are detected`, the pattern isn't a single parseable node — wrap and use `sel`
+- C++ qualified calls used as expression statements need the statement semicolon in the pattern: use `ns::doThing($ARG);`, `$CALLEE($ARG)`, or wrap a statement snippet and select `call_expression`. Without `;`, tree-sitter-cpp may parse `ns::doThing($ARG)` as declaration-like syntax and return no matches
 - For TS declarations/methods, tolerate unknown annotations: `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($ARG: $_): $_ { $$$BODY } }`
 - Declaration forms are structurally distinct — top-level `function foo`, class method `foo()`, and `const foo = () => {}` are different AST shapes; search the right form before concluding absence
 - Loosest existence check: `pat: ["executeBash"]` with `sel: "identifier"`

package/src/prompts/tools/browser.md

@@ -1,6 +1,7 @@
 Navigates, clicks, types, scrolls, drags, queries DOM content, and captures screenshots.
 
 <instruction>
+- For fetching static web content (articles, docs, issues/PRs, JSON, PDFs, feeds), prefer the `read` tool with a URL — it returns clean reader-mode text without spinning up a browser. Use this tool only when you need JS execution, authentication, or interactive actions.
 - `"open"` starts a headless session (or implicitly on first action); `"goto"` navigates to `url`; `"close"` releases the browser
 - `"observe"` captures a numbered accessibility snapshot — prefer `click_id`/`type_id`/`fill_id` using returned `element_id` values; flags: `include_all`, `viewport_only`
 - `"click"`, `"type"`, `"fill"`, `"press"`, `"scroll"`, `"drag"` for selector-based interactions — prefer ARIA/text selectors (`p-aria/[name="Sign in"]`, `p-text/Continue`) over brittle CSS

package/src/prompts/tools/chunk-edit.md

@@ -1,13 +1,14 @@
-Edits files via syntax-aware chunks. Run `read(path="file.ts")` first.
+Edits files via syntax-aware chunks. Use `read(path="file.ts")` to read and discover chunks before editing.
+- `read` is the canonical read path for chunk source and `sel="?"` tree listings.
 - `write` rewrites the entire targeted region — best for most edits.
-- `replace` does surgical find-and-replace within a chunk — use when making small changes to a large chunk, or batching multiple substitutions.
 - `insert` adds content before/after a chunk.
+- `delete` deletes a targeted chunk and must be explicit.
 
 Call format: `{"edits": [{"path": "file:chunk#ID~", "write": "new body"}, …]}`
 
 <rules>
-- **MUST** `read` first. Never invent chunk paths or IDs. Copy them from the latest `read` output or edit response.
-- `path` format: `file:selector` — e.g. `src/app.ts:fn_foo#ABCD~`. Append `~` for body, `^` for head, or nothing for the whole chunk. Include `#ID` for `put`/`find`+`replace`/`delete`.
+- **MUST** inspect first with `read`. Never invent chunk paths or IDs. Copy them from the latest `read` output or edit response.
+- `path` format: `file:selector` — e.g. `src/app.ts:fn_foo#ABCD~`. Append `~` for body, `^` for head, or nothing for the whole chunk. Include `#ID` for `write`/`delete`.
 - If the exact chunk path is unclear, run `read(path="file", sel="?")` and copy a selector from that listing.
 {{#if chunkAutoIndent}}
 - Use `\t` for indentation in `content`. Write content at indent-level 0 — the tool re-indents it to match the chunk's position in the file. For example, to replace `~` of a method, write the body starting at column 0:
@@ -16,6 +17,8 @@ Call format: `{"edits": [{"path": "file:chunk#ID~", "write": "new body"}, …]}`
   ```
   The tool adds the correct base indent automatically. Never manually pad with the chunk's own indentation.
   Multiple sibling body lines at the same level all start at column 0: `"print(a)\nprint(b)\nprint(c)\n"`. Only use `\t` when nesting deeper (e.g. `"if cond:\n\tinner\nouter\n"`).
+  Before applying the target's base indent, the tool strips any common leading whitespace shared by all non-empty `write` lines as a safety net. Do not rely on that cleanup for mixed indentation; write `~` bodies at column 0 and use one `\t` per relative nesting level.
+  Multi-line replacements use the same relative-indentation model: the replacement text is dedented, then re-indented to the matched source line. Do not include the chunk's base indentation in replacement text.
   **Common mistake** when replacing `~` of a function body: do NOT include the function's own indentation.
   Wrong: `"if b == 0:\n\t\treturn None\n\treturn a / b\n"` — adds the function's base `\t` to every line.
   Correct: `"if b == 0:\n\treturn None\nreturn a / b\n"` — `if` and `return a / b` at column 0, only `return None` gets `\t` for nesting.
@@ -26,10 +29,15 @@ Call format: `{"edits": [{"path": "file:chunk#ID~", "write": "new body"}, …]}`
   content: "if (x) {\n  return true;\n}"
   ```
   The tool adds the correct base indent automatically, then preserves the tabs/spaces you used inside the snippet. Never manually pad with the chunk's own indentation.
+  Before applying the target's base indent, the tool strips any common leading whitespace shared by all non-empty `write` lines as a safety net. Do not rely on that cleanup for mixed indentation; write `~` bodies at column 0.
+  Multi-line replacements use the same relative-indentation model: the replacement text is dedented, then re-indented to the matched source line. Do not include the chunk's base indentation in replacement text.
 {{/if}}
-- Region suffixes only apply to container chunks (classes, functions, impl blocks, sections). On leaf chunks (enum variants, fields, single statements, and compound statements like `if`/`for`/`while`/`match`/`try`), `~` and `^` silently fall back to whole-chunk replacement — prefer the unsuffixed form and always supply the complete replacement (condition + body, not just the body) to avoid dropping structural parts.
-- `put`, `find`+`replace`, and `delete` require the current ID. `prepend`/`append` do not.
+- Region suffixes only apply to chunks with a real head/body boundary (classes, functions, impl blocks, and similar containers). On code leaf chunks (enum variants, fields, single statements, and compound statements like `if`/`for`/`while`/`match`/`try`), `~` and `^` are rejected. Use the unsuffixed selector and supply the complete replacement content, or edit the parent container's `~` body.
+- Unsuffixed `write` on a leaf chunk uses your content verbatim after normal replacement; it is not a body-region rewrite. Include the exact indentation and punctuation the leaf needs in the file.
+- `^` head writes and `~` body writes use the same base-indent model: write content at column 0 relative to the target region, and the tool applies the chunk's file indentation.
+- `write` and `delete` require the current ID. `prepend`/`append` do not.
 - **IDs change after every edit.** The edit response always carries the new IDs — use those for the next call or run `read(path="file", sel="?")` to refresh. Never reuse an ID from before the latest edit.
+- Same-file edit batches are transactional: if any operation in that file fails, no changes from that file's batch are saved. Multi-file edit calls run per file, so a later file error does not roll back earlier files that already succeeded.
 </rules>
 
 <critical>
@@ -42,24 +50,25 @@ You **MUST** use the narrowest region that covers your change. Putting without a
 
 <regions>
 In `read` output, lines marked `^` between the line number and `|` are **head** lines (doc comments, attributes/decorators, signature). Lines without `^` are **body** lines. Use this to decide which region to target:
-- `fn_foo#ID~` — **body only (the default choice for most edits).** Head lines (`^`) are preserved automatically — doc comments, attributes, and signature stay untouched. On leaf chunks, falls back to whole chunk.
+- `fn_foo#ID~` — **body only (the default choice for most edits).** Head lines (`^`) are preserved automatically — doc comments, attributes, and signature stay untouched. On code leaf chunks, this is rejected because there is no safe body boundary.
 - `fn_foo#ID^` — head only (decorators, attributes, doc comments, signature, opening delimiter). Body stays untouched.
 - `fn_foo#ID` — entire chunk including leading trivia. **You must include doc comments and attributes in `content`; omitting them deletes them.**
-- `chunk~` + `append`/`prepend` inserts *inside* the container. `chunk` + `append`/`prepend` inserts *outside*.
+- `chunk~` + `append`/`prepend` inserts *inside* the container. `chunk` + `append`/`prepend` inserts *outside*. Appending to a container without `~` emits a warning because it lands after the closing delimiter, not before it.
 
-**Note on leading trivia:** whether a decorator/doc comment belongs to `^` depends on the parser. In Rust and Python, attributes and decorators are attached to the function chunk, so `^` covers them. In TypeScript/JavaScript, a `@decorator` + `/** jsdoc */` block immediately above a method often surfaces as a **separate sibling chunk** (shown as `chunk#ID` in the `?` listing) rather than as part of the function's `^`. If you need to rewrite a decorator, check the `?` listing for a sibling `chunk#ID` directly above your target.
+**Note on leading trivia:** whether a decorator/doc comment belongs to `^` depends on the parser. In Rust and Python, attributes and decorators are attached to the function chunk, so `^` covers them. In TypeScript/JavaScript, a `@decorator` + `/** jsdoc */` block immediately above a method often surfaces as a **separate sibling chunk** (shown as `chunk#ID` in the `?` listing) rather than as part of the function's `^`. JSDoc directly above a plain function is more likely to be absorbed into that function's `^`. If you need to rewrite a decorated member, run `read(path="file", sel="?")` and check for a sibling `chunk#ID` directly above your target.
 
-**Note on non-code formats:** for prose and data formats (markdown, YAML, JSON, fenced code blocks, frontmatter), `^` and `~` fall back to the whole chunk. Always replace the entire chunk and include any delimiter syntax (fence backticks, `---` frontmatter markers, list markers) in your `content` — omitting them deletes them. For markdown sections (`sect_*`), always use unsuffixed whole-chunk replace — `^` and `~` on section containers also fall back to whole-chunk replace. When editing fenced code blocks in markdown, use the exact whitespace from the file (read with `raw` first) — the tool preserves literal indentation inside fenced blocks, but any content you supply is written verbatim. To insert content after a markdown section heading, use `after` on the heading chunk (`sect_*.chunk` or `sect_*.chunk_1`) — not `before`/`prepend` on the section itself, which lands physically before the heading and gets absorbed by the preceding section on reparse.
+**Python notes:** Python docstrings are body lines, not head lines. A `~` body write on a function that has a docstring deletes the docstring unless you include the docstring in `content`. Python enum members and nested functions/closures are often opaque inside their parent chunk and may not appear as addressable child chunks; rewrite the parent container body. Python decorated class/function `^` writes and Python `^` deletes are rejected because indentation-sensitive bodies can become attached to the wrong block while still parsing.
+
+**Note on non-code formats:** for prose and data formats (markdown, YAML, JSON, frontmatter), unsupported `^` and `~` suffixes warn and fall back to whole-chunk editing. Always replace the entire chunk and include any delimiter syntax (fence backticks, `---` frontmatter markers, list markers, table rows, headings) in your `content` — omitting them deletes them. For markdown sections (`sect_*`), prefer unsuffixed whole-chunk replace because `^`/`~` on prose sections can replace the heading and child content too; if you only need the heading, target the heading child chunk shown in `sel="?"`. Fenced code blocks with a declared language are parsed again and can expose inner chunks such as `code_py#ID.fn_gre#ID`; target those inner chunks when available. Markdown root writes preserve fenced code indentation verbatim. Recognized pipe tables expose `row_N` children for row-level edits; table cells and list items are not independently addressable, so rewrite the whole list/table chunk for those structural changes. Appending a table-row-shaped string (`| value |`) to a table chunk inserts it before the trailing blank-line separator so it remains part of the table. Otherwise read with `raw` first and preserve the exact whitespace inside fences. To insert content after a markdown section heading, use `after` on the heading chunk (`sect_*.chunk` or `sect_*.chunk_1`) — not `before`/`prepend` on the section itself, which lands physically before the heading and gets absorbed by the preceding section on reparse.
 </regions>
 
 <ops>
-Each edit entry has `path` (`file:selector`) plus **exactly one** operation field — `write`, `replace`, or `insert`. Never set more than one on the same entry.
+Each edit entry has `path` (`file:selector`) plus **exactly one** operation field — `write`, `insert`, or `delete`. Never set more than one on the same entry. `write:null`, `write:""`, and bare `{path}` entries are rejected; they do not delete.
 
 |fields|path (selector part)|effect|
 |---|---|---|
 |`write: "content"`|`file:chunk#ID`, `file:chunk#ID~`, or `file:chunk#ID^`|write complete new content to the region|
-|`write: null`|`file:chunk#ID`|delete the chunk|
-|`replace: {old, new}`|`file:chunk#ID`|find a literal substring in the chunk and replace it|
+|`delete: true`|`file:chunk#ID`|delete the chunk explicitly|
 |`insert: {loc, body}`|`file:chunk` or `file:chunk~`|insert before/after the chunk (`loc`: `"prepend"` or `"append"`)|
 </ops>
 
@@ -185,12 +194,6 @@ Result — the head (all `^` lines + opening brace) changes, body untouched:
     }
 ```
 
-**Find and replace** (surgical edit within a chunk):
-```
-{ "path": "counter.rs:impl_Counte.fn_increm#MNHV", "replace": { "old": "self.value += 1;", "new": "self.value = (self.value + 1).min(self.max);" } }
-```
-Result — only the matched substring changes, everything else is preserved.
-
 **Insert before a chunk** (`prepend`):
 ```
 { "path": "counter.rs:impl_Counte.fn_get", "insert": { "loc": "prepend", "body": "/// Resets the counter to zero.\npub fn reset(&mut self) {\n\tself.value = 0;\n}\n\n" } }
@@ -258,7 +261,7 @@ Result — a new method is added at the end of the impl body, before the closing
 
 **Delete a chunk**:
 ```
-{ "path": "counter.rs:impl_Counte.fn_decrem#TTWB", "write": null }
+{ "path": "counter.rs:impl_Counte.fn_decrem#TTWB", "delete": true }
 ```
 Result — the method (including its doc comment and signature) is removed.
 - Indentation rules (important):
@@ -268,12 +271,12 @@ Result — the method (including its doc comment and signature) is removed.
   - Match the file's real indentation characters in your snippet. The tool preserves your literal tabs/spaces after adding the target region's base indent.
 {{/if}}
   - Do NOT include the chunk's base indentation — only indent relative to the region's opening level.
+  - For `write`, the tool strips common leading whitespace shared by all non-empty lines, then adds the target region's base indent. If lines have mixed relative indentation, write them at column 0 so the common-margin cleanup cannot change the structure.
   - For `~` of a function: write at column 0, and use `\t` for *relative* nesting. Flat body: `"return x;\n"`. Multiple sibling lines: `"print(a)\nprint(b)\nprint(c)\n"` — all at column 0, the tool adds the function's base indent. Nested body: `"if (cond) {\n\treturn x;\n}\n"` — the `if` is at column 0, the `return` is one tab in. Python example — to replace `~` of `def divide(a, b):`, write: `"if b == 0:\n\treturn None\nreturn a / b\n"` — the `if` and `return a / b` are at column 0, `return None` is one `\t` in.
-  - For `^`: write at the chunk's own depth. A class member's head uses `"/// doc\n#[attr]\npub fn start() {"`.
+  - For `^`: write at column 0 relative to the head region, just like `~`. A class member's head uses `"/// doc\n#[attr]\npub fn start() {"` — do not include the class/member base indentation.
 {{#if chunkAutoIndent}}
   - For a top-level item: start at zero indent. Write `"fn foo() {\n\treturn 1;\n}\n"`.
 {{else}}
   - For a top-level item: start at zero indent. Write `"fn foo() {\n  return 1;\n}\n"`.
 {{/if}}
-  - The tool strips common leading indentation from your content as a safety net, so accidental over-indentation is corrected.
 </examples>

package/src/prompts/tools/gh-pr-push.md

@@ -2,7 +2,8 @@ Pushes a checked-out pull request branch back to its source branch through local
 
 <instruction>
 - Defaults to the current checked-out git branch
-- Uses branch metadata recorded by `gh_pr_checkout` to push back to the contributor fork and PR head branch
+- Requires branch metadata recorded by `gh_pr_checkout`; fail instead of pushing if the branch was not checked out with `gh_pr_checkout`
+- Pushes back to the contributor fork and PR head branch recorded in that metadata
 - Use `forceWithLease` only when rewriting the branch intentionally
 </instruction>
 

package/src/prompts/tools/grep.md

@@ -21,7 +21,8 @@ Searches files using powerful regex matching.
 </output>
 
 <critical>
-- You **MUST** use Grep when searching for content.
-- You **MUST NOT** invoke `grep` or `rg` via Bash.
-- If the search is open-ended, requiring multiple rounds, you **MUST** use Task tool with explore subagent instead.
+- You **MUST** use the built-in Grep tool for any content search. Do **NOT** shell out to `grep`, `rg`, `ripgrep`, `ag`, `ack`, `git grep`, `awk`, `sed`-for-search, or any other CLI search via Bash — even for a single match, even "just to check quickly", even piped through other commands.
+- Bash `grep`/`rg` returns raw text without chunk paths, loses `.gitignore` semantics, bypasses result limits, and wastes tokens. The Grep tool is faster, structured, and already wired into the workspace — there is no scenario where Bash search is preferable.
+- If you catch yourself typing `grep`, `rg`, or `| grep` in a Bash command, stop and re-issue the search through the Grep tool instead.
+- If the search is open-ended, requiring multiple rounds, you **MUST** use the Task tool with the explore subagent instead of chaining Grep calls yourself.
 </critical>

package/src/prompts/tools/lsp.md

@@ -31,3 +31,9 @@ Interacts with Language Server Protocol servers for code intelligence.
 - Glob expansion samples up to 20 files per request; use `file: "*"` for broader coverage
 - When `symbol` is provided for position-based actions, missing symbols or out-of-bounds `occurrence` values return an explicit error instead of silently falling back
 </caution>
+
+<critical>
+- You **MUST** use `lsp` for symbol-aware operations (rename, find references, go to definition/implementation, code actions) whenever a language server is available — it is safer and more accurate than text-based alternatives.
+- You **MUST NOT** perform cross-file renames with `ast_edit`, `sed`, `rsed`, or manual edits when `lsp` `rename` can do it. Text-based renames miss shadowing, re-exports, and usages in other files.
+- Prefer `lsp` `code_actions` for imports, quick-fixes, and refactors the language server already knows how to apply.
+</critical>