@oh-my-pi/pi-coding-agent 13.3.7 → 13.3.8

package/src/lsp/render.ts

@@ -15,6 +15,7 @@ import {
 	formatExpandHint,
 	formatMoreItems,
 	formatStatusIcon,
+	replaceTabs,
 	shortenPath,
 	TRUNCATE_LENGTHS,
 	truncateToWidth,
@@ -31,9 +32,16 @@ import type { LspParams, LspToolDetails } from "./types";
  * Render the LSP tool call in the TUI.
  * Shows: "lsp <operation> <file/filecount>"
  */
+function sanitizeInlineText(value: string): string {
+	return replaceTabs(value).replaceAll(/\r?\n/g, " ");
+}
+
 export function renderCall(args: LspParams, _options: RenderResultOptions, theme: Theme): Text {
 	const actionLabel = (args.action ?? "request").replace(/_/g, " ");
 	const queryPreview = args.query ? truncateToWidth(args.query, TRUNCATE_LENGTHS.SHORT) : undefined;
+	const symbolPreview = args.symbol
+		? truncateToWidth(sanitizeInlineText(args.symbol), TRUNCATE_LENGTHS.SHORT)
+		: undefined;
 
 	let target: string | undefined;
 	let hasFileTarget = false;
@@ -41,26 +49,17 @@ export function renderCall(args: LspParams, _options: RenderResultOptions, theme
 	if (args.file) {
 		target = shortenPath(args.file);
 		hasFileTarget = true;
-	} else if (args.files?.length === 1) {
-		target = shortenPath(args.files[0]);
-		hasFileTarget = true;
-	} else if (args.files?.length) {
-		target = `${args.files.length} files`;
 	}
 
 	if (hasFileTarget && args.line !== undefined) {
-		const col = args.column !== undefined ? `:${args.column}` : "";
-		target += `:${args.line}${col}`;
-		if (args.end_line !== undefined) {
-			const endCol = args.end_character !== undefined ? `:${args.end_character}` : "";
-			target += `-${args.end_line}${endCol}`;
+		target += `:${args.line}`;
+		if (symbolPreview) {
+			target += ` (${symbolPreview})`;
 		}
 	} else if (!target && args.line !== undefined) {
-		const col = args.column !== undefined ? `:${args.column}` : "";
-		target = `line ${args.line}${col}`;
-		if (args.end_line !== undefined) {
-			const endCol = args.end_character !== undefined ? `:${args.end_character}` : "";
-			target += `-${args.end_line}${endCol}`;
+		target = `line ${args.line}`;
+		if (symbolPreview) {
+			target += ` (${symbolPreview})`;
 		}
 	}
 
@@ -68,9 +67,6 @@ export function renderCall(args: LspParams, _options: RenderResultOptions, theme
 	if (queryPreview && target) meta.push(`query:${queryPreview}`);
 	if (args.new_name) meta.push(`new:${args.new_name}`);
 	if (args.apply !== undefined) meta.push(`apply:${args.apply ? "true" : "false"}`);
-	if (args.include_declaration !== undefined) {
-		meta.push(`include_decl:${args.include_declaration ? "true" : "false"}`);
-	}
 
 	const descriptionParts = [actionLabel];
 	if (target) {
@@ -104,7 +100,7 @@ export function renderResult(
 	result: { content: Array<{ type: string; text?: string }>; details?: LspToolDetails; isError?: boolean },
 	options: RenderResultOptions,
 	theme: Theme,
-	args?: LspParams & { file?: string; files?: string[] },
+	args?: LspParams,
 ): Component {
 	const content = result.content?.[0];
 	if (!content || content.type !== "text" || !("text" in content) || !content.text) {
@@ -129,25 +125,19 @@ export function renderResult(
 	const requestLines: string[] = [];
 	if (request?.file) {
 		requestLines.push(theme.fg("toolOutput", request.file));
-	} else if (request?.files?.length === 1) {
-		requestLines.push(theme.fg("toolOutput", request.files[0]));
-	} else if (request?.files?.length) {
-		requestLines.push(theme.fg("dim", `${request.files.length} file(s)`));
 	}
 	if (request?.line !== undefined) {
-		const col = request.column !== undefined ? `:${request.column}` : "";
-		requestLines.push(theme.fg("dim", `line ${request.line}${col}`));
+		requestLines.push(theme.fg("dim", `line ${request.line}`));
 	}
-	if (request?.end_line !== undefined) {
-		const endCol = request.end_character !== undefined ? `:${request.end_character}` : "";
-		requestLines.push(theme.fg("dim", `end ${request.end_line}${endCol}`));
+	if (request?.symbol) {
+		requestLines.push(theme.fg("dim", `symbol: ${sanitizeInlineText(request.symbol)}`));
+		if (request.occurrence !== undefined) {
+			requestLines.push(theme.fg("dim", `occurrence: ${request.occurrence}`));
+		}
 	}
 	if (request?.query) requestLines.push(theme.fg("dim", `query: ${request.query}`));
 	if (request?.new_name) requestLines.push(theme.fg("dim", `new name: ${request.new_name}`));
 	if (request?.apply !== undefined) requestLines.push(theme.fg("dim", `apply: ${request.apply ? "true" : "false"}`));
-	if (request?.include_declaration !== undefined) {
-		requestLines.push(theme.fg("dim", `include declaration: ${request.include_declaration ? "true" : "false"}`));
-	}
 
 	const outputBlock = new CachedOutputBlock();
 

package/src/lsp/types.ts

@@ -7,19 +7,32 @@ import { type Static, Type } from "@sinclair/typebox";
 // =============================================================================
 
 export const lspSchema = Type.Object({
-	action: StringEnum(["diagnostics", "definition", "references", "hover", "symbols", "rename", "status", "reload"], {
-		description: "LSP operation",
-	}),
-	files: Type.Optional(Type.Array(Type.String({ description: "File path" }))),
+	action: StringEnum(
+		[
+			"diagnostics",
+			"definition",
+			"references",
+			"hover",
+			"symbols",
+			"rename",
+			"code_actions",
+			"type_definition",
+			"implementation",
+			"status",
+			"reload",
+		],
+		{ description: "LSP operation" },
+	),
 	file: Type.Optional(Type.String({ description: "File path" })),
 	line: Type.Optional(Type.Number({ description: "Line number (1-indexed)" })),
-	column: Type.Optional(Type.Number({ description: "Column number (1-indexed)" })),
-	end_line: Type.Optional(Type.Number({ description: "End line for range (1-indexed)" })),
-	end_character: Type.Optional(Type.Number({ description: "End column for range (1-indexed)" })),
+	symbol: Type.Optional(
+		Type.String({ description: "Symbol/substring to locate on the line (used to compute column)" }),
+	),
+	occurrence: Type.Optional(Type.Number({ description: "Symbol occurrence on line (1-indexed, default: 1)" })),
 	query: Type.Optional(Type.String({ description: "Search query or SSR pattern" })),
 	new_name: Type.Optional(Type.String({ description: "New name for rename" })),
 	apply: Type.Optional(Type.Boolean({ description: "Apply edits (default: true)" })),
-	include_declaration: Type.Optional(Type.Boolean({ description: "Include declaration in refs (default: true)" })),
+	timeout: Type.Optional(Type.Number({ description: "Request timeout in seconds" })),
 });
 
 export type LspParams = Static<typeof lspSchema>;

package/src/lsp/utils.ts

@@ -1,8 +1,11 @@
 export { truncate } from "@oh-my-pi/pi-utils";
 
 import path from "node:path";
+import { isEnoent } from "@oh-my-pi/pi-utils";
 import { type Theme, theme } from "../modes/theme/theme";
 import type {
+	CodeAction,
+	Command,
 	Diagnostic,
 	DiagnosticSeverity,
 	DocumentSymbol,
@@ -475,7 +478,8 @@ export function formatDocumentSymbol(symbol: DocumentSymbol, indent = 0): string
 	const prefix = "  ".repeat(indent);
 	const icon = symbolKindToIcon(symbol.kind);
 	const line = symbol.range.start.line + 1;
-	const results = [`${prefix}${icon} ${symbol.name} @ line ${line}`];
+	const detail = symbol.detail ? ` ${symbol.detail}` : "";
+	const results = [`${prefix}${icon} ${symbol.name}${detail} @ line ${line}`];
 
 	if (symbol.children) {
 		for (const child of symbol.children) {
@@ -496,6 +500,110 @@ export function formatSymbolInformation(symbol: SymbolInformation, cwd: string):
 	return `${icon} ${symbol.name}${container} @ ${location}`;
 }
 
+export function filterWorkspaceSymbols(symbols: SymbolInformation[], query: string): SymbolInformation[] {
+	const needle = query.trim().toLowerCase();
+	if (!needle) return symbols;
+	return symbols.filter(symbol => {
+		const fields = [symbol.name, symbol.containerName ?? "", uriToFile(symbol.location.uri)];
+		return fields.some(field => field.toLowerCase().includes(needle));
+	});
+}
+
+export function dedupeWorkspaceSymbols(symbols: SymbolInformation[]): SymbolInformation[] {
+	const seen = new Set<string>();
+	const unique: SymbolInformation[] = [];
+	for (const symbol of symbols) {
+		const key = [
+			symbol.name,
+			symbol.containerName ?? "",
+			symbol.kind,
+			symbol.location.uri,
+			symbol.location.range.start.line,
+			symbol.location.range.start.character,
+		].join(":");
+		if (seen.has(key)) continue;
+		seen.add(key);
+		unique.push(symbol);
+	}
+	return unique;
+}
+
+export function formatCodeAction(action: CodeAction | Command, index: number): string {
+	const kind = "kind" in action && action.kind ? action.kind : "action";
+	const preferred = "isPreferred" in action && action.isPreferred ? " (preferred)" : "";
+	const disabled = "disabled" in action && action.disabled ? ` (disabled: ${action.disabled.reason})` : "";
+	return `${index}: [${kind}] ${action.title}${preferred}${disabled}`;
+}
+
+export interface CodeActionApplyDependencies {
+	resolveCodeAction?: (action: CodeAction) => Promise<CodeAction>;
+	applyWorkspaceEdit: (edit: WorkspaceEdit) => Promise<string[]>;
+	executeCommand: (command: Command) => Promise<void>;
+}
+
+export interface AppliedCodeActionResult {
+	title: string;
+	edits: string[];
+	executedCommands: string[];
+}
+
+function isCommandItem(action: CodeAction | Command): action is Command {
+	return typeof action.command === "string";
+}
+
+export async function applyCodeAction(
+	action: CodeAction | Command,
+	dependencies: CodeActionApplyDependencies,
+): Promise<AppliedCodeActionResult | null> {
+	if (isCommandItem(action)) {
+		await dependencies.executeCommand(action);
+		return { title: action.title, edits: [], executedCommands: [action.command] };
+	}
+
+	let resolvedAction = action;
+	if (!resolvedAction.edit && dependencies.resolveCodeAction) {
+		try {
+			resolvedAction = await dependencies.resolveCodeAction(resolvedAction);
+		} catch {
+			// Resolve is optional; continue with unresolved action.
+		}
+	}
+
+	const edits = resolvedAction.edit ? await dependencies.applyWorkspaceEdit(resolvedAction.edit) : [];
+	const executedCommands: string[] = [];
+	if (resolvedAction.command) {
+		await dependencies.executeCommand(resolvedAction.command);
+		executedCommands.push(resolvedAction.command.command);
+	}
+
+	if (edits.length === 0 && executedCommands.length === 0) {
+		return null;
+	}
+
+	return { title: resolvedAction.title, edits, executedCommands };
+}
+
+const GLOB_PATTERN_CHARS = /[*?[{]/;
+
+export function hasGlobPattern(value: string): boolean {
+	return GLOB_PATTERN_CHARS.test(value);
+}
+
+export async function collectGlobMatches(
+	pattern: string,
+	cwd: string,
+	maxMatches: number,
+): Promise<{ matches: string[]; truncated: boolean }> {
+	const normalizedLimit = Number.isFinite(maxMatches) ? Math.max(1, Math.trunc(maxMatches)) : 1;
+	const matches: string[] = [];
+	for await (const match of new Bun.Glob(pattern).scan({ cwd })) {
+		if (matches.length >= normalizedLimit) {
+			return { matches, truncated: true };
+		}
+		matches.push(match);
+	}
+	return { matches, truncated: false };
+}
 // =============================================================================
 // Hover Content Extraction
 // =============================================================================
@@ -525,3 +633,87 @@ export function extractHoverText(
 
 // =============================================================================
 // General Utilities
+
+function firstNonWhitespaceColumn(lineText: string): number {
+	const match = lineText.match(/\S/);
+	return match ? (match.index ?? 0) : 0;
+}
+
+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 indexes: number[] = [];
+	let fromIndex = 0;
+	while (fromIndex <= haystack.length - needle.length) {
+		const matchIndex = haystack.indexOf(needle, fromIndex);
+		if (matchIndex === -1) break;
+		indexes.push(matchIndex);
+		fromIndex = matchIndex + needle.length;
+	}
+	return indexes;
+}
+
+function normalizeOccurrence(occurrence?: number): number {
+	if (occurrence === undefined || !Number.isFinite(occurrence)) return 1;
+	return Math.max(1, Math.trunc(occurrence));
+}
+
+export async function resolveSymbolColumn(
+	filePath: string,
+	line: number,
+	symbol?: string,
+	occurrence?: number,
+): Promise<number> {
+	const lineNumber = Math.max(1, line);
+	const matchOccurrence = normalizeOccurrence(occurrence);
+	try {
+		const fileText = await Bun.file(filePath).text();
+		const lines = fileText.split("\n");
+		const targetLine = lines[lineNumber - 1] ?? "";
+		if (!symbol) {
+			return firstNonWhitespaceColumn(targetLine);
+		}
+
+		const exactIndexes = findSymbolMatchIndexes(targetLine, symbol);
+		const fallbackIndexes = exactIndexes.length > 0 ? exactIndexes : findSymbolMatchIndexes(targetLine, symbol, true);
+		if (fallbackIndexes.length === 0) {
+			throw new Error(`Symbol "${symbol}" not found on line ${lineNumber}`);
+		}
+		if (matchOccurrence > fallbackIndexes.length) {
+			throw new Error(
+				`Symbol "${symbol}" occurrence ${matchOccurrence} is out of bounds on line ${lineNumber} (found ${fallbackIndexes.length})`,
+			);
+		}
+		return fallbackIndexes[matchOccurrence - 1];
+	} catch (error) {
+		if (isEnoent(error)) {
+			throw new Error(`File not found: ${filePath}`);
+		}
+		throw error;
+	}
+}
+
+export async function readLocationContext(filePath: string, line: number, contextLines = 1): Promise<string[]> {
+	const targetLine = Math.max(1, line);
+	const surrounding = Math.max(0, contextLines);
+	try {
+		const fileText = await Bun.file(filePath).text();
+		const lines = fileText.split("\n");
+		if (lines.length === 0) return [];
+
+		const startLine = Math.max(1, targetLine - surrounding);
+		const endLine = Math.min(lines.length, targetLine + surrounding);
+		const context: string[] = [];
+		for (let currentLine = startLine; currentLine <= endLine; currentLine++) {
+			const content = lines[currentLine - 1] ?? "";
+			context.push(`${currentLine}: ${content}`);
+		}
+		return context;
+	} catch (error) {
+		if (isEnoent(error)) {
+			return [];
+		}
+		throw error;
+	}
+}

package/src/mcp/config-writer.ts

@@ -6,6 +6,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { isEnoent } from "@oh-my-pi/pi-utils";
+import { invalidate as invalidateFsCache } from "../capability/fs";
 
 import { validateServerConfig } from "./config";
 import type { MCPConfigFile, MCPServerConfig } from "./types";
@@ -44,6 +45,8 @@ export async function writeMCPConfigFile(filePath: string, config: MCPConfigFile
 
 	// Rename to final path (atomic on most systems)
 	await fs.promises.rename(tmpPath, filePath);
+	// Invalidate the capability fs cache so subsequent reads see the new content
+	invalidateFsCache(filePath);
 }
 
 /**

package/src/modes/components/settings-defs.ts

@@ -149,6 +149,15 @@ const OPTION_PROVIDERS: Partial<Record<SettingPath, OptionProvider>> = {
 		{ value: "60", label: "60 seconds" },
 		{ value: "120", label: "120 seconds" },
 	],
+	// Global tool timeout ceiling
+	"tools.maxTimeout": [
+		{ value: "0", label: "No limit" },
+		{ value: "30", label: "30 seconds" },
+		{ value: "60", label: "60 seconds" },
+		{ value: "120", label: "120 seconds" },
+		{ value: "300", label: "5 minutes" },
+		{ value: "600", label: "10 minutes" },
+	],
 	// Edit fuzzy threshold
 	"edit.fuzzyThreshold": [
 		{ value: "0.85", label: "0.85", description: "Lenient" },

package/src/modes/interactive-mode.ts

@@ -54,7 +54,7 @@ import { SSHCommandController } from "./controllers/ssh-command-controller";
 import { OAuthManualInputManager } from "./oauth-manual-input";
 import { setMermaidRenderCallback } from "./theme/mermaid-cache";
 import type { Theme } from "./theme/theme";
-import { getEditorTheme, getMarkdownTheme, onThemeChange, theme } from "./theme/theme";
+import { getEditorTheme, getMarkdownTheme, onTerminalAppearanceChange, onThemeChange, theme } from "./theme/theme";
 import type { CompactionQueuedMessage, InteractiveModeContext, TodoItem, TodoPhase } from "./types";
 import { UiHelpers } from "./utils/ui-helpers";
 
@@ -363,6 +363,13 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.ui.requestRender();
 		});
 
+		// Subscribe to terminal Mode 2031 dark/light appearance change notifications.
+		// When the OS or terminal switches between dark and light mode, the terminal
+		// sends a DSR and we re-evaluate which theme to use.
+		this.ui.terminal.onAppearanceChange(mode => {
+			onTerminalAppearanceChange(mode);
+		});
+
 		// Set up git branch watcher
 		this.statusLine.watchBranch(() => {
 			this.updateEditorTopBorder();

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

@@ -6,9 +6,9 @@ import {
 } from "@oh-my-pi/pi-tui";
 import { logger } from "@oh-my-pi/pi-utils";
 
-const cache = new Map<string, MermaidImage>();
-const pending = new Map<string, Promise<MermaidImage | null>>();
-const failed = new Set<string>();
+const cache = new Map<bigint, MermaidImage>();
+const pending = new Map<bigint, Promise<MermaidImage | null>>();
+const failed = new Set<bigint>();
 
 const defaultOptions: MermaidRenderOptions = {
 	theme: "dark",
@@ -28,7 +28,7 @@ export function setMermaidRenderCallback(callback: (() => void) | null): void {
  * Get a pre-rendered mermaid image by hash.
  * Returns null if not cached or rendering failed.
  */
-export function getMermaidImage(hash: string): MermaidImage | null {
+export function getMermaidImage(hash: bigint): MermaidImage | null {
 	return cache.get(hash) ?? null;
 }
 

package/src/modes/theme/theme.ts

@@ -1616,7 +1616,15 @@ export async function getThemeByName(name: string): Promise<Theme | undefined> {
 	}
 }
 
+/** Appearance reported by Mode 2031 (terminal DSR), or undefined if not (yet) available. */
+var terminalReportedAppearance: "dark" | "light" | undefined;
+
 function detectTerminalBackground(): "dark" | "light" {
+	// Prefer terminal-reported appearance from Mode 2031 (CSI ? 997 ; {1,2} n)
+	if (terminalReportedAppearance) {
+		return terminalReportedAppearance;
+	}
+	// Fallback: COLORFGBG environment variable (static, set once at terminal launch)
 	const colorfgbg = Bun.env.COLORFGBG || "";
 	if (colorfgbg) {
 		const parts = colorfgbg.split(";");
@@ -1793,6 +1801,31 @@ export function setAutoThemeMapping(mode: "dark" | "light", themeName: string):
 		});
 }
 
+/**
+ * Called when the terminal reports a dark/light appearance change via Mode 2031.
+ * Updates the cached appearance and triggers auto-theme re-evaluation.
+ * This is the cross-platform mechanism supported by Ghostty, Kitty, Contour,
+ * VTE (GNOME Terminal), and tmux 3.6+.
+ */
+export function onTerminalAppearanceChange(mode: "dark" | "light"): void {
+	if (terminalReportedAppearance === mode) return;
+	terminalReportedAppearance = mode;
+	if (!autoDetectedTheme) return;
+	const resolved = getDefaultTheme();
+	if (resolved === currentThemeName) return;
+	currentThemeName = resolved;
+	loadTheme(resolved, getCurrentThemeOptions())
+		.then(loadedTheme => {
+			theme = loadedTheme;
+			if (onThemeChangeCallback) {
+				onThemeChangeCallback();
+			}
+		})
+		.catch(err => {
+			logger.debug("Mode 2031 appearance switch failed", { error: String(err) });
+		});
+}
+
 export function setThemeInstance(themeInstance: Theme): void {
 	autoDetectedTheme = false;
 	theme = themeInstance;

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

@@ -1,6 +1,8 @@
 {{#if context}}
 {{SECTION_SEPERATOR "Background"}}
+<context>
 {{context}}
+</context>
 {{/if}}
 
 {{SECTION_SEPERATOR "Task"}}

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

@@ -106,7 +106,7 @@ Domain-specific rules from past experience. **MUST** read `rule://<name>` when w
 You **MUST** use tools to complete the task.
 
 {{#if intentTracing}}
-Every tool call **MUST** include the `{{intentField}}` parameter: one sentence in present participle form (e.g., Inserting comment before the function), no trailing period. This is a contract-level requirement, not optional metadata.
+Every tool call **MUST** include the `{{intentField}}` parameter: one concise sentence in present participle form (e.g., Updating imports), ideally 2-6 words, with no trailing period. This is a contract-level requirement, not optional metadata.
 {{/if}}
 
 You **MUST** use the following tools, as effectively as possible, to complete the task:
@@ -147,10 +147,21 @@ You **MUST NOT** use Python or Bash when a specialized tool exists.
 
 Semantic questions **MUST** be answered with semantic tools.
 - Where is this thing defined? → `lsp definition`
+- What type does this thing resolve to? → `lsp type_definition`
+- What concrete implementations exist? → `lsp implementation`
 - What uses this thing I'm about to change? → `lsp references`
 - What is this thing? → `lsp hover`
+- Can the server propose fixes/imports/refactors? → `lsp code_actions` (list first, then apply with `apply: true` + `query`)
 {{/has}}
 
+{{#ifAny (includes tools "ast_find") (includes tools "ast_replace")}}
+### AST tools for structural code work
+
+When AST tools are available, syntax-aware operations take priority over text hacks.
+{{#has tools "ast_find"}}- Use `ast_find` for structural discovery (call shapes, declarations, syntax patterns) before text grep when code structure matters{{/has}}
+{{#has tools "ast_replace"}}- Use `ast_replace` for structural codemods/replacements; do not use bash `sed`/`perl`/`awk` for syntax-level rewrites{{/has}}
+- Use `grep` for plain text/regex lookup only when AST shape is irrelevant
+{{/ifAny}}
 {{#if eagerTasks}}
 <eager-tasks>
 You **SHOULD** delegate work to subagents by default. Working alone is the exception, not the rule.

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

@@ -0,0 +1,20 @@
+Performs structural code search using AST matching via native ast-grep.
+
+<instruction>
+- Use this when syntax shape matters more than raw text (calls, declarations, specific language constructs)
+- Prefer a precise `path` scope to keep results targeted and deterministic (`path` accepts files, directories, or glob patterns)
+- `pattern` is required; `lang` is optional (`lang` is inferred per file extension when omitted)
+- Use `selector` only for contextual pattern mode; otherwise provide a direct pattern
+- Enable `include_meta` when metavariable captures are needed in output
+</instruction>
+
+<output>
+- Returns grouped matches with file path, byte range, and line/column ranges
+- Includes summary counts (`totalMatches`, `filesWithMatches`, `filesSearched`) and parse issues when present
+</output>
+
+<critical>
+- `pattern` is required
+- Set `lang` explicitly to constrain matching when path pattern spans mixed-language trees
+- If exploration is broad/open-ended across subsystems, use Task tool with explore subagent first
+</critical>

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

@@ -0,0 +1,21 @@
+Performs structural AST-aware rewrites via native ast-grep.
+
+<instruction>
+- Use for codemods and structural rewrites where plain text replace is unsafe
+- Narrow scope with `path` before replacing (`path` accepts files, directories, or glob patterns)
+- `pattern` + `rewrite` are required; `lang` is optional only when all matched files resolve to a single language
+- Keep `dry_run` enabled unless explicit apply intent is clear
+- Use `max_files` and `max_replacements` as safety caps on broad rewrites
+</instruction>
+
+<output>
+- Returns replacement summary, per-file replacement counts, and change previews
+- Reports whether changes were applied or only previewed
+- Includes parse issues when files cannot be processed
+</output>
+
+<critical>
+- `pattern` + `rewrite` are required
+- If the path pattern spans multiple languages, set `lang` explicitly for deterministic rewrites
+- For one-off local text edits, prefer the Edit tool instead of AST replace
+</critical>

package/src/prompts/tools/bash.md

@@ -35,6 +35,8 @@ You **MUST** use specialized tools instead of bash for ALL file operations:
 |`ls dir/`|`read(path="dir/")`|
 |`cat <<'EOF' > file`|`write(path="file", content="...")`|
 |`sed -i 's/old/new/' file`|`edit(path="file", edits=[...])`|
+- If `ast_find` / `ast_replace` tools are available in the session, you **MUST** use them for structural code search/rewrites instead of bash `grep`/`sed`/`awk`/`perl` pipelines
+- Bash is for command execution, not syntax-aware code transformation; prefer `ast_find` for discovery and `ast_replace` for codemods
 - You **MUST NOT** use Bash for these operations like read, grep, find, edit, write, where specialized tools exist.
 - You **MUST NOT** use `2>&1` | `2>/dev/null` pattern, stdout and stderr are already merged.
 - You **MUST NOT** use `| head -n 50` or `| tail -n 100` pattern, use `head` and `tail` parameters instead.

package/src/prompts/tools/hashline.md

@@ -175,26 +175,44 @@ Good — include original `}` in the replaced range when replacement keeps `}`:
 Also apply the same rule to `);`, `],`, and `},` closers: if replacement includes the closer token, `end` must include the original closer line.
 </example>
 
-<example name="insert between siblings">
+<example name="insert between sibling declarations">
 ```ts
-{{hlinefull 44 "  \"build\": \"bun run compile\","}}
-{{hlinefull 45 "  \"test\": \"bun test\""}}
+{{hlinefull 44 "function x() {"}}
+{{hlinefull 45 "  runX();"}}
+{{hlinefull 46 "}"}}
+{{hlinefull 47 ""}}
+{{hlinefull 48 "function y() {"}}
+{{hlinefull 49 "  runY();"}}
+{{hlinefull 50 "}"}}
 ```
 ```
 {
   path: "…",
   edits: [{
     op: "prepend",
-    pos: "{{hlineref 45 "  \"test\": \"bun test\""}}",
-    lines: ["  \"lint\": \"biome check\","]
+    pos: "{{hlineref 48 "function y() {"}}",
+    lines: [
+      "function z() {",
+      "  runZ();",
+      "}",
+      ""
+    ]
   }]
 }
 ```
 Result:
 ```ts
-{{hlinefull 44 "  \"build\": \"bun run compile\","}}
-{{hlinefull 45 "  \"lint\": \"biome check\","}}
-{{hlinefull 46 "  \"test\": \"bun test\""}}
+{{hlinefull 44 "function x() {"}}
+{{hlinefull 45 "  runX();"}}
+{{hlinefull 46 "}"}}
+{{hlinefull 47 ""}}
+{{hlinefull 48 "function z() {"}}
+{{hlinefull 49 "  runZ();"}}
+{{hlinefull 50 "}"}}
+{{hlinefull 51 ""}}
+{{hlinefull 52 "function y() {"}}
+{{hlinefull 53 "  runY();"}}
+{{hlinefull 54 "}"}}
 ```
 </example>