@oh-my-pi/pi-coding-agent 15.1.6 → 15.1.7

package/src/hashline/recovery.ts

@@ -3,7 +3,8 @@ import { generateDiffString } from "../edit/diff";
 import type { FileReadCache } from "../edit/file-read-cache";
 import { HashlineMismatchError } from "./anchors";
 import { applyHashlineEdits, type HashlineApplyResult } from "./apply";
-import type { HashlineApplyOptions, HashlineEdit } from "./types";
+import { computeLineHash } from "./hash";
+import type { Anchor, HashlineApplyOptions, HashlineEdit } from "./types";
 
 export interface HashlineRecoveryArgs {
 	cache: FileReadCache;
@@ -19,23 +20,58 @@ export interface HashlineRecoveryResult {
 	warnings: string[];
 }
 
-const HASHLINE_RECOVERY_FUZZ_FACTOR = 3;
+// Anchors are line-precise; never let Diff.applyPatch slide a hunk onto a
+// duplicate closer 100+ lines away. If the snapshot-based replay does not
+// align by exact line number, refuse and let the model re-read.
+const HASHLINE_RECOVERY_FUZZ_FACTOR = 0;
 
 const HASHLINE_RECOVERY_WARNING =
 	"Recovered from stale anchors using a previous read snapshot (file changed externally between read and edit).";
 
+/** Collect every line anchor an edit batch depends on. */
+function collectEditAnchors(edits: HashlineEdit[]): Anchor[] {
+	const anchors: Anchor[] = [];
+	for (const edit of edits) {
+		if (edit.kind === "delete") {
+			anchors.push(edit.anchor);
+			continue;
+		}
+		const cursor = edit.cursor;
+		if (cursor.kind === "before_anchor" || cursor.kind === "after_anchor") {
+			anchors.push(cursor.anchor);
+		}
+	}
+	return anchors;
+}
+
 /**
  * Attempt to recover from a `HashlineMismatchError` by replaying the edits
  * against a cached pre-edit snapshot of the file and 3-way-merging the result
  * onto the current on-disk content. Returns `null` when no recovery is
  * possible — callers should propagate the original mismatch error in that
  * case.
+ *
+ * Recovery is gated on a strict precondition: every line the model anchored
+ * MUST be present in the cached snapshot AND its content MUST hash to the
+ * model-supplied hash. This prevents 3-way merges from silently sliding onto
+ * the wrong site when only tangential parts of the file went stale.
  */
 export function tryRecoverHashlineWithCache(args: HashlineRecoveryArgs): HashlineRecoveryResult | null {
 	const { cache, absolutePath, currentText, edits, options } = args;
 	const snapshot = cache.get(absolutePath);
 	if (!snapshot || snapshot.lines.size === 0) return null;
 
+	// Precondition: the model's anchors must be vouched-for by the cache. If
+	// even one anchored line is missing from the snapshot, or its cached
+	// content hashes to a different value than the model supplied, refuse —
+	// any merge from here is a guess.
+	const anchors = collectEditAnchors(edits);
+	for (const anchor of anchors) {
+		const cachedLine = snapshot.lines.get(anchor.line);
+		if (cachedLine === undefined) return null;
+		if (computeLineHash(anchor.line, cachedLine) !== anchor.hash) return null;
+	}
+
 	const overlaid = currentText.split("\n");
 	let maxCachedLine = 0;
 	for (const lineNum of snapshot.lines.keys()) {
@@ -62,7 +98,12 @@ export function tryRecoverHashlineWithCache(args: HashlineRecoveryArgs): Hashlin
 	if (typeof merged !== "string" || merged === currentText) return null;
 
 	const mergedDiff = generateDiffString(currentText, merged);
-	const recoveryWarnings = [HASHLINE_RECOVERY_WARNING, ...(applied.warnings ?? [])];
+	// Only surface the recovery warning when the merge actually changed
+	// something visible. A no-op merge (e.g. trailing-newline only) is noise.
+	const hasNetChange = mergedDiff.firstChangedLine !== undefined;
+	const recoveryWarnings = hasNetChange
+		? [HASHLINE_RECOVERY_WARNING, ...(applied.warnings ?? [])]
+		: [...(applied.warnings ?? [])];
 
 	return {
 		lines: merged,

package/src/lsp/edits.ts

@@ -1,7 +1,17 @@
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import { formatPathRelativeToCwd } from "../tools/path-utils";
-import type { CreateFile, DeleteFile, RenameFile, TextDocumentEdit, TextEdit, WorkspaceEdit } from "./types";
+import { ToolError } from "../tools/tool-errors";
+import type {
+	CreateFile,
+	DeleteFile,
+	Position,
+	Range,
+	RenameFile,
+	TextDocumentEdit,
+	TextEdit,
+	WorkspaceEdit,
+} from "./types";
 import { uriToFile } from "./utils";
 
 // =============================================================================
@@ -23,6 +33,19 @@ export function applyTextEditsToString(content: string, edits: TextEdit[]): stri
 		return b.range.start.character - a.range.start.character;
 	});
 
+	// Detect overlapping ranges: in reverse-sorted order, each edit's start
+	// must be >= the next edit's end. If not, the edits would clobber each other
+	// once applied bottom-up (typically a multi-server rename with stale positions).
+	for (let i = 0; i < sortedEdits.length - 1; i++) {
+		const later = sortedEdits[i].range;
+		const earlier = sortedEdits[i + 1].range;
+		if (comparePosition(earlier.end, later.start) > 0) {
+			throw new ToolError(
+				`overlapping LSP edits: ${formatRange(earlier)} conflicts with ${formatRange(later)}; multi-server rename produced inconsistent edits`,
+			);
+		}
+	}
+
 	for (const edit of sortedEdits) {
 		const { start, end } = edit.range;
 
@@ -42,6 +65,47 @@ export function applyTextEditsToString(content: string, edits: TextEdit[]): stri
 	return lines.join("\n");
 }
 
+function comparePosition(a: Position, b: Position): number {
+	return a.line === b.line ? a.character - b.character : a.line - b.line;
+}
+
+function formatRange(range: Range): string {
+	return `${range.start.line + 1}:${range.start.character + 1}-${range.end.line + 1}:${range.end.character + 1}`;
+}
+
+/** True when two ranges overlap (share any position other than a touching boundary). */
+export function rangesOverlap(a: Range, b: Range): boolean {
+	return comparePosition(a.start, b.end) < 0 && comparePosition(b.start, a.end) < 0;
+}
+
+/**
+ * Flatten a WorkspaceEdit's text edits into a Map<uri, TextEdit[]>.
+ * Resource operations (create/rename/delete) are ignored — callers handle them separately.
+ */
+export function flattenWorkspaceTextEdits(edit: WorkspaceEdit): Map<string, TextEdit[]> {
+	const out = new Map<string, TextEdit[]>();
+	const push = (uri: string, edits: TextEdit[]) => {
+		if (edits.length === 0) return;
+		const prev = out.get(uri);
+		if (prev) prev.push(...edits);
+		else out.set(uri, [...edits]);
+	};
+	if (edit.changes) {
+		const changes = edit.changes;
+		for (const uri in changes) push(uri, changes[uri]);
+	}
+	if (edit.documentChanges) {
+		for (const change of edit.documentChanges) {
+			if ("textDocument" in change && change.textDocument && "edits" in change && change.edits) {
+				const tdc = change as TextDocumentEdit;
+				const textEdits = tdc.edits.filter((e): e is TextEdit => "range" in e && "newText" in e);
+				push(tdc.textDocument.uri, textEdits);
+			}
+		}
+	}
+	return out;
+}
+
 /**
  * Apply text edits to a file.
  * Edits are applied in reverse order (bottom-to-top) to preserve line/character indices.
@@ -63,47 +127,37 @@ export async function applyTextEdits(filePath: string, edits: TextEdit[]): Promi
 export async function applyWorkspaceEdit(edit: WorkspaceEdit, cwd: string): Promise<string[]> {
 	const applied: string[] = [];
 
-	// Handle changes map (legacy format)
-	if (edit.changes) {
-		for (const [uri, textEdits] of Object.entries(edit.changes)) {
-			const filePath = uriToFile(uri);
-			await applyTextEdits(filePath, textEdits);
-			applied.push(`Applied ${textEdits.length} edit(s) to ${formatPathRelativeToCwd(filePath, cwd)}`);
-		}
+	// Coalesce all text edits per URI before applying so a single file's edits
+	// are applied in one pass against a single snapshot — multiple TextDocumentEdits
+	// for the same URI would otherwise read stale positions on subsequent writes.
+	const textEditsByUri = flattenWorkspaceTextEdits(edit);
+	for (const [uri, textEdits] of textEditsByUri) {
+		const filePath = uriToFile(uri);
+		await applyTextEdits(filePath, textEdits);
+		applied.push(`Applied ${textEdits.length} edit(s) to ${formatPathRelativeToCwd(filePath, cwd)}`);
 	}
 
-	// Handle documentChanges array (modern format)
+	// Resource operations (create/rename/delete) preserve their original order.
 	if (edit.documentChanges) {
 		for (const change of edit.documentChanges) {
-			if ("textDocument" in change && change.textDocument && "edits" in change && change.edits) {
-				// TextDocumentEdit
-				const docChange = change as TextDocumentEdit;
-				const filePath = uriToFile(docChange.textDocument.uri);
-				const textEdits = docChange.edits.filter((e): e is TextEdit => "range" in e && "newText" in e);
-				await applyTextEdits(filePath, textEdits);
-				applied.push(`Applied ${textEdits.length} edit(s) to ${formatPathRelativeToCwd(filePath, cwd)}`);
-			} else if ("kind" in change && change.kind) {
-				// Resource operations
-				if (change.kind === "create") {
-					const createOp = change as CreateFile;
-					const filePath = uriToFile(createOp.uri);
-					await Bun.write(filePath, "");
-					applied.push(`Created ${formatPathRelativeToCwd(filePath, cwd)}`);
-				} else if (change.kind === "rename") {
-					const renameOp = change as RenameFile;
-					const oldPath = uriToFile(renameOp.oldUri);
-					const newPath = uriToFile(renameOp.newUri);
-					await fs.mkdir(path.dirname(newPath), { recursive: true });
-					await fs.rename(oldPath, newPath);
-					applied.push(
-						`Renamed ${formatPathRelativeToCwd(oldPath, cwd)} → ${formatPathRelativeToCwd(newPath, cwd)}`,
-					);
-				} else if (change.kind === "delete") {
-					const deleteOp = change as DeleteFile;
-					const filePath = uriToFile(deleteOp.uri);
-					await fs.rm(filePath, { recursive: true });
-					applied.push(`Deleted ${formatPathRelativeToCwd(filePath, cwd)}`);
-				}
+			if (!("kind" in change) || !change.kind) continue;
+			if (change.kind === "create") {
+				const createOp = change as CreateFile;
+				const filePath = uriToFile(createOp.uri);
+				await Bun.write(filePath, "");
+				applied.push(`Created ${formatPathRelativeToCwd(filePath, cwd)}`);
+			} else if (change.kind === "rename") {
+				const renameOp = change as RenameFile;
+				const oldPath = uriToFile(renameOp.oldUri);
+				const newPath = uriToFile(renameOp.newUri);
+				await fs.mkdir(path.dirname(newPath), { recursive: true });
+				await fs.rename(oldPath, newPath);
+				applied.push(`Renamed ${formatPathRelativeToCwd(oldPath, cwd)} → ${formatPathRelativeToCwd(newPath, cwd)}`);
+			} else if (change.kind === "delete") {
+				const deleteOp = change as DeleteFile;
+				const filePath = uriToFile(deleteOp.uri);
+				await fs.rm(filePath, { recursive: true });
+				applied.push(`Deleted ${formatPathRelativeToCwd(filePath, cwd)}`);
 			}
 		}
 	}

package/src/lsp/index.ts

@@ -7,7 +7,7 @@ import { type Theme, theme } from "../modes/theme/theme";
 import lspDescription from "../prompts/tools/lsp.md" with { type: "text" };
 import type { ToolSession } from "../tools";
 import { formatPathRelativeToCwd, resolveToCwd } from "../tools/path-utils";
-import { ToolAbortError, throwIfAborted } from "../tools/tool-errors";
+import { ToolAbortError, ToolError, throwIfAborted } from "../tools/tool-errors";
 import { clampTimeout } from "../tools/tool-timeouts";
 import {
 	ensureFileOpen,
@@ -25,7 +25,13 @@ import {
 } from "./client";
 import { getLinterClient } from "./clients";
 import { getServersForFile, type LspConfig, loadConfig } from "./config";
-import { applyTextEditsToString, applyWorkspaceEdit } from "./edits";
+import {
+	applyTextEdits,
+	applyTextEditsToString,
+	applyWorkspaceEdit,
+	flattenWorkspaceTextEdits,
+	rangesOverlap,
+} from "./edits";
 import { detectLspmux } from "./lspmux";
 import { renderCall, renderResult } from "./render";
 import {
@@ -1197,7 +1203,8 @@ export class LspTool implements AgentTool<typeof lspSchema, LspToolDetails, Them
 		const { action, file, line, symbol, query, new_name, apply, timeout } = params;
 		const timeoutSec = clampTimeout("lsp", timeout);
 		const timeoutSignal = AbortSignal.timeout(timeoutSec * 1000);
-		signal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+		const callerSignal = signal;
+		signal = callerSignal ? AbortSignal.any([callerSignal, timeoutSignal]) : timeoutSignal;
 		throwIfAborted(signal);
 
 		const config = getConfig(this.session.cwd);
@@ -1519,11 +1526,81 @@ export class LspTool implements AgentTool<typeof lspSchema, LspToolDetails, Them
 			}
 
 			const summary: string[] = [];
+
+			// Coalesce per-URI edits across servers before applying. Each server
+			// computed positions against the pre-edit file content, so applying
+			// server A then re-reading for server B yields stale positions and
+			// produces malformed imports. Group all text edits by URI, prefer the
+			// project-primary (project-aware) server on overlap, and apply once
+			// per URI from a single snapshot.
+			const serverConfigByName = new Map(servers);
+			interface AcceptedBucket {
+				primaryServer: string;
+				edits: TextEdit[];
+				discarded: number;
+				conflictServers: Set<string>;
+			}
+			const acceptedByUri = new Map<string, AcceptedBucket>();
 			for (const { serverName, edit } of perServerEdits) {
-				const applied = await applyWorkspaceEdit(edit, this.session.cwd);
-				if (applied.length > 0) {
-					summary.push(`  ${serverName}:`);
-					summary.push(...applied.map(line => `    ${line}`));
+				const cfg = serverConfigByName.get(serverName);
+				const incomingPrimary = cfg ? isProjectAwareLspServer(cfg) : false;
+				const flat = flattenWorkspaceTextEdits(edit);
+				for (const [uri, edits] of flat) {
+					const existing = acceptedByUri.get(uri);
+					if (!existing) {
+						acceptedByUri.set(uri, {
+							primaryServer: serverName,
+							edits: [...edits],
+							discarded: 0,
+							conflictServers: new Set(),
+						});
+						continue;
+					}
+					const existingCfg = serverConfigByName.get(existing.primaryServer);
+					const existingIsPrimary = existingCfg ? isProjectAwareLspServer(existingCfg) : false;
+					if (incomingPrimary && !existingIsPrimary) {
+						// Promote incoming to primary; keep existing edits that don't overlap.
+						const keptOld: TextEdit[] = [];
+						let discardedOld = 0;
+						for (const oe of existing.edits) {
+							if (edits.some(ne => rangesOverlap(ne.range, oe.range))) discardedOld++;
+							else keptOld.push(oe);
+						}
+						if (discardedOld > 0) existing.conflictServers.add(existing.primaryServer);
+						existing.discarded += discardedOld;
+						existing.primaryServer = serverName;
+						existing.edits = [...edits, ...keptOld];
+					} else {
+						// Existing wins; discard incoming edits that overlap any accepted edit.
+						let discardedNew = 0;
+						for (const ne of edits) {
+							if (existing.edits.some(ae => rangesOverlap(ae.range, ne.range))) {
+								discardedNew++;
+							} else {
+								existing.edits.push(ne);
+							}
+						}
+						if (discardedNew > 0) {
+							existing.conflictServers.add(serverName);
+							existing.discarded += discardedNew;
+						}
+					}
+				}
+			}
+
+			for (const [uri, bucket] of acceptedByUri) {
+				const filePath = uriToFile(uri);
+				await applyTextEdits(filePath, bucket.edits);
+				const rel = formatPathRelativeToCwd(filePath, this.session.cwd);
+				summary.push(`  ${bucket.primaryServer}: applied ${bucket.edits.length} edit(s) to ${rel}`);
+				if (bucket.discarded > 0) {
+					const others = Array.from(bucket.conflictServers).join(", ");
+					summary.push(
+						`    note: discarded ${bucket.discarded} overlapping edit(s) from ${others} (kept ${bucket.primaryServer})`,
+					);
+					logger.warn(
+						`lsp rename_file: discarded ${bucket.discarded} overlapping edit(s) from ${others} on ${rel}; kept ${bucket.primaryServer}`,
+					);
 				}
 			}
 
@@ -1844,6 +1921,22 @@ export class LspTool implements AgentTool<typeof lspSchema, LspToolDetails, Them
 				await ensureFileOpen(client, targetFile, signal);
 			}
 
+			// For project-aware servers, references/rename/definition without a `symbol`
+			// silently falls back to the first non-whitespace column on the line, which
+			// frequently points at the wrong identifier (decorator, keyword, parameter)
+			// and the server returns plausible-looking but unrelated results. Require
+			// `symbol` explicitly so callers cannot accidentally trigger that fallback.
+			if (
+				targetFile &&
+				line !== undefined &&
+				!symbol &&
+				(action === "references" || action === "rename" || action === "definition") &&
+				isProjectAwareLspServer(serverConfig)
+			) {
+				throw new ToolError(
+					`symbol is required for project-aware ${action}; pass symbol=<name>, optionally symbol#N for repeated occurrences`,
+				);
+			}
 			const uri = targetFile ? fileToUri(targetFile) : "";
 			const resolvedLine = line ?? 1;
 			const resolvedCharacter = targetFile ? await resolveSymbolColumn(targetFile, resolvedLine, symbol) : 0;
@@ -2166,7 +2259,17 @@ export class LspTool implements AgentTool<typeof lspSchema, LspToolDetails, Them
 				details: { serverName, action, success: true, request: params },
 			};
 		} catch (err) {
+			if (err instanceof ToolError) throw err;
 			if (err instanceof ToolAbortError || signal?.aborted) {
+				// Distinguish a wall-clock timeout from a caller cancel:
+				// callerSignal aborting → real cancel (re-throw ToolAbortError);
+				// timeoutSignal aborting without callerSignal → emit a ToolError naming the
+				// elapsed budget and server, instead of opaque "Operation aborted".
+				if (timeoutSignal.aborted && !callerSignal?.aborted) {
+					throw new ToolError(
+						`LSP ${action} timed out after ${timeoutSec}s on ${serverName}. The server may still be indexing; try again or pass timeout=<larger>.`,
+					);
+				}
 				throw new ToolAbortError();
 			}
 			const errorMessage = err instanceof Error ? err.message : String(err);

package/src/lsp/utils.ts

@@ -581,15 +581,28 @@ function firstNonWhitespaceColumn(lineText: string): number {
 	return match ? (match.index ?? 0) : 0;
 }
 
+const BARE_IDENTIFIER_RE = /^[A-Za-z_][\w]*$/;
+const IDENTIFIER_CHAR_RE = /[A-Za-z0-9_$]/;
+
 function findSymbolMatchIndexes(lineText: string, symbol: string, caseInsensitive = false): number[] {
 	if (symbol.length === 0) return [];
 	const haystack = caseInsensitive ? lineText.toLowerCase() : lineText;
 	const needle = caseInsensitive ? symbol.toLowerCase() : symbol;
+	const requireWordBoundary = BARE_IDENTIFIER_RE.test(symbol);
 	const indexes: number[] = [];
 	let fromIndex = 0;
 	while (fromIndex <= haystack.length - needle.length) {
 		const matchIndex = haystack.indexOf(needle, fromIndex);
 		if (matchIndex === -1) break;
+		if (requireWordBoundary) {
+			const before = matchIndex > 0 ? haystack[matchIndex - 1] : "";
+			const afterIdx = matchIndex + needle.length;
+			const after = afterIdx < haystack.length ? haystack[afterIdx] : "";
+			if (IDENTIFIER_CHAR_RE.test(before) || IDENTIFIER_CHAR_RE.test(after)) {
+				fromIndex = matchIndex + 1;
+				continue;
+			}
+		}
 		indexes.push(matchIndex);
 		fromIndex = matchIndex + needle.length;
 	}

package/src/modes/acp/acp-client-bridge.ts

@@ -124,6 +124,7 @@ async function requestPermission(
 		...(toolCall.kind ? { kind: toolCall.kind as ToolCallUpdate["kind"] } : {}),
 		...(toolCall.status ? { status: toolCall.status as ToolCallUpdate["status"] } : {}),
 		...(toolCall.rawInput !== undefined ? { rawInput: toolCall.rawInput } : {}),
+		...(toolCall.content ? { content: toolCall.content as ToolCallUpdate["content"] } : {}),
 		...(toolCall.locations ? { locations: toolCall.locations } : {}),
 	};
 	const acpOptions: AcpPermissionOption[] = options.map(option => ({

package/src/modes/components/status-line/segments.ts

@@ -84,7 +84,7 @@ const modelSegment: StatusLineSegment = {
 
 		let content = withIcon(theme.icon.model, modelName);
 
-		if (ctx.session.isFastModeEnabled() && theme.icon.fast) {
+		if (ctx.session.isFastModeActive() && theme.icon.fast) {
 			content += ` ${theme.icon.fast}`;
 		}
 

package/src/prompts/tools/bash.md

@@ -23,3 +23,17 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 - Truncated output is retrievable from `artifact://<id>` (linked in metadata)
 - Exit codes shown on non-zero exit
 </output>
+
+{{#if asyncEnabled}}
+# Timeout and async
+
+- `timeout` (seconds) caps the **wall-clock duration** of the command. When it elapses the process is killed and the call returns with a timeout annotation. Range: `1`–`3600`s; default `300`s (see `clampTimeout("bash", …)` in `tool-timeouts.ts`).
+- `async: true` only defers **reporting** of the result — it does NOT disable, extend, or detach the timeout. A daemon started with `async: true` is still killed when `timeout` elapses, regardless of how long the agent waits before reading the result.
+- For long-running daemons (dev servers, watchers): either pass an explicit large `timeout` (up to `3600`), or fully detach the process from this shell using `nohup …  &` / `setsid … &` / `disown` so it survives independent of the bash call's lifecycle.
+{{/if}}
+
+# Output minimizer
+
+- Bash stdout/stderr may be rewritten before you see it: long output is head/tail truncated, and test/lint runners (e.g. `bun test`, `cargo test`, ESLint) are passed through heuristic filters that drop noise and keep failures.
+- When the minimizer changes the visible text, the tool appends a `[raw output: artifact://<id>]` footer pointing at the **full untouched capture**. If a run looks suspicious (e.g. only a version banner) or you need the exact bytes, read that artifact.
+- If no footer is present, what you see is what the command actually emitted.

package/src/prompts/tools/debug.md

@@ -4,6 +4,7 @@ Use for launching or attaching debuggers, setting breakpoints, stepping through
 <instruction>
 - Prefer over bash for program state, breakpoints, stepping, thread inspection, or interrupting a running process.
 - `action: "launch"` starts a session; `program` is required, `adapter` optional (auto-selected from target path and workspace).
+  For Python, set `adapter: "debugpy"` and `program` to the target `.py` file; put interpreter/script flags in `args`.
 - `action: "attach"` connects to an existing process: `pid` for local attach, `port` for remote attach (where the adapter supports it), `adapter` to force a specific debugger.
 - **Breakpoints**: `set_breakpoint`/`remove_breakpoint` with source (`file`+`line`) or function (`function`); optional `condition` for conditional breakpoints.
 - **Flow control**: `continue` (resumes; briefly waits to observe whether the program stops or keeps running), `step_over`/`step_in`/`step_out` (single-step), `pause` (interrupt a running program so you can inspect state).
@@ -15,6 +16,7 @@ Use for launching or attaching debuggers, setting breakpoints, stepping through
 - Only one active debug session is supported at a time.
 - Some adapters require a launched session to receive `configurationDone` before the target actually runs; if the tool says configuration is pending, set breakpoints and then call `continue`.
 - Adapter availability depends on local binaries. Common built-ins: `gdb`, `lldb-dap`, `python -m debugpy.adapter`, `dlv dap`.
+- `program` must be an executable file or debug target, not a directory or interpreter name that resolves to a workspace directory.
 </caution>
 
 <examples>
@@ -24,7 +26,8 @@ Use for launching or attaching debuggers, setting breakpoints, stepping through
 3. `debug(action: "continue")`
 4. If the program appears hung: `debug(action: "pause")`
 5. Inspect state with `threads`, `stack_trace`, `scopes`, and `variables`
-
+# Launch a Python script with debugpy
+`debug(action: "launch", adapter: "debugpy", program: "scripts/job.py", args: ["--flag"])`
 # Raw debugger command through repl
 `debug(action: "evaluate", expression: "info registers", context: "repl")`
 </examples>

package/src/prompts/tools/find.md

@@ -2,6 +2,10 @@ Finds files using fast pattern matching that works with any codebase size.
 
 <instruction>
 - `paths` is required and accepts an array of globs, files, or directories
+- Pass multiple targets as **separate array elements** (`paths: ["a", "b"]`), NEVER as a single comma-joined string (`paths: ["a,b"]` is rejected)
+- `gitignore` defaults to `true` and hides files matched by `.gitignore`. Set `gitignore: false` to find `.env*`, `*.log`, freshly-created build outputs, or anything else your repo ignores
+- `hidden` defaults to `true`; combine with `gitignore: false` to surface dotfiles that are also gitignored
+- `timeout` is in seconds (default 5, clamped to 0.5–60). On timeout, find returns whatever partial matches it has collected with `truncated: true` and a notice — increase `timeout` or narrow the pattern instead of retrying blindly
 - You SHOULD perform multiple searches in parallel when potentially useful
 </instruction>
 
@@ -12,6 +16,12 @@ Matching file paths sorted by modification time (most recent first). Truncated a
 <examples>
 # Find files
 `{"paths": ["src/**/*.ts"], "limit": 1000}`
+# Multiple targets — separate array elements
+`{"paths": ["src/**/*.ts", "test/**/*.ts"]}`
+# Find gitignored files like .env
+`{"paths": [".env*"], "gitignore": false}`
+# Long-running search on a slow volume
+`{"paths": ["/Volumes/Storage/**/*.py"], "timeout": 30}`
 </examples>
 
 <avoid>

package/src/prompts/tools/hashline.md

@@ -19,8 +19,9 @@ Each op line is ONE of:
 Op lines carry no content — payload goes on the next line.
 
 WRONG: + 5pg| some code
+WRONG: {{hsep}} some code
 RIGHT: + 5pg
-       {{hsep}} some code
+{{hsep}}some code
 
 A single `+`/`<`/`=` op accepts MANY `{{hsep}}` payload lines. To insert N consecutive lines, write ONE op followed by N payload lines — NEVER N ops with one payload each.
 
@@ -37,8 +38,9 @@ RIGHT (one op, many payload lines):
 </format-reminder>
 
 <rules>
-- Every payload line MUST start with `{{hsep}}`.
-- Payload is verbatim — NEVER escape unicode.
+- Every payload line MUST start with `{{hsep}}` immediately followed by payload text. Do NOT add a readability space after `{{hsep}}`.
+- Every character after `{{hsep}}` is file content. If the target line intentionally starts with one space, write exactly one space after `{{hsep}}`; otherwise write none.
+- Payload text is verbatim — NEVER escape unicode.
 - **Payload is only what's NEW relative to your range:**
   - `=` replaces inside; NEVER include lines outside.
   - `+`/`<` adds at the anchor; NEVER repeat line A or neighbors.

package/src/prompts/tools/resolve.md

@@ -3,7 +3,7 @@ Resolves a pending action by either applying or discarding it.
   - `"apply"` persists / submits the pending action.
   - `"discard"` rejects the pending action.
 - `reason` is required: one short complete sentence explaining why, starting with a capital letter and ending with a period.
-- `extra` (optional) is free-form metadata passed to the resolving tool. Schema depends on context:
+- `extra` (optional) is free-form metadata passed to the resolving tool. When the pending action is a plan-approval gate, supply `extra.title` (kebab/PascalCase slug for the approved plan filename). For preview-style pending actions (e.g. `ast_edit`), `extra` is unused.
 
 Valid whenever a pending action exists — either a preview-style staging (e.g. `ast_edit`) or a long-lived approval gate.
 Call fails with an error when no pending action exists.

package/src/prompts/tools/search.md

@@ -1,8 +1,9 @@
 Searches files using powerful regex matching.
 
 <instruction>
-- Supports full regex syntax (e.g., `log.*Error`, `function\\s+\\w+`); literal braces need escaping (`interface\\{\\}` for `interface{}` in Go)
+- Supports Rust regex syntax (RE2-style — no lookaround or backreferences). Use line anchors or post-filters instead of (?!…)/(?<!…)
 - `paths` is required and accepts an array of files, directories, globs, or internal URLs
+- `paths` is an array; do not embed commas or spaces inside a single entry. Pass `["src", "tests"]` not `["src,tests"]`.
 - Cross-line patterns are detected from literal `\n` or escaped `\\n` in `pattern`
 </instruction>
 

package/src/prompts/tools/task.md

@@ -70,8 +70,12 @@ Parallel when tasks touch disjoint files or are independent refactors/tests.
 </assignment-fmt>
 
 <agents>
+{{#if spawningDisabled}}
+Agent spawning is disabled for this context.
+{{else}}
 {{#list agents join="\n"}}
 # {{name}}
 {{description}}
 {{/list}}
+{{/if}}
 </agents>

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

@@ -1,3 +1,5 @@
+**Tasks are referenced by their verbatim content string, not by any auto-generated ID. There is no "task-1"/"task-N" identifier — the tool never emits one. Pass the task's content text in the `task` field.**
+
 Manages a phased task list. Pass `ops`: a flat array of operations.
 The next pending task is auto-promoted to `in_progress` after each completion.
 Allowed `op` values are only `init`, `start`, `done`, `drop`, `rm`, `append`, and `note`. `pending` is a task status, not an `op`; leave not-yet-started tasks implicit in `init`/`append` lists.