pi-subagents 0.63.0 → 0.64.0

package/src/watchdog/register-child.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { captureWatchdogDiffBaseline, type WatchdogDiffBaseline } from "./diff-tool.ts";
 import { MainWatchdogRuntime } from "./runtime.ts";
 import { createMainWatchdogReview } from "./review.ts";
 import { DEFAULT_WATCHDOG_CONFIG } from "./settings.ts";
@@ -23,11 +24,8 @@ export function childResolvedConfig(config: ChildWatchdogConfig): ResolvedWatchd
 			...(config.model ? { model: config.model } : {}),
 			...(config.thinking !== undefined ? { thinking: config.thinking } : {}),
 		},
-		autoFollow: {
-			blockers: config.autoFollowBlockers,
-			maxAttempts: config.autoFollowMaxAttempts,
-			stalemateRepeats: config.stalemateRepeats,
-		},
+		stalemateRepeats: config.stalemateRepeats,
+		cadence: { ...config.cadence },
 		children: {
 			...DEFAULT_WATCHDOG_CONFIG.children,
 			watchdogTailTimeoutMs: config.watchdogTailTimeoutMs,
@@ -55,10 +53,11 @@ function writeStatus(event: unknown): void {
 
 export function registerChildWatchdog(pi: ExtensionAPI, rawConfig = process.env[CHILD_WATCHDOG_CONFIG_ENV]): MainWatchdogRuntime | undefined {
 	const childConfig = decodeChildWatchdogConfig(rawConfig);
-	if (!childConfig?.enabled) return undefined;
+	if (!childConfig) return undefined;
 	let currentContext: ExtensionContext | undefined;
+	let diffBaseline: WatchdogDiffBaseline | undefined;
 	let seq = 0;
-	const emitStatus = (phase: ChildWatchdogPhase, followUpPending = false, reason?: string): void => {
+	const emitStatus = (phase: ChildWatchdogPhase, reason?: string): void => {
 		writeStatus({
 			type: CHILD_WATCHDOG_STATUS_EVENT,
 			...(childConfig.runId ? { runId: childConfig.runId } : {}),
@@ -67,19 +66,18 @@ export function registerChildWatchdog(pi: ExtensionAPI, rawConfig = process.env[
 			seq: ++seq,
 			phase,
 			ts: Date.now(),
-			followUpPending,
 			...(reason ? { reason } : {}),
 		});
 	};
 	const resolved = childResolvedConfig(childConfig);
 	const runtime = new MainWatchdogRuntime({
 		resolveConfig: () => ({ ok: true, config: resolved, errors: [], sources: [{ scope: "session", exists: true }] }),
-		review: createMainWatchdogReview(() => currentContext, { getThinkingLevel: () => pi.getThinkingLevel() }),
+		review: createMainWatchdogReview(() => currentContext, { getThinkingLevel: () => pi.getThinkingLevel(), diffBaseline: () => diffBaseline }),
 		reviewDescription: "child model review",
 		reviewChangesOnly: true,
-		displayWarning: (details) => {
+		displayWarning: (details, options) => {
 			const childDetails = childWarningDetails(details, childConfig);
-			pi.sendMessage(createWatchdogWarningMessage(childDetails, { display: true, details: childDetails }));
+			pi.sendMessage(createWatchdogWarningMessage(childDetails, { display: true, details: childDetails }), options);
 		},
 	});
 	const rememberContext = (ctx: ExtensionContext) => {
@@ -88,6 +86,7 @@ export function registerChildWatchdog(pi: ExtensionAPI, rawConfig = process.env[
 	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown, ctx: ExtensionContext) => unknown) => void;
 	onRuntimeEvent("session_start", (_event, ctx) => {
 		rememberContext(ctx);
+		diffBaseline = captureWatchdogDiffBaseline(ctx.cwd);
 		runtime.bindSession(ctx);
 		emitStatus("idle");
 	});
@@ -99,13 +98,17 @@ export function registerChildWatchdog(pi: ExtensionAPI, rawConfig = process.env[
 		rememberContext(ctx);
 		runtime.handleTurnEnd(event, ctx);
 	});
+	onRuntimeEvent("tool_result", (_event, ctx) => {
+		rememberContext(ctx);
+		runtime.handleToolResult(ctx);
+	});
 	onRuntimeEvent("agent_end", async (event, ctx) => {
 		rememberContext(ctx);
 		emitStatus("reviewing");
 		await runtime.handleAgentEnd(event, ctx);
 		const snapshot = runtime.getSnapshot(ctx.cwd);
-		if (snapshot.status === "failed") emitStatus("failed", false, snapshot.lastError);
-		else if (snapshot.status === "stale") emitStatus("stale", false, "review stale");
+		if (snapshot.status === "failed") emitStatus("failed", snapshot.lastError);
+		else if (snapshot.status === "stale") emitStatus("stale", "review stale");
 		else emitStatus("idle");
 	});
 	onRuntimeEvent("session_shutdown", () => {

package/src/watchdog/register-main.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@e
 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 { renderWatchdogWarning } from "./render.ts";
 import { createMainWatchdogReview } from "./review.ts";
@@ -120,7 +121,8 @@ export function buildWatchdogStatus(snapshot: ReturnType<MainWatchdogRuntime["ge
 		childrenLine(snapshot),
 		recommendationLine(ctx),
 		`Agent-end timeout: ${snapshot.config.agentEndTimeoutMs}ms`,
-		`Auto-follow: ${snapshot.enabled && snapshot.config.autoFollow.blockers ? "on for blockers" : "off"} · attempts ${snapshot.autoFollowAttempts}${snapshot.config.autoFollow.maxAttempts === null ? "" : `/${snapshot.config.autoFollow.maxAttempts}`}${snapshot.autoFollowQueued ? " · queued" : ""}${snapshot.autoFollowStalemate ? " · stalemate" : ""}`,
+		`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"}`,
 		`Review model call: ${snapshot.reviewDescription}`,
 	];
 	if (snapshot.failedReviews > 0) lines.push(`Failed reviews: ${snapshot.failedReviews}`);
@@ -238,7 +240,7 @@ function createTestWarning(severity: "concern" | "blocker", text: string): Watch
 		summary: text,
 		evidence: `Manual /subagents-watchdog test ${severity} message from the main session.`,
 		recommendedAction: severity === "blocker"
-			? "Verify the renderer, transcript delivery, and auto-follow policy."
+			? "Verify the renderer and transcript delivery."
 			: "Verify the renderer and transcript delivery; decide manually whether any action is needed.",
 	};
 }
@@ -376,17 +378,15 @@ async function handleWatchdogCommand(
 
 export function registerMainWatchdog(pi: ExtensionAPI, options: RegisterMainWatchdogOptions = {}): MainWatchdogRuntime {
 	let currentContext: ExtensionContext | undefined;
+	let diffBaseline: WatchdogDiffBaseline | undefined;
 	const rememberContext = (ctx: ExtensionContext) => {
 		currentContext = ctx;
 	};
 	const runtime = options.runtime ?? new MainWatchdogRuntime({
-		review: options.review ?? createMainWatchdogReview(() => currentContext, { getThinkingLevel: () => pi.getThinkingLevel() }),
+		review: options.review ?? createMainWatchdogReview(() => currentContext, { getThinkingLevel: () => pi.getThinkingLevel(), diffBaseline: () => diffBaseline }),
 		reviewDescription: options.review ? "injected seam" : "real model review",
 		reviewChangesOnly: true,
-		displayWarning: (details, delivery) => {
-			pi.sendMessage(createWatchdogWarningMessage(details, { display: true, details }), delivery?.deliverAs === "steer" ? { deliverAs: "steer" } : undefined);
-		},
-		sendUserMessage: (message) => pi.sendUserMessage(message),
+		displayWarning: (details, options) => pi.sendMessage(createWatchdogWarningMessage(details, { display: true, details }), options),
 	});
 
 	pi.registerMessageRenderer<WatchdogWarningDetails>(SUBAGENT_WATCHDOG_WARNING_TYPE, (message, renderOptions, theme) => {
@@ -410,6 +410,7 @@ export function registerMainWatchdog(pi: ExtensionAPI, options: RegisterMainWatc
 
 	pi.on("session_start", (_event, ctx) => {
 		rememberContext(ctx);
+		diffBaseline = captureWatchdogDiffBaseline(ctx.cwd);
 		runtime.bindSession(ctx);
 	});
 	pi.on("before_agent_start", (event, ctx) => {
@@ -428,8 +429,8 @@ export function registerMainWatchdog(pi: ExtensionAPI, options: RegisterMainWatc
 		rememberContext(ctx);
 		return runtime.handleAgentEnd(event, ctx);
 	});
-	pi.on("session_before_switch", () => runtime.reset("session switch", { clearReviewInputSignature: true, clearLspLedger: true, clearScope: true, resetAutoFollow: true }));
-	pi.on("session_before_fork", () => runtime.reset("session fork", { clearReviewInputSignature: true, clearLspLedger: true, clearScope: true, resetAutoFollow: true }));
+	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_shutdown", () => {
 		currentContext = undefined;

package/src/watchdog/render.ts

@@ -13,10 +13,9 @@ function titleCase(value: string): string {
 function stateLabels(warning: WatchdogWarningDetails): string[] {
 	const labels: string[] = [];
 	if (warning.state === "displayed") labels.push("displayed");
-	if (warning.stale || warning.state === "stale") labels.push("stale · no auto-follow");
+	if (warning.stale || warning.state === "stale") labels.push("stale");
 	if (warning.state === "failed") labels.push("failed review");
-	if (warning.state === "stalemate") labels.push("stalemate · auto-follow stopped");
-	if (warning.autoFollowAttempt !== undefined) labels.push(`auto-follow attempt ${warning.autoFollowAttempt}`);
+	if (warning.state === "stalemate") labels.push("stalemate");
 	return labels;
 }
 
@@ -31,9 +30,9 @@ export function formatWatchdogWarningRenderText(warning: WatchdogWarningDetails)
 	];
 	if (warning.state === "failed" && warning.error) lines.push(`Failure: ${warning.error}`);
 	if (warning.state === "stalemate" && warning.stalemateRepeats !== undefined) {
-		lines.push(`Auto-follow stopped after ${warning.stalemateRepeats} repeated blocker warning${warning.stalemateRepeats === 1 ? "" : "s"}.`);
+		lines.push(`Same warning ${warning.stalemateRepeats} time${warning.stalemateRepeats === 1 ? "" : "s"} in a row; the watchdog stopped continuing the run.`);
 	}
-	if (warning.stale || warning.state === "stale") lines.push("This warning arrived after the watchdog catch-up timeout and must not auto-follow.");
+	if (warning.stale || warning.state === "stale") lines.push("This warning arrived after the watchdog catch-up timeout.");
 	return lines.join("\n");
 }
 

package/src/watchdog/review.ts

@@ -6,6 +6,8 @@ import { Type, type Static } from "typebox";
 import { resolveModelCandidate } from "../runs/shared/model-fallback.ts";
 import { agentStreamOptions } from "../shared/agent-stream-options.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 {
 	WATCHDOG_WARNING_CATEGORIES,
@@ -18,7 +20,7 @@ import {
 	type WatchdogWarning,
 } from "./types.ts";
 
-const WATCHDOG_ALLOWED_TOOL_NAMES = new Set(["read", "grep", "find", "ls", "watchdog_warn"]);
+const WATCHDOG_ALLOWED_TOOL_NAMES = new Set(["read", "grep", "find", "ls", "watchdog_warn", WATCHDOG_DIFF_TOOL_NAME]);
 
 const WatchdogWarnParams = Type.Object({
 	severity: Type.String({ enum: WATCHDOG_WARNING_SEVERITIES, description: "concern for actionable risk, blocker for a likely wrong or unsafe outcome" }),
@@ -52,6 +54,7 @@ export interface CreateMainWatchdogReviewOptions {
 	streamFn?: StreamFn;
 	createReadOnlyTools?: (cwd: string) => AgentTool[];
 	getThinkingLevel?: () => ThinkingLevel | undefined;
+	diffBaseline?: () => WatchdogDiffBaseline | undefined;
 }
 
 function fullModelId(model: Pick<RegistryModel, "provider" | "id">): string {
@@ -205,18 +208,20 @@ function createWatchdogWarnTool(request: WatchdogReviewRequest): AgentTool<typeo
 	};
 }
 
-function buildWatchdogSystemPrompt(ctx: ExtensionContext, options: { hasScope?: boolean } = {}): string {
+export function buildWatchdogSystemPrompt(ctx: Pick<ExtensionContext, "cwd">, options: { hasScope?: boolean; guidance?: string; hasDiff?: boolean } = {}): string {
+	const guidance = options.guidance?.trim();
 	return [
 		"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,
-		"You are read-only. You may use read, grep, find, and ls. Do not edit files, run shell commands, spawn agents, or mutate state.",
+		`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.",
 		"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,
 	].filter((line): line is string => Boolean(line)).join("\n");
 }
 
@@ -269,13 +274,19 @@ export function createMainWatchdogReview(provider: WatchdogContextProvider, opti
 			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 }),
+				systemPrompt: buildWatchdogSystemPrompt(ctx, {
+					hasScope: request.hasScope,
+					guidance: loadWatchdogGuidance(ctx.cwd, request.config.guidance.watchdogMd),
+					hasDiff: diffBaseline !== undefined,
+				}),
 				model: selection.model,
 				thinkingLevel: selection.thinkingLevel,
 				tools,

package/src/watchdog/rules.ts

@@ -0,0 +1,70 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { splitKnownThinkingSuffix } from "../shared/model-info.ts";
+import { resolveWatchdogConfig } from "./settings.ts";
+import type { WatchdogRulesConfig, WatchdogWarning } from "./types.ts";
+import { createWatchdogWarningMessage } from "./warning-format.ts";
+
+export interface WatchdogRuleViolation {
+	agent: string;
+	summary: string;
+	evidence: string;
+	recommendedAction: string;
+}
+
+function loadWatchdogLaunchRules(cwd: string): WatchdogRulesConfig | undefined {
+	const result = resolveWatchdogConfig(cwd);
+	return result.ok ? result.config.rules : undefined;
+}
+
+/** `*` matches any run of characters, `?` one character; anchored, case-sensitive. */
+export function watchdogGlobMatch(pattern: string, value: string): boolean {
+	const source = pattern.split("").map((char) => char === "*" ? ".*" : char === "?" ? "." : char.replace(/[.+^${}()|[\]\\]/g, "\\$&")).join("");
+	return new RegExp(`^${source}$`).test(value);
+}
+
+function modelMatches(patterns: string[], model: string): string | undefined {
+	const base = splitKnownThinkingSuffix(model).baseModel;
+	return patterns.find((pattern) => watchdogGlobMatch(pattern, model) || watchdogGlobMatch(pattern, base));
+}
+
+/** Deny wins over allow; an unknown model cannot be judged. */
+export function evaluateLaunchRule(rules: WatchdogRulesConfig | undefined, agent: string, model: string | undefined): WatchdogRuleViolation | undefined {
+	const roleRule = rules?.roleModels[agent];
+	if (!roleRule || !model) return undefined;
+	const note = roleRule.note ? ` ${roleRule.note}` : "";
+	const denied = roleRule.deny?.length ? modelMatches(roleRule.deny, model) : undefined;
+	if (denied !== undefined) {
+		return {
+			agent,
+			summary: `Agent '${agent}' was launched with denied model '${model}'.`,
+			evidence: `subagents.watchdog.rules.roleModels.${agent}.deny matches '${denied}'.${note}`,
+			recommendedAction: roleRule.allow?.length ? `Use one of: ${roleRule.allow.join(", ")}.` : "Choose a different model for this role.",
+		};
+	}
+	if (!roleRule.allow?.length || modelMatches(roleRule.allow, model) !== undefined) return undefined;
+	return {
+		agent,
+		summary: `Agent '${agent}' was launched with model '${model}', which is not in its allowed list.`,
+		evidence: `subagents.watchdog.rules.roleModels.${agent}.allow is [${roleRule.allow.join(", ")}].${note}`,
+		recommendedAction: `Use one of: ${roleRule.allow.join(", ")}.`,
+	};
+}
+
+export function ruleViolationWarning(violation: WatchdogRuleViolation): WatchdogWarning {
+	return { severity: "concern", category: "missed-constraint", confidence: "high", source: "main", ...violation };
+}
+
+export function applyWatchdogLaunchRules(input: { cwd: string; agent: string; model?: string; warn?: (violation: WatchdogRuleViolation) => void }): string | undefined {
+	const rules = loadWatchdogLaunchRules(input.cwd);
+	const violation = evaluateLaunchRule(rules, input.agent, input.model);
+	if (!violation) return undefined;
+	if (rules?.action === "block") return `Launch blocked by subagents.watchdog.rules: ${violation.summary}`;
+	input.warn?.(violation);
+	return undefined;
+}
+
+/** For launch paths without a main watchdog runtime (background chain steps). */
+export function sendRuleViolationWarning(pi: Pick<ExtensionAPI, "sendMessage">, violation: WatchdogRuleViolation): void {
+	const warning = ruleViolationWarning(violation);
+	pi.sendMessage(createWatchdogWarningMessage(warning, { display: true, details: { state: "displayed", displayedAt: new Date().toISOString() } }), { deliverAs: "steer" });
+}