@oh-my-pi/pi-coding-agent 14.5.7 → 14.5.9

package/src/modes/utils/context-usage.ts

@@ -0,0 +1,294 @@
+import type { Model } from "@oh-my-pi/pi-ai";
+import { countTokens } from "@oh-my-pi/pi-natives";
+import { formatNumber } from "@oh-my-pi/pi-utils";
+import type { Skill } from "../../extensibility/skills";
+import type { AgentSession } from "../../session/agent-session";
+import type { CompactionSettings } from "../../session/compaction";
+import { effectiveReserveTokens, estimateTokens, resolveThresholdTokens } from "../../session/compaction";
+import type { Tool } from "../../tools";
+import type { theme as Theme } from "../theme/theme";
+
+const GRID_COLS = 20;
+const GRID_ROWS = 10;
+const GRID_CELLS = GRID_COLS * GRID_ROWS;
+const GRID_GUTTER = "   ";
+
+const CELL_FILLED = "⛁";
+const CELL_FILLED_MESSAGES = "⛃";
+const CELL_FREE = "⛶";
+const CELL_BUFFER = "⛝";
+
+type CategoryId = "systemPrompt" | "systemTools" | "skills" | "messages";
+
+interface CategoryInfo {
+	id: CategoryId;
+	label: string;
+	tokens: number;
+	color: "accent" | "warning" | "success" | "userMessageText";
+	glyph: string;
+}
+
+export interface ContextBreakdown {
+	model: Model | undefined;
+	contextWindow: number;
+	categories: CategoryInfo[];
+	usedTokens: number;
+	autoCompactBufferTokens: number;
+	freeTokens: number;
+}
+
+function estimateSkillsTokens(skills: readonly Skill[]): number {
+	const fragments: string[] = [];
+	for (const skill of skills) {
+		// "- name: description\n" wire framing tokenizes ~identically to the
+		// concatenated form, so encode each piece separately and sum.
+		fragments.push(skill.name, skill.description);
+	}
+	return countTokens(fragments);
+}
+
+function estimateToolSchemaTokens(tools: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">>): number {
+	const fragments: string[] = [];
+	for (const tool of tools) {
+		fragments.push(tool.name, tool.description);
+		try {
+			fragments.push(JSON.stringify(tool.parameters ?? {}));
+		} catch {
+			// Schema may contain functions or cycles; ignore.
+		}
+	}
+	return countTokens(fragments);
+}
+
+function estimateMessagesTokens(session: AgentSession): number {
+	let total = 0;
+	for (const message of session.messages) {
+		total += estimateTokens(message);
+	}
+	return total;
+}
+
+/**
+ * Compute a breakdown of estimated context usage by category for the active
+ * session and model.
+ */
+export function computeContextBreakdown(session: AgentSession): ContextBreakdown {
+	const model = session.model;
+	const contextWindow = model?.contextWindow ?? 0;
+
+	const skillsTokens = estimateSkillsTokens(session.skills);
+	const toolsTokens = estimateToolSchemaTokens(session.agent.state.tools);
+	const messagesTokens = estimateMessagesTokens(session);
+
+	// The rendered system prompt already contains the skill descriptions and the
+	// markdown tool descriptions. To present a non-overlapping breakdown:
+	//   System prompt = total system prompt text - skills section (tool descriptions stay)
+	//   Tools         = JSON tool schema sent separately on the wire
+	//   Skills        = the skill list embedded in the system prompt
+	//   Messages      = conversation messages
+	const systemPromptTextTokens = countTokens(session.systemPrompt);
+	const systemPromptTokens = Math.max(0, systemPromptTextTokens - skillsTokens);
+
+	const categories: CategoryInfo[] = [
+		{ id: "systemPrompt", label: "System prompt", tokens: systemPromptTokens, color: "accent", glyph: CELL_FILLED },
+		{ id: "systemTools", label: "System tools", tokens: toolsTokens, color: "warning", glyph: CELL_FILLED },
+		{ id: "skills", label: "Skills", tokens: skillsTokens, color: "success", glyph: CELL_FILLED },
+		{
+			id: "messages",
+			label: "Messages",
+			tokens: messagesTokens,
+			color: "userMessageText",
+			glyph: CELL_FILLED_MESSAGES,
+		},
+	];
+
+	const usedTokens = categories.reduce((sum, c) => sum + c.tokens, 0);
+
+	let autoCompactBufferTokens = 0;
+	if (contextWindow > 0) {
+		const compactionSettings = session.settings.getGroup("compaction") as CompactionSettings;
+		if (compactionSettings.enabled && compactionSettings.strategy !== "off") {
+			const threshold = resolveThresholdTokens(contextWindow, compactionSettings);
+			autoCompactBufferTokens = Math.max(0, contextWindow - threshold);
+		} else {
+			autoCompactBufferTokens = 0;
+		}
+		// Even when fully disabled, fall back to a sensible reserve floor for display.
+		if (autoCompactBufferTokens === 0 && compactionSettings.enabled) {
+			autoCompactBufferTokens = effectiveReserveTokens(contextWindow, compactionSettings);
+		}
+	}
+	autoCompactBufferTokens = Math.min(autoCompactBufferTokens, Math.max(0, contextWindow - usedTokens));
+
+	const freeTokens = Math.max(0, contextWindow - usedTokens - autoCompactBufferTokens);
+
+	return {
+		model,
+		contextWindow,
+		categories,
+		usedTokens,
+		autoCompactBufferTokens,
+		freeTokens,
+	};
+}
+
+interface CellSpec {
+	glyph: string;
+	color: "accent" | "warning" | "success" | "userMessageText" | "muted" | "dim";
+}
+
+function planCells(breakdown: ContextBreakdown): CellSpec[] {
+	const cells: CellSpec[] = [];
+	const window = breakdown.contextWindow;
+
+	if (window <= 0) {
+		for (let i = 0; i < GRID_CELLS; i++) {
+			cells.push({ glyph: CELL_FREE, color: "dim" });
+		}
+		return cells;
+	}
+
+	const tokensPerCell = window / GRID_CELLS;
+
+	const ratioCells = (tokens: number): number => {
+		if (tokens <= 0) return 0;
+		return Math.max(1, Math.round(tokens / tokensPerCell));
+	};
+
+	const categoryCounts = breakdown.categories.map(category => ({
+		category,
+		count: ratioCells(category.tokens),
+	}));
+
+	let bufferCount = ratioCells(breakdown.autoCompactBufferTokens);
+
+	let usedCount = categoryCounts.reduce((sum, c) => sum + c.count, 0);
+
+	// Prevent the visualization from over-running the grid.
+	const maxUsable = GRID_CELLS - bufferCount;
+	if (usedCount > maxUsable) {
+		// Scale categories proportionally down to fit.
+		let overflow = usedCount - maxUsable;
+		// Trim from the largest categories first to preserve visibility for small ones.
+		const order = [...categoryCounts].sort((a, b) => b.count - a.count);
+		for (const entry of order) {
+			while (overflow > 0 && entry.count > 1) {
+				entry.count -= 1;
+				overflow -= 1;
+			}
+		}
+		usedCount = categoryCounts.reduce((sum, c) => sum + c.count, 0);
+		if (usedCount + bufferCount > GRID_CELLS) {
+			bufferCount = Math.max(0, GRID_CELLS - usedCount);
+		}
+	}
+
+	for (const { category, count } of categoryCounts) {
+		for (let i = 0; i < count; i++) {
+			cells.push({ glyph: category.glyph, color: category.color });
+		}
+	}
+
+	const freeCount = Math.max(0, GRID_CELLS - cells.length - bufferCount);
+	for (let i = 0; i < freeCount; i++) {
+		cells.push({ glyph: CELL_FREE, color: "dim" });
+	}
+	for (let i = 0; i < bufferCount; i++) {
+		cells.push({ glyph: CELL_BUFFER, color: "warning" });
+	}
+
+	// Pad to exactly GRID_CELLS in case rounding undershot.
+	while (cells.length < GRID_CELLS) {
+		cells.push({ glyph: CELL_FREE, color: "dim" });
+	}
+	return cells.slice(0, GRID_CELLS);
+}
+
+function percentString(part: number, whole: number, fractionDigits = 1): string {
+	if (whole <= 0) return "0%";
+	const pct = (part / whole) * 100;
+	if (pct > 0 && pct < 0.05) return "<0.1%";
+	return `${pct.toFixed(fractionDigits)}%`;
+}
+
+function buildLegendLines(breakdown: ContextBreakdown, theme: typeof Theme): string[] {
+	const lines: string[] = [];
+	const { model, contextWindow, categories, usedTokens, autoCompactBufferTokens, freeTokens } = breakdown;
+
+	const modelName = model?.name ?? model?.id ?? "no model";
+	const modelId = model?.id ?? "unknown";
+	const windowLabel = formatNumber(contextWindow).toLowerCase();
+
+	lines.push(theme.bold(`${modelName}`) + theme.fg("dim", ` (${windowLabel} context)`));
+	lines.push(theme.fg("muted", `${modelId}[${windowLabel}]`));
+	lines.push(
+		`${theme.bold(formatNumber(usedTokens))}${theme.fg("dim", `/${windowLabel} tokens`)}` +
+			theme.fg("muted", ` (${percentString(usedTokens, contextWindow)})`),
+	);
+	lines.push("");
+	lines.push(theme.fg("muted", "Estimated usage by category"));
+
+	for (const category of categories) {
+		const dot = theme.fg(category.color, category.glyph);
+		const label = category.label;
+		const tokens = formatNumber(category.tokens);
+		const pct = percentString(category.tokens, contextWindow);
+		lines.push(`${dot} ${label}: ${theme.bold(tokens)} ${theme.fg("dim", `tokens (${pct})`)}`);
+	}
+
+	const freeDot = theme.fg("dim", CELL_FREE);
+	lines.push(
+		`${freeDot} Free space: ${theme.bold(formatNumber(freeTokens))} ${theme.fg("dim", `(${percentString(freeTokens, contextWindow)})`)}`,
+	);
+
+	if (autoCompactBufferTokens > 0) {
+		const bufferDot = theme.fg("warning", CELL_BUFFER);
+		lines.push(
+			`${bufferDot} Autocompact buffer: ${theme.bold(formatNumber(autoCompactBufferTokens))} ${theme.fg(
+				"dim",
+				`tokens (${percentString(autoCompactBufferTokens, contextWindow)})`,
+			)}`,
+		);
+	}
+
+	return lines;
+}
+
+/**
+ * Render a colorful context-usage panel as ANSI text. Output is a series of
+ * lines pairing the grid (left) with the legend (right).
+ */
+export function renderContextUsage(breakdown: ContextBreakdown, theme: typeof Theme): string {
+	if (breakdown.contextWindow <= 0) {
+		return theme.fg("muted", "Context usage is unavailable: no model is selected for this session.");
+	}
+
+	const cells = planCells(breakdown);
+	const legend = buildLegendLines(breakdown, theme);
+
+	const totalLines = Math.max(GRID_ROWS, legend.length);
+	const lines: string[] = [];
+
+	for (let row = 0; row < totalLines; row++) {
+		let gridSegment = "";
+		if (row < GRID_ROWS) {
+			const rowCells: string[] = [];
+			for (let col = 0; col < GRID_COLS; col++) {
+				const cell = cells[row * GRID_COLS + col];
+				rowCells.push(theme.fg(cell.color, cell.glyph));
+			}
+			gridSegment = rowCells.join(" ");
+		} else {
+			// Pad with blanks the same visible width as a grid row so legend lines
+			// past the grid stay aligned with their column.
+			const blank = " ".repeat(GRID_COLS * 2 - 1);
+			gridSegment = blank;
+		}
+
+		const legendSegment = legend[row] ?? "";
+		const line = legendSegment.length > 0 ? `${gridSegment}${GRID_GUTTER}${legendSegment}` : gridSegment;
+		lines.push(line);
+	}
+
+	return lines.join("\n");
+}

package/src/prompts/tools/atom.md

@@ -1,26 +1,45 @@
-Your patch language is a compact, file-oriented edit format.
+Your patch language is a compact, line-anchored edit format.
 
-When emitting a patch, the first non-blank line **MUST** be `---PATH`.
-A Lid is the anchor emitted in read/grep etc. (line number + id, e.g. `5th`).
+A patch contains one or more file sections. The first non-blank line of every section **MUST** be `---PATH`.
+A "Lid" is a per-line anchor emitted by `read`, `grep`, etc. — `<lineNumber><2-letter-hash>`, e.g. `5th`, `123ab`. You **MUST** copy a Lid verbatim from the latest output for the file you're editing.
+
+This format is purely textual. The tool has NO awareness of language, indentation, brackets, fences, or table widths. You are responsible for emitting valid syntax in your replacements/insertions.
 
 <ops>
----PATH  start editing PATH with cursor at EOF
-!rm      delete PATH
-!mv X    move file to X
-$        move cursor to BOF
-^        move cursor to EOF
-@Lid     move cursor after Lid
-+X       insert X at the cursor; `+` alone inserts a blank line
-Lid=X    replace whole line with X; `Lid=` blanks it out
--Lid     delete line (repeat for multi)
+---PATH    start a section editing PATH; cursor begins at EOF
+^          move cursor to BOF (before line 1)
+$          move cursor to EOF (after the last line)
+@Lid       move cursor to AFTER the anchored line (does not modify the file)
+^Lid       move cursor to BEFORE the anchored line (does not modify the file)
++TEXT      insert one line containing TEXT at the cursor
++          insert one blank line at the cursor
+Lid=TEXT   replace the anchored line with TEXT
+LidA..LidB=TEXT replace the range with one line; following `\TEXT` lines append literal lines to the replacement
+\TEXT      append literal TEXT to the active replacement (after `Lid=…` or `LidA..LidB=…`)
+\          append a blank line to the active replacement
+Lid=       blank the anchored line's content but KEEP the line (results in an empty line, NOT a removed line; use `-Lid` to remove)
+-Lid       delete the anchored line (repeat for multi-line delete)
+-LidA..LidB delete the contiguous line range LidA..LidB (inclusive)
+!rm        delete the section's PATH (**MUST** be the only op in the section)
+!mv DEST   rename the section's PATH to DEST (**MUST** be the only op in the section)
 </ops>
 
 <rules>
-- You may have multiple `---PATH` sections to edit multiple files at once.
-- Ops starting with `$` / `^` / `@Lid` do not alter lines; you must still issue an op like `+` afterwards.
-- Consecutive `+X` ops insert consecutive lines.
-- `Lid=X` replaces the whole line. X must be the complete new line, not a fragment.
-- To rewrite multiple adjacent lines, delete each with `-Lid` then emit the new content as `+TEXT` lines. Do not stack `Lid=X` over a contiguous range — it requires the new block to match the old line count and silently corrupts the file when they differ.
+- Cursor-only ops (`^`, `$`, `@Lid`, `^Lid`) reposition without modifying. To insert anything you **MUST** follow them with `+TEXT` (or `+` for a blank).
+- TEXT in `+TEXT`, `Lid=TEXT`, and `\TEXT` is literal line content, INCLUDING leading whitespace. You **MUST NOT** trim or re-indent it.
+- Consecutive `+TEXT` ops produce consecutive lines in the order written. You **MUST NOT** separate them with a stray `+` unless you intend to insert a blank line.
+- `Lid=TEXT` rewrites ONE line. To rewrite K adjacent lines, you **MUST** use `LidA..LidB=FIRST_LINE` followed immediately by `\NEXT_LINE` continuation lines (canonical form for any block replacement). You **MUST** use bare `\` for blank replacement lines.
+- You **MUST** prefix every replacement continuation line with `\`, especially when the replacement line starts with edit syntax characters such as `#`, `+`, `-`, `@`, `$`, `^`, `!`, or a Lid-shaped token.
+- `\TEXT` **MUST** appear only immediately after an active `Lid=…` or `LidA..LidB=…` replacement. It **MUST NOT** be used as a general insert operator.
+- A `\TEXT` line **MUST** be the immediate continuation of a `Lid=…` or `LidA..LidB=…` op on the line above (or another `\` line rooted in one). If the line above is `+TEXT`, a bare Lid, a cursor op, or whitespace, the `\` is invalid and the tool will not interpret it as part of a replacement.
+- The legacy `-LidA..LidB` + `+TEXT…` block-rewrite form also works.
+- To insert ABOVE a line, you **MUST** use `^Lid` then `+TEXT`. To insert above line 1, you **MUST** use `^` (BOF) then `+TEXT`. To insert below a line, you **MUST** use `@Lid` then `+TEXT`.
+- Multiple `---PATH` sections **MAY** appear in one input; each section is applied in order.
+- `!rm` / `!mv DEST` **MUST NOT** be combined with line edits in the same section.
+- Lids contain a content hash. If a line has changed since you read it, the tool rejects the edit and shows the current content; you **MUST** re-read and retry with fresh Lids. Small drift (≤5 lines) where the original hash still matches a nearby line auto-rebases with a warning. Larger shifts may show a hash-only candidate, but two-letter hashes collide; verify surrounding content or re-read before using it.
+- After `+TEXT` (or `+`) the cursor advances past the inserted line, so consecutive `+TEXT` ops stack in order. After `Lid=TEXT` the cursor sits on the modified anchor; after `-Lid` it sits on the slot the deleted line vacated. You **MUST** use a fresh `@Lid` / `^Lid` / `^` / `$` to reposition.
+- The tool is syntax-blind: it will not check brackets, indentation, table column counts, or fence integrity. You **MUST** verify indentation-sensitive or structured files after editing (Python, Markdown tables/fences).
+- A section whose PATH does not yet exist creates the file from your `+TEXT` lines (use `^` or `$` then `+TEXT…`). No separate "create file" op is needed.
 </rules>
 
 <case file="a.ts">
@@ -33,11 +52,11 @@ Lid=X    replace whole line with X; `Lid=` blanks it out
 </case>
 
 <examples>
-# Replace line
+# Replace one line (preserve the leading tab from the original)
 ---a.ts
 {{hrefr 5}}=	return clean.trim().toUpperCase();
 
-# Rewrite multiple adjacent lines (delete the old, insert the new)
+# Rewrite multiple adjacent lines (delete each, then insert new content)
 ---a.ts
 -{{hrefr 3}}
 -{{hrefr 4}}
@@ -47,48 +66,84 @@ Lid=X    replace whole line with X; `Lid=` blanks it out
 +	return (name || DEF).trim().toUpperCase();
 +}
 
-# Append after
+# Same rewrite using a range (equivalent to four `-Lid` lines)
 ---a.ts
-@{{hrefr 4}}
-+	const suffix = "";
+-{{hrefr 3}}..{{hrefr 6}}
++export function label(name: string): string {
++	return (name || DEF).trim().toUpperCase();
++}
 
-# Delete a line
+# Replace a contiguous range with one line (range-replace shorthand)
 ---a.ts
--{{hrefr 2}}
+{{hrefr 3}}..{{hrefr 6}}=export const label = (name: string) => (name || DEF).trim().toUpperCase();
 
-# Prepend and append
+# Replace a contiguous range with multiple lines (continuation form)
 ---a.ts
-$
+{{hrefr 3}}..{{hrefr 6}}=export function label(name: string): string {
+\	return (name || DEF).trim().toUpperCase();
+\}
+
+# Replace a block with a longer multi-line block, including blank lines (canonical form for refactors)
+---a.ts
+{{hrefr 3}}..{{hrefr 6}}=/** Format a display label, falling back to DEF when empty. */
+\export function label(name: string): string {
+\	const clean = (name || DEF).trim();
+\
+\	if (clean.length === 0) return DEF;
+\	return clean.toUpperCase();
+\}
+
+# Insert ABOVE a line
+---a.ts
+^{{hrefr 5}}
++	const debug = false;
+
+# Insert BELOW a line
+---a.ts
+@{{hrefr 4}}
++	const debug = false;
+
+# Insert above the first line (use BOF)
+---a.ts
+^
 +// Copyright (c) 2026
 +
-^
+
+# Append at end of file
+---a.ts
+$
 +export { DEF };
 
-# File ops
+# Delete a single line
 ---a.ts
-!rm
----b.ts
-!mv a.ts
+-{{hrefr 2}}
 
-# Wrong: `@Lid=TEXT` is not replacement syntax
+# Delete the file (no other ops in the section)
 ---a.ts
-@{{hrefr 5}}=	return clean.trim().toUpperCase();
+!rm
 
-# Wrong: do not split `Lid=TEXT` across lines
+# Rename a file
 ---a.ts
-{{hrefr 5}}=
-	return clean.trim().toUpperCase();
+!mv b.ts
 
-# Wrong: do not replace by deleting then adding
+# Multi-file edit in one input
 ---a.ts
--{{hrefr 5}}
-+{{hrefr 5}}=	return clean.trim().toUpperCase();
+{{hrefr 1}}=const DEF = "user";
+---other.ts
+$
++// new footer
 </examples>
 
 <critical>
-- Copy Lids **EXACTLY** from prior tool output. Never guess, shorten, or omit the letters.
-- Only emit lines that change. Never repeat unchanged context — anchors imply it.
-- This is **NOT** unified diff. Never send `@@`, `-OLD` / `+NEW` pairs, or unchanged context.
-- Never split `Lid=TEXT` across two physical lines.
-- Never stack `Lid=X` over a contiguous range. Use `-Lid`+`+TEXT` for block rewrites.
+- You **MUST** copy Lids EXACTLY from the latest read/grep output. You **MUST NOT** guess, shorten, drop letters, or invent line numbers.
+- Current/added preview lines include fresh `LINE+hash|content` anchors. Removed preview lines show deleted content and **MUST NOT** be reused as anchors.
+- You **MUST** emit only lines that change. You **MUST NOT** echo unchanged context; the anchor implies position.
+- You **MUST NOT** write `Lid=<sameTextThatIsAlreadyOnThatLine>`; the tool reports a no-op (no change applied). Emit `Lid=TEXT` only when TEXT differs.
+- A line of the form `Lid|content` (a Lid, then `|`, then text, with NO leading `+`/`-`/`^`/`@`/`\`/`=`/`..`) is **FORBIDDEN**. That shape only appears in `read`/`grep` output as an anchor for *you*; it is never an edit op. If you copy a `Lid|content` line verbatim from a read into a patch, you have made an error — every edit op must start with `+`, `-`, `^`, `@`, `\`, `$`, `!`, or a Lid immediately followed by `=` or `..`.
+- To replace a contiguous block with new content, the canonical form is `LidA..LidB=FIRST_LINE` + `\NEXT_LINE…`. You **MUST NOT** write the old block and then the new block — that is unified-diff thinking and the tool does not understand it. If you find yourself emitting pre-image lines (with or without operators) before your new content, STOP and rewrite the section as a single range-replace.
+- TEXT after `=`, `+`, or `\` includes leading whitespace verbatim. You **MUST NOT** trim or re-indent it.
+- This is NOT unified diff. You **MUST NOT** write `@@` headers, `-OLD`/`+NEW` pairs, context lines, or `+Lid|…` (bad: `+5th|new text`; good: `5th=new text`).
+- You **MUST NOT** split `Lid=TEXT` across two physical lines.
+- For a contiguous range replacement, you **MAY** use either `Lid=FIRST_LINE` + `\NEXT_LINE…` (extends one anchor) or `LidA..LidB=FIRST_LINE` + `\NEXT_LINE…` (collapses an existing range), or fall back to `-LidA..LidB` + `+TEXT…` (delete + insert).
+- The tool is syntax-blind. Indentation, brackets, fences, table widths — you remain responsible.
 </critical>

package/src/prompts/tools/exit-plan-mode.md

@@ -1,40 +1,6 @@
-Signals plan completion, requests user approval, and provides the final plan title for handoff.
+Submits a finalized implementation plan for user approval.
 
-<conditions>
-Use when:
-- Plan written to `local://PLAN.md`
-- No unresolved questions about requirements or approach
-- Ready for user review and approval
-</conditions>
-
-<instruction>
-- You **MUST** write plan to plan file BEFORE calling this tool
-- Tool reads plan from file—does not take plan content as parameter
-- You **MUST** provide a `title` argument for the final plan artifact (example: `WP_MIGRATION_PLAN`)
-- `.md` is optional in `title`; it is appended automatically when omitted
-- User sees plan contents when reviewing
-</instruction>
-
-<output>
-Presents plan to user for approval. If approved, plan mode exits with full tool access restored and the plan is renamed to `local://<title>.md`.
-</output>
-
-<examples>
-# Ready
-Plan complete at local://PLAN.md, no open questions.
-→ Call `exit_plan_mode` with `{ "title": "WP_MIGRATION_PLAN" }`
-# Unclear
-Unsure about auth method (OAuth vs JWT).
-→ Use `ask` first to clarify, then call `exit_plan_mode`
-</examples>
-
-<avoid>
-- **MUST NOT** call before plan is written to file
-- **MUST NOT** omit `title`
-- **MUST NOT** use `ask` to request plan approval (this tool does that)
-- **MUST NOT** call after pure research tasks (no implementation planned)
-</avoid>
-
-<critical>
-You **MUST** only use when planning implementation steps. Research tasks (searching, reading, understanding) do not need this tool.
-</critical>
+Write the plan to `local://PLAN.md` first, then call this with `title` (e.g. `WP_MIGRATION_PLAN`); on approval the file is renamed to `local://<title>.md` and full tool access is restored.
+- Use only after planning implementation steps; not for pure research.
+- **MUST NOT** call before the plan file exists.
+- **MUST NOT** use `ask` to request plan approval — this tool does that.

package/src/prompts/tools/lsp.md

@@ -17,8 +17,7 @@ Interacts with Language Server Protocol servers for code intelligence.
 <parameters>
 - `file`: File path, glob pattern (e.g. `src/**/*.ts`), or `"*"` for workspace scope. Globs are expanded locally before dispatch. `"*"` routes `diagnostics`/`symbols`/`reload` to their workspace-wide form.
 - `line`: 1-indexed line number for position-based actions
-- `symbol`: Substring on the target line used to resolve column automatically
-- `occurrence`: 1-indexed match index when `symbol` appears multiple times on the same line
+- `symbol`: Substring on the target line used to resolve column automatically. Append `#N` to pick the Nth occurrence on that line (1-indexed; default 1) — e.g. `foo#2` selects the second `foo`.
 - `query`: Symbol search query, code-action kind filter (list mode), or code-action selector (apply mode)
 - `new_name`: Required for rename
 - `apply`: Apply edits for rename/code_actions (default true for rename, list mode for code_actions unless explicitly true)
@@ -29,7 +28,7 @@ Interacts with Language Server Protocol servers for code intelligence.
 - Requires running LSP server for target language
 - Some operations require file to be saved to disk
 - Glob expansion samples up to 20 files per request; use `file: "*"` for broader coverage
-- When `symbol` is provided for position-based actions, missing symbols or out-of-bounds `occurrence` values return an explicit error instead of silently falling back
+- When `symbol` is provided for position-based actions, missing symbols or out-of-bounds `#N` occurrence selectors return an explicit error instead of silently falling back
 </caution>
 
 <critical>

package/src/prompts/tools/recipe.md

@@ -0,0 +1,16 @@
+Run a recipe / script / target from the project's task runners.
+
+<instruction>
+- `op` is a single string: task name plus any args, e.g. `{op: "test"}` or `{op: "build --release"}`.
+- In monorepos, package and Cargo target tasks are namespaced with `/`, e.g. `{op: "pkg-a/test"}` or `{op: "crate/bin/server"}`.
+{{#if hasMultipleRunners}}- When the same task name exists in more than one runner, prefix with the runner id, e.g. `{op: "{{ambiguityExampleRunner}}:{{ambiguityExampleTask}}"}`. The available runner ids are: {{#each runners}}`{{id}}`{{#unless @last}}, {{/unless}}{{/each}}.
+{{/if}}- Runs in the session's cwd. Output and exit code are returned in the same shape as `bash`.
+</instruction>
+
+{{#each runners}}
+<runner id="{{id}}" label="{{label}}" command="{{commandPrefix}}">
+{{#each tasks}}
+- `{{name}}{{#if paramSig}} {{paramSig}}{{/if}}`{{#if doc}} — {{doc}}{{/if}}{{#if command}} (`{{command}}`{{#if cwd}} in `{{cwd}}`{{/if}}){{/if}}
+{{/each}}
+</runner>
+{{/each}}