pi-subagents 0.66.0 → 0.67.0

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 }),
 	};
 }

package/src/watchdog/runtime.ts

@@ -12,7 +12,7 @@ import {
 import { ruleViolationWarning, type WatchdogRuleViolation } from "./rules.ts";
 import { WatchdogScopeArtifact } from "./scope.ts";
 import { resolveWatchdogConfig } from "./settings.ts";
-import { formatWatchdogTurnDelta } from "./turn-delta.ts";
+import { formatWatchdogOrchestrationActivity, formatWatchdogTurnDelta } from "./turn-delta.ts";
 import {
 	type ResolvedWatchdogConfig,
 	type WatchdogEndpointConfig,
@@ -31,6 +31,7 @@ type ReviewStopReason = "stop" | "error" | "aborted" | "length";
 export interface WatchdogReviewResult {
 	warnings?: WatchdogWarning[];
 	stopReason?: ReviewStopReason;
+	clarification?: { question: string; evidence: string };
 }
 
 export interface WatchdogReviewRequest {
@@ -40,6 +41,7 @@ export interface WatchdogReviewRequest {
 	reviewId: number;
 	config: ResolvedWatchdogConfig;
 	emitWarning(warning: WatchdogWarning): boolean;
+	allowClarification?: boolean;
 	signal?: AbortSignal;
 }
 
@@ -81,6 +83,8 @@ interface MainWatchdogRuntimeOptions {
 	review?: WatchdogReviewFunction;
 	reviewDescription?: string;
 	displayWarning?: (warning: WatchdogWarningDetails, options?: WatchdogWarningSendOptions) => void;
+	/** Supplying this main-session delivery capability gates clarification (children omit it). */
+	displayClarification?: (content: string) => void;
 	reviewChangesOnly?: boolean;
 	lspDiagnostics?: WatchdogLspDiagnosticsFunction;
 	repoChangeSignature?: typeof computeWatchdogRepoChangeSignature;
@@ -88,8 +92,8 @@ interface MainWatchdogRuntimeOptions {
 
 export type WatchdogWarningSendOptions = { deliverAs: "steer" } | { triggerTurn: false };
 
-type ContextLike = Pick<ExtensionContext, "cwd">;
-type ReviewDeltaOutcome = "completed" | "timeout" | "stale";
+type ContextLike = Pick<ExtensionContext, "cwd"> & { signal?: AbortSignal };
+type ReviewDeltaOutcome = "completed" | "timeout" | "stale" | NonNullable<WatchdogReviewResult["clarification"]>;
 
 const DEFAULT_REVIEW: WatchdogReviewFunction = () => ({ warnings: [] });
 const MAX_REVIEW_INPUT_CHARS = 24_000;
@@ -170,6 +174,11 @@ export class MainWatchdogRuntime {
 	private activeReviewAbortController: AbortController | undefined;
 	private failedReviews = 0;
 	private staleReviews = 0;
+	private readonly displayClarification: MainWatchdogRuntimeOptions["displayClarification"];
+	private askedThisPrompt = false;
+	private activityTail = "";
+	private activityPending = false;
+	private activityReviewUsed = false;
 
 	constructor(options: MainWatchdogRuntimeOptions = {}) {
 		this.cwd = options.cwd ?? process.cwd();
@@ -178,6 +187,7 @@ export class MainWatchdogRuntime {
 		this.reviewConnected = Boolean(options.review);
 		this.reviewDescription = options.reviewDescription ?? (options.review ? "injected seam" : "not wired");
 		this.displayWarning = options.displayWarning;
+		this.displayClarification = options.displayClarification;
 		this.reviewChangesOnly = options.reviewChangesOnly === true;
 		this.lspDiagnostics = options.lspDiagnostics ?? collectWatchdogLspDiagnostics;
 		this.repoChangeSignature = options.repoChangeSignature ?? computeWatchdogRepoChangeSignature;
@@ -200,6 +210,8 @@ export class MainWatchdogRuntime {
 	refreshConfig(cwd = this.cwd): WatchdogSettingsResult {
 		this.cwd = cwd;
 		const wasEnabled = this.isEnabled();
+		const hadClarification = this.configResult.config.clarification;
+		const previousMain = this.configResult.config.main;
 		const session = this.sessionOverrideEnabled === undefined && this.sessionModelOverride === undefined
 			? undefined
 			: {
@@ -215,6 +227,10 @@ export class MainWatchdogRuntime {
 			this.guard = new WatchdogEmissionGuard({ maxWarnings: this.guardMaxWarnings });
 		}
 		if (wasEnabled && !this.isEnabled()) this.invalidateActiveReview("watchdog disabled");
+		if (!this.isEnabled() || !this.configResult.config.clarification) this.clearActivity();
+		if (this.displayClarification && (hadClarification || this.configResult.config.clarification) && (this.reviewing || this.waitingAtAgentEnd)) {
+			if (!this.configResult.config.clarification || previousMain.model !== this.configResult.config.main.model || previousMain.thinking !== this.configResult.config.main.thinking) this.invalidateActiveReview("clarification configuration changed");
+		}
 		return this.configResult;
 	}
 
@@ -253,6 +269,7 @@ export class MainWatchdogRuntime {
 	}
 
 	reset(_reason = "reset", options: { clearReviewInputSignature?: boolean; resetChangeSignature?: boolean; clearLspLedger?: boolean; clearScope?: boolean } = {}): void {
+		this.activeReviewAbortController?.abort();
 		this.abortActiveAgentEnd();
 		this.epoch++;
 		this.status = "idle";
@@ -273,7 +290,10 @@ export class MainWatchdogRuntime {
 			this.lspLedger.reset();
 			this.lastLspSnapshot = undefined;
 		}
-		if (options.clearScope) this.scope.reset();
+		if (options.clearScope) {
+			this.scope.reset();
+			this.clearActivity();
+		}
 		if (options.clearReviewInputSignature) this.lastReviewInputSignature = undefined;
 		if (options.resetChangeSignature) this.resetRepoChangeBaseline({ reviewed: true });
 		this.guard.reset();
@@ -281,6 +301,8 @@ export class MainWatchdogRuntime {
 	}
 
 	dispose(): void {
+		this.clearActivity();
+		this.activeReviewAbortController?.abort();
 		this.disposed = true;
 		this.abortActiveAgentEnd();
 		this.epoch++;
@@ -305,6 +327,8 @@ export class MainWatchdogRuntime {
 		if (this.disposed) return;
 		const incomingPrompt = promptFromBeforeAgentStart(event);
 		this.reset("before_agent_start");
+		this.askedThisPrompt = false;
+		this.activityReviewUsed = false;
 		this.resetBoundaryRepeats();
 		this.refreshConfig(ctx.cwd);
 		this.userPrompt = incomingPrompt;
@@ -322,6 +346,13 @@ export class MainWatchdogRuntime {
 		this.refreshConfig(ctx.cwd);
 		if (!this.isEnabled()) return;
 		try {
+			if (this.displayClarification && this.configResult.config.clarification && this.boundaryRepeats === 0) {
+				const activity = formatWatchdogOrchestrationActivity(event);
+				if (activity) {
+					this.activityTail = [this.activityTail, boundWatchdogReviewText(activity, 3_000)].filter(Boolean).join(REVIEW_DELTA_SEPARATOR).slice(-6_000);
+					this.activityPending = true;
+				}
+			}
 			this.observedRepoEditThisTurn ||= eventIndicatesRepoEdit(event);
 			const delta = formatWatchdogTurnDelta({
 				includeUserPrompt: this.includeUserPromptInNextDelta,
@@ -359,20 +390,19 @@ export class MainWatchdogRuntime {
 		if (this.disposed) return;
 		this.refreshConfig(ctx.cwd);
 		if (!this.isEnabled()) return;
-		const changeSignature = this.resolveReviewChangeSignature(ctx.cwd);
-		if (this.reviewChangesOnly && !changeSignature) {
-			this.clearPendingDeltas();
-			if (this.status === "queued") this.status = "idle";
-			this.resolveWaiters(true);
-			return;
-		}
-		if (changeSignature && changeSignature.key === this.lastReviewedChangeSignature) {
+		if (ctx.signal?.aborted) return;
+		const changeSignature = this.resolveReviewChangeSignature(this.currentRepoChangeSignature(ctx.cwd), ctx.cwd);
+		const activityReview = Boolean(this.displayClarification && this.configResult.config.clarification && !this.activityReviewUsed && this.boundaryRepeats === 0 && this.activityPending);
+		const knownEvidence = changeSignature && changeSignature.key === this.lastReviewedChangeSignature;
+		if (!activityReview && (knownEvidence || (this.reviewChangesOnly && !changeSignature))) {
 			this.clearPendingDeltas();
-			this.status = "idle";
+			if (knownEvidence || this.status === "queued") this.status = "idle";
 			this.resolveWaiters(true);
 			return;
 		}
 		this.cancelMidRunReview();
+		if (activityReview && (!changeSignature || knownEvidence)) this.activityReviewUsed = true;
+		this.activityPending = false;
 		this.waitingAtAgentEnd = true;
 		const agentEndEpoch = this.epoch;
 		const agentEndId = ++this.agentEndIdCounter;
@@ -403,7 +433,8 @@ export class MainWatchdogRuntime {
 				this.resolveWaiters(true);
 				return;
 			}
-			const outcome = await this.reviewDelta(delta, this.configResult.config.agentEndTimeoutMs);
+			const outcome = await this.reviewDelta(delta, this.configResult.config.agentEndTimeoutMs, { allowClarification: true });
+			if (!this.isAgentEndCurrent(agentEndEpoch, agentEndId)) return;
 			this.waitingAtAgentEnd = false;
 			if (outcome === "timeout") {
 				this.staleReviews++;
@@ -413,11 +444,16 @@ export class MainWatchdogRuntime {
 				this.resolveWaiters(true);
 				return;
 			}
-			if (outcome === "completed" && this.status !== "failed" && this.status !== "stale") {
+			if ((outcome === "completed" || typeof outcome === "object") && this.status !== "failed" && this.status !== "stale") {
+				// A question consumes this evidence just like a completed review, not a pending exchange.
 				this.lastReviewInputSignature = signature;
 				if (changeSignature) this.lastReviewedChangeSignature = changeSignature.key;
 				this.currentChangedPaths = changeSignature?.changedPaths;
 				this.status = "idle";
+				if (typeof outcome === "object" && !ctx.signal?.aborted) this.displayClarification?.([
+					"Main watchdog clarification:", outcome.question, `Evidence: ${outcome.evidence}`,
+					"Consider this missing context as you continue the task. This is not approval, permission, or a warning. The reviewer has yielded; no reply or follow-up review is required.",
+				].join("\n"));
 			}
 			this.resolveWaiters(true);
 		} finally {
@@ -468,6 +504,15 @@ export class MainWatchdogRuntime {
 		};
 	}
 
+	/** A real mid-stream user input can steer without emitting before_agent_start. */
+	handleUserInput(): void {
+		if (this.displayClarification && this.configResult.config.clarification && (this.reviewing || this.waitingAtAgentEnd)) this.reset("new user input");
+	}
+
+	handleModelChange(): void {
+		if (this.displayClarification && this.configResult.config.clarification && (this.reviewing || this.waitingAtAgentEnd)) this.reset("model changed");
+	}
+
 	async waitForIdle(timeoutMs = 1_000): Promise<boolean> {
 		return this.waitForSettled(timeoutMs);
 	}
@@ -523,6 +568,7 @@ export class MainWatchdogRuntime {
 	}
 
 	private invalidateActiveReview(_reason: string): void {
+		this.activeReviewAbortController?.abort();
 		this.abortActiveAgentEnd();
 		this.epoch++;
 		this.status = "idle";
@@ -567,7 +613,7 @@ export class MainWatchdogRuntime {
 		this.activeReviewWarning = undefined;
 	}
 
-	private async reviewDelta(delta: string, timeoutMs: number, options: { correction?: boolean } = {}): Promise<ReviewDeltaOutcome> {
+	private async reviewDelta(delta: string, timeoutMs: number, options: { correction?: boolean; allowClarification?: boolean } = {}): Promise<ReviewDeltaOutcome> {
 		if (this.reviewing || this.disposed) return "stale";
 		this.reviewing = true;
 		const reviewEpoch = this.epoch;
@@ -578,6 +624,7 @@ export class MainWatchdogRuntime {
 		let timeout: ReturnType<typeof setTimeout> | undefined;
 		const abortController = new AbortController();
 		this.activeReviewAbortController = abortController;
+		const allowClarification = Boolean(options.allowClarification && this.displayClarification && this.configResult.config.clarification && !this.askedThisPrompt && !this.stalemate);
 		const reviewPromise = Promise.resolve().then(() => this.review({
 			delta,
 			epoch: reviewEpoch,
@@ -586,6 +633,7 @@ export class MainWatchdogRuntime {
 			hasScope: this.scopeBlock().trim().length > 0,
 			signal: abortController.signal,
 			emitWarning: (warning) => this.acceptWarning(reviewEpoch, reviewId, warning),
+			...(allowClarification ? { allowClarification: true } : {}),
 		}));
 		try {
 			const result = await Promise.race([
@@ -600,6 +648,14 @@ export class MainWatchdogRuntime {
 			}
 			if (!this.isCurrent(reviewEpoch, reviewId)) return "stale";
 			if (!result) return "stale";
+			if (allowClarification && this.configResult.config.clarification && result.clarification && (!result.stopReason || result.stopReason === "stop") && !this.activeReviewWarning && !result.warnings?.length && !abortController.signal.aborted) {
+				const question = result.clarification.question.trim();
+				const evidence = result.clarification.evidence.trim();
+				if (question && evidence) {
+					this.askedThisPrompt = true;
+					return { question: boundWatchdogReviewText(question, 1_000), evidence: boundWatchdogReviewText(evidence, 2_000) };
+				}
+			}
 			for (const warning of result.warnings ?? []) this.acceptWarning(reviewEpoch, reviewId, warning);
 			if (result.stopReason && result.stopReason !== "stop") {
 				this.fail(`Watchdog review ended with stop reason '${result.stopReason}'.`);
@@ -681,9 +737,8 @@ export class MainWatchdogRuntime {
 		this.observedRepoEditThisTurn = false;
 	}
 
-	private resolveReviewChangeSignature(cwd = this.cwd): WatchdogRepoChangeSignature | undefined {
+	private resolveReviewChangeSignature(current: WatchdogRepoChangeSignature | undefined, cwd: string): WatchdogRepoChangeSignature | undefined {
 		if (!this.reviewChangesOnly) return undefined;
-		const current = this.currentRepoChangeSignature(cwd);
 		if (current) {
 			this.currentChangedPaths = current.changedPaths;
 			if (current.key === this.turnStartChangeSignature?.key) return undefined;
@@ -785,13 +840,14 @@ export class MainWatchdogRuntime {
 		const changes = changeSignature?.changedPaths.length
 			? ["Changed repo paths:", ...changeSignature.changedPaths.slice(0, 200).map((file) => `- ${file}`)].join("\n")
 			: "";
-		const contextPieces = [scopeBlock, changes, lspBlock].filter(Boolean);
+		const activity = this.activityTail ? `Recent delivered orchestration activity (oldest first; bounded observations, not a task board; waits/holds are not evidence of neglect):\n${this.activityTail}` : "";
+		const contextPieces = [scopeBlock, changes, lspBlock, activity].filter(Boolean);
 		if (!contextPieces.length) return boundWatchdogReviewText(input);
 
 		const maxContextLength = Math.floor(MAX_REVIEW_INPUT_CHARS / 2);
 		const maxPieceLength = Math.max(1_000, Math.floor(maxContextLength / contextPieces.length));
 		const boundedContext = contextPieces.map((piece) => piece.length > maxPieceLength
-			? `${piece.slice(0, maxPieceLength - 6)}\n- ...`
+			? piece === activity ? boundWatchdogReviewText(piece, maxPieceLength) : `${piece.slice(0, maxPieceLength - 6)}\n- ...`
 			: piece).join(REVIEW_DELTA_SEPARATOR);
 		const separatorLength = input ? REVIEW_DELTA_SEPARATOR.length : 0;
 		const inputBudget = MAX_REVIEW_INPUT_CHARS - boundedContext.length - separatorLength;
@@ -808,6 +864,12 @@ export class MainWatchdogRuntime {
 		this.pendingDeltaChars = 0;
 	}
 
+	private clearActivity(): void {
+		if (!this.activityTail) return;
+		this.activityTail = "";
+		this.activityPending = false;
+	}
+
 	private fail(message: string): void {
 		this.failedReviews++;
 		this.lastError = message;

package/src/watchdog/scope.ts

@@ -32,7 +32,7 @@ export class WatchdogScopeArtifact {
 		if (!this.entries.length) return "";
 		return [
 			"Current scope:",
-			"The following real user prompts are the current scope record, newest last. Newer prompts supersede and mutate older prompts: they may add, modify, or remove requirements. Flag work that serves no current scope item as category 'scope-drift'.",
+			"The following real user prompts are the current scope record, newest last. Side questions are additive, not scope drift or cancellation of older objectives; only explicit changes supersede requirements. Use watchdog_warn for evidence-backed reminders of forgotten authorized work, not dependencies still pending or explicit holds. The orchestrator owns task tracking. Flag unauthorized work as category 'scope-drift'.",
 			...this.entries.map((entry, index) => [
 				`Scope prompt ${index + 1} (${entry.createdAt}):`,
 				entry.prompt,

package/src/watchdog/settings.ts

@@ -61,6 +61,7 @@ interface ParseMeta {
 
 export const DEFAULT_WATCHDOG_CONFIG: ResolvedWatchdogConfig = {
 	enabled: false,
+	clarification: false,
 	agentEndTimeoutMs: 30_000,
 	severityThreshold: "concern",
 	maxWarnings: null,
@@ -92,6 +93,7 @@ export const DEFAULT_WATCHDOG_CONFIG: ResolvedWatchdogConfig = {
 
 const WATCHDOG_FIELDS = new Set([
 	"enabled",
+	"clarification",
 	"agentEndTimeoutMs",
 	"severityThreshold",
 	"maxWarnings",
@@ -109,9 +111,9 @@ const ROLE_MODEL_RULE_FIELDS = new Set(["allow", "deny", "note"]);
 const GUIDANCE_FIELDS = new Set(["watchdogMd"]);
 const SCOPE_FIELDS = new Set(["enabled"]);
 const CADENCE_FIELDS = new Set(["everyNTools"]);
-const ENDPOINT_FIELDS = new Set(["enabled", "model", "thinking"]);
-const CHILDREN_FIELDS = new Set(["enabled", "model", "thinking", "watchdogTailTimeoutMs", "cadence", "overrides"]);
-const CHILD_OVERRIDE_FIELDS = new Set(["enabled", "model", "thinking", "cadence"]);
+const ENDPOINT_FIELDS = new Set(["enabled", "model", "fallbackModels", "thinking"]);
+const CHILDREN_FIELDS = new Set(["enabled", "model", "fallbackModels", "thinking", "watchdogTailTimeoutMs", "cadence", "overrides"]);
+const CHILD_OVERRIDE_FIELDS = new Set(["enabled", "model", "fallbackModels", "thinking", "cadence"]);
 const LSP_FIELDS = new Set(["enabled", "timeoutMs", "maxFiles", "maxDiagnostics"]);
 
 function cloneDefaultConfig(): ResolvedWatchdogConfig {
@@ -219,6 +221,7 @@ function parseEndpointPatch(value: unknown, field: string, meta: ParseMeta): Wat
 	const input = parseObject(value, field, meta);
 	assertKnownFields(input, ENDPOINT_FIELDS, field, meta);
 	const patch: WatchdogEndpointPatch = {};
+	if ("fallbackModels" in input) patch.fallbackModels = parseStringList(input.fallbackModels, `${field}.fallbackModels`, meta);
 	if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
 	if ("model" in input) patch.model = parseNonEmptyString(input.model, `${field}.model`, meta);
 	if ("thinking" in input) patch.thinking = parseThinking(input.thinking, `${field}.thinking`, meta);
@@ -229,6 +232,7 @@ function parseChildOverridePatch(value: unknown, field: string, meta: ParseMeta)
 	const input = parseObject(value, field, meta);
 	assertKnownFields(input, CHILD_OVERRIDE_FIELDS, field, meta);
 	const patch: WatchdogChildOverridePatch = {};
+	if ("fallbackModels" in input) patch.fallbackModels = parseStringList(input.fallbackModels, `${field}.fallbackModels`, meta);
 	if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
 	if ("model" in input) patch.model = parseNonEmptyString(input.model, `${field}.model`, meta);
 	if ("thinking" in input) patch.thinking = parseThinking(input.thinking, `${field}.thinking`, meta);
@@ -240,6 +244,7 @@ function parseChildrenPatch(value: unknown, field: string, meta: ParseMeta): Wat
 	const input = parseObject(value, field, meta);
 	assertKnownFields(input, CHILDREN_FIELDS, field, meta);
 	const patch: WatchdogChildrenPatch = {};
+	if ("fallbackModels" in input) patch.fallbackModels = parseStringList(input.fallbackModels, `${field}.fallbackModels`, meta);
 	if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
 	if ("model" in input) patch.model = parseNonEmptyString(input.model, `${field}.model`, meta);
 	if ("thinking" in input) patch.thinking = parseThinking(input.thinking, `${field}.thinking`, meta);
@@ -303,6 +308,7 @@ function parseWatchdogPatch(value: unknown, field: string, meta: ParseMeta): Wat
 	assertKnownFields(input, WATCHDOG_FIELDS, field, meta);
 	const patch: WatchdogConfigPatch = {};
 	if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
+	if ("clarification" in input) patch.clarification = parseBoolean(input.clarification, `${field}.clarification`, meta);
 	if ("agentEndTimeoutMs" in input) {
 		patch.agentEndTimeoutMs = parseInteger(input.agentEndTimeoutMs, `${field}.agentEndTimeoutMs`, meta, "a positive integer", (candidate) => candidate >= 1);
 	}