@oh-my-pi/pi-coding-agent 14.9.8 → 15.0.0

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

@@ -240,45 +240,12 @@ export class InputController {
 				text = slashResult;
 			}
 
-			// Handle skill commands (/skill:name [args])
-			if (text.startsWith("/skill:")) {
-				const spaceIndex = text.indexOf(" ");
-				const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
-				const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
-				const skillPath = this.ctx.skillCommands?.get(commandName);
-				if (skillPath) {
-					this.ctx.editor.addToHistory(text);
-					this.ctx.editor.setText("");
-					try {
-						const content = await Bun.file(skillPath).text();
-						const body = content.replace(/^---\n[\s\S]*?\n---\n/, "").trim();
-						const metaLines = [`Skill: ${skillPath}`];
-						if (args) {
-							metaLines.push(`User: ${args}`);
-						}
-						const message = `${body}\n\n---\n\n${metaLines.join("\n")}`;
-						const skillName = commandName.slice("skill:".length);
-						const details: SkillPromptDetails = {
-							name: skillName || commandName,
-							path: skillPath,
-							args: args || undefined,
-							lineCount: body ? body.split("\n").length : 0,
-						};
-						await this.ctx.session.promptCustomMessage(
-							{
-								customType: SKILL_PROMPT_MESSAGE_TYPE,
-								content: message,
-								display: true,
-								details,
-								attribution: "user",
-							},
-							{ streamingBehavior: "followUp" },
-						);
-					} catch (err) {
-						this.ctx.showError(`Failed to load skill: ${err instanceof Error ? err.message : String(err)}`);
-					}
-					return;
-				}
+			// Handle skill commands (/skill:name [args]). Enter ⇒ steer (matches the
+			// free-text Enter semantics applied a few lines below at the streaming
+			// branch). Ctrl+Enter routes through `handleFollowUp` and dispatches the
+			// same helper with `"followUp"`.
+			if (await this.#invokeSkillCommand(text, "steer")) {
+				return;
 			}
 
 			// Handle bash command (! for normal, !! for excluded from context)
@@ -439,16 +406,82 @@ export class InputController {
 		}
 	}
 
+	/**
+	 * Dispatch a `/skill:<name> [args]` invocation through `promptCustomMessage`
+	 * using the supplied `streamingBehavior`. Returns true if the text was a
+	 * recognised skill command and was dispatched. A failure to load the skill
+	 * file is surfaced via `showError` but still returns true — the editor was
+	 * already cleared on the success path, so falling through to plain-text
+	 * handling at that point would double-submit. Returns false when the text
+	 * isn't a `/skill:` prefix or the command name isn't a registered skill,
+	 * so the caller can fall through to plain-text handling (this branch
+	 * leaves the editor state untouched). `streamingBehavior` is only consulted
+	 * while the agent is streaming; the idle path of `promptCustomMessage`
+	 * ignores it.
+	 */
+	async #invokeSkillCommand(text: string, streamingBehavior: "steer" | "followUp"): Promise<boolean> {
+		if (!text.startsWith("/skill:")) return false;
+		const spaceIndex = text.indexOf(" ");
+		const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+		const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
+		const skillPath = this.ctx.skillCommands?.get(commandName);
+		if (!skillPath) return false;
+		this.ctx.editor.addToHistory(text);
+		this.ctx.editor.setText("");
+		try {
+			const content = await Bun.file(skillPath).text();
+			const body = content.replace(/^---\n[\s\S]*?\n---\n/, "").trim();
+			const metaLines = [`Skill: ${skillPath}`];
+			if (args) {
+				metaLines.push(`User: ${args}`);
+			}
+			const message = `${body}\n\n---\n\n${metaLines.join("\n")}`;
+			const skillName = commandName.slice("skill:".length);
+			const details: SkillPromptDetails = {
+				name: skillName || commandName,
+				path: skillPath,
+				args: args || undefined,
+				lineCount: body ? body.split("\n").length : 0,
+			};
+			await this.ctx.session.promptCustomMessage(
+				{
+					customType: SKILL_PROMPT_MESSAGE_TYPE,
+					content: message,
+					display: true,
+					details,
+					attribution: "user",
+				},
+				{ streamingBehavior },
+			);
+		} catch (err) {
+			this.ctx.showError(`Failed to load skill: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		return true;
+	}
+
 	/** Send editor text as a follow-up message (queued behind current stream). */
 	async handleFollowUp(): Promise<void> {
 		const text = this.ctx.editor.getText().trim();
 		if (!text) return;
 
+		// Compaction first: while compacting, free text gets queued via
+		// `queueCompactionMessage`, and `/skill:*` rides the same queue so a
+		// skill typed during compaction is not lost or short-circuited through
+		// `promptCustomMessage`. The skill text is queued verbatim; whether
+		// the queued entry is later re-parsed into a skill invocation is a
+		// separate concern owned by the compaction-resume path.
 		if (this.ctx.session.isCompacting) {
 			this.ctx.queueCompactionMessage(text, "followUp");
 			return;
 		}
 
+		// Skill commands invoke through the custom-message path regardless of
+		// which keybinding submitted them. Enter routes them as `steer`;
+		// Ctrl+Enter (this handler) routes them as `followUp`.
+		if (await this.#invokeSkillCommand(text, "followUp")) {
+			return;
+		}
+
 		if (this.ctx.session.isStreaming) {
 			this.ctx.editor.addToHistory(text);
 			this.ctx.editor.setText("");

package/src/modes/interactive-mode.ts

@@ -41,7 +41,11 @@ import { resolveLocalUrlToPath } from "../internal-urls";
 import { LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "../lsp/startup-events";
 import { renameApprovedPlanFile } from "../plan-mode/approved-plan";
 import planModeApprovedPrompt from "../prompts/system/plan-mode-approved.md" with { type: "text" };
+import planModeCompactInstructionsPrompt from "../prompts/system/plan-mode-compact-instructions.md" with {
+	type: "text",
+};
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
+import type { CompactionOutcome } from "../session/compaction";
 import { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
 import { getRecentSessions } from "../session/session-manager";
@@ -1109,7 +1113,12 @@ export class InteractiveMode implements InteractiveModeContext {
 
 	async #approvePlan(
 		planContent: string,
-		options: { planFilePath: string; finalPlanFilePath: string; preserveContext?: boolean },
+		options: {
+			planFilePath: string;
+			finalPlanFilePath: string;
+			preserveContext?: boolean;
+			compactBeforeExecute?: boolean;
+		},
 	): Promise<void> {
 		await renameApprovedPlanFile({
 			planFilePath: options.planFilePath,
@@ -1119,6 +1128,8 @@ export class InteractiveMode implements InteractiveModeContext {
 		});
 		const previousTools = this.#planModePreviousTools ?? this.session.getActiveToolNames();
 		await this.#exitPlanMode({ silent: true, paused: false });
+
+		let compactOutcome: CompactionOutcome | undefined;
 		if (!options.preserveContext) {
 			await this.handleClearCommand();
 			// The new session has a fresh local:// root — persist the approved plan there
@@ -1128,11 +1139,50 @@ export class InteractiveMode implements InteractiveModeContext {
 				getSessionId: () => this.sessionManager.getSessionId(),
 			});
 			await Bun.write(newLocalPath, planContent);
-		}
+		} else if (options.compactBeforeExecute) {
+			// Distill the plan-mode transcript before the execution turn is queued so
+			// the plan-approved synthetic prompt lands as a fresh cache anchor.
+			// Outcome is consumed after tool-restoration and plan-reference-path
+			// bookkeeping below; `markPlanReferenceSent` is intentionally deferred
+			// past the cancel guard — see the comment at the cancel branch.
+			// Cancellation skips the synthetic-prompt dispatch (operator's explicit
+			// abort is honored); failure proceeds best-effort — approval intent stands.
+			const compactionPrompt = prompt.render(planModeCompactInstructionsPrompt, {
+				planFilePath: options.finalPlanFilePath,
+			});
+			// Pin the plan reference path BEFORE compaction so any user messages
+			// queued during the compaction await (which `handleCompactCommand`
+			// flushes via `flushCompactionQueue` before returning) see the
+			// approved plan in `#buildPlanReferenceMessage`. Reassignment at
+			// line 1161 below is idempotent and kept for the !compactBeforeExecute
+			// branch.
+			this.session.setPlanReferencePath(options.finalPlanFilePath);
+			compactOutcome = await this.handleCompactCommand(compactionPrompt);
+		}
+
+		// Tool restoration runs on every path — the plan mode tools must be
+		// retired regardless of whether the synthetic prompt fires.
 		if (previousTools.length > 0) {
 			await this.session.setActiveToolsByName(previousTools);
 		}
 		this.session.setPlanReferencePath(options.finalPlanFilePath);
+
+		if (compactOutcome === "cancelled") {
+			// Explicit abort: honor it. `executeCompaction` already surfaced
+			// `showError("Compaction cancelled")` to the operator; we add the
+			// deferred-dispatch warning and exit. `markPlanReferenceSent` is
+			// intentionally skipped here: `#planReferenceSent` stays false, so
+			// `AgentSession.#buildPlanReferenceMessage` will inject the plan
+			// reference on the operator's next `prompt()` call. If we marked it
+			// sent here, the executor's first turn would have no plan context.
+			this.showWarning(
+				"Plan approved, but compaction was cancelled — execution not dispatched. Submit a turn to continue.",
+			);
+			return;
+		}
+
+		// markPlanReferenceSent fires only on the dispatch path so the synthetic
+		// plan-approved prompt is the source of the reference injection.
 		this.session.markPlanReferenceSent();
 		const planModePrompt = prompt.render(planModeApprovedPrompt, {
 			planContent,
@@ -1185,14 +1235,24 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#renderPlanPreview(planContent, { append: true });
 		const choice = await this.showHookSelector(
 			"Plan mode - next step",
-			["Approve and execute", "Approve and keep context", "Refine plan", "Stay in plan mode"],
+			[
+				"Approve and execute",
+				"Approve and compact context",
+				"Approve and keep context",
+				"Refine plan",
+				"Stay in plan mode",
+			],
 			{
 				helpText: this.#getPlanReviewHelpText(),
 				onExternalEditor: () => void this.#openPlanInExternalEditor(planFilePath),
 			},
 		);
 
-		if (choice === "Approve and execute" || choice === "Approve and keep context") {
+		if (
+			choice === "Approve and execute" ||
+			choice === "Approve and compact context" ||
+			choice === "Approve and keep context"
+		) {
 			const finalPlanFilePath = details.finalPlanFilePath || planFilePath;
 			try {
 				const latestPlanContent = await this.#readPlanFile(planFilePath);
@@ -1203,7 +1263,8 @@ export class InteractiveMode implements InteractiveModeContext {
 				await this.#approvePlan(latestPlanContent, {
 					planFilePath,
 					finalPlanFilePath,
-					preserveContext: choice === "Approve and keep context",
+					preserveContext: choice !== "Approve and execute",
+					compactBeforeExecute: choice === "Approve and compact context",
 				});
 			} catch (error) {
 				this.showError(
@@ -1727,7 +1788,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		await controller.handle(text);
 	}
 
-	handleCompactCommand(customInstructions?: string): Promise<void> {
+	handleCompactCommand(customInstructions?: string): Promise<CompactionOutcome> {
 		return this.#commandController.handleCompactCommand(customInstructions);
 	}
 
@@ -1735,7 +1796,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.#commandController.handleHandoffCommand(customInstructions);
 	}
 
-	executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<void> {
+	executeCompaction(
+		customInstructionsOrOptions?: string | CompactOptions,
+		isAuto?: boolean,
+	): Promise<CompactionOutcome> {
 		return this.#commandController.executeCompaction(customInstructionsOrOptions, isAuto);
 	}
 

package/src/modes/rpc/rpc-mode.ts

@@ -154,8 +154,17 @@ export function requestRpcEditor(
  * Run in RPC mode.
  * Listens for JSON commands on stdin, outputs events and responses on stdout.
  */
-export async function runRpcMode(session: AgentSession): Promise<never> {
+export async function runRpcMode(
+	session: AgentSession,
+	setToolUIContext?: (uiContext: ExtensionUIContext, hasUI: boolean) => void,
+): Promise<never> {
 	// Signal to RPC clients that the server is ready to accept commands
+	// Suppress terminal notifications: they write \x07 (BEL) or OSC sequences directly to
+	// process.stdout with no newline, which the reader merges with the next JSON line and
+	// breaks JSON.parse. In RPC mode stdout is the JSON protocol channel — nothing else
+	// may write there.
+	process.env.PI_NOTIFICATIONS = "off";
+
 	process.stdout.write(`${JSON.stringify({ type: "ready" })}\n`);
 	const output = (obj: RpcResponse | RpcExtensionUIRequest | object) => {
 		process.stdout.write(`${JSON.stringify(obj)}\n`);
@@ -405,6 +414,12 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 		}
 	}
 
+	// Wire up UI context for tool execution (ask tool, etc.) and extensions.
+	// A single shared instance routes all responses received on stdin to the
+	// correct waiting promise regardless of which code path created the request.
+	const rpcUiContext = new RpcExtensionUIContext(pendingExtensionRequests, output);
+	setToolUIContext?.(rpcUiContext, true);
+
 	// Set up extensions with RPC-based UI context
 	const extensionRunner = session.extensionRunner;
 	if (extensionRunner) {
@@ -481,7 +496,7 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 				},
 				compact: instructionsOrOptions => runExtensionCompact(session, instructionsOrOptions),
 			},
-			new RpcExtensionUIContext(pendingExtensionRequests, output),
+			rpcUiContext,
 		);
 		extensionRunner.onError(err => {
 			output({ type: "extension_error", extensionPath: err.extensionPath, event: err.event, error: err.error });

package/src/modes/types.ts

@@ -12,6 +12,7 @@ import type {
 import type { CompactOptions } from "../extensibility/extensions/types";
 import type { MCPManager } from "../mcp";
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
+import type { CompactionOutcome } from "../session/compaction";
 import type { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
 import type { ExitPlanModeDetails, LspStartupServerInfo } from "../tools";
@@ -207,13 +208,16 @@ export interface InteractiveModeContext {
 	handlePythonCommand(code: string, excludeFromContext?: boolean): Promise<void>;
 	handleMCPCommand(text: string): Promise<void>;
 	handleSSHCommand(text: string): Promise<void>;
-	handleCompactCommand(customInstructions?: string): Promise<void>;
+	handleCompactCommand(customInstructions?: string): Promise<CompactionOutcome>;
 	handleHandoffCommand(customInstructions?: string): Promise<void>;
 	handleMoveCommand(targetPath: string): Promise<void>;
 	handleRenameCommand(title: string): Promise<void>;
 	handleMemoryCommand(text: string): Promise<void>;
 	handleSTTToggle(): Promise<void>;
-	executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<void>;
+	executeCompaction(
+		customInstructionsOrOptions?: string | CompactOptions,
+		isAuto?: boolean,
+	): Promise<CompactionOutcome>;
 	openInBrowser(urlOrPath: string): void;
 	refreshSlashCommandState(cwd?: string): Promise<void>;
 

package/src/modes/utils/ui-helpers.ts

@@ -9,7 +9,11 @@ import { CompactionSummaryMessageComponent } from "../../modes/components/compac
 import { CustomMessageComponent } from "../../modes/components/custom-message";
 import { DynamicBorder } from "../../modes/components/dynamic-border";
 import { EvalExecutionComponent } from "../../modes/components/eval-execution";
-import { ReadToolGroupComponent } from "../../modes/components/read-tool-group";
+import {
+	ReadToolGroupComponent,
+	readArgsHaveTarget,
+	readArgsTargetInternalUrl,
+} from "../../modes/components/read-tool-group";
 import { SkillMessageComponent } from "../../modes/components/skill-message";
 import { ToolExecutionComponent } from "../../modes/components/tool-execution";
 import { UserMessageComponent } from "../../modes/components/user-message";
@@ -302,7 +306,11 @@ export class UiHelpers {
 						continue;
 					}
 
-					if (content.name === "read") {
+					if (
+						content.name === "read" &&
+						readArgsHaveTarget(content.arguments) &&
+						!readArgsTargetInternalUrl(content.arguments)
+					) {
 						if (hasErrorStop && errorMessage) {
 							if (!readGroup) {
 								readGroup = new ReadToolGroupComponent({
@@ -364,7 +372,11 @@ export class UiHelpers {
 					}
 				}
 			} else if (message.role === "toolResult") {
-				if (message.toolName === "read") {
+				const pendingReadComponent = this.ctx.pendingTools.get(message.toolCallId);
+				const isReadGroupResult =
+					message.toolName === "read" &&
+					(!pendingReadComponent || pendingReadComponent instanceof ReadToolGroupComponent);
+				if (isReadGroupResult) {
 					const assistantComponent = readToolCallAssistantComponents.get(message.toolCallId);
 					const images: ImageContent[] = message.content.filter(
 						(content): content is ImageContent => content.type === "image",

package/src/prompts/agents/designer.md

@@ -30,9 +30,9 @@ Implement and review UI designs. Edit files, create components, run commands whe
 </procedure>
 
 <directives>
-- You **SHOULD** prefer editing existing files over creating new ones
-- Changes **MUST** be minimal and consistent with existing code style
-- You **MUST NOT** create documentation files (*.md) unless explicitly requested
+- You SHOULD prefer editing existing files over creating new ones
+- Changes MUST be minimal and consistent with existing code style
+- You NEVER create documentation files (*.md) unless explicitly requested
 </directives>
 
 <avoid>
@@ -61,6 +61,6 @@ Implement and review UI designs. Edit files, create components, run commands whe
 
 <critical>
 Every interface should prompt "how was this made?" not "which AI made this?"
-You **MUST** commit to clear aesthetic direction and execute with precision.
-You **MUST** keep going until implementation is complete.
+You MUST commit to clear aesthetic direction and execute with precision.
+You MUST keep going until implementation is complete.
 </critical>

package/src/prompts/agents/explore.md

@@ -32,13 +32,13 @@ output:
 Investigate the codebase rapidly. Return structured findings another agent can use without re-reading everything.
 
 <directives>
-- You **MUST** use tools for broad pattern matching / code search as much as possible.
-- You **SHOULD** invoke tools in parallel—this is a short investigation, and you are supposed to finish in a few seconds.
-- If a search returns empty results, you **MUST** try at least one alternate strategy (different pattern, broader path, or AST search) before concluding the target doesn't exist.
+- You MUST use tools for broad pattern matching / code search as much as possible.
+- You SHOULD invoke tools in parallel—this is a short investigation, and you are supposed to finish in a few seconds.
+- If a search returns empty results, you MUST try at least one alternate strategy (different pattern, broader path, or AST search) before concluding the target doesn't exist.
 </directives>
 
 <thoroughness>
-You **MUST** infer the thoroughness from the task; default to medium:
+You MUST infer the thoroughness from the task; default to medium:
 - **Quick**: Targeted lookups, key files only
 - **Medium**: Follow imports, read critical sections
 - **Thorough**: Trace all dependencies, check tests/types.
@@ -46,12 +46,12 @@ You **MUST** infer the thoroughness from the task; default to medium:
 
 <procedure>
 1. Locate relevant code using tools.
-2. Read key sections (You **MUST NOT** read full files unless they're tiny)
+2. Read key sections (You NEVER read full files unless they're tiny)
 3. Identify types/interfaces/key functions.
 4. Note dependencies between files.
 </procedure>
 
 <critical>
-You **MUST** operate as read-only. You **MUST NOT** write, edit, or modify files, nor execute any state-changing commands, via git, build system, package manager, etc.
-You **MUST** keep going until complete.
+You MUST operate as read-only. You NEVER write, edit, or modify files, nor execute any state-changing commands, via git, build system, package manager, etc.
+You MUST keep going until complete.
 </critical>

package/src/prompts/agents/init.md

@@ -18,16 +18,16 @@ Generate AGENTS.md by launching multiple `explore` agents in parallel (via `task
 </structure>
 
 <directives>
-- You **MUST** title the document "Repository Guidelines"
-- You **MUST** use Markdown headings for structure
-- You **MUST** be concise and practical
-- You **MUST** focus on what an AI assistant needs to help with the codebase
-- You **SHOULD** include examples where helpful (commands, paths, naming patterns)
-- You **SHOULD** include file paths where relevant
-- You **MUST** call out architecture and code patterns explicitly
-- You **SHOULD** omit information obvious from code structure
+- You MUST title the document "Repository Guidelines"
+- You MUST use Markdown headings for structure
+- You MUST be concise and practical
+- You MUST focus on what an AI assistant needs to help with the codebase
+- You SHOULD include examples where helpful (commands, paths, naming patterns)
+- You SHOULD include file paths where relevant
+- You MUST call out architecture and code patterns explicitly
+- You SHOULD omit information obvious from code structure
 </directives>
 
 <output>
-After analysis, you **MUST** write AGENTS.md to the project root.
+After analysis, you MUST write AGENTS.md to the project root.
 </output>

package/src/prompts/agents/librarian.md

@@ -68,8 +68,8 @@ output:
 Answer questions about external libraries, frameworks, and APIs by reading source code and official documentation.
 
 <critical>
-You **MUST** ground every claim in source code or official documentation. You **MUST NOT** rely on training data for API details — it may be stale or wrong.
-You **MUST** operate as read-only on the user's project. You **MUST NOT** modify any project files.
+You MUST ground every claim in source code or official documentation. You NEVER rely on training data for API details — it may be stale or wrong.
+You MUST operate as read-only on the user's project. You NEVER modify any project files.
 </critical>
 
 <procedure>
@@ -93,27 +93,27 @@ You **MUST** operate as read-only on the user's project. You **MUST NOT** modify
 ## 4. Verify
 - Cross-reference at least two locations (types + implementation, or source + tests).
 - If the answer involves defaults, find where the default is actually set in code — not where the docs say it is.
-- For API signatures: copy verbatim from source. You **MUST NOT** paraphrase or reconstruct from memory.
+- For API signatures: copy verbatim from source. You NEVER paraphrase or reconstruct from memory.
 
 ## 5. Report
 - Call `yield` with structured findings.
-- Every `sources` entry **MUST** include a verbatim excerpt.
-- The `api` array **MUST** contain exact signatures copied from source.
+- 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-*`.
 </procedure>
 
 <directives>
-- You **SHOULD** invoke tools in parallel — search multiple paths simultaneously.
-- You **MUST** include the exact version you investigated in the `version` field.
-- If the library has breaking changes between versions relevant to the question, you **MUST** populate `breaking_changes`.
-- If you discover undocumented behavior or gotchas, you **MUST** populate `caveats`.
-- When local `node_modules` has the package, you **SHOULD** prefer it over cloning — it reflects the version the project actually uses.
-- You **SHOULD** use `web_search` to find the canonical repo URL and to check for known issues, but the definitive answer **MUST** come from reading source code.
-- If a search or lookup returns empty or unexpectedly few results, you **MUST** try at least 2 fallback strategies (broader query, alternate path, different source) before concluding nothing exists.
-- If the package is absent from local `node_modules` and cloning fails, you **MUST** fall back to `web_search` for official API documentation before reporting failure.
+- You SHOULD invoke tools in parallel — search multiple paths simultaneously.
+- You MUST include the exact version you investigated in the `version` field.
+- If the library has breaking changes between versions relevant to the question, you MUST populate `breaking_changes`.
+- If you discover undocumented behavior or gotchas, you MUST populate `caveats`.
+- When local `node_modules` has the package, you SHOULD prefer it over cloning — it reflects the version the project actually uses.
+- You SHOULD use `web_search` to find the canonical repo URL and to check for known issues, but the definitive answer MUST come from reading source code.
+- If a search or lookup returns empty or unexpectedly few results, you MUST try at least 2 fallback strategies (broader query, alternate path, different source) before concluding nothing exists.
+- If the package is absent from local `node_modules` and cloning fails, you MUST fall back to `web_search` for official API documentation before reporting failure.
 </directives>
 
 <critical>
 Source code is truth. Documentation is aspiration. Training data is history.
-You **MUST** keep going until you have a definitive, source-verified answer.
+You MUST keep going until you have a definitive, source-verified answer.
 </critical>

package/src/prompts/agents/plan.md

@@ -20,7 +20,7 @@ Analyze the codebase and the user's request. Produce a detailed implementation p
 4. Identify types, interfaces, contracts
 5. Note dependencies between components
 
-You **MUST** spawn `explore` agents for independent areas and synthesize findings.
+You MUST spawn `explore` agents for independent areas and synthesize findings.
 
 ## Phase 3: Design
 1. List concrete changes (files, functions, types)
@@ -31,7 +31,7 @@ You **MUST** spawn `explore` agents for independent areas and synthesize finding
 
 ## Phase 4: Produce Plan
 
-You **MUST** write a plan executable without re-exploration.
+You MUST write a plan executable without re-exploration.
 
 <structure>
 - **Summary**: What to build and why (one paragraph).
@@ -43,6 +43,6 @@ You **MUST** write a plan executable without re-exploration.
 </structure>
 
 <critical>
-You **MUST** operate as read-only. You **MUST NOT** write, edit, or modify files, nor execute any state-changing commands, via git, build system, package manager, etc.
-You **MUST** keep going until complete.
+You MUST operate as read-only. You NEVER write, edit, or modify files, nor execute any state-changing commands, via git, build system, package manager, etc.
+You MUST keep going until complete.
 </critical>

package/src/prompts/agents/reviewer.md

@@ -64,7 +64,7 @@ Identify bugs the author would want fixed before merge.
 3. Call `report_finding` per issue
 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.
+Bash is read-only: `git diff`, `git log`, `git show`, `gh pr diff`. You NEVER make file edits or trigger builds.
 </procedure>
 
 <criteria>
@@ -86,7 +86,7 @@ For every new type, variant, or value introduced by the patch that crosses a fun
 3. If the new type falls through to a silent drop, no-op, or discard (e.g. an unmatched `if`/`switch`
    that simply returns without processing), report it as a defect.
 
-The dispatch point is frequently **outside the diff**. You **MUST** read it before concluding
+The dispatch point is frequently **outside the diff**. You MUST read it before concluding
 the producing side is correct. Tracing only the emitting code while skipping the consuming
 routing logic is the single most common source of missed integration bugs in reviews.
 </cross-boundary>
@@ -128,13 +128,13 @@ 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
-- `result.data.findings`: Optional; **MUST** omit (auto-populated from `report_finding`)
+- `result.data.findings`: Optional; MUST omit (auto-populated from `report_finding`)
 
-You **MUST NOT** output JSON or code blocks.
+You NEVER output JSON or code blocks.
 
 Correctness ignores non-blocking issues (style, docs, nits).
 </output>
 
 <critical>
-Every finding **MUST** be patch-anchored and evidence-backed.
+Every finding MUST be patch-anchored and evidence-backed.
 </critical>

package/src/prompts/agents/task.md

@@ -1,16 +1,16 @@
 You are a worker agent for delegated tasks.
 
-You have FULL access to all tools (edit, write, bash, search, read, etc.) and you **MUST** use them as needed to complete your task.
+You have FULL access to all tools (edit, write, bash, search, read, etc.) and you MUST use them as needed to complete your task.
 
-You **MUST** maintain hyperfocus on the task at hand, do not deviate from what was assigned to you.
+You MUST maintain hyperfocus on the task at hand, do not deviate from what was assigned to you.
 
 <directives>
-- You **MUST** finish only the assigned work and return the minimum useful result. Do not repeat what you have written to the filesystem.
-- You **MAY** make file edits, run commands, and create files when your task requires it—and **SHOULD** do so.
-- You **MUST** be concise. You **MUST NOT** include filler, repetition, or tool transcripts. User cannot even see you. Your result is just the notes you are leaving for yourself.
-- You **SHOULD** prefer narrow lookups (`search`/`find`) then read only needed ranges. Do not bother yourself with anything beyond your current scope.
-- You **SHOULD NOT** do full-file reads unless necessary.
-- You **SHOULD** prefer edits to existing files over creating new ones.
-- You **MUST NOT** create documentation files (*.md) unless explicitly requested.
-- You **MUST** follow the assignment and the instructions given to you. You gave them for a reason.
+- You MUST finish only the assigned work and return the minimum useful result. Do not repeat what you have written to the filesystem.
+- You MAY make file edits, run commands, and create files when your task requires it—and SHOULD do so.
+- You MUST be concise. You NEVER include filler, repetition, or tool transcripts. User cannot even see you. Your result is just the notes you are leaving for yourself.
+- You SHOULD prefer narrow lookups (`search`/`find`) then read only needed ranges. Do not bother yourself with anything beyond your current scope.
+- AVOID full-file reads unless necessary.
+- You SHOULD prefer edits to existing files over creating new ones.
+- You NEVER create documentation files (*.md) unless explicitly requested.
+- You MUST follow the assignment and the instructions given to you. You gave them for a reason.
 </directives>

package/src/prompts/commands/orchestrate.md

@@ -20,13 +20,13 @@ You decompose, dispatch, verify, and iterate. You do **not** edit code. Every fi
 <rules>
 1. **Do not yield until everything is closed.** A phase finishing is *not* a yield point — launch the next phase in the same turn. Stop only when every requested item is verifiably done, or you hit a concrete [blocked] state that genuinely requires the user.
 2. **Enumerate the full surface before dispatching.** If the task references audits, plans, checklists, phase lists, or file lists, expand them into a flat set of items in `todo_write`. "Most of them" or "the important ones" is failure. Re-read the source documents — do not work from memory.
-3. **Parallelize maximally.** Every set of edits with disjoint file scope **MUST** ship as one `task` batch. Serialize only when one subagent produces a contract (types, schema, shared module) the next consumes — and state the dependency when you do.
+3. **Parallelize maximally.** Every set of edits with disjoint file scope MUST ship as one `task` batch. Serialize only when one subagent produces a contract (types, schema, shared module) the next consumes — and state the dependency when you do.
 4. **Each `task` assignment is self-contained.** Subagents have no shared context. Spell out: target files (≤3–5 explicit paths, no globs), the change with APIs and patterns, edge cases, and observable acceptance criteria. Do not assume they read the same plan you did.
 5. **Verify after every phase before launching the next.** Run the appropriate gate: `bun check` for types, package-scoped `bun test` for behavior, `lsp diagnostics` for changed files. If a phase introduced breakage, dispatch fix-up subagents *before* moving on. Never declare a phase done on a red tree.
 6. **Commit policy.** If the task asks for commits or the repo workflow expects them, commit after each green phase with a focused message. Never commit a red tree. Never commit work the user did not ask to commit.
 7. **Respawn, do not absorb.** If a subagent returns incomplete or wrong work, spawn a corrective subagent with the specific gap — do not silently fix it yourself.
 8. **No scope creep, no scope shrink.** Do not add work the user did not ask for. Do not relabel unfinished items as "follow-up", "v1", or "MVP" to imply completion.
-9. **Subagents do not verify, lint, or format.** Every `task` assignment **MUST** instruct the subagent to skip all gates and formatters. Their job is the edit only. You — the orchestrator — run verification and formatting **once** at the end of the phase across the union of changed files. Avoids redundant runs and racing formatter passes.
+9. **Subagents do not verify, lint, or format.** Every `task` assignment MUST instruct the subagent to skip all gates and formatters. Their job is the edit only. You — the orchestrator — run verification and formatting **once** at the end of the phase across the union of changed files. Avoids redundant runs and racing formatter passes.
 </rules>
 
 <workflow>

package/src/prompts/compaction/branch-summary.md

@@ -1,6 +1,6 @@
-You **MUST** create a structured summary of the conversation branch for context when returning.
+You MUST create a structured summary of the conversation branch for context when returning.
 
-You **MUST** use EXACT format:
+You MUST use EXACT format:
 
 ## Goal
 
@@ -27,4 +27,4 @@ You **MUST** use EXACT format:
 ## Next Steps
 1. [What should happen next to continue]
 
-Sections **MUST** be kept concise. You **MUST** preserve exact file paths, function names, error messages.
+Sections MUST be kept concise. You MUST preserve exact file paths, function names, error messages.