@oh-my-pi/pi-coding-agent 16.2.5 → 16.2.6

package/src/mcp/oauth-flow.ts

@@ -75,6 +75,10 @@ export interface MCPStoredOAuthCredential extends OAuthCredential {
 const DEFAULT_PORT = 3000;
 const CALLBACK_PATH = "/callback";
 
+function hasOAuthScope(scopes: string | null | undefined, scope: string): boolean {
+	return !!scopes && scopes.split(/\s+/).includes(scope);
+}
+
 function isLoopbackHostname(hostname: string): boolean {
 	return hostname === "localhost" || hostname === "127.0.0.1";
 }
@@ -225,12 +229,10 @@ export interface MCPOAuthConfig {
 	/** OAuth scopes (space-separated) */
 	scopes?: string;
 	/**
-	 * `prompt` parameter for the authorization request. Defaults to `"consent"`
-	 * so the provider always shows its authorize screen instead of silently
-	 * re-approving the browser's current session — without it, reauthorizing to
-	 * switch accounts/workspaces is impossible once a session cookie exists
-	 * (RFC 6749 §3.1 requires servers to ignore the param when unsupported).
-	 * Set to `""` to omit the parameter entirely.
+	 * `prompt` parameter for the authorization request. By default the parameter
+	 * is omitted, matching the reference MCP SDK, except for `offline_access`
+	 * requests where OIDC Core requires `prompt=consent` to issue refresh-token
+	 * access. Set to `""` to omit the parameter entirely.
 	 */
 	prompt?: string;
 	/** Exact redirect URI to advertise to the provider */
@@ -325,7 +327,7 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 		if (this.config.scopes && !params.get("scope")) {
 			params.set("scope", this.config.scopes);
 		}
-		const prompt = this.config.prompt ?? "consent";
+		const prompt = this.config.prompt ?? (hasOAuthScope(params.get("scope"), "offline_access") ? "consent" : "");
 		if (prompt && !params.get("prompt")) {
 			params.set("prompt", prompt);
 		}
@@ -494,7 +496,7 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 					Accept: "application/json",
 				},
 				body: JSON.stringify({
-					client_name: "Codex",
+					client_name: "oh-my-pi",
 					redirect_uris: [redirectUri],
 					grant_types: ["authorization_code", "refresh_token"],
 					response_types: ["code"],

package/src/mcp/transports/stdio.ts

@@ -147,21 +147,6 @@ function resolveWindowsShimPath(value: string, shimDir: string): string | null {
 	return path.join(shimDir, ...suffix.split(/[\\/]+/).filter(Boolean));
 }
 
-function extractWindowsNpmShimTarget(content: string): string | null {
-	const match = /"%_prog%"\s+"([^"]+)"\s+%\*/i.exec(content);
-	return match?.[1] ?? null;
-}
-
-/**
- * Extract the shim's PATH-fallback interpreter (`SET "_prog=node"`). The
- * `IF EXIST` branch assigns a `%dp0%`-prefixed value, so requiring a
- * non-`%`-leading value picks the bare program name.
- */
-function extractWindowsNpmShimProg(content: string): string | null {
-	const match = /SET\s+"_prog=([^%"][^"]*)"/i.exec(content);
-	return match?.[1] ?? null;
-}
-
 async function resolveWindowsNpmShimCommand(
 	command: string,
 	args: readonly string[],
@@ -171,6 +156,11 @@ async function resolveWindowsNpmShimCommand(
 	if (!isWindowsBatchCommand(command)) return null;
 	if (!hasPathSegment(command)) return null;
 	const commandPath = path.resolve(cwd, command);
+	const commandName = path
+		.basename(commandPath)
+		.replace(/\.cmd$/i, "")
+		.toLowerCase();
+	if (commandName === "npx") return null;
 
 	let content: string;
 	try {
@@ -181,7 +171,9 @@ async function resolveWindowsNpmShimCommand(
 
 	// cmd-shim emits the same invocation line for every interpreter; only
 	// bypass cmd.exe when the shim's fallback interpreter is actually node.
-	const prog = extractWindowsNpmShimProg(content);
+	// The IF EXIST branch assigns a %dp0%-prefixed value, so requiring a
+	// non-%-leading SET value picks the bare PATH-fallback program name.
+	const prog = /SET\s+"_prog=([^%"][^"]*)"/i.exec(content)?.[1];
 	if (
 		!prog ||
 		path
@@ -191,7 +183,7 @@ async function resolveWindowsNpmShimCommand(
 	)
 		return null;
 
-	const rawTarget = extractWindowsNpmShimTarget(content);
+	const rawTarget = /"%_prog%"\s+"([^"]+)"\s+%\*/i.exec(content)?.[1];
 	if (!rawTarget) return null;
 
 	const target = resolveWindowsShimPath(rawTarget, path.dirname(commandPath));

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

@@ -50,6 +50,15 @@ const MAX_LIVE_IRC_CARDS = 4;
 const IDLE_RECAP_MIN_SECONDS = 1;
 const IDLE_RECAP_MAX_SECONDS = 3600;
 
+const RAW_PARTIAL_JSON_RENDERERS: Record<string, true> = { bash: true, edit: true, apply_patch: true };
+
+function exposesRawPartialJson(toolName: string, rawInput: boolean, tool: unknown): boolean {
+	if (rawInput) return true;
+	if (RAW_PARTIAL_JSON_RENDERERS[toolName]) return true;
+	if (tool === null || typeof tool !== "object" || !("renderCall" in tool)) return false;
+	return typeof tool.renderCall === "function";
+}
+
 type AgentSessionEventHandlers = {
 	[E in AgentSessionEventKind]: (event: Extract<AgentSessionEvent, { type: E }>) => Promise<void>;
 };
@@ -623,7 +632,7 @@ export class EventController {
 					// Internal URL read falls through to ToolExecutionComponent below.
 				}
 
-				// Preserve the raw partial JSON for renderers that need to surface fields before the JSON object closes.
+				// Preserve the raw partial JSON only for renderers that need to surface fields before the JSON object closes.
 				// Bash uses this to show inline env assignments during streaming instead of popping them in at completion.
 				// While the JSON is still open, ToolArgsRevealController paces the
 				// reveal (write/edit/bash previews grow smoothly when a slow provider
@@ -631,13 +640,14 @@ export class EventController {
 				// as-is — mirroring how assistant text snaps at message_end.
 				let renderArgs: Record<string, unknown>;
 				const partialJson = getStreamingPartialJson(content);
+				const rawInput = content.customWireName !== undefined;
+				const tool = this.ctx.viewSession.getToolByName(content.name);
 				if (partialJson) {
-					renderArgs = this.#toolArgsReveal.setTarget(
-						content.id,
-						partialJson,
-						content.customWireName !== undefined,
-						content.arguments,
-					);
+					renderArgs = this.#toolArgsReveal.setTarget(content.id, partialJson, {
+						rawInput,
+						exposeRawPartialJson: exposesRawPartialJson(content.name, rawInput, tool),
+						fullArgs: content.arguments,
+					});
 				} else {
 					this.#toolArgsReveal.finish(content.id);
 					renderArgs = content.arguments;
@@ -645,7 +655,6 @@ export class EventController {
 				if (!this.ctx.pendingTools.has(content.id)) {
 					this.#resolveDisplaceablePoll(content.name);
 					this.#resetReadGroup();
-					const tool = this.ctx.viewSession.getToolByName(content.name);
 					const component = new ToolExecutionComponent(
 						content.name,
 						renderArgs,

package/src/modes/controllers/tool-args-reveal.ts

@@ -1,4 +1,4 @@
-import { parseStreamingJson } from "@oh-my-pi/pi-utils";
+import { parseStreamingJson, parseStreamingJsonThrottled, STREAMING_JSON_PARSE_MIN_GROWTH } from "@oh-my-pi/pi-utils";
 import { nextStep, STREAMING_REVEAL_FRAME_MS } from "./streaming-reveal";
 
 /** Minimal component surface the reveal pushes frames into. */
@@ -19,6 +19,16 @@ type RevealEntry = {
 	revealed: number;
 	/** Custom-tool raw input: display args are `{ input: prefix }`, never parsed as JSON. */
 	rawInput: boolean;
+	/** Whether the renderer observes fresh raw JSON prefixes directly. */
+	exposeRawPartialJson: boolean;
+	/** Last parsed JSON args from the revealed prefix. */
+	parsedArgs: Record<string, unknown>;
+	/** Prefix length covered by `parsedArgs`. */
+	parsedLen: number;
+	/** Last object handed to a component; reused when visible args have not changed. */
+	displayArgs: Record<string, unknown>;
+	/** Raw prefix carried by `displayArgs.__partialJson`. */
+	displayPrefix: string;
 };
 
 /** Clamp a slice end into `text`, never splitting a surrogate pair: a prefix
@@ -32,15 +42,64 @@ function clampSliceEnd(text: string, end: number): number {
 	return code >= 0xd800 && code <= 0xdbff ? end + 1 : end;
 }
 
-/** Display args for a revealed raw-stream prefix. Function-tool prefixes are
- *  re-parsed with the same streaming-tolerant parser providers use, so every
- *  frame is a state the provider itself could have produced; custom tools
- *  mirror the provider's `{ input }` shape. `__partialJson` carries the
- *  matching raw prefix for renderers that read it directly (bash env preview,
- *  edit strategies). */
-function buildDisplayArgs(prefix: string, rawInput: boolean): Record<string, unknown> {
-	const base: Record<string, unknown> = rawInput ? { input: prefix } : parseStreamingJson(prefix);
-	return { ...base, __partialJson: prefix };
+type ToolArgsRevealTarget = {
+	rawInput: boolean;
+	exposeRawPartialJson: boolean;
+	fullArgs: Record<string, unknown>;
+};
+
+type DisplayArgsStep = {
+	args: Record<string, unknown>;
+	changed: boolean;
+};
+
+function initialDisplayArgs(): Record<string, unknown> {
+	return { __partialJson: "" };
+}
+
+function resetDisplayState(entry: RevealEntry): void {
+	entry.parsedArgs = {};
+	entry.parsedLen = 0;
+	entry.displayArgs = initialDisplayArgs();
+	entry.displayPrefix = "";
+}
+
+/** Display args for a revealed prefix. Function-tool JSON is parsed at the same
+ * growth-throttled cadence providers use, so a long `write` payload cannot make
+ * the reveal loop re-parse the whole growing buffer every frame. Renderers that
+ * read raw JSON directly still receive fresh `__partialJson` prefixes; other
+ * renderers get a stable object reference while parsed fields are unchanged. */
+function displayArgsForPrefix(entry: RevealEntry, prefix: string, forceParse = false): DisplayArgsStep {
+	if (entry.rawInput) {
+		if (prefix === entry.displayPrefix) return { args: entry.displayArgs, changed: false };
+		const args = { input: prefix, __partialJson: prefix };
+		entry.displayArgs = args;
+		entry.displayPrefix = prefix;
+		return { args, changed: true };
+	}
+
+	let parsedChanged = false;
+	if (forceParse || (prefix.length > 0 && prefix.length < STREAMING_JSON_PARSE_MIN_GROWTH)) {
+		entry.parsedArgs = parseStreamingJson<Record<string, unknown>>(prefix);
+		entry.parsedLen = prefix.length;
+		parsedChanged = true;
+	} else {
+		const throttled = parseStreamingJsonThrottled<Record<string, unknown>>(prefix, entry.parsedLen);
+		if (throttled) {
+			entry.parsedArgs = throttled.value;
+			entry.parsedLen = throttled.parsedLen;
+			parsedChanged = true;
+		}
+	}
+
+	const rawPrefixChanged = entry.exposeRawPartialJson && prefix !== entry.displayPrefix;
+	if (!parsedChanged && !rawPrefixChanged) return { args: entry.displayArgs, changed: false };
+
+	const displayPrefix = entry.exposeRawPartialJson || parsedChanged ? prefix : entry.displayPrefix;
+	const args = { ...entry.parsedArgs, __partialJson: displayPrefix };
+	entry.displayArgs = args;
+	entry.displayPrefix = displayPrefix;
+	return { args, changed: true };
 }
 
 /**
@@ -49,7 +108,9 @@ function buildDisplayArgs(prefix: string, rawInput: boolean): Record<string, unk
  * (or throttle their partial parses) would otherwise make write/edit/bash
  * streaming previews jump in chunks. Each pending tool call reveals its raw
  * argument stream at the shared 30fps cadence with the same adaptive
- * catch-up step, re-parsing the revealed prefix per frame.
+ * catch-up step. JSON prefixes are parsed only when enough new bytes arrive to
+ * change renderer-visible fields, while raw-prefix consumers still receive
+ * fresh `__partialJson` on every reveal frame.
  *
  * Reveal units are UTF-16 code units of the raw stream, not graphemes —
  * the prefix goes through a JSON parser rather than straight to the screen,
@@ -71,12 +132,8 @@ export class ToolArgsRevealController {
 	 * args to render right now. With smoothing disabled the full target passes
 	 * through in the caller's legacy shape (`{ ...args, __partialJson }`).
 	 */
-	setTarget(
-		id: string,
-		partialJson: string,
-		rawInput: boolean,
-		fullArgs: Record<string, unknown>,
-	): Record<string, unknown> {
+	setTarget(id: string, partialJson: string, target: ToolArgsRevealTarget): Record<string, unknown> {
+		const { rawInput, exposeRawPartialJson, fullArgs } = target;
 		if (!this.#getSmoothStreaming()) {
 			// Toggle may flip mid-call: drop any live entry so ticks stop.
 			this.#entries.delete(id);
@@ -84,18 +141,34 @@ export class ToolArgsRevealController {
 		}
 		let entry = this.#entries.get(id);
 		if (!entry) {
-			entry = { component: undefined, target: partialJson, revealed: 0, rawInput };
+			entry = {
+				component: undefined,
+				target: partialJson,
+				revealed: 0,
+				rawInput,
+				exposeRawPartialJson,
+				parsedArgs: {},
+				parsedLen: 0,
+				displayArgs: initialDisplayArgs(),
+				displayPrefix: "",
+			};
 			this.#entries.set(id, entry);
 		} else {
+			if (entry.rawInput !== rawInput || entry.exposeRawPartialJson !== exposeRawPartialJson) {
+				entry.rawInput = rawInput;
+				entry.exposeRawPartialJson = exposeRawPartialJson;
+				resetDisplayState(entry);
+			}
 			// Streams only append; a non-prefix target means a rewind — snap into range.
 			if (!partialJson.startsWith(entry.target)) {
 				entry.revealed = Math.min(entry.revealed, partialJson.length);
+				resetDisplayState(entry);
 			}
 			entry.target = partialJson;
 		}
 		entry.revealed = clampSliceEnd(entry.target, entry.revealed);
 		this.#syncTimer();
-		return buildDisplayArgs(entry.target.slice(0, entry.revealed), entry.rawInput);
+		return displayArgsForPrefix(entry, entry.target.slice(0, entry.revealed)).args;
 	}
 
 	/** Attach the component future ticks push frames into. */
@@ -118,7 +191,7 @@ export class ToolArgsRevealController {
 	flushAll(): void {
 		for (const [id, entry] of this.#entries) {
 			if (entry.component && entry.revealed < entry.target.length) {
-				entry.component.updateArgs(buildDisplayArgs(entry.target, entry.rawInput), id);
+				entry.component.updateArgs(displayArgsForPrefix(entry, entry.target, true).args, id);
 			}
 		}
 		this.#entries.clear();
@@ -157,15 +230,20 @@ export class ToolArgsRevealController {
 
 	#tick(): void {
 		let advanced = false;
+		let rendered = false;
 		for (const [id, entry] of this.#entries) {
 			const backlog = entry.target.length - entry.revealed;
 			if (backlog <= 0 || !entry.component) continue;
 			entry.revealed = clampSliceEnd(entry.target, entry.revealed + nextStep(backlog));
-			entry.component.updateArgs(buildDisplayArgs(entry.target.slice(0, entry.revealed), entry.rawInput), id);
+			const display = displayArgsForPrefix(entry, entry.target.slice(0, entry.revealed));
+			if (display.changed) {
+				entry.component.updateArgs(display.args, id);
+				rendered = true;
+			}
 			advanced = true;
 		}
 		if (advanced) {
-			this.#requestRender();
+			if (rendered) this.#requestRender();
 		} else {
 			// Every entry caught up (or unbound); setTarget restarts on growth.
 			this.#stopTimer();

package/src/prompts/bench.md

@@ -1,12 +1,6 @@
-You are given a relational schema and a multi-way analytical query, and you must work out from first principles the execution plan a cost-based optimizer should choose. This is a hard estimation problem with a large search space, so think it all the way through before you settle on anything and reason your way to each number instead of answering from intuition. Do not recite how query optimization works in general — actually do the analysis for this query, deriving every estimate.
-
-Schema and statistics: orders(id, customer_id, status, total) holds 50,000,000 rows with 5 distinct status values; customers(id, country, segment) holds 4,000,000 rows across 200 countries; line_items(order_id, product_id, qty) holds 300,000,000 rows; products(id, category, price) holds 80,000 rows across 600 categories. The query reports total revenue per product category for shipped orders placed by customers in one given country.
-
-Reason step by step and keep going: estimate the selectivity and output cardinality of each predicate and each join, then enumerate every join order over the four tables and derive the cost of each under both nested-loop and hash-join operators, weigh index access against full scans for each table, decide where the aggregation belongs and whether a partial pre-aggregation or a semi-join reduction earns its keep, and account for a memory limit that forces a hash build side to spill to disk. Compute the number behind every decision before you commit to it; when you finish one candidate plan, move on to the next and derive its cost too, and choose a winner only after you have costed the whole field. Never assert a choice you have not justified with an estimate.
+Write a detailed, four-paragraph explanation of how a web browser renders a webpage. Cover the process from receiving the initial HTML payload to painting pixels on the screen. Include the construction of the DOM and CSSOM, the render tree, layout, and painting.
 
 Form:
-- Plain paragraphs only: no headings, no lists, no code fences, no tables, no preamble.
-- Derive each estimate explicitly; state no conclusion you have not computed.
-- Do not wrap up early or summarize; keep reasoning until you are cut off.
-
-Output only the analysis.
+- Plain paragraphs only: no headings, no lists, no code fences, no preamble.
+- Do not summarize early; keep explaining until you reach the token limit.
+- Output only the explanation.

package/src/prompts/tools/irc.md

@@ -1,33 +1,23 @@
-Send/receive short text messages between agents in this process.
+Send and receive short text messages between the agents running in this process.
 
-<instruction>
-- Main agent is `Main`; subagents reuse their task id (`AuthLoader`, `AuthLoader-2` on repeat).
-- `op: "list"` — peers with status (`running` | `idle` | `parked`), unread count, parent, last activity. Use when unsure who exists.
-- `op: "send"` — fire-and-forget; returns per-recipient receipts immediately, NEVER waits for the recipient to act. Outcomes: delivered, or `failed` (unreachable). `to: "all"` broadcasts to live peers.
-- Messaging an `idle`/`parked` peer wakes it — no separate revive call.
-- `op: "wait"` — block for a message (optionally only `from` one peer); consumes + returns it. Timeout = clean "no message", not an error.
-- `op: "inbox"` — drain pending messages without blocking.
-- Replies arrive only when the recipient sends one; don't interrogate a peer for status.
-</instruction>
+# Addressing and Discovery
+The main agent is always `Main`. Subagents inherit their task ID (e.g., `AuthLoader`). If you don't know who is currently running, use `op: "list"` to view all peers alongside their status, unread message count, and recent activity. Address peers by their exact ID from the roster; NEVER invent names.
 
-<when_to_use>
-Reach for `irc` when going alone is wasteful or wrong; when in doubt, message.
-- **Unexpected state** — missing file, config contradicting the assignment, API/tool behaving differently than told. DM `Main` (or your spawner), don't guess.
-- **Blocked by another agent** — a peer holds the file/branch/resource/decision you need, or started your change. DM them (or broadcast to find who) before duplicating work.
-- **Decision outside your scope** — a genuine fork the assignment didn't pre-decide. Ask the requester, don't pick unilaterally.
-- **Coordination** — a peer's in-flight work overlaps yours (roster shows each peer's role + activity); message before editing a shared file or duplicating a sibling's change.
+# Messaging Rules
+Use `op: "send"` to deliver a message to a specific peer or broadcast to `"all"`.
+- **Fire and forget:** Sending NEVER blocks. You get delivery receipts immediately (`delivered` or `failed`). Do not wait around—send your message and keep working. If a receipt says `failed`, the peer is gone; do not retry.
+- **Waking peers:** Sending a message to an `idle` or `parked` agent automatically wakes them up.
+- **Answering:** When replying to a question, use `op: "send"`, lead directly with your answer (NEVER quote the original message), and set `replyTo` so the recipient can correlate it.
+- **Format:** Messages MUST be plain prose. NEVER send JSON status objects. Keep it terse and share paths via `local://` or `artifact://` URLs, not pasted blobs.
 
-NEVER for: routine progress updates, things a tool call can verify, questions your assignment/repo/docs already answer.
-</when_to_use>
+# Waiting and Inboxes
+Messages only arrive when the peer actively sends one—do not interrogate a peer for status.
+- If you are completely blocked and MUST wait for an answer, use `op: "wait"` (or `await: true` on a send). This blocks your turn until a message arrives. If it times out, that just means "no message arrived", not a failure.
+- To check for messages without blocking, use `op: "inbox"` to drain your queue.
 
-<etiquette>
-Applies to sending + replying.
-- **Plain prose only.** NEVER JSON status payloads like `{"type":"task_completed",…}` — write a normal sentence.
-- **NEVER quote the message you answer.** Lead with the answer; set `replyTo`.
-- **Learn about peers via IRC** — NEVER grep artifacts, read other sessions' JSONL, or shell-poke. DM them.
-- **Send, then keep working.** `wait`/`await: true` only when you cannot proceed. NEVER "did you get my message?". A `failed` receipt = peer unreachable — move on; NEVER retry in a loop.
-- **Answer expected questions** via `irc send` to the sender (finish your current step first).
-- **Stay terse.** One question per send; share files via `local://`/`memory://`/`artifact://` URLs, never pasted blobs.
-- **Address peers by exact id** from `op: "list"` (e.g. `AuthLoader`, `Main`). NEVER invent friendly names.
-- **NEVER IRC what a tool answers.** A `read`, grep, or build resolves it? Do that first.
-</etiquette>
+# When to Coordinate
+Message peers instead of guessing, duplicating work, or spying.
+- Use IRC when you hit an unexpected state (e.g., missing files) or an out-of-scope decision. DM `Main` or your spawner for guidance.
+- If you overlap with another agent's work or need a file they are touching, DM them before editing.
+- NEVER use shell tools, grep, or read other sessions' files to figure out what a peer is doing. Message them directly.
+- NEVER use IRC for something a tool can answer (e.g., grepping codebase, running a build).

package/src/prompts/tools/job.md

@@ -1,17 +1,11 @@
-Inspects, waits, or cancels async jobs.
+Manages async background tasks (e.g. bash scripts, subagents).
 
-Results arrive automatically on completion; reach for this tool only to intervene.
+Background tasks deliver their results automatically the moment they finish. You NEVER need to poll to retrieve output. Only use this tool if you need to intervene in the lifecycle of a task.
 
-# Operations
+# Interventions
 
-## `list: true`
-Inspect what's running.
-
-## `poll: [id, …]`
-Block until specified jobs finish or the wait window elapses. Omit `poll` (no `list`/`cancel`) to wait on ALL running jobs — NEVER enumerate ids you don't need to filter.
-- Use only when genuinely blocked with no other work.
-- Completed jobs include final output.
-
-## `cancel: [id, …]`
-Stop running jobs.
-- Use when a job is stalled, hung, or no longer needed.
+- **Block and wait:** Pass `poll` with specific job IDs when you are completely blocked and cannot do any other work. The call returns as soon as one watched job finishes or the wait window elapses — NOT when all of them finish; re-issue to keep waiting.
+  - To watch EVERY running job, issue a call with NO fields at all (no `poll`, no `cancel`, no `list`). NEVER pass an array of every running ID.
+  - A finished job's output is included in the wait result.
+- **Stop execution:** Pass `cancel` with job IDs to kill jobs that have hung, stalled, or are no longer needed. A cancel-only call returns immediately.
+- **Snapshot:** Pass `list: true` to get the current status of all jobs without waiting.

package/src/prompts/tools/lsp.md

@@ -1,39 +1,28 @@
-Language Server Protocol (LSP) servers for code intelligence.
+Symbol-aware code intelligence from language servers — the accurate path for navigation, refactors, and diagnostics where text search or edits would miss callsites.
 
 <operations>
-- `diagnostics`: errors/warnings for a file, glob, or workspace (`file: "*"`)
-- `definition`: symbol definition
-- `type_definition`: symbol's type definition
-- `implementation`: concrete implementations
-- `references`: all references
-- `hover`: type info / docs
-- `symbols`: list file symbols, or search workspace with `file: "*"` + `query`
-- `rename`: rename symbol codebase-wide
-- `rename_file`: rename/move a file/directory; updates import paths + other references
-- `code_actions`: list quick-fixes/refactors/import actions; apply one when `apply: true` + `query` matches title or index
-- `status`: active language servers
-- `capabilities`: per-server capabilities
-- `request`: raw LSP request — `query` = method name (e.g. `rust-analyzer/expandMacro`, `workspace/executeCommand`); `payload` = JSON params
-- `reload`: restart one server (via `file`) or all (`file: "*"`)
-</operations>
+Position-based — pass `file` + `line` + `symbol` (substring on that line; append `#N` for the Nth match, e.g. `kind#2`):
+- `definition`, `type_definition`, `implementation`, `references`, `hover` — standard LSP lookups
+- `rename` — rename the symbol everywhere; **applies by default**, `apply: false` previews; needs `new_name`
+- `code_actions` — quick-fixes/refactors/imports at that position; lists by default (`query` filters by kind, e.g. `quickfix`, `source.organizeImports`), **applies one only with `apply: true` + `query`** (then `query` = action title substring or numeric index)
+
+File / workspace:
+- `diagnostics` — errors/warnings for a path, a glob (`src/**/*.ts`), or the whole workspace (`file: "*"`)
+- `symbols` — `file` lists that file's symbols; `file: "*"` + `query` searches the workspace
+- `rename_file` — move `file` → `new_name` on disk AND rewrite imports/references through the server; applies by default
 
-<parameters>
-- `file`: path, glob (e.g. `src/**/*.ts`), or `"*"` for workspace scope
-- `line`: 1-indexed line for position-based actions
-- `symbol`: substring on the target line. Append `#N` for the Nth occurrence — e.g. `foo#2` = second `foo`.
-- `query`: symbol search, code-action kind filter/selector (list/apply mode), or LSP method name when `action: request`
-- `new_name`: required for `rename` (new identifier) and `rename_file` (destination path)
-- `apply`: apply edits for rename/rename_file/code_actions (default true for rename/rename_file; code_actions list mode unless true)
-- `payload`: JSON params for `action: request`
-- `timeout`: seconds
-</parameters>
+Servers:
+- `status`, `capabilities` — what's running / per-server capabilities (one via `file`, all via `*`)
+- `reload` — restart one server (`file`) or all (`*`); `reload *` also re-reads project LSP config
+- `request` — raw escape hatch: `query` = method (`rust-analyzer/expandMacro`, `workspace/executeCommand`), `payload` = JSON params (else auto-built from `file`/`line`/`symbol`)
+</operations>
 
 <caution>
-- Missing `symbol` or out-of-bounds `#N` → explicit error.
+- `line` is 1-indexed. Project-aware `definition`/`references`/`rename` ERROR without `symbol` rather than guess the wrong identifier; a missing match or out-of-range `#N` is an explicit error, never a silent fallback.
 </caution>
 
 <critical>
-- You MUST use `lsp` for symbol-aware operations (rename, references, definition/implementation, code actions) whenever a language server is available — safer and more accurate than text-based alternatives.
-- You NEVER perform cross-file renames with `ast_edit`, `sed`, or manual edits when `lsp` `rename` can do it. Text-based renames miss shadowing, re-exports, and cross-file usages.
-- You SHOULD use `lsp` `code_actions` for imports, quick-fixes, and refactors the server already applies.
+- Symbol-aware work (rename, references, definition/type/impl, code actions) MUST use `lsp` whenever a server is available — it follows shadowing, re-exports, and cross-file usages that text tools miss.
+- NEVER do a cross-file rename with `ast_edit`, `sed`, or hand edits when `lsp` `rename`/`rename_file` can — text renames silently drop callsites.
+- Reach for `code_actions` on imports, quick-fixes, and server-known refactors before editing by hand.
 </critical>