pi-subagents 0.63.0 → 0.65.0

package/src/watchdog/child-status.ts

@@ -1,13 +1,14 @@
-import type { ResolvedWatchdogConfig, WatchdogLspConfig } from "./types.ts";
+import type { ChildWatchdogProgress, ChildWatchdogWarningSummary } from "../shared/types.ts";
+import { SUBAGENT_WATCHDOG_WARNING_TYPE, type ResolvedWatchdogConfig, type WatchdogCadenceConfig, type WatchdogCategory, type WatchdogLspConfig } from "./types.ts";
+
+export const CHILD_WATCHDOG_WARNING_LIMIT = 20;
 
-export const CHILD_WATCHDOG_CONFIG_ENV = "PI_SUBAGENT_WATCHDOG_CHILD_CONFIG";
 export const CHILD_WATCHDOG_STATUS_EVENT = "subagent.watchdog.status";
 
-export const CHILD_WATCHDOG_PHASES = ["idle", "reviewing", "autofollow", "settling", "stale", "failed"] as const;
+export const CHILD_WATCHDOG_PHASES = ["idle", "reviewing", "stale", "failed"] as const;
 export type ChildWatchdogPhase = typeof CHILD_WATCHDOG_PHASES[number];
 
 export interface ChildWatchdogConfig {
-	enabled: boolean;
 	runId?: string;
 	agent?: string;
 	childIndex?: number;
@@ -17,9 +18,9 @@ export interface ChildWatchdogConfig {
 	model?: string;
 	thinking?: string | false;
 	lsp: WatchdogLspConfig;
-	autoFollowBlockers: boolean;
-	autoFollowMaxAttempts: number | null;
 	stalemateRepeats: number;
+	/** Mid-run review cadence; everyNTools null means boundary reviews only. */
+	cadence: WatchdogCadenceConfig;
 }
 
 export interface ChildWatchdogStatusEvent {
@@ -31,18 +32,10 @@ export interface ChildWatchdogStatusEvent {
 	seq: number;
 	phase: ChildWatchdogPhase;
 	ts: number;
-	followUpPending: boolean;
 	reason?: string;
 }
 
-export interface ChildWatchdogStateSnapshot {
-	phase: ChildWatchdogPhase;
-	seq: number;
-	lastUpdate: number;
-	followUpPending: boolean;
-	reason?: string;
-	timedOut?: boolean;
-}
+export type ChildWatchdogStateSnapshot = ChildWatchdogProgress;
 
 export function resolveChildWatchdogConfig(input: {
 	config: ResolvedWatchdogConfig;
@@ -55,8 +48,8 @@ export function resolveChildWatchdogConfig(input: {
 	if (!enabled) return undefined;
 	const model = override?.model ?? input.config.children.model;
 	const thinking = override?.thinking ?? input.config.children.thinking;
+	const cadence = override?.cadence ?? input.config.children.cadence ?? input.config.cadence;
 	return {
-		enabled: true,
 		...(input.runId ? { runId: input.runId } : {}),
 		...(input.agent ? { agent: input.agent } : {}),
 		...(input.childIndex !== undefined ? { childIndex: input.childIndex } : {}),
@@ -66,16 +59,11 @@ export function resolveChildWatchdogConfig(input: {
 		...(model ? { model } : {}),
 		...(thinking !== undefined ? { thinking } : {}),
 		lsp: { ...input.config.lsp },
-		autoFollowBlockers: input.config.children.autoFollow.blockers,
-		autoFollowMaxAttempts: input.config.children.autoFollow.maxAttempts,
-		stalemateRepeats: input.config.children.autoFollow.stalemateRepeats,
+		stalemateRepeats: input.config.stalemateRepeats,
+		cadence: { everyNTools: cadence.everyNTools ?? null },
 	};
 }
 
-export function encodeChildWatchdogConfig(config: ChildWatchdogConfig | undefined): string | undefined {
-	return config ? JSON.stringify(config) : undefined;
-}
-
 function childConfigObject(value: unknown, field: string): Record<string, unknown> {
 	if (value && typeof value === "object" && !Array.isArray(value)) return value as Record<string, unknown>;
 	throw new Error(`Invalid child watchdog config: ${field} must be an object.`);
@@ -108,10 +96,12 @@ function childConfigNullableNonNegativeInteger(input: Record<string, unknown>, f
 	throw new Error(`Invalid child watchdog config: ${field} must be null or a non-negative integer.`);
 }
 
-function childConfigBoolean(input: Record<string, unknown>, field: string): boolean {
-	const value = input[field];
-	if (typeof value === "boolean") return value;
-	throw new Error(`Invalid child watchdog config: ${field} must be a boolean.`);
+function childConfigCadence(value: unknown): WatchdogCadenceConfig {
+	const input = childConfigObject(value, "cadence");
+	const everyNTools = input.everyNTools;
+	if (everyNTools === null) return { everyNTools: null };
+	if (typeof everyNTools === "number" && Number.isInteger(everyNTools) && everyNTools >= 5) return { everyNTools };
+	throw new Error("Invalid child watchdog config: cadence.everyNTools must be null or an integer >= 5.");
 }
 
 function childConfigLsp(value: unknown): WatchdogLspConfig {
@@ -138,7 +128,7 @@ export function decodeChildWatchdogConfig(raw: string | undefined): ChildWatchdo
 	if (!raw) return undefined;
 	const parsed = childConfigObject(JSON.parse(raw), "root");
 	if (parsed.enabled === false) return undefined;
-	if (parsed.enabled !== true) throw new Error("Invalid child watchdog config: enabled must be true or false.");
+	if ("enabled" in parsed && parsed.enabled !== true) throw new Error("Invalid child watchdog config: enabled must be true or false.");
 	const thinking = parsed.thinking;
 	if (thinking !== undefined && typeof thinking !== "string" && thinking !== false) {
 		throw new Error("Invalid child watchdog config: thinking must be a string or false.");
@@ -148,7 +138,6 @@ export function decodeChildWatchdogConfig(raw: string | undefined): ChildWatchdo
 	const childIndex = childConfigOptionalIndex(parsed, "childIndex");
 	const model = childConfigOptionalString(parsed, "model");
 	return {
-		enabled: true,
 		...(runId ? { runId } : {}),
 		...(agent ? { agent } : {}),
 		...(childIndex !== undefined ? { childIndex } : {}),
@@ -158,9 +147,8 @@ export function decodeChildWatchdogConfig(raw: string | undefined): ChildWatchdo
 		...(model ? { model } : {}),
 		...(thinking !== undefined ? { thinking: thinking as string | false } : {}),
 		lsp: childConfigLsp(parsed.lsp),
-		autoFollowBlockers: childConfigBoolean(parsed, "autoFollowBlockers"),
-		autoFollowMaxAttempts: childConfigNullableNonNegativeInteger(parsed, "autoFollowMaxAttempts"),
 		stalemateRepeats: childConfigPositiveInteger(parsed, "stalemateRepeats"),
+		cadence: childConfigCadence(parsed.cadence),
 	};
 }
 
@@ -173,14 +161,13 @@ export function isChildWatchdogStatusEvent(value: unknown): value is ChildWatchd
 		&& event.seq >= 0
 		&& typeof event.ts === "number"
 		&& Number.isFinite(event.ts)
-		&& typeof event.followUpPending === "boolean"
 		&& typeof event.phase === "string"
 		&& (CHILD_WATCHDOG_PHASES as readonly string[]).includes(event.phase);
 }
 
 export function childWatchdogIsActive(snapshot: ChildWatchdogStateSnapshot | undefined): boolean {
 	if (!snapshot) return false;
-	return snapshot.followUpPending || snapshot.phase === "reviewing" || snapshot.phase === "autofollow" || snapshot.phase === "settling";
+	return snapshot.phase === "reviewing";
 }
 
 export function acceptChildWatchdogEvent(input: {
@@ -199,7 +186,40 @@ export function acceptChildWatchdogEvent(input: {
 		phase: input.event.phase,
 		seq: input.event.seq,
 		lastUpdate: input.event.ts,
-		followUpPending: input.event.followUpPending,
 		...(input.event.reason ? { reason: input.event.reason } : {}),
+		...(input.current?.warnings?.length ? { warnings: input.current.warnings } : {}),
 	};
 }
+
+function childWatchdogWarningFromMessage(message: unknown): ChildWatchdogWarningSummary | undefined {
+	const candidate = message as { role?: unknown; customType?: unknown; details?: Record<string, unknown> } | undefined;
+	if (candidate?.role !== "custom" || candidate.customType !== SUBAGENT_WATCHDOG_WARNING_TYPE) return undefined;
+	const details = candidate.details ?? {};
+	if (details.severity !== "concern" && details.severity !== "blocker") return undefined;
+	if (typeof details.summary !== "string" || typeof details.evidence !== "string" || typeof details.recommendedAction !== "string") return undefined;
+	return {
+		severity: details.severity,
+		category: details.category as WatchdogCategory,
+		summary: details.summary,
+		evidence: details.evidence,
+		recommendedAction: details.recommendedAction,
+		...(typeof details.displayedAt === "string" ? { displayedAt: details.displayedAt } : {}),
+		addressed: false,
+		stalemate: details.state === "stalemate",
+	};
+}
+
+/** A watchdog warning message is appended; an assistant turn marks earlier warnings addressed. Undefined when unchanged. */
+export function applyChildWatchdogMessage(current: ChildWatchdogStateSnapshot | undefined, message: unknown, now = Date.now()): ChildWatchdogStateSnapshot | undefined {
+	const warning = childWatchdogWarningFromMessage(message);
+	if (warning) {
+		const warnings = [...(current?.warnings ?? []), warning].slice(-CHILD_WATCHDOG_WARNING_LIMIT);
+		return current ? { ...current, warnings } : { phase: "idle", seq: 0, lastUpdate: now, warnings };
+	}
+	if ((message as { role?: unknown } | undefined)?.role !== "assistant" || !current?.warnings?.some((entry) => !entry.addressed)) return undefined;
+	return { ...current, warnings: current.warnings.map((entry) => entry.addressed ? entry : { ...entry, addressed: true }) };
+}
+
+export function unresolvedChildWatchdogBlockers(progress: Pick<ChildWatchdogProgress, "warnings"> | undefined): ChildWatchdogWarningSummary[] {
+	return (progress?.warnings ?? []).filter((warning) => warning.severity === "blocker" && (!warning.addressed || warning.stalemate));
+}

package/src/watchdog/diff-tool.ts

@@ -0,0 +1,77 @@
+import { spawnSync } from "node:child_process";
+import * as path from "node:path";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type, type Static } from "typebox";
+
+export const WATCHDOG_DIFF_TOOL_NAME = "watchdog_diff";
+export const WATCHDOG_DIFF_MAX_CHARS = 24_000;
+const MAX_UNTRACKED_FILES = 50;
+
+export interface WatchdogDiffBaseline {
+	root: string;
+	ref: string;
+}
+
+const WatchdogDiffParams = Type.Object({
+	path: Type.Optional(Type.String({ description: "Restrict the diff to one file or directory, relative to the repo root." })),
+	stat: Type.Optional(Type.Boolean({ description: "Return per-file change counts instead of the full diff." })),
+}, { additionalProperties: false });
+
+type WatchdogDiffParams = Static<typeof WatchdogDiffParams>;
+
+function runGit(root: string, args: string[]): { ok: boolean; stdout: string; stderr: string } {
+	const result = spawnSync("git", ["-C", root, ...args], { encoding: "utf-8", maxBuffer: 16 * 1024 * 1024, windowsHide: true });
+	return { ok: result.status === 0, stdout: result.stdout ?? "", stderr: (result.stderr ?? "").trim() };
+}
+
+/** HEAD at session start, so later child commits still show in the diff. */
+export function captureWatchdogDiffBaseline(cwd: string): WatchdogDiffBaseline | undefined {
+	const toplevel = runGit(cwd, ["rev-parse", "--show-toplevel"]);
+	if (!toplevel.ok) return undefined;
+	const head = runGit(cwd, ["rev-parse", "HEAD"]);
+	if (!head.ok) return undefined;
+	const root = toplevel.stdout.trim();
+	const ref = head.stdout.trim();
+	return root && ref ? { root, ref } : undefined;
+}
+
+function validatePath(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	if (!trimmed) return undefined;
+	if (trimmed.startsWith("-")) throw new Error("watchdog_diff path must not start with '-'.");
+	if (path.isAbsolute(trimmed)) throw new Error("watchdog_diff path must be relative to the repo root.");
+	if (trimmed.split(/[\\/]/).includes("..")) throw new Error("watchdog_diff path must not contain '..'.");
+	return trimmed;
+}
+
+function bound(text: string): string {
+	if (text.length <= WATCHDOG_DIFF_MAX_CHARS) return text;
+	const marker = `\n\n[... ${text.length - WATCHDOG_DIFF_MAX_CHARS} characters omitted; call again with a narrower path ...]`;
+	return `${text.slice(0, WATCHDOG_DIFF_MAX_CHARS - marker.length)}${marker}`;
+}
+
+/** In a shared cwd, changes already pending when the session started also appear. */
+export function createWatchdogDiffTool(baseline: WatchdogDiffBaseline): AgentTool<typeof WatchdogDiffParams, { chars: number }> {
+	return {
+		name: WATCHDOG_DIFF_TOOL_NAME,
+		label: "Watchdog diff",
+		description: "Show the repository diff since the review baseline, plus untracked file paths. Optional path narrows it; stat:true returns per-file counts only.",
+		parameters: WatchdogDiffParams,
+		executionMode: "sequential",
+		async execute(_toolCallId, params: WatchdogDiffParams) {
+			const pathFilter = validatePath(params.path);
+			const diff = runGit(baseline.root, ["diff", "--no-color", "--no-ext-diff", ...(params.stat === true ? ["--stat"] : []), baseline.ref, "--", ...(pathFilter ? [pathFilter] : [])]);
+			if (!diff.ok) throw new Error(`git diff failed: ${diff.stderr || "unknown error"}`);
+			const untrackedResult = runGit(baseline.root, ["ls-files", "--others", "--exclude-standard", "-z", "--", ...(pathFilter ? [pathFilter] : [])]);
+			const untracked = untrackedResult.ok ? untrackedResult.stdout.split("\0").filter(Boolean) : [];
+			const sections = [diff.stdout.trimEnd()];
+			if (untracked.length) {
+				const shown = untracked.slice(0, MAX_UNTRACKED_FILES);
+				sections.push(["Untracked files (use read to inspect):", ...shown.map((file) => ` ${file}`)].join("\n"));
+				if (untracked.length > shown.length) sections.push(`... ${untracked.length - shown.length} more untracked files`);
+			}
+			const text = bound(sections.filter(Boolean).join("\n\n")) || `No changes since baseline ${baseline.ref.slice(0, 12)}.`;
+			return { content: [{ type: "text", text }], details: { chars: text.length } };
+		},
+	};
+}

package/src/watchdog/emission-guard.ts

@@ -88,7 +88,8 @@ export class WatchdogEmissionGuard {
 		this.startModelUpdate();
 	}
 
-	evaluate(warning: WatchdogWarning): WatchdogEmissionDecision {
+	/** `allowRepeatOf`: one already-accepted identity that may repeat (boundary re-findings before stalemate). */
+	evaluate(warning: WatchdogWarning, options: { allowRepeatOf?: string } = {}): WatchdogEmissionDecision {
 		if (isContentFree(warning.summary) || isContentFree(warning.evidence) || isContentFree(warning.recommendedAction)) {
 			return { accepted: false, reason: "content-free" };
 		}
@@ -102,8 +103,9 @@ export class WatchdogEmissionGuard {
 				&& warning.severity === "blocker";
 			if (!updateEscalation) return { accepted: false, reason: "update-budget", identity, underlyingIdentity };
 		}
-		if (priorSeverity !== undefined && !escalation) return { accepted: false, reason: "duplicate", identity, underlyingIdentity };
-		if (this.maxWarnings !== null && this.acceptedCount >= this.maxWarnings && !escalation) {
+		const repeat = priorSeverity !== undefined && options.allowRepeatOf === identity;
+		if (priorSeverity !== undefined && !escalation && !repeat) return { accepted: false, reason: "duplicate", identity, underlyingIdentity };
+		if (this.maxWarnings !== null && this.acceptedCount >= this.maxWarnings && !escalation && !repeat) {
 			return { accepted: false, reason: "max-warnings", identity, underlyingIdentity };
 		}
 

package/src/watchdog/guidance.ts

@@ -0,0 +1,20 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
+
+export const WATCHDOG_GUIDANCE_MAX_CHARS = 8_000;
+
+function readOptional(filePath: string): string {
+	try {
+		return fs.readFileSync(filePath, "utf-8").trim();
+	} catch {
+		return "";
+	}
+}
+
+/** Read fresh on every review; project file first, then user file. */
+export function loadWatchdogGuidance(cwd: string, enabled: boolean): string {
+	if (!enabled) return "";
+	const sections = [getProjectConfigDir(cwd), getAgentDir()].map((dir) => readOptional(path.join(dir, "WATCHDOG.md"))).filter(Boolean);
+	return sections.join("\n\n").slice(0, WATCHDOG_GUIDANCE_MAX_CHARS);
+}

package/src/watchdog/register-child.ts

@@ -1,14 +1,14 @@
 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";
 import { createWatchdogWarningMessage } from "./warning-format.ts";
 import {
-	CHILD_WATCHDOG_CONFIG_ENV,
 	CHILD_WATCHDOG_STATUS_EVENT,
-	decodeChildWatchdogConfig,
 	type ChildWatchdogConfig,
 	type ChildWatchdogPhase,
+	type ChildWatchdogStatusEvent,
 } from "./child-status.ts";
 import type { ResolvedWatchdogConfig, WatchdogWarningDetails } from "./types.ts";
 
@@ -23,11 +23,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,
@@ -45,20 +42,22 @@ function childWarningDetails(details: WatchdogWarningDetails, config: ChildWatch
 	};
 }
 
-function writeStatus(event: unknown): void {
-	try {
-		process.stdout.write(`${JSON.stringify(event)}\n`);
-	} catch {
-		// Child watchdog status is advisory; stdout failures are handled by the child process itself.
-	}
-}
-
-export function registerChildWatchdog(pi: ExtensionAPI, rawConfig = process.env[CHILD_WATCHDOG_CONFIG_ENV]): MainWatchdogRuntime | undefined {
-	const childConfig = decodeChildWatchdogConfig(rawConfig);
-	if (!childConfig?.enabled) return undefined;
+/**
+ * Register the child-side watchdog. Status events go to the sink the hosting
+ * process passed in the child runtime config; the host folds them into the
+ * child's event stream.
+ */
+export function registerChildWatchdog(
+	pi: ExtensionAPI,
+	childConfig: ChildWatchdogConfig | undefined,
+	writeStatus: ((event: ChildWatchdogStatusEvent) => void) | undefined,
+): MainWatchdogRuntime | undefined {
+	if (!childConfig) return undefined;
+	if (!writeStatus) throw new Error("Child watchdog status sink is missing; the host must pass ChildRuntimeConfig.watchdogStatus.");
 	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" });
+}