@oh-my-pi/pi-coding-agent 15.13.3 → 16.0.0

package/src/main.ts

@@ -140,6 +140,10 @@ const HOST_DEFAULTED_SETTING_PATHS: SettingPath[] = [
 	// memory should opt in explicitly through their own settings layer.
 	"memory.backend",
 	"memories.enabled",
+	// Advisor is interactive-session assistance. Protocol hosts opt in explicitly
+	// instead of inheriting a user's globally-enabled local preference.
+	"advisor.enabled",
+	"advisor.subagents",
 ];
 
 const RPC_BACKGROUND_DEFAULTED_SETTING_PATHS: SettingPath[] = [

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

@@ -0,0 +1,99 @@
+import { type Component, visibleWidth } from "@oh-my-pi/pi-tui";
+import type { AdvisorMessageDetails, AdvisorSeverity } from "../../advisor";
+import {
+	createCachedComponent,
+	formatBadge,
+	replaceTabs,
+	type ToolUIColor,
+	wrapTextWithAnsi,
+} from "../../tools/render-utils";
+import { Ellipsis, renderStatusLine, truncateToWidth } from "../../tui";
+import type { Theme } from "../theme/theme";
+
+const COLLAPSED_NOTES = 3;
+const NOTE_LINE_WIDTH = 110;
+
+function wrapVarying(text: string, w1: number, w2: number): string[] {
+	if (text.length === 0) return [];
+	const firstWrap = wrapTextWithAnsi(text, w1);
+	if (firstWrap.length <= 1) {
+		return firstWrap;
+	}
+	const firstLine = firstWrap[0];
+	const idx = text.indexOf(firstLine);
+	if (idx === -1) {
+		return wrapTextWithAnsi(text, w2);
+	}
+	const remainder = text.slice(idx + firstLine.length).trimStart();
+	const restWrap = wrapTextWithAnsi(remainder, w2);
+	return [firstLine, ...restWrap];
+}
+
+function severityColor(severity: AdvisorSeverity | undefined): ToolUIColor {
+	switch (severity) {
+		case "blocker":
+			return "error";
+		case "concern":
+			return "warning";
+		default:
+			return "muted";
+	}
+}
+
+/**
+ * Display-only transcript card for advisor notes injected into the primary
+ * session. Mirrors the IRC card's glyph + quote-border conventions so passive
+ * advice reads as a distinct, non-interrupting aside rather than a user turn.
+ */
+export function createAdvisorMessageCard(
+	details: AdvisorMessageDetails | undefined,
+	getExpanded: () => boolean,
+	uiTheme: Theme,
+): Component {
+	const notes = details?.notes ?? [];
+	const blockers = notes.filter(note => note.severity === "blocker").length;
+	const meta: string[] = [`${notes.length} ${notes.length === 1 ? "note" : "notes"}`];
+	if (blockers > 0) meta.push(uiTheme.fg("error", `${blockers} blocker${blockers === 1 ? "" : "s"}`));
+
+	return createCachedComponent(
+		getExpanded,
+		(width, expanded) => {
+			const glyph = uiTheme.styledSymbol("status.info", "accent");
+			const lines = [renderStatusLine({ iconOverride: glyph, title: "Advisor", meta }, uiTheme)];
+			const quote = uiTheme.fg("dim", uiTheme.md.quoteBorder);
+			const shown = expanded ? notes : notes.slice(0, COLLAPSED_NOTES);
+			for (const entry of shown) {
+				const badge = entry.severity
+					? `${formatBadge(entry.severity, severityColor(entry.severity), uiTheme)} `
+					: "";
+				const quotePrefix = `  ${quote} `;
+				const quoteWidth = visibleWidth(quotePrefix);
+				const badgeWidth = visibleWidth(badge);
+				const w1 = Math.max(10, Math.min(NOTE_LINE_WIDTH, width) - quoteWidth - badgeWidth);
+				const w2 = Math.max(10, Math.min(NOTE_LINE_WIDTH, width) - quoteWidth);
+
+				const paragraphs = entry.note.split("\n").filter(p => p.trim());
+				const bodyLines: string[] = [];
+				for (let i = 0; i < paragraphs.length; i++) {
+					const p = paragraphs[i];
+					if (i === 0) {
+						bodyLines.push(...wrapVarying(p, w1, w2));
+					} else {
+						bodyLines.push(...wrapTextWithAnsi(p, w2));
+					}
+				}
+
+				bodyLines.forEach((line, index) => {
+					const prefix = index === 0 ? badge : "";
+					lines.push(`  ${quote} ${prefix}${uiTheme.fg("toolOutput", replaceTabs(line))}`);
+				});
+			}
+			const hidden = notes.length - shown.length;
+			if (hidden > 0) {
+				lines.push(`  ${quote} ${uiTheme.fg("dim", `… +${hidden} more ${hidden === 1 ? "note" : "notes"}`)}`);
+			}
+			return lines.map(line => truncateToWidth(line, width, Ellipsis.Unicode));
+		},
+		{ paddingX: 1 },
+	);
+}

package/src/modes/components/agent-hub.ts

@@ -19,6 +19,7 @@ import type { AgentMessage, AgentTool } from "@oh-my-pi/pi-agent-core";
 import type { Usage } from "@oh-my-pi/pi-ai";
 import { Container, Editor, matchesKey, ScrollView, Text, type TUI } from "@oh-my-pi/pi-tui";
 import { formatAge, formatBytes, formatDuration, formatNumber, getProjectDir, logger } from "@oh-my-pi/pi-utils";
+import type { AdvisorMessageDetails } from "../../advisor";
 import { COLLAB_PROMPT_MESSAGE_TYPE, type CollabPromptDetails } from "../../collab/protocol";
 import type { KeyId } from "../../config/keybindings";
 import { settings } from "../../config/settings";
@@ -45,6 +46,7 @@ import { canonicalizeMessage } from "../../utils/thinking-display";
 import type { ObservableSession, SessionObserverRegistry } from "../session-observer-registry";
 import { getEditorTheme, theme } from "../theme/theme";
 import { matchesSelectDown, matchesSelectUp } from "../utils/keybinding-matchers";
+import { createAdvisorMessageCard } from "./advisor-message";
 import { AssistantMessageComponent } from "./assistant-message";
 import { createBackgroundTanDispatchBlock } from "./background-tan-message";
 import { BashExecutionComponent } from "./bash-execution";
@@ -1241,6 +1243,11 @@ export class AgentHubOverlayComponent extends Container {
 			this.#chatLog.addChild(card);
 			return;
 		}
+		if (message.customType === "advisor") {
+			const details = (message as CustomMessage<AdvisorMessageDetails>).details;
+			this.#chatLog.addChild(createAdvisorMessageCard(details, () => this.#chatExpanded, theme));
+			return;
+		}
 		if (message.customType === BACKGROUND_TAN_DISPATCH_MESSAGE_TYPE) {
 			this.#chatLog.addChild(createBackgroundTanDispatchBlock(message as CustomMessage<unknown>));
 			return;

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

@@ -15,6 +15,15 @@ import { canonicalizeMessage } from "../../utils/thinking-display";
  */
 const MAX_TRANSCRIPT_ERROR_LINES = 8;
 
+/**
+ * Frames for the streaming "thinking" pulse rendered in place of a hidden
+ * thinking block while the model is still producing it. A single fixed-width
+ * glyph that rises ▁▃▄▃ so the indicator animates without shifting the line.
+ * Advanced every {@link THINKING_DOTS_FRAME_MS}.
+ */
+const THINKING_DOTS_FRAMES = ["▁", "▃", "▄", "▃"] as const;
+const THINKING_DOTS_FRAME_MS = 320;
+
 /**
  * Component that renders a complete assistant message
  */
@@ -50,6 +59,11 @@ export class AssistantMessageComponent extends Container {
 	#fastPathItems:
 		| Array<{ md: Markdown; contentIndex: number; blockType: "text" | "thinking"; lastText: string }>
 		| undefined;
+	/** Live "thinking" pulse shown in place of a hidden thinking block while it
+	 *  streams; undefined when not animating. Driven by {@link #thinkingDotsTimer}. */
+	#thinkingDots: Text | undefined;
+	#thinkingDotsTimer: NodeJS.Timeout | undefined;
+	#thinkingDotsFrame = 0;
 
 	constructor(
 		message?: AssistantMessage,
@@ -87,6 +101,60 @@ export class AssistantMessageComponent extends Container {
 		this.hideThinkingBlock = hide;
 	}
 
+	override dispose(): void {
+		this.#stopThinkingAnimation();
+		super.dispose();
+	}
+
+	/**
+	 * Whether to render the animated "thinking" pulse in place of the suppressed
+	 * reasoning: only while this block is still streaming (not yet finalized — the
+	 * in-flight message always carries `stopReason: "stop"`, so finalization is the
+	 * only reliable live signal), thinking is hidden, no tool call has started, and
+	 * the active tail block is a thinking block (the model is reasoning right now).
+	 * Once text starts, a tool call streams, or the block is sealed, the pulse ends.
+	 */
+	#shouldAnimateThinking(message: AssistantMessage): boolean {
+		if (!this.hideThinkingBlock || this.#transcriptBlockFinalized) return false;
+		let tail: "text" | "thinking" | undefined;
+		for (const content of message.content) {
+			if (content.type === "toolCall") return false;
+			if (content.type === "text" && canonicalizeMessage(content.text)) tail = "text";
+			else if (content.type === "thinking" && canonicalizeMessage(content.thinking)) tail = "thinking";
+		}
+		return tail === "thinking";
+	}
+
+	#thinkingDotsLabel(): string {
+		const glyph = THINKING_DOTS_FRAMES[this.#thinkingDotsFrame % THINKING_DOTS_FRAMES.length] ?? "…";
+		return theme.fg("thinkingText", glyph);
+	}
+
+	#startThinkingAnimation(): void {
+		if (this.#thinkingDotsTimer) return;
+		this.#thinkingDotsTimer = setInterval(() => this.#advanceThinkingDots(), THINKING_DOTS_FRAME_MS);
+		this.#thinkingDotsTimer.unref?.();
+	}
+
+	#advanceThinkingDots(): void {
+		if (!this.#thinkingDots) {
+			this.#stopThinkingAnimation();
+			return;
+		}
+		this.#thinkingDotsFrame = (this.#thinkingDotsFrame + 1) % THINKING_DOTS_FRAMES.length;
+		if (this.#thinkingDots.setText(this.#thinkingDotsLabel())) {
+			this.onImageUpdate?.();
+		}
+	}
+
+	#stopThinkingAnimation(): void {
+		if (this.#thinkingDotsTimer) {
+			clearInterval(this.#thinkingDotsTimer);
+			this.#thinkingDotsTimer = undefined;
+		}
+		this.#thinkingDotsFrame = 0;
+	}
+
 	/**
 	 * Toggle suppression of the inline `Error: …` line while the same error is
 	 * pinned in the banner above the editor. Re-renders so the change is visible.
@@ -109,6 +177,14 @@ export class AssistantMessageComponent extends Container {
 
 	markTranscriptBlockFinalized(): void {
 		this.#transcriptBlockFinalized = true;
+		this.#stopThinkingAnimation();
+		// If the live pulse was on screen when the block sealed, drop the fast path
+		// and rebuild so the placeholder is removed — finalized blocks never animate.
+		if (this.#thinkingDots) {
+			this.#fastPathKey = undefined;
+			this.#fastPathItems = undefined;
+			if (this.#lastMessage) this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
+		}
 	}
 
 	/**
@@ -326,6 +402,7 @@ export class AssistantMessageComponent extends Container {
 
 		// Clear content container
 		this.#contentContainer.clear();
+		this.#thinkingDots = undefined;
 
 		// Determine if we should capture Markdown instances for next fast path
 		const shouldCapture = this.#canFastPath(message);
@@ -382,6 +459,15 @@ export class AssistantMessageComponent extends Container {
 			}
 		}
 
+		if (this.#shouldAnimateThinking(message)) {
+			if (hasVisibleContent) this.#contentContainer.addChild(new Spacer(1));
+			this.#thinkingDots = new Text(this.#thinkingDotsLabel(), 1, 0);
+			this.#contentContainer.addChild(this.#thinkingDots);
+			this.#startThinkingAnimation();
+		} else {
+			this.#stopThinkingAnimation();
+		}
+
 		this.#renderToolImages();
 		// Check if aborted - show after partial content
 		// But only if there are no tool calls (tool execution components will show the error)

package/src/modes/components/status-line/segments.ts

@@ -86,32 +86,45 @@ const modelSegment: StatusLineSegment = {
 			modelName = modelName.slice(7);
 		}
 
-		let content = withIcon(theme.icon.model, modelName);
-
+		// Fast-mode icon and thinking-level suffix trail the model name and are
+		// colored together with it as `statusLineModel`. The advisor "++" badge
+		// sits between the name and that tail in `accent`, so it reads as a
+		// distinct marker. theme.fg resets only the fg, so the spans are
+		// concatenated (not nested) to keep each color intact.
+		let tail = "";
 		if (ctx.session.isFastModeActive() && theme.icon.fast) {
-			content += ` ${theme.icon.fast}`;
+			tail += ` ${theme.icon.fast}`;
 		}
 
-		// Add thinking level with dot separator
 		if (opts.showThinkingLevel !== false && state.model?.thinking) {
 			if (ctx.session.isAutoThinking) {
 				// Pending (no turn classified yet / classifying) shows a symbol-theme
 				// question-box marker; once resolved it shows `<level>`.
 				const resolved = ctx.session.autoResolvedThinkingLevel();
 				const resolvedText = resolved ? (theme.thinking[resolved as keyof typeof theme.thinking] ?? resolved) : "";
-				content += `${theme.sep.dot}${resolved ? resolvedText : `${theme.thinking.autoPending} auto`}`;
+				tail += `${theme.sep.dot}${resolved ? resolvedText : `${theme.thinking.autoPending} auto`}`;
 			} else {
 				const level = state.thinkingLevel ?? ThinkingLevel.Off;
 				if (level !== ThinkingLevel.Off) {
 					const thinkingText = theme.thinking[level as keyof typeof theme.thinking];
 					if (thinkingText) {
-						content += `${theme.sep.dot}${thinkingText}`;
+						tail += `${theme.sep.dot}${thinkingText}`;
 					}
 				}
 			}
 		}
 
-		return { content: theme.fg("statusLineModel", content), visible: true };
+		// `statusLineModel` is aliased to `accent` in many themes, so the badge
+		// uses `success` to stay visibly distinct from the model name color.
+		let content = theme.fg("statusLineModel", withIcon(theme.icon.model, modelName));
+		if (ctx.session.isAdvisorActive()) {
+			content += theme.fg("success", "++");
+		}
+		if (tail) {
+			content += theme.fg("statusLineModel", tail);
+		}
+
+		return { content, visible: true };
 	},
 };
 

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

@@ -84,9 +84,9 @@ export class CommandController {
 		}
 	}
 
-	handleDumpCommand() {
+	handleDumpCommand(isRaw = false) {
 		try {
-			const formatted = this.ctx.session.formatSessionAsText();
+			const formatted = this.ctx.session.formatSessionAsText({ compact: !isRaw });
 			if (!formatted) {
 				this.ctx.showError("No messages to dump yet.");
 				return;
@@ -98,6 +98,26 @@ export class CommandController {
 		}
 	}
 
+	handleAdvisorDumpCommand(isRaw = false) {
+		try {
+			const advisorHistory = this.ctx.session.formatAdvisorHistoryAsText({ compact: !isRaw });
+			if (advisorHistory === null) {
+				this.ctx.showError("Advisor is not active for this session.");
+				return;
+			}
+			if (!advisorHistory) {
+				this.ctx.showError("Advisor has no history yet.");
+				return;
+			}
+			copyToClipboard(advisorHistory);
+			this.ctx.showStatus("Advisor history copied to clipboard");
+		} catch (error: unknown) {
+			this.ctx.showError(
+				`Failed to copy advisor history: ${error instanceof Error ? error.message : "Unknown error"}`,
+			);
+		}
+	}
+
 	async handleDebugTranscriptCommand(): Promise<void> {
 		try {
 			const width = Math.max(1, this.ctx.ui.terminal.columns);
@@ -305,6 +325,53 @@ export class CommandController {
 		this.ctx.present([new Spacer(1), new Text(info, 1, 0)]);
 	}
 
+	async handleAdvisorStatusCommand(): Promise<void> {
+		const stats = this.ctx.session.getAdvisorStats();
+		if (!stats.active) {
+			this.ctx.present([
+				new Spacer(1),
+				new Text(
+					stats.configured
+						? "Advisor setting is enabled, but no model is assigned to the 'advisor' role."
+						: "Advisor is disabled.",
+					1,
+					0,
+				),
+			]);
+			return;
+		}
+		const model = stats.model!;
+		let info = `${theme.bold("Advisor Status")}\n\n`;
+		info += `${theme.bold("Provider")}\n`;
+		info += `${theme.fg("dim", "Model:")} ${model.provider}/${model.id}\n`;
+		info += `\n${theme.bold("Messages")}\n`;
+		info += `${theme.fg("dim", "User:")} ${stats.messages.user.toLocaleString()}\n`;
+		info += `${theme.fg("dim", "Assistant:")} ${stats.messages.assistant.toLocaleString()}\n`;
+		info += `${theme.fg("dim", "Total:")} ${stats.messages.total.toLocaleString()}\n`;
+		info += `\n${theme.bold("Context")}\n`;
+		if (stats.contextWindow > 0) {
+			const percent = Math.round((stats.contextTokens / stats.contextWindow) * 100);
+			info += `${theme.fg("dim", "Tokens:")} ${stats.contextTokens.toLocaleString()} / ${stats.contextWindow.toLocaleString()} (${percent}%)\n`;
+		} else {
+			info += `${theme.fg("dim", "Tokens:")} ${stats.contextTokens.toLocaleString()}\n`;
+		}
+		info += `\n${theme.bold("Spend")}\n`;
+		info += `${theme.fg("dim", "Input:")} ${stats.tokens.input.toLocaleString()}\n`;
+		info += `${theme.fg("dim", "Output:")} ${stats.tokens.output.toLocaleString()}\n`;
+		if (stats.tokens.cacheRead > 0) {
+			info += `${theme.fg("dim", "Cache Read:")} ${stats.tokens.cacheRead.toLocaleString()}\n`;
+		}
+		if (stats.tokens.cacheWrite > 0) {
+			info += `${theme.fg("dim", "Cache Write:")} ${stats.tokens.cacheWrite.toLocaleString()}\n`;
+		}
+		info += `${theme.fg("dim", "Total:")} ${stats.tokens.total.toLocaleString()}\n`;
+		if (stats.cost > 0) {
+			info += `\n${theme.bold("Cost")}\n`;
+			info += `${theme.fg("dim", "Total:")} $${stats.cost.toFixed(4)}\n`;
+		}
+		this.ctx.present([new Spacer(1), new Text(info, 1, 0)]);
+	}
+
 	async handleJobsCommand(): Promise<void> {
 		const snapshot = this.ctx.session.getAsyncJobSnapshot({ recentLimit: 5 });
 		if (!snapshot) {

package/src/modes/interactive-mode.ts

@@ -542,6 +542,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		if (eventBus) {
 			this.#eventBusUnsubscribers.push(
 				eventBus.on(LSP_STARTUP_EVENT_CHANNEL, data => {
+					if (this.settings.get("startup.quiet")) return;
 					this.#handleLspStartupEvent(data as LspStartupEvent);
 				}),
 			);
@@ -551,6 +552,7 @@ export class InteractiveMode implements InteractiveModeContext {
 						logger.warn("Ignoring malformed mcp:connecting event", { data });
 						return;
 					}
+					if (this.settings.get("startup.quiet")) return;
 					this.showStatus(formatMCPConnectingMessage(data.serverNames));
 				}),
 			);
@@ -3333,8 +3335,12 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.#commandController.handleExportCommand(text);
 	}
 
-	handleDumpCommand() {
-		return this.#commandController.handleDumpCommand();
+	handleDumpCommand(isRaw?: boolean) {
+		return this.#commandController.handleDumpCommand(isRaw);
+	}
+
+	handleAdvisorDumpCommand(isRaw?: boolean) {
+		return this.#commandController.handleAdvisorDumpCommand(isRaw);
 	}
 
 	handleDebugTranscriptCommand(): Promise<void> {
@@ -3353,6 +3359,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.#commandController.handleSessionCommand();
 	}
 
+	handleAdvisorStatusCommand(): Promise<void> {
+		return this.#commandController.handleAdvisorStatusCommand();
+	}
+
 	handleJobsCommand(): Promise<void> {
 		return this.#commandController.handleJobsCommand();
 	}

package/src/modes/types.ts

@@ -270,13 +270,15 @@ export interface InteractiveModeContext {
 	handleShareCommand(): Promise<void>;
 	handleTodoCommand(args: string): Promise<void>;
 	handleSessionCommand(): Promise<void>;
+	handleAdvisorStatusCommand(): Promise<void>;
 	handleJobsCommand(): Promise<void>;
 	handleUsageCommand(reports?: UsageReport[] | null): Promise<void>;
 	handleChangelogCommand(showFull?: boolean): Promise<void>;
 	handleHotkeysCommand(): void;
 	handleToolsCommand(): void;
 	handleContextCommand(): void;
-	handleDumpCommand(): void;
+	handleDumpCommand(isRaw?: boolean): void;
+	handleAdvisorDumpCommand(isRaw?: boolean): void;
 	handleDebugTranscriptCommand(): Promise<void>;
 	handleClearCommand(): Promise<void>;
 	handleFreshCommand(): Promise<void>;

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

@@ -1,9 +1,11 @@
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, ImageContent, Message, Usage } from "@oh-my-pi/pi-ai";
 import { type Component, Spacer, Text, TruncatedText } from "@oh-my-pi/pi-tui";
+import type { AdvisorMessageDetails } from "../../advisor";
 import { COLLAB_PROMPT_MESSAGE_TYPE, type CollabPromptDetails } from "../../collab/protocol";
 import { settings } from "../../config/settings";
 import { getFileSnapshotStore } from "../../edit/file-snapshot-store";
+import { createAdvisorMessageCard } from "../../modes/components/advisor-message";
 import { AssistantMessageComponent } from "../../modes/components/assistant-message";
 import { createBackgroundTanDispatchBlock } from "../../modes/components/background-tan-message";
 import { BashExecutionComponent } from "../../modes/components/bash-execution";
@@ -240,6 +242,13 @@ export class UiHelpers {
 						this.ctx.chatContainer.addChild(card);
 						return [card];
 					}
+					if (message.customType === "advisor") {
+						const details = (message as CustomMessage<AdvisorMessageDetails>).details;
+						this.ctx.chatContainer.addChild(
+							createAdvisorMessageCard(details, () => this.ctx.toolOutputExpanded, theme),
+						);
+						break;
+					}
 					if (message.customType === BACKGROUND_TAN_DISPATCH_MESSAGE_TYPE) {
 						this.ctx.chatContainer.addChild(createBackgroundTanDispatchBlock(message as CustomMessage<unknown>));
 						break;

package/src/prompts/advisor/advise-tool.md

@@ -0,0 +1 @@
+Send one concrete, terse piece of advice to the agent you are watching. Use sparingly; stay silent when nothing matters.

package/src/prompts/advisor/system.md

@@ -0,0 +1,31 @@
+<system-conventions>
+RFC 2119 applies to MUST, REQUIRED, SHOULD, RECOMMENDED, MAY, OPTIONAL. `NEVER` and `AVOID` are aliases for `MUST NOT` and `SHOULD NOT`.
+You can explore the workspace; budget is 2–3 tool calls per advise (exception: critical bugs warrant deeper verification before raising a blocker).
+</system-conventions>
+
+You bring a different angle.
+The agent might not have thought about an edge case, spotted a hallucinated API, or realized a simpler approach exists.
+Your job is to offer that view before they sink work into the wrong direction.
+
+<workflow>
+You receive the agent's transcript incrementally, including private thinking.
+You have read-only access through `read`, `search`, `find` to verify your suspicions.
+Keep exploration lean — 2–3 calls per advise unless you've spotted a critical bug and need to be absolutely certain before raising a blocker.
+</workflow>
+
+<communication>
+At most one `advise` per update. Prefer silence when the agent is on track. Address the agent directly. Offer alternatives, not lectures. Never restate what they know; never explain how to use the advisor.
+</communication>
+
+<critical>
+You SHOULD call `advise` when: agent might be heading the wrong way, missed an edge case, about to call a hallucinated API, going in circles, picking brittle approach over better one. Low confidence bar — "this might be wrong" is worth noting if they didn't think about it.
+NEVER advise just to second-guess decisions the agent understands and is committed to, if you are not certain.
+</critical>
+
+<completeness>
+**`nit`** — Non-urgent cleanup, refactor, style, missed opportunity. Folded at next step boundary; agent keeps working. Examples: edge cases that don't break correctness, simplifications, better approach the agent can consider.
+**`concern`** — Agent might be heading wrong or missed something material. Offers your view; agent decides. Use when: exploring wrong code path, picking fragile approach when better exists, missing constraint, hallucinated API, going in circles, edge case about to be baked in.
+**`blocker`** — Stop and reconsider. Use ONLY when: continuing will clearly waste the turn, produce broken output, or the path is fundamentally unsound. Verify thoroughly before raising.
+</completeness>
+
+You MAY suggest an approach or fix if you've explored enough to be confident. Your job is pair programming, not just bugs — offer the better designs, not just the warning.