pi-subagents 0.65.1 → 0.67.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";
@@ -63,11 +63,16 @@ function mainThinkingLine(snapshot: ReturnType<MainWatchdogRuntime["getSnapshot"
 }
 
 function mainModelLine(snapshot: ReturnType<MainWatchdogRuntime["getSnapshot"]>, ctx: ExtensionContext): string {
+	const fallbacks = fallbackLine(snapshot.config.main.fallbackModels);
 	if (snapshot.config.main.model) {
 		const source = snapshot.sessionModelOverride?.model ? "session override" : "configured";
-		return `Main model: ${splitKnownThinkingSuffix(snapshot.config.main.model).baseModel} (${source})`;
+		return `Main model: ${splitKnownThinkingSuffix(snapshot.config.main.model).baseModel} (${source})${fallbacks}`;
 	}
-	return `Main model: ${currentSessionModelLine(ctx)}`;
+	return `Main model: ${currentSessionModelLine(ctx)}${fallbacks}`;
+}
+
+function fallbackLine(models: string[] | undefined): string {
+	return models === undefined ? "" : ` · fallbacks ${models.length ? models.join(" → ") : "none"}`;
 }
 
 function childrenLine(snapshot: ReturnType<MainWatchdogRuntime["getSnapshot"]>): string {
@@ -80,19 +85,19 @@ function childrenLine(snapshot: ReturnType<MainWatchdogRuntime["getSnapshot"]>):
 			const bits = [agent];
 			if (override.enabled !== undefined) bits.push(boolLabel(override.enabled));
 			if (override.model) bits.push(splitKnownThinkingSuffix(override.model).baseModel);
+			if (override.fallbackModels !== undefined) bits.push(fallbackLine(override.fallbackModels));
 			if (override.thinking !== undefined) bits.push(`thinking ${override.thinking === false ? "off" : override.thinking}`);
 			return bits.join(" ");
 		}).join("; ")}`
 		: "";
-	return `Children: ${boolLabel(snapshot.config.enabled && children.enabled)} · model ${model} · thinking ${thinking}${overrideText}`;
+	return `Children: ${boolLabel(snapshot.config.enabled && children.enabled)} · model ${model}${fallbackLine(children.fallbackModels)} · 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 +116,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 +125,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 +151,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",
@@ -171,12 +177,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 +197,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,12 +227,7 @@ 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");
 }
 
@@ -258,7 +259,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 +302,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 +320,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 +330,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.",
@@ -387,6 +388,7 @@ 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),
+		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) => {
@@ -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);

package/src/watchdog/review.ts

@@ -3,12 +3,13 @@ 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 { buildModelCandidates, isContextOverflow, isRetryableModelFailureAttempt, resolveModelCandidate } from "../runs/shared/model-fallback.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,
@@ -22,6 +23,8 @@ import {
 
 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" }),
 	summary: Type.String({ description: "One concise sentence naming the issue." }),
@@ -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 } : {}),
@@ -214,7 +224,7 @@ 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.",
@@ -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,126 @@ 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" };
+		const inherited = !request.config.main.model && ctx.model ? fullModelId(ctx.model) : undefined;
+		const candidates = request.config.main.fallbackModels?.length
+			? buildModelCandidates(request.config.main.model ?? inherited, request.config.main.fallbackModels,
+				ctx.modelRegistry.getAvailable().map(toModelInfo), ctx.model?.provider, { primaryModelFromParent: Boolean(inherited) })
+			: [request.config.main.model];
+		for (let index = 0; index < candidates.length; index++) {
+			if (aborted()) return { stopReason: "aborted" };
+			const candidate = candidates[index];
+			const config = { ...request.config, main: { ...request.config.main, model: candidate === inherited ? undefined : candidate } };
+			try {
+				const attempt = await runWatchdogAttempt(ctx, { ...request, config }, options);
+				if (aborted()) return { stopReason: "aborted" };
+				if (!attempt.retryable || index === candidates.length - 1) return attempt.result;
+			} catch (error) {
+				if (aborted()) return { stopReason: "aborted" };
+				if (!(error instanceof WatchdogAuthError)) throw error;
+				if (isContextOverflow(error.message) || !isRetryableModelFailureAttempt({ error: error.message }) || index === candidates.length - 1) throw error.cause ?? error;
+			}
+		}
+		throw new Error("No usable watchdog model candidates.");
+	};
+}
+
+async function runWatchdogAttempt(ctx: ExtensionContext, request: WatchdogReviewRequest, options: CreateMainWatchdogReviewOptions): Promise<{
+	result: Awaited<ReturnType<WatchdogReviewFunction>>;
+	retryable?: boolean;
+}> {
+	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 } : { stopReason },
+		retryable: !clarification && stopReason === "error" && !isContextOverflow(error) && isRetryableModelFailureAttempt({ error, messages: agent.state.messages, toolCount }),
 	};
 }