@davidorex/pi-behavior-monitors 0.1.2

package/index.ts

@@ -0,0 +1,1166 @@
+/**
+ * Behavior monitors for pi — watches agent activity, classifies against
+ * pattern libraries, steers corrections, and writes structured findings
+ * to JSON files for downstream consumption.
+ *
+ * Monitor definitions are JSON files (.monitor.json) with typed blocks:
+ * classify (LLM side-channel), patterns (JSON library), actions (steer + write).
+ * Patterns and instructions are JSON arrays conforming to schemas.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { complete } from "@mariozechner/pi-ai";
+import type { Api, AssistantMessage, Model, TextContent, ToolCall } from "@mariozechner/pi-ai";
+import type {
+	AgentEndEvent,
+	ExtensionAPI,
+	ExtensionContext,
+	MessageEndEvent,
+	SessionEntry,
+	SessionMessageEntry,
+	TurnEndEvent,
+} from "@mariozechner/pi-coding-agent";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { Box, Text } from "@mariozechner/pi-tui";
+
+const EXTENSION_DIR = path.dirname(fileURLToPath(import.meta.url));
+const EXAMPLES_DIR = path.join(EXTENSION_DIR, "examples");
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface MonitorScope {
+	target: "main" | "subagent" | "all" | "workflow";
+	filter?: {
+		agent_type?: string[];
+		step_name?: string;
+		workflow?: string;
+	};
+}
+
+export interface MonitorAction {
+	steer?: string | null;
+	learn_pattern?: boolean;
+	write?: {
+		path: string;
+		schema?: string;
+		merge: "append" | "upsert";
+		array_field: string;
+		template: Record<string, string>;
+	};
+}
+
+export interface MonitorSpec {
+	name: string;
+	description: string;
+	event: MonitorEvent;
+	when: string;
+	scope: MonitorScope;
+	classify: {
+		model: string;
+		context: string[];
+		excludes: string[];
+		prompt: string;
+	};
+	patterns: {
+		path: string;
+		learn: boolean;
+	};
+	instructions: {
+		path: string;
+	};
+	actions: {
+		on_flag?: MonitorAction | null;
+		on_new?: MonitorAction | null;
+		on_clean?: MonitorAction | null;
+	};
+	ceiling: number;
+	escalate: "ask" | "dismiss";
+}
+
+export interface MonitorPattern {
+	id: string;
+	description: string;
+	severity?: string;
+	category?: string;
+	examples?: string[];
+	learned_at?: string;
+	source?: string;
+}
+
+export interface MonitorInstruction {
+	text: string;
+	added_at?: string;
+}
+
+export interface Monitor extends MonitorSpec {
+	dir: string;
+	resolvedPatternsPath: string;
+	resolvedInstructionsPath: string;
+	// runtime state
+	activationCount: number;
+	whileCount: number;
+	lastUserText: string;
+	dismissed: boolean;
+}
+
+export interface ClassifyResult {
+	verdict: "clean" | "flag" | "new";
+	description?: string;
+	newPattern?: string;
+}
+
+export interface MonitorMessageDetails {
+	monitorName: string;
+	verdict: "flag" | "new";
+	description: string;
+	steer: string;
+	whileCount: number;
+	ceiling: number;
+}
+
+type MonitorEvent = "message_end" | "turn_end" | "agent_end" | "command";
+
+const VALID_EVENTS = new Set<string>(["message_end", "turn_end", "agent_end", "command"]);
+
+function isValidEvent(event: string): event is MonitorEvent {
+	return VALID_EVENTS.has(event);
+}
+
+// =============================================================================
+// Discovery
+// =============================================================================
+
+function discoverMonitors(): Monitor[] {
+	const dirs: string[] = [];
+
+	// project-local
+	let cwd = process.cwd();
+	while (true) {
+		const candidate = path.join(cwd, ".pi", "monitors");
+		if (isDir(candidate)) {
+			dirs.push(candidate);
+			break;
+		}
+		const parent = path.dirname(cwd);
+		if (parent === cwd) break;
+		cwd = parent;
+	}
+
+	// global
+	const globalDir = path.join(getAgentDir(), "monitors");
+	if (isDir(globalDir)) dirs.push(globalDir);
+
+	const seen = new Map<string, Monitor>();
+	for (const dir of dirs) {
+		for (const file of listMonitorFiles(dir)) {
+			const monitor = parseMonitorJson(path.join(dir, file), dir);
+			if (monitor && !seen.has(monitor.name)) {
+				seen.set(monitor.name, monitor);
+			}
+		}
+	}
+	return Array.from(seen.values());
+}
+
+function isDir(p: string): boolean {
+	try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+function listMonitorFiles(dir: string): string[] {
+	try {
+		return fs.readdirSync(dir).filter((f) => f.endsWith(".monitor.json"));
+	} catch { return []; }
+}
+
+function parseMonitorJson(filePath: string, dir: string): Monitor | null {
+	let raw: string;
+	try { raw = fs.readFileSync(filePath, "utf-8"); } catch { return null; }
+
+	let spec: Record<string, unknown>;
+	try { spec = JSON.parse(raw); } catch {
+		console.error(`[monitors] Failed to parse ${filePath}`);
+		return null;
+	}
+
+	const name = spec.name as string | undefined;
+	if (!name) return null;
+
+	const event = String(spec.event ?? "message_end");
+	if (!isValidEvent(event)) {
+		console.error(`[${name}] Invalid event: ${event}. Must be one of: ${[...VALID_EVENTS].join(", ")}`);
+		return null;
+	}
+
+	const classify = spec.classify as MonitorSpec["classify"] | undefined;
+	if (!classify?.prompt) {
+		console.error(`[${name}] Missing classify.prompt`);
+		return null;
+	}
+
+	const patternsSpec = spec.patterns as MonitorSpec["patterns"] | undefined;
+	if (!patternsSpec?.path) {
+		console.error(`[${name}] Missing patterns.path`);
+		return null;
+	}
+
+	const scope = spec.scope as MonitorScope | undefined;
+	const instructions = spec.instructions as MonitorSpec["instructions"] | undefined;
+	const actions = spec.actions as MonitorSpec["actions"] | undefined;
+
+	return {
+		name,
+		description: String(spec.description ?? ""),
+		event: event as MonitorEvent,
+		when: String(spec.when ?? "always"),
+		scope: scope ?? { target: "main" },
+		classify: {
+			model: classify.model ?? "claude-sonnet-4-20250514",
+			context: Array.isArray(classify.context) ? classify.context : ["tool_results", "assistant_text"],
+			excludes: Array.isArray(classify.excludes) ? classify.excludes : [],
+			prompt: classify.prompt,
+		},
+		patterns: {
+			path: patternsSpec.path,
+			learn: patternsSpec.learn !== false,
+		},
+		instructions: {
+			path: instructions?.path ?? `${name}.instructions.json`,
+		},
+		actions: actions ?? {},
+		ceiling: Number(spec.ceiling) || 5,
+		escalate: (spec.escalate === "dismiss" ? "dismiss" : "ask"),
+		dir,
+		resolvedPatternsPath: path.resolve(dir, patternsSpec.path),
+		resolvedInstructionsPath: path.resolve(dir, instructions?.path ?? `${name}.instructions.json`),
+		// runtime state
+		activationCount: 0,
+		whileCount: 0,
+		lastUserText: "",
+		dismissed: false,
+	};
+}
+
+// =============================================================================
+// Example seeding
+// =============================================================================
+
+function resolveProjectMonitorsDir(): string {
+	let cwd = process.cwd();
+	while (true) {
+		const piDir = path.join(cwd, ".pi");
+		if (isDir(piDir)) return path.join(piDir, "monitors");
+		const parent = path.dirname(cwd);
+		if (parent === cwd) break;
+		cwd = parent;
+	}
+	return path.join(process.cwd(), ".pi", "monitors");
+}
+
+function seedExamples(): number {
+	if (discoverMonitors().length > 0) return 0;
+	if (!isDir(EXAMPLES_DIR)) return 0;
+
+	const targetDir = resolveProjectMonitorsDir();
+	fs.mkdirSync(targetDir, { recursive: true });
+
+	if (listMonitorFiles(targetDir).length > 0) return 0;
+
+	const files = fs.readdirSync(EXAMPLES_DIR).filter((f) => f.endsWith(".json"));
+	let copied = 0;
+	for (const file of files) {
+		const dest = path.join(targetDir, file);
+		if (!fs.existsSync(dest)) {
+			fs.copyFileSync(path.join(EXAMPLES_DIR, file), dest);
+			copied++;
+		}
+	}
+	return copied;
+}
+
+// =============================================================================
+// Context collection
+// =============================================================================
+
+const TRUNCATE = 2000;
+
+function extractText(parts: (TextContent | ToolCall)[]): string {
+	return parts.filter((b): b is TextContent => b.type === "text").map((b) => b.text).join("");
+}
+
+function extractUserText(parts: string | (TextContent | { type: string })[]): string {
+	if (typeof parts === "string") return parts;
+	if (!Array.isArray(parts)) return "";
+	return parts.filter((b): b is TextContent => b.type === "text").map((b) => b.text).join("");
+}
+
+function trunc(text: string): string {
+	return text.length <= TRUNCATE ? text : `${text.slice(0, TRUNCATE)} [TRUNCATED]`;
+}
+
+function isMessageEntry(entry: SessionEntry): entry is SessionMessageEntry {
+	return entry.type === "message";
+}
+
+function collectUserText(branch: SessionEntry[]): string {
+	let foundAssistant = false;
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (!isMessageEntry(entry)) continue;
+		if (!foundAssistant) {
+			if (entry.message.role === "assistant") foundAssistant = true;
+			continue;
+		}
+		if (entry.message.role === "user") return extractUserText(entry.message.content);
+	}
+	return "";
+}
+
+function collectAssistantText(branch: SessionEntry[]): string {
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (isMessageEntry(entry) && entry.message.role === "assistant") {
+			return extractText(entry.message.content);
+		}
+	}
+	return "";
+}
+
+function collectToolResults(branch: SessionEntry[], limit = 5): string {
+	const results: string[] = [];
+	for (let i = branch.length - 1; i >= 0 && results.length < limit; i--) {
+		const entry = branch[i];
+		if (!isMessageEntry(entry) || entry.message.role !== "toolResult") continue;
+		const text = extractUserText(entry.message.content);
+		if (text) results.push(`---\n[${entry.message.toolName}${entry.message.isError ? " ERROR" : ""}] ${trunc(text)}\n---`);
+	}
+	return results.reverse().join("\n");
+}
+
+function collectToolCalls(branch: SessionEntry[], limit = 20): string {
+	const calls: string[] = [];
+	for (let i = branch.length - 1; i >= 0 && calls.length < limit; i--) {
+		const entry = branch[i];
+		if (!isMessageEntry(entry)) continue;
+		const msg = entry.message;
+		if (msg.role === "assistant") {
+			for (const part of msg.content) {
+				if (part.type === "toolCall") {
+					calls.push(`[call ${part.name}] ${trunc(JSON.stringify(part.arguments ?? {}))}`);
+				}
+			}
+		}
+		if (msg.role === "toolResult") {
+			calls.push(`[result ${msg.toolName}${msg.isError ? " ERROR" : ""}] ${trunc(extractUserText(msg.content))}`);
+		}
+	}
+	return calls.reverse().join("\n");
+}
+
+function collectCustomMessages(branch: SessionEntry[]): string {
+	const msgs: string[] = [];
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (!isMessageEntry(entry)) continue;
+		if (entry.message.role === "user") break;
+		const msg = entry.message as Record<string, unknown>;
+		if (msg.customType) {
+			msgs.unshift(`[${msg.customType}] ${msg.content ?? ""}`);
+		}
+	}
+	return msgs.join("\n");
+}
+
+const collectors: Record<string, (branch: SessionEntry[]) => string> = {
+	user_text: collectUserText,
+	assistant_text: collectAssistantText,
+	tool_results: collectToolResults,
+	tool_calls: collectToolCalls,
+	custom_messages: collectCustomMessages,
+};
+
+function hasToolResults(branch: SessionEntry[]): boolean {
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (!isMessageEntry(entry)) continue;
+		if (entry.message.role === "user") break;
+		if (entry.message.role === "toolResult") return true;
+	}
+	return false;
+}
+
+function hasToolNamed(branch: SessionEntry[], name: string): boolean {
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (!isMessageEntry(entry)) continue;
+		if (entry.message.role === "user") break;
+		if (entry.message.role === "assistant") {
+			for (const part of entry.message.content) {
+				if (part.type === "toolCall" && part.name === name) return true;
+			}
+		}
+	}
+	return false;
+}
+
+// =============================================================================
+// When evaluation
+// =============================================================================
+
+function evaluateWhen(monitor: Monitor, branch: SessionEntry[]): boolean {
+	const w = monitor.when;
+	if (w === "always") return true;
+	if (w === "has_tool_results") return hasToolResults(branch);
+	if (w === "has_file_writes") return hasToolNamed(branch, "write") || hasToolNamed(branch, "edit");
+	if (w === "has_bash") return hasToolNamed(branch, "bash");
+
+	const everyMatch = w.match(/^every\((\d+)\)$/);
+	if (everyMatch) {
+		const n = parseInt(everyMatch[1]);
+		const userText = collectUserText(branch);
+		if (userText !== monitor.lastUserText) {
+			monitor.activationCount = 0;
+			monitor.lastUserText = userText;
+		}
+		monitor.activationCount++;
+		if (monitor.activationCount >= n) {
+			monitor.activationCount = 0;
+			return true;
+		}
+		return false;
+	}
+
+	const toolMatch = w.match(/^tool\((\w+)\)$/);
+	if (toolMatch) return hasToolNamed(branch, toolMatch[1]);
+
+	return true;
+}
+
+// =============================================================================
+// Template rendering (JSON patterns → text for LLM prompt)
+// =============================================================================
+
+function loadPatterns(monitor: Monitor): MonitorPattern[] {
+	try {
+		const raw = fs.readFileSync(monitor.resolvedPatternsPath, "utf-8");
+		return JSON.parse(raw);
+	} catch {
+		return [];
+	}
+}
+
+function formatPatternsForPrompt(patterns: MonitorPattern[]): string {
+	return patterns
+		.map((p, i) => `${i + 1}. [${p.severity ?? "warning"}] ${p.description}`)
+		.join("\n");
+}
+
+function loadInstructions(monitor: Monitor): MonitorInstruction[] {
+	try {
+		const raw = fs.readFileSync(monitor.resolvedInstructionsPath, "utf-8");
+		return JSON.parse(raw);
+	} catch {
+		return [];
+	}
+}
+
+function saveInstructions(monitor: Monitor, instructions: MonitorInstruction[]): string | null {
+	try {
+		fs.writeFileSync(monitor.resolvedInstructionsPath, JSON.stringify(instructions, null, 2) + "\n");
+		return null;
+	} catch (err) {
+		return err instanceof Error ? err.message : String(err);
+	}
+}
+
+// =============================================================================
+// /monitors command — parsing and handlers
+// =============================================================================
+
+export type MonitorsCommand =
+	| { type: "list" }
+	| { type: "on" }
+	| { type: "off" }
+	| { type: "inspect"; name: string }
+	| { type: "rules-list"; name: string }
+	| { type: "rules-add"; name: string; text: string }
+	| { type: "rules-remove"; name: string; index: number }
+	| { type: "rules-replace"; name: string; index: number; text: string }
+	| { type: "patterns-list"; name: string }
+	| { type: "dismiss"; name: string }
+	| { type: "reset"; name: string }
+	| { type: "error"; message: string };
+
+export function parseMonitorsArgs(args: string, knownNames: Set<string>): MonitorsCommand {
+	const trimmed = args.trim();
+	if (!trimmed) return { type: "list" };
+
+	const tokens = trimmed.split(/\s+/);
+	const first = tokens[0];
+
+	// global commands (only if not a monitor name)
+	if (!knownNames.has(first)) {
+		if (first === "on") return { type: "on" };
+		if (first === "off") return { type: "off" };
+		return { type: "error", message: `Unknown monitor: ${first}\nAvailable: ${[...knownNames].join(", ")}` };
+	}
+
+	const name = first;
+	if (tokens.length === 1) return { type: "inspect", name };
+
+	const verb = tokens[1];
+
+	if (verb === "rules") {
+		if (tokens.length === 2) return { type: "rules-list", name };
+		const action = tokens[2];
+		if (action === "add") {
+			const text = tokens.slice(3).join(" ");
+			if (!text) return { type: "error", message: "Usage: /monitors <name> rules add <text>" };
+			return { type: "rules-add", name, text };
+		}
+		if (action === "remove") {
+			const n = parseInt(tokens[3]);
+			if (isNaN(n) || n < 1) return { type: "error", message: "Usage: /monitors <name> rules remove <number>" };
+			return { type: "rules-remove", name, index: n };
+		}
+		if (action === "replace") {
+			const n = parseInt(tokens[3]);
+			const text = tokens.slice(4).join(" ");
+			if (isNaN(n) || n < 1 || !text) return { type: "error", message: "Usage: /monitors <name> rules replace <number> <text>" };
+			return { type: "rules-replace", name, index: n, text };
+		}
+		return { type: "error", message: `Unknown rules action: ${action}\nAvailable: add, remove, replace` };
+	}
+
+	if (verb === "patterns") return { type: "patterns-list", name };
+	if (verb === "dismiss") return { type: "dismiss", name };
+	if (verb === "reset") return { type: "reset", name };
+
+	return { type: "error", message: `Unknown subcommand: ${verb}\nAvailable: rules, patterns, dismiss, reset` };
+}
+
+function handleList(
+	monitors: Monitor[],
+	ctx: ExtensionContext,
+	enabled: boolean,
+): void {
+	const header = enabled ? "monitors: ON" : "monitors: OFF (all monitoring paused)";
+	const lines = monitors.map((m) => {
+		const state = m.dismissed
+			? "dismissed"
+			: m.whileCount > 0
+				? `engaged (${m.whileCount}/${m.ceiling})`
+				: "idle";
+		const scope = m.scope.target !== "main" ? ` [scope:${m.scope.target}]` : "";
+		return `  ${m.name} [${m.event}${m.when !== "always" ? `, when: ${m.when}` : ""}]${scope} — ${state}`;
+	});
+	ctx.ui.notify(`${header}\n${lines.join("\n")}`, "info");
+}
+
+function handleInspect(monitor: Monitor, ctx: ExtensionContext): void {
+	const rules = loadInstructions(monitor);
+	const patterns = loadPatterns(monitor);
+	const state = monitor.dismissed
+		? "dismissed"
+		: monitor.whileCount > 0
+			? `engaged (${monitor.whileCount}/${monitor.ceiling})`
+			: "idle";
+	const lines = [
+		`[${monitor.name}] ${monitor.description}`,
+		`event: ${monitor.event}, when: ${monitor.when}, scope: ${monitor.scope.target}`,
+		`state: ${state}, ceiling: ${monitor.ceiling}, escalate: ${monitor.escalate}`,
+		`rules: ${rules.length}, patterns: ${patterns.length}`,
+	];
+	ctx.ui.notify(lines.join("\n"), "info");
+}
+
+function handleRulesList(monitor: Monitor, ctx: ExtensionContext): void {
+	const rules = loadInstructions(monitor);
+	if (rules.length === 0) {
+		ctx.ui.notify(`[${monitor.name}] (no rules)`, "info");
+		return;
+	}
+	const lines = rules.map((r, i) => `${i + 1}. ${r.text}`);
+	ctx.ui.notify(`[${monitor.name}] rules:\n${lines.join("\n")}`, "info");
+}
+
+function handleRulesAdd(monitor: Monitor, ctx: ExtensionContext, text: string): void {
+	const rules = loadInstructions(monitor);
+	rules.push({ text, added_at: new Date().toISOString() });
+	const err = saveInstructions(monitor, rules);
+	if (err) {
+		ctx.ui.notify(`[${monitor.name}] Failed to save: ${err}`, "error");
+	} else {
+		ctx.ui.notify(`[${monitor.name}] Rule added: ${text}`, "info");
+	}
+}
+
+function handleRulesRemove(monitor: Monitor, ctx: ExtensionContext, index: number): void {
+	const rules = loadInstructions(monitor);
+	if (index < 1 || index > rules.length) {
+		ctx.ui.notify(`[${monitor.name}] Invalid index ${index}. Have ${rules.length} rules.`, "error");
+		return;
+	}
+	const removed = rules.splice(index - 1, 1)[0];
+	const err = saveInstructions(monitor, rules);
+	if (err) {
+		ctx.ui.notify(`[${monitor.name}] Failed to save: ${err}`, "error");
+	} else {
+		ctx.ui.notify(`[${monitor.name}] Removed rule ${index}: ${removed.text}`, "info");
+	}
+}
+
+function handleRulesReplace(monitor: Monitor, ctx: ExtensionContext, index: number, text: string): void {
+	const rules = loadInstructions(monitor);
+	if (index < 1 || index > rules.length) {
+		ctx.ui.notify(`[${monitor.name}] Invalid index ${index}. Have ${rules.length} rules.`, "error");
+		return;
+	}
+	const old = rules[index - 1].text;
+	rules[index - 1] = { text, added_at: new Date().toISOString() };
+	const err = saveInstructions(monitor, rules);
+	if (err) {
+		ctx.ui.notify(`[${monitor.name}] Failed to save: ${err}`, "error");
+	} else {
+		ctx.ui.notify(`[${monitor.name}] Replaced rule ${index}:\n  was: ${old}\n  now: ${text}`, "info");
+	}
+}
+
+function handlePatternsList(monitor: Monitor, ctx: ExtensionContext): void {
+	const patterns = loadPatterns(monitor);
+	if (patterns.length === 0) {
+		ctx.ui.notify(`[${monitor.name}] (no patterns — monitor will not classify)`, "info");
+		return;
+	}
+	const lines = patterns.map((p, i) => {
+		const source = p.source ? ` (${p.source})` : "";
+		return `${i + 1}. [${p.severity ?? "warning"}] ${p.description}${source}`;
+	});
+	ctx.ui.notify(`[${monitor.name}] patterns:\n${lines.join("\n")}`, "info");
+}
+
+function formatInstructionsForPrompt(instructions: MonitorInstruction[]): string {
+	if (instructions.length === 0) return "";
+	const lines = instructions.map((i) => `- ${i.text}`).join("\n");
+	return `\nOperating instructions from the user (follow these strictly):\n${lines}\n`;
+}
+
+function renderTemplate(monitor: Monitor, branch: SessionEntry[]): string | null {
+	const patterns = loadPatterns(monitor);
+	if (patterns.length === 0) return null;
+
+	const instructions = loadInstructions(monitor);
+
+	const collected: Record<string, string> = {};
+	for (const key of monitor.classify.context) {
+		const fn = collectors[key];
+		if (fn) collected[key] = fn(branch);
+	}
+
+	return monitor.classify.prompt.replace(/\{(\w+)\}/g, (match, key: string) => {
+		if (key === "patterns") return formatPatternsForPrompt(patterns);
+		if (key === "instructions") return formatInstructionsForPrompt(instructions);
+		if (key === "iteration") return String(monitor.whileCount);
+		return collected[key] ?? match;
+	});
+}
+
+// =============================================================================
+// Classification
+// =============================================================================
+
+export function parseVerdict(raw: string): ClassifyResult {
+	const text = raw.trim();
+	if (text.startsWith("CLEAN")) return { verdict: "clean" };
+	if (text.startsWith("NEW:")) {
+		const rest = text.slice(4);
+		const pipe = rest.indexOf("|");
+		if (pipe !== -1) return { verdict: "new", newPattern: rest.slice(0, pipe).trim(), description: rest.slice(pipe + 1).trim() };
+		return { verdict: "new", newPattern: rest.trim(), description: rest.trim() };
+	}
+	if (text.startsWith("FLAG:")) return { verdict: "flag", description: text.slice(5).trim() };
+	return { verdict: "clean" };
+}
+
+export function parseModelSpec(spec: string): { provider: string; modelId: string } {
+	const slashIndex = spec.indexOf("/");
+	if (slashIndex !== -1) {
+		return { provider: spec.slice(0, slashIndex), modelId: spec.slice(slashIndex + 1) };
+	}
+	return { provider: "anthropic", modelId: spec };
+}
+
+async function classifyPrompt(ctx: ExtensionContext, monitor: Monitor, prompt: string, signal?: AbortSignal): Promise<ClassifyResult> {
+	const { provider, modelId } = parseModelSpec(monitor.classify.model);
+	const model = ctx.modelRegistry.find(provider, modelId);
+	if (!model) throw new Error(`Model ${monitor.classify.model} not found`);
+
+	const apiKey = await ctx.modelRegistry.getApiKey(model);
+	if (!apiKey) throw new Error(`No API key for ${monitor.classify.model}`);
+
+	const response: AssistantMessage = await complete(
+		model as Model<Api>,
+		{ messages: [{ role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() }] },
+		{ apiKey, maxTokens: 150, signal },
+	);
+
+	return parseVerdict(extractText(response.content));
+}
+
+// =============================================================================
+// Pattern learning (JSON)
+// =============================================================================
+
+function learnPattern(monitor: Monitor, description: string): void {
+	const patterns = loadPatterns(monitor);
+	const id = description.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 60);
+
+	// dedup by description
+	if (patterns.some((p) => p.description === description)) return;
+
+	patterns.push({
+		id,
+		description,
+		severity: "warning",
+		source: "learned",
+		learned_at: new Date().toISOString(),
+	});
+
+	try {
+		fs.writeFileSync(monitor.resolvedPatternsPath, JSON.stringify(patterns, null, 2) + "\n");
+	} catch (err) {
+		console.error(`[${monitor.name}] Failed to write pattern: ${err instanceof Error ? err.message : err}`);
+	}
+}
+
+// =============================================================================
+// Action execution — write findings to JSON files
+// =============================================================================
+
+export function generateFindingId(monitorName: string, _description: string): string {
+	return `${monitorName}-${Date.now().toString(36)}`;
+}
+
+function executeWriteAction(
+	monitor: Monitor,
+	action: MonitorAction,
+	result: ClassifyResult,
+): void {
+	if (!action.write) return;
+
+	const writeCfg = action.write;
+	const filePath = path.isAbsolute(writeCfg.path)
+		? writeCfg.path
+		: path.resolve(process.cwd(), writeCfg.path);
+
+	// Build the entry from template, substituting placeholders
+	const findingId = generateFindingId(monitor.name, result.description ?? "unknown");
+	const entry: Record<string, unknown> = {};
+	for (const [key, tmpl] of Object.entries(writeCfg.template)) {
+		entry[key] = String(tmpl)
+			.replace(/\{finding_id\}/g, findingId)
+			.replace(/\{description\}/g, result.description ?? "Issue detected")
+			.replace(/\{severity\}/g, "warning")
+			.replace(/\{monitor_name\}/g, monitor.name)
+			.replace(/\{timestamp\}/g, new Date().toISOString());
+	}
+
+	// Read existing file or create structure
+	let data: Record<string, unknown> = {};
+	try {
+		data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+	} catch {
+		// file doesn't exist or is invalid — create fresh
+	}
+
+	const arrayField = writeCfg.array_field;
+	if (!Array.isArray(data[arrayField])) {
+		data[arrayField] = [];
+	}
+	const arr = data[arrayField] as Record<string, unknown>[];
+
+	if (writeCfg.merge === "upsert") {
+		const idx = arr.findIndex((item) => item.id === entry.id);
+		if (idx !== -1) {
+			arr[idx] = entry;
+		} else {
+			arr.push(entry);
+		}
+	} else {
+		arr.push(entry);
+	}
+
+	try {
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
+	} catch (err) {
+		console.error(`[${monitor.name}] Failed to write to ${filePath}: ${err instanceof Error ? err.message : err}`);
+	}
+}
+
+// =============================================================================
+// Activation
+// =============================================================================
+
+let monitorsEnabled = true;
+
+async function activate(
+	monitor: Monitor,
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	branch: SessionEntry[],
+	steeredThisTurn: Set<string>,
+	updateStatus: () => void,
+): Promise<void> {
+	if (!monitorsEnabled) return;
+	if (monitor.dismissed) return;
+
+	// check excludes
+	for (const ex of monitor.classify.excludes) {
+		if (steeredThisTurn.has(ex)) return;
+	}
+
+	if (!evaluateWhen(monitor, branch)) return;
+
+	// dedup: skip if user text unchanged since last classification
+	const currentUserText = collectUserText(branch);
+	if (currentUserText && currentUserText === monitor.lastUserText) return;
+
+	// ceiling check
+	if (monitor.whileCount >= monitor.ceiling) {
+		await escalate(monitor, pi, ctx);
+		updateStatus();
+		return;
+	}
+
+	const prompt = renderTemplate(monitor, branch);
+	if (!prompt) return;
+
+	// create an abort controller so classification can be cancelled if the user aborts
+	const abortController = new AbortController();
+	const onAbort = () => abortController.abort();
+	const unsubAbort = pi.events.on("monitors:abort", onAbort);
+
+	let result: ClassifyResult;
+	try {
+		result = await classifyPrompt(ctx, monitor, prompt, abortController.signal);
+	} catch (e: unknown) {
+		if (abortController.signal.aborted) return;
+		const message = e instanceof Error ? e.message : String(e);
+		if (ctx.hasUI) {
+			ctx.ui.notify(`[${monitor.name}] Classification failed: ${message}`, "error");
+		} else {
+			console.error(`[${monitor.name}] Classification failed: ${message}`);
+		}
+		return;
+	} finally {
+		unsubAbort();
+	}
+
+	// mark this user text as classified
+	monitor.lastUserText = currentUserText;
+
+	if (result.verdict === "clean") {
+		const cleanAction = monitor.actions.on_clean;
+		if (cleanAction) {
+			executeWriteAction(monitor, cleanAction, result);
+		}
+		monitor.whileCount = 0;
+		updateStatus();
+		return;
+	}
+
+	// Determine which action to execute
+	const action = result.verdict === "new" ? monitor.actions.on_new : monitor.actions.on_flag;
+	if (!action) return;
+
+	// Learn new pattern
+	if (result.verdict === "new" && result.newPattern && action.learn_pattern) {
+		learnPattern(monitor, result.newPattern);
+	}
+
+	// Execute write action (findings to JSON file)
+	executeWriteAction(monitor, action, result);
+
+	// Steer (inject message into conversation) — only for main scope
+	if (action.steer && monitor.scope.target === "main") {
+		const description = result.description ?? "Issue detected";
+		const annotation = result.verdict === "new" ? " — new pattern learned" : "";
+		const details: MonitorMessageDetails = {
+			monitorName: monitor.name,
+			verdict: result.verdict,
+			description,
+			steer: action.steer,
+			whileCount: monitor.whileCount + 1,
+			ceiling: monitor.ceiling,
+		};
+		pi.sendMessage<MonitorMessageDetails>(
+			{
+				customType: "monitor-steer",
+				content: `[${monitor.name}] ${description}${annotation}. ${action.steer}`,
+				display: true,
+				details,
+			},
+			{ deliverAs: "steer", triggerTurn: true },
+		);
+	}
+
+	monitor.whileCount++;
+	steeredThisTurn.add(monitor.name);
+	updateStatus();
+}
+
+async function escalate(monitor: Monitor, pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+	if (monitor.escalate === "dismiss") {
+		monitor.dismissed = true;
+		monitor.whileCount = 0;
+		return;
+	}
+
+	// In headless mode there is no way to prompt the user, so auto-dismiss
+	// to avoid an infinite classify-reset cycle that can never be resolved.
+	if (!ctx.hasUI) {
+		monitor.dismissed = true;
+		monitor.whileCount = 0;
+		return;
+	}
+
+	if (ctx.hasUI) {
+		const choice = await ctx.ui.confirm(
+			`[${monitor.name}] Steered ${monitor.ceiling} times`,
+			"Continue steering, or dismiss this monitor for the session?",
+		);
+		if (!choice) {
+			monitor.dismissed = true;
+			monitor.whileCount = 0;
+			return;
+		}
+	}
+	monitor.whileCount = 0;
+}
+
+// =============================================================================
+// Extension entry point
+// =============================================================================
+
+export default function (pi: ExtensionAPI) {
+	const seeded = seedExamples();
+
+	const monitors = discoverMonitors();
+	if (monitors.length === 0) return;
+
+	let statusCtx: ExtensionContext | undefined;
+
+	function updateStatus(): void {
+		if (!statusCtx?.hasUI) return;
+		const theme = statusCtx.ui.theme;
+
+		if (!monitorsEnabled) {
+			statusCtx.ui.setStatus("monitors", `${theme.fg("dim", "monitors:")}${theme.fg("warning", "OFF")}`);
+			return;
+		}
+
+		const engaged = monitors.filter((m) => m.whileCount > 0 && !m.dismissed);
+		const dismissed = monitors.filter((m) => m.dismissed);
+
+		if (engaged.length === 0 && dismissed.length === 0) {
+			const count = theme.fg("dim", `${monitors.length}`);
+			statusCtx.ui.setStatus("monitors", `${theme.fg("dim", "monitors:")}${count}`);
+			return;
+		}
+
+		const parts: string[] = [];
+		for (const m of engaged) {
+			parts.push(theme.fg("warning", `${m.name}(${m.whileCount}/${m.ceiling})`));
+		}
+		if (dismissed.length > 0) {
+			parts.push(theme.fg("dim", `${dismissed.length} dismissed`));
+		}
+		statusCtx.ui.setStatus("monitors", `${theme.fg("dim", "monitors:")}${parts.join(" ")}`);
+	}
+
+	pi.on("session_start", async (_event: unknown, ctx: ExtensionContext) => {
+		statusCtx = ctx;
+		if (seeded > 0 && ctx.hasUI) {
+			const dir = resolveProjectMonitorsDir();
+			ctx.ui.notify(
+				`Seeded ${seeded} example monitor files into ${dir}\nEdit or delete them to customize.`,
+				"info",
+			);
+		}
+		updateStatus();
+	});
+
+	pi.on("session_switch", async (_event: unknown, ctx: ExtensionContext) => {
+		statusCtx = ctx;
+		for (const m of monitors) {
+			m.whileCount = 0;
+			m.dismissed = false;
+			m.lastUserText = "";
+			m.activationCount = 0;
+		}
+		monitorsEnabled = true;
+		updateStatus();
+	});
+
+	// --- message renderer ---
+	pi.registerMessageRenderer<MonitorMessageDetails>("monitor-steer", (message, { expanded }, theme) => {
+		const details = message.details;
+		if (!details) {
+			const box = new Box(1, 1, (t: string) => theme.bg("customMessageBg", t));
+			box.addChild(new Text(String(message.content), 0, 0));
+			return box;
+		}
+
+		const verdictColor = details.verdict === "new" ? "warning" : "error";
+		const prefix = theme.fg(verdictColor, `[${details.monitorName}]`);
+		const desc = ` ${details.description}`;
+		const counter = theme.fg("dim", ` (${details.whileCount}/${details.ceiling})`);
+
+		let text = `${prefix}${desc}${counter}`;
+
+		if (details.verdict === "new") {
+			text += theme.fg("dim", " — new pattern learned");
+		}
+
+		text += `\n${theme.fg("muted", details.steer)}`;
+
+		if (expanded) {
+			text += `\n${theme.fg("dim", `verdict: ${details.verdict}`)}`;
+		}
+
+		const box = new Box(1, 1, (t: string) => theme.bg("customMessageBg", t));
+		box.addChild(new Text(text, 0, 0));
+		return box;
+	});
+
+	// --- abort support ---
+	pi.on("agent_end", async () => {
+		pi.events.emit("monitors:abort", undefined);
+	});
+
+	// --- per-turn exclusion tracking ---
+	let steeredThisTurn = new Set<string>();
+	pi.on("turn_start", () => { steeredThisTurn = new Set(); });
+
+	// group monitors by validated event
+	const byEvent = new Map<MonitorEvent, Monitor[]>();
+	for (const m of monitors) {
+		const list = byEvent.get(m.event) ?? [];
+		list.push(m);
+		byEvent.set(m.event, list);
+	}
+
+	// wire event handlers
+	for (const [event, group] of byEvent) {
+		if (event === "command") {
+			for (const m of group) {
+				pi.registerCommand(m.name, {
+					description: m.description || `Run ${m.name} monitor`,
+					handler: async (_args: string, ctx: ExtensionContext) => {
+						const branch = ctx.sessionManager.getBranch();
+						await activate(m, pi, ctx, branch, steeredThisTurn, updateStatus);
+					},
+				});
+			}
+		} else if (event === "message_end") {
+			pi.on("message_end", async (ev: MessageEndEvent, ctx: ExtensionContext) => {
+				if (ev.message.role !== "assistant") return;
+				const branch = ctx.sessionManager.getBranch();
+				for (const m of group) {
+					await activate(m, pi, ctx, branch, steeredThisTurn, updateStatus);
+				}
+			});
+		} else if (event === "turn_end") {
+			pi.on("turn_end", async (_ev: TurnEndEvent, ctx: ExtensionContext) => {
+				const branch = ctx.sessionManager.getBranch();
+				for (const m of group) {
+					await activate(m, pi, ctx, branch, steeredThisTurn, updateStatus);
+				}
+			});
+		} else if (event === "agent_end") {
+			pi.on("agent_end", async (_ev: AgentEndEvent, ctx: ExtensionContext) => {
+				const branch = ctx.sessionManager.getBranch();
+				for (const m of group) {
+					await activate(m, pi, ctx, branch, steeredThisTurn, updateStatus);
+				}
+			});
+		}
+	}
+
+	// /monitors command — unified management interface
+	const monitorNames = new Set(monitors.map((m) => m.name));
+	const monitorsByName = new Map(monitors.map((m) => [m.name, m]));
+
+	pi.registerCommand("monitors", {
+		description: "Manage behavior monitors",
+		handler: async (args: string, ctx: ExtensionContext) => {
+			const cmd = parseMonitorsArgs(args, monitorNames);
+
+			if (cmd.type === "error") {
+				ctx.ui.notify(cmd.message, "error");
+				return;
+			}
+
+			if (cmd.type === "list") {
+				handleList(monitors, ctx, monitorsEnabled);
+				return;
+			}
+
+			if (cmd.type === "on") {
+				monitorsEnabled = true;
+				updateStatus();
+				ctx.ui.notify("Monitors enabled", "info");
+				return;
+			}
+
+			if (cmd.type === "off") {
+				monitorsEnabled = false;
+				updateStatus();
+				ctx.ui.notify("All monitors paused for this session", "info");
+				return;
+			}
+
+			const monitor = monitorsByName.get(cmd.name);
+			if (!monitor) {
+				ctx.ui.notify(`Unknown monitor: ${cmd.name}`, "error");
+				return;
+			}
+
+			switch (cmd.type) {
+				case "inspect":
+					handleInspect(monitor, ctx);
+					break;
+				case "rules-list":
+					handleRulesList(monitor, ctx);
+					break;
+				case "rules-add":
+					handleRulesAdd(monitor, ctx, cmd.text);
+					break;
+				case "rules-remove":
+					handleRulesRemove(monitor, ctx, cmd.index);
+					break;
+				case "rules-replace":
+					handleRulesReplace(monitor, ctx, cmd.index, cmd.text);
+					break;
+				case "patterns-list":
+					handlePatternsList(monitor, ctx);
+					break;
+				case "dismiss":
+					monitor.dismissed = true;
+					monitor.whileCount = 0;
+					updateStatus();
+					ctx.ui.notify(`[${monitor.name}] Dismissed for this session`, "info");
+					break;
+				case "reset":
+					monitor.dismissed = false;
+					monitor.whileCount = 0;
+					updateStatus();
+					ctx.ui.notify(`[${monitor.name}] Reset`, "info");
+					break;
+			}
+		},
+	});
+}