pi-subagents 0.66.0 → 0.68.0

package/src/watchdog/register-main.ts

@@ -3,7 +3,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { resolveEffectiveThinking, splitKnownThinkingSuffix, THINKING_LEVELS, type ThinkingLevel } from "../shared/model-info.ts";
 import { SLASH_TEXT_RESULT_TYPE } from "../shared/types.ts";
 import { captureWatchdogDiffBaseline, type WatchdogDiffBaseline } from "./diff-tool.ts";
-import { recommendStrongWatchdogModel, resolveWatchdogModelInput, parseWatchdogThinkingInput } from "./model-selection.ts";
+import { formatWatchdogRecommendation, recommendWatchdogModel, resolveWatchdogModelInput, parseWatchdogThinkingInput } from "./model-selection.ts";
 import { renderWatchdogWarning } from "./render.ts";
 import { createMainWatchdogReview } from "./review.ts";
 import { MainWatchdogRuntime, type WatchdogReviewFunction } from "./runtime.ts";
@@ -87,12 +87,11 @@ function childrenLine(snapshot: ReturnType<MainWatchdogRuntime["getSnapshot"]>):
 	return `Children: ${boolLabel(snapshot.config.enabled && children.enabled)} · model ${model} · thinking ${thinking}${overrideText}`;
 }
 
-function recommendationLine(ctx: ExtensionContext): string {
+function recommendationLine(snapshot: ReturnType<MainWatchdogRuntime["getSnapshot"]>, ctx: ExtensionContext): string {
 	try {
-		const recommendation = recommendStrongWatchdogModel(ctx);
-		return `Recommended strong watchdog: ${recommendation.model}:${recommendation.thinking} (${recommendation.label}, complementary reviewer)`;
+		return formatWatchdogRecommendation(recommendWatchdogModel(ctx, snapshot.config.main));
 	} catch (error) {
-		return `Recommended strong watchdog: unavailable (${messageFromError(error)})`;
+		return `Watchdog recommendation unavailable (${messageFromError(error)})`;
 	}
 }
 
@@ -111,7 +110,8 @@ export function buildWatchdogStatus(snapshot: ReturnType<MainWatchdogRuntime["ge
 		"Subagent watchdog",
 		`Main: ${boolLabel(snapshot.enabled)}${!snapshot.config.enabled && snapshot.sessionOverride === undefined ? " (default off)" : ""}`,
 		`Runtime: ${statusLabel(snapshot.status)}${snapshot.bufferedDeltas > 0 ? ` · buffered deltas ${snapshot.bufferedDeltas}` : ""}`,
-		`Review trigger: ${snapshot.reviewTrigger === "repo-edits" ? "repo edits only" : "every non-empty turn delta"}`,
+		`Review trigger: ${snapshot.reviewTrigger === "repo-edits" ? snapshot.config.clarification ? "repo edits + bounded main orchestration activity" : "repo edits only" : "every non-empty turn delta"}`,
+		`Main clarification: ${snapshot.config.clarification ? "on" : "off"}`,
 		`Scope context: ${snapshot.config.scope.enabled ? "on" : "off"}`,
 		`Cadence: ${snapshot.config.cadence.everyNTools === null ? "boundary only" : `every ${snapshot.config.cadence.everyNTools} tools + boundary`}`,
 		lspLine(snapshot),
@@ -119,7 +119,7 @@ export function buildWatchdogStatus(snapshot: ReturnType<MainWatchdogRuntime["ge
 		mainModelLine(snapshot, ctx),
 		`Main thinking: ${mainThinkingLine(snapshot, ctx)}`,
 		childrenLine(snapshot),
-		recommendationLine(ctx),
+		recommendationLine(snapshot, ctx),
 		`Agent-end timeout: ${snapshot.config.agentEndTimeoutMs}ms`,
 		`Stalemate: ${snapshot.boundaryRepeats}/${snapshot.config.stalemateRepeats}${snapshot.stalemate ? " · stopped" : ""}`,
 		`Rules: ${snapshot.config.rules ? `${Object.keys(snapshot.config.rules.roleModels).length} role models · ${snapshot.config.rules.action}` : "none"}`,
@@ -145,7 +145,7 @@ export function buildWatchdogStatus(snapshot: ReturnType<MainWatchdogRuntime["ge
 		"",
 		"Model commands:",
 		"- /subagents-watchdog recommend-model",
-		"- /subagents-watchdog model recommended",
+		"- /subagents-watchdog model recommended (saves to user settings, not project settings)",
 		"- /subagents-watchdog model <provider/model[:thinking]>",
 		"- /subagents-watchdog model inherit",
 		"- /subagents-watchdog session model recommended",
@@ -154,10 +154,10 @@ export function buildWatchdogStatus(snapshot: ReturnType<MainWatchdogRuntime["ge
 	return lines.join("\n");
 }
 
-function parseTestCommand(input: string): { severity: "concern" | "blocker"; text: string } | undefined {
-	const match = input.match(/^test\s+(concern|blocker)\s+([\s\S]+)$/);
+function parseTestCommand(input: string): { severity: "concern" | "blocker"; importance: "low" | "medium" | "high"; text: string } | undefined {
+	const match = input.match(/^test\s+(concern|blocker)\s+(low|medium|high)\s+([\s\S]+)$/);
 	if (!match) return undefined;
-	return { severity: match[1] as "concern" | "blocker", text: match[2]!.trim() };
+	return { severity: match[1] as "concern" | "blocker", importance: match[2] as "low" | "medium" | "high", text: match[3]!.trim() };
 }
 
 function formatThinking(value: ThinkingLevel | false | undefined): string {
@@ -171,12 +171,12 @@ function parseThinkingCommand(raw: string): ThinkingLevel | false | null {
 	return parseWatchdogThinkingInput(value, "/subagents-watchdog thinking") ?? null;
 }
 
-function resolveModelCommandValue(ctx: ExtensionCommandContext, raw: string): { model: string | null; thinking: ThinkingLevel | false | null; description: string } {
+function resolveModelCommandValue(runtime: MainWatchdogRuntime, ctx: ExtensionCommandContext, raw: string): { model: string | null; thinking: ThinkingLevel | false | null; description: string } {
 	const value = raw.trim();
 	if (!value) throw new Error("Expected a model, 'recommended', or 'inherit'.");
 	if (value === "inherit") return { model: null, thinking: null, description: "current session model and thinking" };
 	if (value === "recommended") {
-		const recommendation = recommendStrongWatchdogModel(ctx as ExtensionContext);
+		const recommendation = recommendWatchdogModel(ctx, runtime.getSnapshot(ctx.cwd).config.main);
 		return {
 			model: recommendation.model,
 			thinking: recommendation.thinking,
@@ -191,18 +191,18 @@ function resolveModelCommandValue(ctx: ExtensionCommandContext, raw: string): {
 	};
 }
 
-function buildRecommendationText(ctx: ExtensionCommandContext): string {
-	const recommendation = recommendStrongWatchdogModel(ctx as ExtensionContext);
+function buildRecommendationText(runtime: MainWatchdogRuntime, ctx: ExtensionCommandContext): string {
+	const recommendation = recommendWatchdogModel(ctx, runtime.getSnapshot(ctx.cwd).config.main);
 	return [
 		"Subagent watchdog recommended model",
 		`Current session: ${currentSessionModelLine(ctx as ExtensionContext)}`,
-		`Recommended: ${recommendation.model}:${recommendation.thinking}`,
+		recommendation.source === "configured" ? formatWatchdogRecommendation(recommendation) : `Recommended: ${recommendation.model}:${recommendation.thinking}`,
 		`Reason: ${recommendation.reason}`,
 		"",
 		"Apply for this session:",
 		"/subagents-watchdog session model recommended",
 		"",
-		"Save as your user default:",
+		"Save as your user default (affects other projects without overrides; does not change project settings):",
 		"/subagents-watchdog model recommended",
 	].join("\n");
 }
@@ -221,20 +221,15 @@ function buildCheckText(runtime: MainWatchdogRuntime, ctx: ExtensionCommandConte
 	}
 	lines.push(`Main thinking: ${mainThinkingLine(snapshot, ctx as ExtensionContext)}`);
 	lines.push(lspLine(snapshot));
-	try {
-		const recommendation = recommendStrongWatchdogModel(ctx as ExtensionContext);
-		lines.push(`Recommended strong watchdog: ${recommendation.model}:${recommendation.thinking}`);
-	} catch (error) {
-		lines.push(`Recommended strong watchdog: unavailable (${messageFromError(error)})`);
-	}
+	lines.push(recommendationLine(snapshot, ctx));
 	return lines.join("\n");
 }
 
-function createTestWarning(severity: "concern" | "blocker", text: string): WatchdogWarning {
+function createTestWarning(severity: "concern" | "blocker", importance: "low" | "medium" | "high", text: string): WatchdogWarning {
 	return {
 		severity,
 		category: "other",
-		confidence: "high",
+		importance,
 		source: "main",
 		state: "displayed",
 		summary: text,
@@ -258,7 +253,7 @@ async function handleWatchdogCommand(
 	}
 	if (input === "recommend-model") {
 		try {
-			sendSlashText(pi, buildRecommendationText(ctx));
+			sendSlashText(pi, buildRecommendationText(runtime, ctx));
 		} catch (error) {
 			sendSlashText(pi, `Subagent watchdog recommended model\n\n${messageFromError(error)}`);
 		}
@@ -301,7 +296,7 @@ async function handleWatchdogCommand(
 	if (input.startsWith("session model ")) {
 		const rawModel = input.slice("session model ".length);
 		try {
-			const value = resolveModelCommandValue(ctx, rawModel);
+			const value = resolveModelCommandValue(runtime, ctx, rawModel);
 			const snapshot = value.model === null
 				? runtime.clearSessionModel(ctx.cwd)
 				: runtime.setSessionModel({ model: value.model, thinking: value.thinking ?? null }, ctx.cwd);
@@ -319,7 +314,7 @@ async function handleWatchdogCommand(
 	if (input.startsWith("model ")) {
 		const rawModel = input.slice("model ".length);
 		try {
-			const value = resolveModelCommandValue(ctx, rawModel);
+			const value = resolveModelCommandValue(runtime, ctx, rawModel);
 			const settingsPath = writeWatchdogModelSettings({
 				scope: "user",
 				target: { kind: "main" },
@@ -329,7 +324,7 @@ async function handleWatchdogCommand(
 			runtime.refreshConfig(ctx.cwd);
 			const snapshot = runtime.getSnapshot(ctx.cwd);
 			sendSlashText(pi, [
-				`Subagent watchdog model saved: ${value.description}.`,
+				`Subagent watchdog model saved to user settings: ${value.description}. Project and session overrides still take precedence.`,
 				`Updated: ${settingsPath}`,
 				`Main now: ${boolLabel(snapshot.enabled)}`,
 				value.model === null ? "The watchdog now inherits the current session model and thinking." : "Run /subagents-watchdog on if the watchdog is still off.",
@@ -365,15 +360,14 @@ async function handleWatchdogCommand(
 	const test = parseTestCommand(input);
 	if (test) {
 		if (!test.text) {
-			ctx.ui.notify("Usage: /subagents-watchdog test concern|blocker <text>", "error");
+			ctx.ui.notify("Usage: /subagents-watchdog test concern|blocker low|medium|high <text>", "error");
 			return;
 		}
-		const warning = createTestWarning(test.severity, test.text);
-		const details = runtime.recordDisplayedWarning(warning);
-		pi.sendMessage(createWatchdogWarningMessage(details, { display: true, details }));
+		const warning = createTestWarning(test.severity, test.importance, test.text);
+		runtime.displayRecordedWarning(warning);
 		return;
 	}
-	ctx.ui.notify(`Usage: /subagents-watchdog [status|on|off|session on|session off|recommend-model|model recommended|model <provider/model[:thinking]>|model inherit|thinking ${THINKING_LEVELS.join("|")}|thinking inherit|session model recommended|check|test concern <text>|test blocker <text>]`, "error");
+	ctx.ui.notify(`Usage: /subagents-watchdog [status|on|off|session on|session off|recommend-model|model recommended|model <provider/model[:thinking]>|model inherit|thinking ${THINKING_LEVELS.join("|")}|thinking inherit|session model recommended|check|test concern|blocker low|medium|high <text>]`, "error");
 }
 
 export function registerMainWatchdog(pi: ExtensionAPI, options: RegisterMainWatchdogOptions = {}): MainWatchdogRuntime {
@@ -387,6 +381,8 @@ export function registerMainWatchdog(pi: ExtensionAPI, options: RegisterMainWatc
 		reviewDescription: options.review ? "injected seam" : "real model review",
 		reviewChangesOnly: true,
 		displayWarning: (details, options) => pi.sendMessage(createWatchdogWarningMessage(details, { display: true, details }), options),
+		displayUserWarning: (details) => pi.appendEntry(SUBAGENT_WATCHDOG_WARNING_TYPE, details),
+		displayClarification: (content) => pi.sendMessage({ customType: "subagent_watchdog_clarification", content, display: true }, { deliverAs: "steer", triggerTurn: true }),
 	});
 
 	pi.registerMessageRenderer<WatchdogWarningDetails>(SUBAGENT_WATCHDOG_WARNING_TYPE, (message, renderOptions, theme) => {
@@ -399,6 +395,12 @@ export function registerMainWatchdog(pi: ExtensionAPI, options: RegisterMainWatc
 		}
 		return renderWatchdogWarning(details, renderOptions, theme);
 	});
+	pi.registerEntryRenderer<WatchdogWarningDetails>(SUBAGENT_WATCHDOG_WARNING_TYPE, (entry, renderOptions, theme) => {
+		const details = entry.data as WatchdogWarningDetails | undefined;
+		return details?.summary && details.evidence && details.recommendedAction
+			? renderWatchdogWarning(details, renderOptions, theme)
+			: undefined;
+	});
 
 	pi.registerCommand("subagents-watchdog", {
 		description: "Show or toggle the default-off subagent watchdog",
@@ -421,6 +423,8 @@ export function registerMainWatchdog(pi: ExtensionAPI, options: RegisterMainWatc
 		rememberContext(ctx);
 		runtime.handleTurnEnd(event, ctx);
 	});
+	pi.on("input", (event) => { if (event.source !== "extension") runtime.handleUserInput(); });
+	pi.on("model_select", () => runtime.handleModelChange());
 	pi.on("tool_result", (_event, ctx) => {
 		rememberContext(ctx);
 		runtime.handleToolResult(ctx);
@@ -431,7 +435,7 @@ export function registerMainWatchdog(pi: ExtensionAPI, options: RegisterMainWatc
 	});
 	pi.on("session_before_switch", () => runtime.reset("session switch", { clearReviewInputSignature: true, clearLspLedger: true, clearScope: true }));
 	pi.on("session_before_fork", () => runtime.reset("session fork", { clearReviewInputSignature: true, clearLspLedger: true, clearScope: true }));
-	pi.on("session_compact", () => runtime.reset("session compact", { clearScope: true }));
+	pi.on("session_compact", () => runtime.reset("session compact", { clearActivity: true }));
 	pi.on("session_shutdown", () => {
 		currentContext = undefined;
 		runtime.dispose();

package/src/watchdog/render.ts

@@ -26,7 +26,7 @@ export function formatWatchdogWarningRenderText(warning: WatchdogWarningDetails)
 		`Subagent watchdog ${subject}${labels.length ? ` (${labels.join(", ")})` : ""}: ${warning.summary}`,
 		`Evidence: ${warning.evidence}`,
 		`Recommended action: ${warning.recommendedAction}`,
-		`Category: ${titleCase(warning.category)} · Source: ${warning.source}${warning.agent ? ` · Agent: ${warning.agent}` : ""}${warning.runId ? ` · Run: ${warning.runId}` : ""}`,
+		`Importance: ${titleCase(warning.importance)} · Category: ${titleCase(warning.category)} · Source: ${warning.source}${warning.agent ? ` · Agent: ${warning.agent}` : ""}${warning.runId ? ` · Run: ${warning.runId}` : ""}`,
 	];
 	if (warning.state === "failed" && warning.error) lines.push(`Failure: ${warning.error}`);
 	if (warning.state === "stalemate" && warning.stalemateRepeats !== undefined) {

package/src/watchdog/review.ts

@@ -3,32 +3,35 @@ import { createReadOnlyTools, convertToLlm, type ExtensionContext } from "@earen
 import { streamSimple } from "@earendil-works/pi-ai/compat";
 import type { Model, ProviderHeaders } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
-import { resolveModelCandidate } from "../runs/shared/model-fallback.ts";
+import { resolveModelCandidate } from "../runs/shared/model-resolution.ts";
 import { agentStreamOptions } from "../shared/agent-stream-options.ts";
+import { opencodeSessionHeaders } from "../shared/opencode-session-headers.ts";
 import { resolveEffectiveThinking, splitKnownThinkingSuffix, THINKING_LEVELS, toModelInfo } from "../shared/model-info.ts";
 import { createWatchdogDiffTool, WATCHDOG_DIFF_TOOL_NAME, type WatchdogDiffBaseline } from "./diff-tool.ts";
 import { loadWatchdogGuidance } from "./guidance.ts";
-import type { WatchdogReviewFunction, WatchdogReviewRequest } from "./runtime.ts";
+import { boundWatchdogReviewText, type WatchdogReviewFunction, type WatchdogReviewRequest } from "./runtime.ts";
 import {
 	WATCHDOG_WARNING_CATEGORIES,
-	WATCHDOG_WARNING_CONFIDENCES,
+	WATCHDOG_WARNING_IMPORTANCES,
 	WATCHDOG_WARNING_SEVERITIES,
 	type ResolvedWatchdogConfig,
 	type WatchdogCategory,
-	type WatchdogConfidence,
+	type WatchdogImportance,
 	type WatchdogSeverity,
 	type WatchdogWarning,
 } from "./types.ts";
 
 const WATCHDOG_ALLOWED_TOOL_NAMES = new Set(["read", "grep", "find", "ls", "watchdog_warn", WATCHDOG_DIFF_TOOL_NAME]);
 
+const WatchdogAskParams = Type.Object({ question: Type.String(), evidence: Type.String() }, { additionalProperties: false });
+
 const WatchdogWarnParams = Type.Object({
 	severity: Type.String({ enum: WATCHDOG_WARNING_SEVERITIES, description: "concern for actionable risk, blocker for a likely wrong or unsafe outcome" }),
+	importance: Type.String({ enum: WATCHDOG_WARNING_IMPORTANCES, description: "low or medium for user-only visibility; high when the parent model must receive the finding" }),
 	summary: Type.String({ description: "One concise sentence naming the issue." }),
 	evidence: Type.String({ description: "Specific evidence from the turn delta or inspected files." }),
 	recommendedAction: Type.String({ description: "Specific action the parent should take before accepting or continuing." }),
 	category: Type.Optional(Type.String({ enum: WATCHDOG_WARNING_CATEGORIES })),
-	confidence: Type.Optional(Type.String({ enum: WATCHDOG_WARNING_CONFIDENCES })),
 }, { additionalProperties: false });
 
 type WatchdogWarnParams = Static<typeof WatchdogWarnParams>;
@@ -114,9 +117,16 @@ function resolveConfiguredModel(ctx: ExtensionContext, rawModel: string): { mode
 	return { model, modelString: resolved };
 }
 
+class WatchdogAuthError extends Error {}
+
 async function resolveReviewAuth(ctx: ExtensionContext, model: RegistryModel): Promise<WatchdogReviewAuth> {
-	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-	if (auth.ok === false) throw new Error(`Watchdog model auth failed for ${fullModelId(model)}: ${auth.error}`);
+	let auth;
+	try {
+		auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	} catch (error) {
+		throw new WatchdogAuthError(`Watchdog model auth failed for ${fullModelId(model)}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+	if (auth.ok === false) throw new WatchdogAuthError(`Watchdog model auth failed for ${fullModelId(model)}: ${auth.error}`);
 	return {
 		...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
 		...(auth.headers ? { headers: auth.headers } : {}),
@@ -172,8 +182,8 @@ function nonEmptyString(value: string, field: string): string {
 function toWatchdogWarning(params: WatchdogWarnParams): WatchdogWarning {
 	return {
 		severity: params.severity as WatchdogSeverity,
+		importance: params.importance as WatchdogImportance,
 		category: (params.category ?? "other") as WatchdogCategory,
-		confidence: (params.confidence ?? "medium") as WatchdogConfidence,
 		source: "main",
 		summary: nonEmptyString(params.summary, "summary"),
 		evidence: nonEmptyString(params.evidence, "evidence"),
@@ -187,7 +197,7 @@ function createWatchdogWarnTool(request: WatchdogReviewRequest): AgentTool<typeo
 		label: "Watchdog warning",
 		description: [
 			"Emit one actionable main-session watchdog warning.",
-			"Use only for medium/high confidence concerns or blockers that the parent should consider before accepting the work.",
+			"Set importance explicitly: low or medium for user-only visibility, high only when the parent model must receive the finding.",
 			"Do not use for nits, praise, informational notes, or clean reviews.",
 		].join(" "),
 		parameters: WatchdogWarnParams,
@@ -214,11 +224,11 @@ export function buildWatchdogSystemPrompt(ctx: Pick<ExtensionContext, "cwd">, op
 		"You are the main-session subagent watchdog for Pi.",
 		`Working directory: ${ctx.cwd}`,
 		"Review only the supplied parent turn delta. Inspect repository files only when needed to verify a concrete concern.",
-		options.hasScope ? "When the review input includes a Current scope block, treat newer scope prompts as superseding/mutating older prompts and use category='scope-drift' for work that serves no current scope item." : undefined,
+		options.hasScope ? "Use the Current scope record alongside supplied activity evidence; an unrelated user question does not cancel older authorized work." : undefined,
 		`You are read-only. You may use ${options.hasDiff ? "read, grep, find, ls, and watchdog_diff (the full repo diff since the session baseline; pass a path to narrow it)" : "read, grep, find, and ls"}. Do not edit files, run shell commands, spawn agents, or mutate state.`,
 		"Emit warnings only by calling watchdog_warn. Freeform assistant text is ignored and must not be used to report warnings.",
-		"Emit only medium/high confidence actionable concerns or blockers: missed user constraints, correctness risks, test gaps that matter, unsafe changes, stale facts, loop risks, or scope drift.",
-		"Do not emit nits, style preferences, low-confidence guesses, informational notes, praise, or summaries.",
+		"Emit only actionable concerns or blockers: missed user constraints, correctness risks, test gaps that matter, unsafe changes, stale facts, loop risks, or scope drift.",
+		"Do not emit nits, style preferences, unsupported guesses, informational notes, praise, or summaries.",
 		"If the turn is clean, call no tools and end normally.",
 		"Use severity='blocker' only when the issue should stop acceptance until addressed; otherwise use severity='concern'.",
 		guidance ? `\nStanding instructions from WATCHDOG.md (project first, then user):\n${guidance}` : undefined,
@@ -236,18 +246,6 @@ function buildReviewPrompt(request: WatchdogReviewRequest, selection: WatchdogRe
 	].join("\n\n");
 }
 
-function finalStopReason(agent: Agent): "stop" | "error" | "aborted" | "length" {
-	for (let index = agent.state.messages.length - 1; index >= 0; index--) {
-		const message = agent.state.messages[index];
-		if (message && typeof message === "object" && (message as { role?: unknown }).role === "assistant") {
-			const stopReason = (message as { stopReason?: unknown }).stopReason;
-			if (stopReason === "error" || stopReason === "aborted" || stopReason === "length") return stopReason;
-			return "stop";
-		}
-	}
-	return "stop";
-}
-
 function resolveContext(provider: WatchdogContextProvider): ExtensionContext | undefined {
 	return typeof provider === "function" ? provider() : provider;
 }
@@ -256,59 +254,110 @@ export function createMainWatchdogReview(provider: WatchdogContextProvider, opti
 	return async (request) => {
 		const ctx = resolveContext(provider);
 		if (!ctx) throw new Error("Main watchdog review cannot run without an active Pi extension context.");
-		if (ctx.signal?.aborted || request.signal?.aborted) return { stopReason: "aborted" };
-		const selection = await resolveWatchdogReviewModel(ctx, request.config, {
-			currentThinkingLevel: options.getThinkingLevel?.(),
-		});
-		if (ctx.signal?.aborted || request.signal?.aborted) return { stopReason: "aborted" };
-		const auth = selection.auth;
-		const registeredProvider = (ctx.modelRegistry as {
-			getRegisteredProviderConfig?: (provider: string) => { api?: string; streamSimple?: StreamFn } | undefined;
-		}).getRegisteredProviderConfig?.(selection.model.provider);
-		const baseStreamFn = options.streamFn ?? (registeredProvider?.streamSimple && registeredProvider.api === selection.model.api
-			? registeredProvider.streamSimple
-			: streamSimple);
-		const streamFn: StreamFn = (model, context, streamOptions) => baseStreamFn(model, context, {
+		const aborted = () => ctx.signal?.aborted || request.signal?.aborted;
+		if (aborted()) return { stopReason: "aborted" };
+		try {
+			return (await runWatchdogAttempt(ctx, request, options)).result;
+		} catch (error) {
+			if (error instanceof WatchdogAuthError) throw error.cause ?? error;
+			throw error;
+		}
+	};
+}
+
+async function runWatchdogAttempt(ctx: ExtensionContext, request: WatchdogReviewRequest, options: CreateMainWatchdogReviewOptions): Promise<{
+	result: Awaited<ReturnType<WatchdogReviewFunction>>;
+}> {
+	const selection = await resolveWatchdogReviewModel(ctx, request.config, {
+		currentThinkingLevel: options.getThinkingLevel?.(),
+	});
+	if (ctx.signal?.aborted || request.signal?.aborted) return { result: { stopReason: "aborted" } };
+	const auth = selection.auth;
+	const registeredProvider = (ctx.modelRegistry as {
+		getRegisteredProviderConfig?: (provider: string) => { api?: string; streamSimple?: StreamFn } | undefined;
+	}).getRegisteredProviderConfig?.(selection.model.provider);
+	const baseStreamFn = options.streamFn ?? (registeredProvider?.streamSimple && registeredProvider.api === selection.model.api
+		? registeredProvider.streamSimple
+		: streamSimple);
+	const sessionId = ctx.sessionManager.getSessionId();
+	const streamFn: StreamFn = (model, context, streamOptions) => {
+		// Agent may enter one final loop iteration after an aborted mixed tool batch.
+		// Never send that iteration to the provider after an intentional yield.
+		if (clarification) throw new Error("Watchdog review yielded for clarification.");
+		return baseStreamFn(model, context, {
 			...streamOptions,
 			...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
 			env: auth.env || streamOptions?.env ? { ...(auth.env ?? {}), ...(streamOptions?.env ?? {}) } : undefined,
-			headers: { ...(streamOptions?.headers ?? {}), ...(auth.headers ?? {}) },
-		});
-		const diffBaseline = options.diffBaseline?.();
-		const tools = [
-			...(options.createReadOnlyTools ?? createReadOnlyTools)(ctx.cwd).filter((tool) => WATCHDOG_ALLOWED_TOOL_NAMES.has(tool.name) && tool.name !== "watchdog_warn"),
-			createWatchdogWarnTool(request),
-			...(diffBaseline ? [createWatchdogDiffTool(diffBaseline)] : []),
-		];
-		const agent = new Agent({
-			initialState: {
-				systemPrompt: buildWatchdogSystemPrompt(ctx, {
-					hasScope: request.hasScope,
-					guidance: loadWatchdogGuidance(ctx.cwd, request.config.guidance.watchdogMd),
-					hasDiff: diffBaseline !== undefined,
-				}),
-				model: selection.model,
-				thinkingLevel: selection.thinkingLevel,
-				tools,
-			},
-			convertToLlm,
-			...agentStreamOptions(streamFn),
-			getApiKey: (providerName) => providerName === selection.model.provider ? auth.apiKey : undefined,
-			beforeToolCall: async ({ toolCall }) => WATCHDOG_ALLOWED_TOOL_NAMES.has(toolCall.name)
-				? undefined
-				: { block: true, reason: `Watchdog reviews are read-only; tool '${toolCall.name}' is not allowed.` },
-			toolExecution: "sequential",
+			headers: { ...opencodeSessionHeaders(model, sessionId), ...(streamOptions?.headers ?? {}), ...(auth.headers ?? {}) },
 		});
-		const abort = () => agent.abort();
-		ctx.signal?.addEventListener("abort", abort, { once: true });
-		request.signal?.addEventListener("abort", abort, { once: true });
-		try {
-			if (ctx.signal?.aborted || request.signal?.aborted) return { stopReason: "aborted" };
-			await agent.prompt(buildReviewPrompt(request, selection));
-		} finally {
-			ctx.signal?.removeEventListener("abort", abort);
-			request.signal?.removeEventListener("abort", abort);
-		}
-		return { stopReason: finalStopReason(agent) };
+	};
+	const diffBaseline = options.diffBaseline?.();
+	let clarification: { question: string; evidence: string } | undefined;
+	let warned = false;
+	let toolCount = 0;
+	const warnRequest = request.allowClarification ? { ...request, emitWarning: (warning: WatchdogWarning) => {
+		if (clarification) return false;
+		const accepted = request.emitWarning(warning);
+		warned ||= accepted;
+		return accepted;
+	} } : request;
+	const tools = [
+		...(options.createReadOnlyTools ?? createReadOnlyTools)(ctx.cwd).filter((tool) => WATCHDOG_ALLOWED_TOOL_NAMES.has(tool.name) && tool.name !== "watchdog_warn"),
+		createWatchdogWarnTool(warnRequest),
+		...(diffBaseline ? [createWatchdogDiffTool(diffBaseline)] : []),
+	];
+	if (request.allowClarification) tools.push({
+		name: "watchdog_ask",
+		label: "Watchdog clarification",
+		description: "Send one focused question when missing task status, intent or other orchestrator context prevents a concrete review judgment. Yields and ends this review so the orchestrator can handle the message and continue; no answer or follow-up review is required. Never ask for approval or permission, or after recording a warning. Question and evidence are capped at 1000 and 2000 characters.",
+		parameters: WatchdogAskParams,
+		executionMode: "sequential",
+		async execute(_id, rawParams) {
+			const params = rawParams as Static<typeof WatchdogAskParams>;
+			if (warned || clarification || ctx.signal?.aborted || request.signal?.aborted) throw new Error("Clarification unavailable after warning, yield, or cancellation.");
+			if (!params.question.trim() || !params.evidence.trim()) throw new Error("A focused question and concrete evidence are required.");
+			clarification = { question: boundWatchdogReviewText(params.question.trim(), 1_000), evidence: boundWatchdogReviewText(params.evidence.trim(), 2_000) };
+			agent.abort(); // Intentional yield also stops mixed tool batches; terminate alone does not.
+			return { content: [{ type: "text", text: "Review yielded for clarification." }], details: {} };
+		},
+	});
+	const agent = new Agent({
+		initialState: {
+			systemPrompt: buildWatchdogSystemPrompt(ctx, {
+				hasScope: request.hasScope,
+				guidance: loadWatchdogGuidance(ctx.cwd, request.config.guidance.watchdogMd),
+				hasDiff: diffBaseline !== undefined,
+			}),
+			model: selection.model,
+			thinkingLevel: selection.thinkingLevel,
+			tools,
+		},
+		convertToLlm,
+		...agentStreamOptions(streamFn),
+		getApiKey: (providerName) => providerName === selection.model.provider ? auth.apiKey : undefined,
+		beforeToolCall: async ({ toolCall }) => !clarification && (WATCHDOG_ALLOWED_TOOL_NAMES.has(toolCall.name) || (request.allowClarification && toolCall.name === "watchdog_ask"))
+			? undefined
+			: { block: true, reason: `Watchdog reviews are read-only; tool '${toolCall.name}' is not allowed.` },
+		toolExecution: "sequential",
+	});
+	// Include rejected/invalid calls as well as read-only work and findings.
+	agent.subscribe((event) => { if (event.type === "tool_execution_start") toolCount++; });
+	const abort = () => agent.abort();
+	ctx.signal?.addEventListener("abort", abort, { once: true });
+	request.signal?.addEventListener("abort", abort, { once: true });
+	try {
+		if (ctx.signal?.aborted || request.signal?.aborted) return { result: { stopReason: "aborted" } };
+		await agent.prompt(buildReviewPrompt(request, selection));
+	} finally {
+		ctx.signal?.removeEventListener("abort", abort);
+		request.signal?.removeEventListener("abort", abort);
+	}
+	if (ctx.signal?.aborted || request.signal?.aborted) return { result: { stopReason: "aborted" } };
+	const terminal = agent.state.messages.findLast((message) => message.role === "assistant");
+	const reason = terminal && "stopReason" in terminal ? terminal.stopReason : undefined;
+	const stopReason = reason === "error" || reason === "aborted" || reason === "length" ? reason : "stop";
+	const error = terminal && "errorMessage" in terminal && typeof terminal.errorMessage === "string" ? terminal.errorMessage : undefined;
+	return {
+		result: clarification ? { clarification } : error ? { stopReason, errorMessage: error } : { stopReason },
 	};
 }

package/src/watchdog/rules.ts

@@ -51,7 +51,7 @@ export function evaluateLaunchRule(rules: WatchdogRulesConfig | undefined, agent
 }
 
 export function ruleViolationWarning(violation: WatchdogRuleViolation): WatchdogWarning {
-	return { severity: "concern", category: "missed-constraint", confidence: "high", source: "main", ...violation };
+	return { severity: "concern", category: "missed-constraint", importance: "high", source: "main", ...violation };
 }
 
 export function applyWatchdogLaunchRules(input: { cwd: string; agent: string; model?: string; warn?: (violation: WatchdogRuleViolation) => void }): string | undefined {