@oh-my-pi/pi-coding-agent 14.3.0 → 14.4.1

package/src/lsp/index.ts

@@ -1115,11 +1115,11 @@ export class LspTool implements AgentTool<typeof lspSchema, LspToolDetails, Them
 	readonly label = "LSP";
 	readonly description: string;
 	readonly parameters = lspSchema;
-	readonly strict = true;
 	readonly renderCall = renderCall;
 	readonly renderResult = renderResult;
 	readonly mergeCallAndResult = true;
 	readonly inline = true;
+	readonly strict = true;
 
 	constructor(private readonly session: ToolSession) {
 		this.description = prompt.render(lspDescription);

package/src/mcp/render.ts

@@ -17,7 +17,6 @@ import {
 	JSON_TREE_SCALAR_LEN_COLLAPSED,
 	JSON_TREE_SCALAR_LEN_EXPANDED,
 	renderJsonTreeLines,
-	stripInternalArgs,
 } from "../tools/json-tree";
 import { formatExpandHint, truncateToWidth } from "../tools/render-utils";
 import { renderStatusLine } from "../tui";
@@ -58,13 +57,7 @@ export function renderMCPResult(
 		lines.push(`${theme.fg("dim", "Args")}`);
 		const maxDepth = JSON_TREE_MAX_DEPTH_EXPANDED;
 		const maxLines = JSON_TREE_MAX_LINES_EXPANDED;
-		const tree = renderJsonTreeLines(
-			stripInternalArgs(args),
-			theme,
-			maxDepth,
-			maxLines,
-			JSON_TREE_SCALAR_LEN_EXPANDED,
-		);
+		const tree = renderJsonTreeLines(args, theme, maxDepth, maxLines, JSON_TREE_SCALAR_LEN_EXPANDED);
 		for (const line of tree.lines) {
 			lines.push(line);
 		}

package/src/modes/components/assistant-message.ts

@@ -155,6 +155,10 @@ export class AssistantMessageComponent extends Container {
 				this.#contentContainer.addChild(new Text(theme.fg("error", `Error: ${errorMsg}`), 1, 0));
 			}
 		}
+		if (message.errorMessage && message.stopReason !== "aborted" && message.stopReason !== "error") {
+			this.#contentContainer.addChild(new Spacer(1));
+			this.#contentContainer.addChild(new Text(theme.fg("error", `Error: ${message.errorMessage}`), 1, 0));
+		}
 
 		// Token usage metadata
 		if (settings.get("display.showTokenUsage") && this.#usageInfo) {

package/src/modes/components/diff.ts

@@ -1,7 +1,7 @@
 import { getIndentation } from "@oh-my-pi/pi-utils";
 import * as Diff from "diff";
 import { theme } from "../../modes/theme/theme";
-import { replaceTabs } from "../../tools/render-utils";
+import { type CodeFrameMarker, formatCodeFrameLine, replaceTabs } from "../../tools/render-utils";
 
 /** SGR dim on / normal intensity — additive, preserves fg/bg colors. */
 const DIM = "\x1b[2m";
@@ -37,14 +37,14 @@ function visualizeIndent(text: string, filePath?: string): string {
  * Parse diff line to extract prefix, line number, and content.
  * Supported formats: "+123|content" (canonical) and "+123 content" (legacy).
  */
-function parseDiffLine(line: string): { prefix: string; lineNum: string; content: string } | null {
+function parseDiffLine(line: string): { prefix: CodeFrameMarker; lineNum: string; content: string } | null {
 	const canonical = line.match(/^([+-\s])(\s*\d+)\|(.*)$/);
 	if (canonical) {
-		return { prefix: canonical[1], lineNum: canonical[2], content: canonical[3] };
+		return { prefix: canonical[1] as CodeFrameMarker, lineNum: canonical[2] ?? "", content: canonical[3] ?? "" };
 	}
 	const legacy = line.match(/^([+-\s])(?:(\s*\d+)\s)?(.*)$/);
 	if (!legacy) return null;
-	return { prefix: legacy[1], lineNum: legacy[2] ?? "", content: legacy[3] };
+	return { prefix: legacy[1] as CodeFrameMarker, lineNum: legacy[2] ?? "", content: legacy[3] ?? "" };
 }
 
 /**
@@ -108,12 +108,27 @@ export interface RenderDiffOptions {
 export function renderDiff(diffText: string, options: RenderDiffOptions = {}): string {
 	const lines = diffText.split("\n");
 	const result: string[] = [];
-
-	const formatLine = (prefix: string, lineNum: string, content: string): string => {
+	const parsedLines = lines.map(parseDiffLine);
+	const lineNumberWidth = parsedLines.reduce((width, parsed) => {
+		const lineNumber = parsed?.lineNum.trim() ?? "";
+		return Math.max(width, lineNumber.length);
+	}, 0);
+
+	// Track the line number rendered on the previous emitted line so we can
+	// blank out duplicate gutters. Two cases trigger this:
+	//  1. Single-line replacement (`-N` followed by `+N`) — the `+N` repeats `N`.
+	//  2. Insertion followed by context (`+N` then ` N` if producer used oldLine).
+	let prevLineNum = "";
+
+	const formatLine = (prefix: CodeFrameMarker, lineNum: string, content: string): string => {
 		if (lineNum.trim().length === 0) {
+			prevLineNum = "";
 			return `${prefix}${content}`;
 		}
-		return `${prefix}${lineNum}|${content}`;
+		const trimmed = lineNum.trim();
+		const displayNum = trimmed === prevLineNum ? "" : trimmed;
+		prevLineNum = trimmed;
+		return formatCodeFrameLine(prefix, displayNum, content, lineNumberWidth);
 	};
 
 	let i = 0;
@@ -122,13 +137,13 @@ export function renderDiff(diffText: string, options: RenderDiffOptions = {}): s
 		const parsed = parseDiffLine(line);
 
 		if (!parsed) {
+			prevLineNum = "";
 			result.push(theme.fg("toolDiffContext", line));
 			i++;
 			continue;
 		}
 
 		if (parsed.prefix === "-") {
-			// Collect consecutive removed lines
 			const removedLines: { lineNum: string; content: string }[] = [];
 			while (i < lines.length) {
 				const p = parseDiffLine(lines[i]);
@@ -137,7 +152,6 @@ export function renderDiff(diffText: string, options: RenderDiffOptions = {}): s
 				i++;
 			}
 
-			// Collect consecutive added lines
 			const addedLines: { lineNum: string; content: string }[] = [];
 			while (i < lines.length) {
 				const p = parseDiffLine(lines[i]);
@@ -146,8 +160,6 @@ export function renderDiff(diffText: string, options: RenderDiffOptions = {}): s
 				i++;
 			}
 
-			// Only do intra-line diffing when there's exactly one removed and one added line
-			// (indicating a single line modification). Otherwise, show lines as-is.
 			if (removedLines.length === 1 && addedLines.length === 1) {
 				const removed = removedLines[0];
 				const added = addedLines[0];
@@ -167,7 +179,6 @@ export function renderDiff(diffText: string, options: RenderDiffOptions = {}): s
 					theme.fg("toolDiffAdded", formatLine("+", added.lineNum, visualizeIndent(addedLine, options.filePath))),
 				);
 			} else {
-				// Show all removed lines first, then all added lines
 				for (const removed of removedLines) {
 					result.push(
 						theme.fg(
@@ -186,7 +197,6 @@ export function renderDiff(diffText: string, options: RenderDiffOptions = {}): s
 				}
 			}
 		} else if (parsed.prefix === "+") {
-			// Standalone added line
 			result.push(
 				theme.fg(
 					"toolDiffAdded",
@@ -195,7 +205,6 @@ export function renderDiff(diffText: string, options: RenderDiffOptions = {}): s
 			);
 			i++;
 		} else {
-			// Context line
 			result.push(
 				theme.fg(
 					"toolDiffContext",

package/src/modes/components/footer.ts

@@ -56,22 +56,27 @@ export class FooterComponent implements Component {
 			this.#gitWatcher = null;
 		}
 
-		git.head.resolve(getProjectDir()).then(head => {
-			if (!head) {
-				return;
-			}
-
-			try {
-				this.#gitWatcher = fs.watch(head.headPath, () => {
-					this.#cachedBranch = undefined; // Invalidate cache
-					if (this.#onBranchChange) {
-						this.#onBranchChange();
-					}
-				});
-			} catch {
-				// Silently fail if we can't watch
-			}
-		});
+		void git.head
+			.resolve(getProjectDir())
+			.then(head => {
+				if (!head) {
+					return;
+				}
+
+				try {
+					this.#gitWatcher = fs.watch(head.headPath, () => {
+						this.#cachedBranch = undefined; // Invalidate cache
+						if (this.#onBranchChange) {
+							this.#onBranchChange();
+						}
+					});
+				} catch {
+					// Silently fail if we can't watch
+				}
+			})
+			.catch(() => {
+				this.#cachedBranch = null;
+			});
 	}
 
 	/**

package/src/modes/components/session-selector.ts

@@ -10,6 +10,7 @@ import {
 	truncateToWidth,
 	visibleWidth,
 } from "@oh-my-pi/pi-tui";
+import { formatBytes } from "@oh-my-pi/pi-utils";
 import { theme } from "../../modes/theme/theme";
 import { matchesAppInterrupt } from "../../modes/utils/keybinding-matchers";
 import type { SessionInfo } from "../../session/session-manager";
@@ -157,10 +158,9 @@ class SessionList implements Component {
 				lines.push(messageLine);
 			}
 
-			// Metadata line: date + message count
+			// Metadata line: date + file size
 			const modified = formatDate(session.modified);
-			const msgCount = `${session.messageCount} message${session.messageCount !== 1 ? "s" : ""}`;
-			const metadata = `  ${modified} ${theme.sep.dot} ${msgCount}`;
+			const metadata = `  ${modified} ${theme.sep.dot} ${formatBytes(session.size)}`;
 			const metadataLine = theme.fg("dim", truncateToWidth(metadata, width));
 
 			lines.push(metadataLine);

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

@@ -355,7 +355,12 @@ const OPTION_PROVIDERS: Partial<Record<SettingPath, OptionProvider>> = {
 		{ value: "parallel", label: "Parallel", description: "Requires PARALLEL_API_KEY" },
 	],
 	"providers.image": [
-		{ value: "auto", label: "Auto", description: "Priority: OpenRouter > Gemini" },
+		{
+			value: "auto",
+			label: "Auto",
+			description: "Priority: GPT model image tool > Antigravity > OpenRouter > Gemini",
+		},
+		{ value: "openai", label: "OpenAI", description: "Uses the active GPT Responses/Codex model" },
 		{ value: "gemini", label: "Gemini", description: "Requires GEMINI_API_KEY" },
 		{ value: "openrouter", label: "OpenRouter", description: "Requires OPENROUTER_API_KEY" },
 	],

package/src/modes/components/todo-reminder.ts

@@ -34,14 +34,7 @@ export class TodoReminderComponent extends Container {
 		this.#box.addChild(new Text(header, 0, 0));
 		this.#box.addChild(new Spacer(1));
 
-		const todoList = this.todos
-			.map(t => {
-				const line = `  ${theme.checkbox.unchecked} ${t.content}`;
-				if (!t.details) return line;
-				const detailLines = t.details.split("\n").map(l => `    ${l}`);
-				return [line, ...detailLines].join("\n");
-			})
-			.join("\n");
+		const todoList = this.todos.map(todo => `  ${theme.checkbox.unchecked} ${todo.content}`).join("\n");
 		this.#box.addChild(new Text(theme.italic(todoList), 0, 0));
 	}
 }

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

@@ -27,7 +27,6 @@ import {
 	JSON_TREE_SCALAR_LEN_COLLAPSED,
 	JSON_TREE_SCALAR_LEN_EXPANDED,
 	renderJsonTreeLines,
-	stripInternalArgs,
 } from "../../tools/json-tree";
 import { PYTHON_DEFAULT_PREVIEW_LINES } from "../../tools/python";
 import { formatExpandHint, replaceTabs, resolveImageOptions, truncateToWidth } from "../../tools/render-utils";
@@ -743,9 +742,7 @@ export class ToolExecutionComponent extends Container {
 			lines.push("");
 			lines.push(theme.fg("dim", "Args"));
 			const tree = renderJsonTreeLines(
-				this.#args && typeof this.#args === "object" && !Array.isArray(this.#args)
-					? stripInternalArgs(this.#args as Record<string, unknown>)
-					: this.#args,
+				this.#args,
 				theme,
 				JSON_TREE_MAX_DEPTH_EXPANDED,
 				JSON_TREE_MAX_LINES_EXPANDED,

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

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

package/src/modes/print-mode.ts

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

package/src/prompts/agents/librarian.md

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

package/src/prompts/agents/reviewer.md

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

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

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

package/src/prompts/review-request.md

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

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

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

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

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

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

@@ -194,6 +194,9 @@ You **MUST NOT** use Python or Bash when a specialized tool exists.
 {{#has tools "edit"}}- Use `edit` for surgical text changes, not `sed`.{{/has}}
 {{/ifAny}}
 
+### Paths
+- For tools that take a `path` (or path-like field), prefer cwd-relative paths for files inside the cwd. Use absolute paths only when targeting files outside the cwd or when expanding `~`.
+
 {{#has tools "lsp"}}
 ### LSP guidance
 Use semantic tools for semantic questions:

package/src/prompts/tools/ask.md

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

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

@@ -2,39 +2,35 @@ Performs structural AST-aware rewrites via native ast-grep.
 
 <instruction>
 - Use for codemods and structural rewrites where plain text replace is unsafe
-- `path` accepts a comma-separated list in addition to file/dir/glob
-- Set `lang` explicitly in mixed-language trees for deterministic rewrites
+- `path` is required and accepts a file, directory, glob, comma-separated path list, or internal URL
+- Language is inferred from `path`; narrow `path` to one language for deterministic rewrites
 - Metavariables captured in `pat` (`$A`, `$$$ARGS`) are substituted into that entry's `out` template
 - **Patterns match AST structure, not text.** `$NAME` = one node (captured); `$_` = one without binding; `$$$NAME` = zero-or-more (lazy — stops at next matchable element); `$$$` = zero-or-more without binding. Use `$$$NAME`, **NOT** `$$NAME` — the two-dollar form is invalid. Metavariable names are UPPERCASE and **MUST** be the whole AST node — partial text like `prefix$VAR` or `"hello $NAME"` does NOT work
 - When the same metavariable appears twice, both occurrences **MUST** match identical code (`$A == $A` matches `x == x`, not `x == y`)
-- Rewrite patterns **MUST** parse as a single valid AST node. For method fragments or body snippets that don't parse standalone, wrap in context (e.g. `class $_ { … }`) and set `sel` to target the inner node — match and replacement target the selected node, not the wrapper. If ast-grep reports `Multiple AST nodes are detected`, wrap and use `sel`
+- Rewrite patterns **MUST** parse as a single valid AST node. For method fragments or body snippets that don't parse standalone, wrap in context (e.g. `class $_ { … }`)
 - For TS declarations/methods, tolerate unknown annotations: `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($ARG: $_): $_ { $$$BODY } }`
 - Delete matched code with empty `out`: `{"pat":"console.log($$$)","out":""}`
 - Each rewrite is a 1:1 structural substitution — cannot split one capture across multiple nodes or merge multiple captures into one
 </instruction>
 
 <output>
-- Replacement summary, per-file replacement counts, and change diffs
+- Replacement summary, per-file replacement counts, and change diffs as `-LINE+ID|before` / `+LINE+ID|after` lines
 - Parse issues when files cannot be processed
 </output>
 
 <examples>
-- Rename a call site across a directory:
-  `{"ops":[{"pat":"oldApi($$$ARGS)","out":"newApi($$$ARGS)"}],"lang":"typescript","path":"src/"}`
-- Delete matching calls (empty `out` removes the node):
-  `{"ops":[{"pat":"console.log($$$ARGS)","out":""}],"lang":"typescript","path":"src/"}`
-- Rewrite import source path:
-  `{"ops":[{"pat":"import { $$$IMPORTS } from \"old-package\"","out":"import { $$$IMPORTS } from \"new-package\""}],"lang":"typescript","path":"src/"}`
-- Modernize to optional chaining (same metavariable enforces identity):
-  `{"ops":[{"pat":"$A && $A()","out":"$A?.()"}],"lang":"typescript","path":"src/"}`
-- Swap two arguments using captures:
-  `{"ops":[{"pat":"assertEqual($A, $B)","out":"assertEqual($B, $A)"}],"lang":"typescript","path":"tests/"}`
-- Rename a function declaration while tolerating any return type annotation:
-  `{"ops":[{"pat":"async function fetchData($$$ARGS): $_ { $$$BODY }","out":"async function loadData($$$ARGS): $_ { $$$BODY }"}],"sel":"function_declaration","lang":"typescript","path":"src/api.ts"}`
-- Rewrite a method body fragment by wrapping in parseable context and selecting the method:
-  `{"ops":[{"pat":"class $_ { async execute($INPUT: $_) { $$$BEFORE; const $PARSED = $_.parse($INPUT); $$$AFTER } }","out":"class $_ { async execute($INPUT: $_) { $$$BEFORE; const $PARSED = $SCHEMA.parse($INPUT); $$$AFTER } }"}],"sel":"method_definition","lang":"typescript","path":"src/tools/todo.ts"}`
-- Python — convert print calls to logging:
-  `{"ops":[{"pat":"print($$$ARGS)","out":"logger.info($$$ARGS)"}],"lang":"python","path":"src/"}`
+# Rename a call site across TypeScript files
+`{"ops":[{"pat":"oldApi($$$ARGS)","out":"newApi($$$ARGS)"}],"path":"src/**/*.ts"}`
+# Delete matching calls
+`{"ops":[{"pat":"console.log($$$ARGS)","out":""}],"path":"src/**/*.ts"}`
+# Rewrite import source path
+`{"ops":[{"pat":"import { $$$IMPORTS } from \"old-package\"","out":"import { $$$IMPORTS } from \"new-package\""}],"path":"src/**/*.ts"}`
+# Modernize to optional chaining (same metavariable enforces identity)
+`{"ops":[{"pat":"$A && $A()","out":"$A?.()"}],"path":"src/**/*.ts"}`
+# Swap two arguments using captures
+`{"ops":[{"pat":"assertEqual($A, $B)","out":"assertEqual($B, $A)"}],"path":"tests/**/*.ts"}`
+# Python — convert print calls to logging
+`{"ops":[{"pat":"print($$$ARGS)","out":"logger.info($$$ARGS)"}],"path":"src/**/*.py"}`
 </examples>
 
 <critical>

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

@@ -2,46 +2,41 @@ Performs structural code search using AST matching via native ast-grep.
 
 <instruction>
 - Use when syntax shape matters more than raw text (calls, declarations, specific language constructs)
-- `path` accepts a comma-separated list in addition to file/dir/glob
-- Set `lang` explicitly in mixed-language trees to avoid parse noise from non-source files
-- Multiple patterns in `pat` run in one native pass, merged, then `offset`/`limit` applied
+- `path` is required and accepts a file, directory, glob, comma-separated path list, or internal URL
+- Language is inferred from `path`; narrow `path` to one language when mixed-language trees could cause parse noise
+- `pat` is a single AST pattern. Run separate calls for distinct unrelated patterns
 - **Patterns match AST structure, not text** — whitespace/formatting is ignored
 - `$NAME` captures one node; `$_` matches one without binding; `$$$NAME` captures zero-or-more (lazy — stops at next matchable element); `$$$` matches zero-or-more without binding. Use `$$$NAME`, **NOT** `$$NAME` — the two-dollar form is invalid and produces a parse error
 - 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
+- Patterns **MUST** parse as a single valid AST node for the inferred target language. For method fragments or body snippets that don't parse standalone, wrap in valid context (e.g. `class $_ { … }`)
+- 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. 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"`
+- Loosest existence check: `pat: "executeBash"` with a narrow `path`
 </instruction>
 
 <output>
 - Grouped matches with file path, byte range, line/column ranges, metavariable captures
+- Match lines are anchor-prefixed: `LINE+ID>content` for the matched line and `LINE+ID:content` for surrounding context
 - Summary counts (`totalMatches`, `filesWithMatches`, `filesSearched`) and parse issues when present
 </output>
 
 <examples>
-- Multi-pattern scoped search:
-  `{"pat":["console.log($$$)","console.error($$$)"],"lang":"typescript","path":"src/"}`
-- Named imports from a specific package (quoted string inside pattern):
-  `{"pat":["import { $$$IMPORTS } from \"react\""],"lang":"typescript","path":"src/"}`
-- Arrow functions assigned to a const (distinct AST from function declarations):
-  `{"pat":["const $NAME = ($$$ARGS) => $BODY"],"lang":"typescript","path":"src/utils/"}`
-- Method call on any object, ignoring method name with `$_`:
-  `{"pat":["logger.$_($$$ARGS)"],"lang":"typescript","path":"src/"}`
-- Contextual pattern with selector — match the identifier `foo`, not the whole call:
-  `{"pat":["foo()"],"sel":"identifier","lang":"typescript","path":"src/utils.ts"}`
-- Match a function declaration while tolerating any return type annotation (`sel` targets the inner node):
-  `{"pat":["async function processItems($$$ARGS): $_ { $$$BODY }"],"sel":"function_declaration","lang":"typescript","path":"src/worker.ts"}`
-- Match a method body fragment by wrapping in parseable context and selecting the method:
-  `{"pat":["class $_ { async execute($INPUT: $_) { $$$BEFORE; const $PARSED = $_.parse($INPUT); $$$AFTER } }"],"sel":"method_definition","lang":"typescript","path":"src/tools/todo.ts"}`
-- Loosest existence check for a symbol in one file:
-  `{"pat":["processItems"],"sel":"identifier","lang":"typescript","path":"src/worker.ts"}`
+# Search TypeScript files under src
+`{"pat":"console.log($$$)","path":"src/**/*.ts"}`
+# Named imports from a specific package
+`{"pat":"import { $$$IMPORTS } from \"react\"","path":"src/**/*.ts"}`
+# Arrow functions assigned to a const
+`{"pat":"const $NAME = ($$$ARGS) => $BODY","path":"src/utils/**/*.ts"}`
+# Method call on any object, ignoring method name with `$_`
+`{"pat":"logger.$_($$$ARGS)","path":"src/**/*.ts"}`
+# Loosest existence check for a symbol in one file
+`{"pat":"processItems","path":"src/worker.ts"}`
 </examples>
 
 <critical>
-- Avoid repo-root AST scans when the target is language-specific — narrow `path` first
-- Parse issues are query failure, not evidence of absence: repair the pattern or tighten `path`/`glob`/`lang` before concluding "no matches"
+- Avoid repo-root scans — narrow `path` first
+- Parse issues are query failure, not evidence of absence: repair the pattern or tighten `path` before concluding "no matches"
 - For broad/open-ended exploration across subsystems, use Task tool with explore subagent first
 </critical>