@yandy0725/pi-subagents 0.1.0

package/src/lifecycle/turn-limits.ts

@@ -0,0 +1,13 @@
+/**
+ * turn-limits.ts — Pure turn-limit normalization for subagent execution.
+ *
+ * Extracted from agent-runner.ts (issue #265) so the turn-counting policy has a
+ * focused home independent of session assembly. Consumed by the subagent tool's
+ * spawn-config resolution and by the turn loop in SubagentSession.
+ */
+
+/** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
+export function normalizeMaxTurns(n: number | undefined): number | undefined {
+	if (n == null || n === 0) return undefined;
+	return Math.max(1, n);
+}

package/src/lifecycle/usage.ts

@@ -0,0 +1,65 @@
+/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
+
+/**
+ * Lifetime usage components, accumulated via `message_end` events. Survives
+ * compaction (which replaces session.state.messages and would reset any
+ * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
+ * the cumulative cached prefix re-read on that one call — summing across
+ * turns counts the prefix N times. See issue #38.
+ */
+export type LifetimeUsage = { input: number; output: number; cacheWrite: number };
+
+/** Sum of lifetime usage components, or 0 if undefined. */
+export function getLifetimeTotal(u?: LifetimeUsage): number {
+	return u ? u.input + u.output + u.cacheWrite : 0;
+}
+
+/** Add a usage delta into a target accumulator (mutates target). */
+export function addUsage(into: LifetimeUsage, delta: LifetimeUsage): void {
+	into.input += delta.input;
+	into.output += delta.output;
+	into.cacheWrite += delta.cacheWrite;
+}
+
+/** Minimal shape we read from upstream `getSessionStats()`. */
+export type SessionStatsLike = {
+	tokens: { input: number; output: number; cacheWrite: number };
+	contextUsage?: { percent: number | null };
+};
+export type SessionLike = { getSessionStats(): SessionStatsLike };
+
+/**
+ * Session-scoped token count: input + output + cacheWrite as reported by
+ * upstream `getSessionStats().tokens` for the *current* session window.
+ *
+ * RESETS at compaction — upstream replaces `session.state.messages` and the
+ * stats are derived from that array. For a lifetime total that survives
+ * compaction, use `getLifetimeTotal(lifetimeUsage)` instead, which reads
+ * from an independent accumulator fed by `message_end` events.
+ *
+ * Avoids upstream's `tokens.total` field, which sums per-turn `cacheRead`
+ * and so counts the cumulative cached prefix N times across N turns
+ * (issue #38).
+ */
+export function getSessionTokens(session: SessionLike | undefined): number {
+	if (!session) return 0;
+	try {
+		const t = session.getSessionStats().tokens;
+		return t.input + t.output + t.cacheWrite;
+	} catch {
+		return 0;
+	}
+}
+
+/**
+ * Context-window utilization (0–100), or null when unavailable
+ * (no model contextWindow, or post-compaction before the next response).
+ */
+export function getSessionContextPercent(session: SessionLike | undefined): number | null {
+	if (!session) return null;
+	try {
+		return session.getSessionStats().contextUsage?.percent ?? null;
+	} catch {
+		return null;
+	}
+}

package/src/lifecycle/workspace-bracket.ts

@@ -0,0 +1,59 @@
+/**
+ * workspace-bracket.ts — Owned prepare/dispose lifecycle for a child workspace.
+ *
+ * Captures the provider resolver (not the provider itself) so provider
+ * resolution stays lazy at run-start. The prepared Workspace is held
+ * privately; dispose() centralises the guard and addendum-unwrap so callers
+ * never reach through to workspace.dispose().resultAddendum directly.
+ *
+ * dispose() deliberately does NOT catch errors — the best-effort try/catch
+ * for failRun() belongs at the call site, preserving the per-caller semantics.
+ */
+
+import type {
+	Workspace,
+	WorkspaceDisposeOutcome,
+	WorkspacePrepareContext,
+	WorkspaceProvider,
+} from "../lifecycle/workspace";
+
+/** Owns the child workspace lifecycle: prepare at run-start, dispose at run-end. */
+export class WorkspaceBracket {
+	private prepared?: Workspace;
+
+	constructor(private readonly resolveProvider: () => WorkspaceProvider | undefined) {}
+
+	/**
+	 * Returns true when a workspace provider is currently registered.
+	 * Use to guard the `await prepare(...)` call and avoid an unnecessary
+	 * microtask boundary in the no-provider path.
+	 */
+	hasProvider(): boolean {
+		return this.resolveProvider() !== undefined;
+	}
+
+	/**
+	 * Resolve the registered provider and prepare the child workspace.
+	 * Returns the workspace's cwd, or undefined when no provider is registered
+	 * or the provider resolves to undefined.
+	 */
+	async prepare(ctx: WorkspacePrepareContext): Promise<string | undefined> {
+		const provider = this.resolveProvider();
+		if (!provider) return undefined;
+		this.prepared = await provider.prepare(ctx);
+		return this.prepared?.cwd;
+	}
+
+	/**
+	 * Dispose the prepared workspace (if any) and return the result addendum
+	 * verbatim. Returns an empty string when no workspace was prepared or when
+	 * the workspace returns no addendum.
+	 *
+	 * Throws propagate — wrap in try/catch at the call site when best-effort
+	 * disposal is desired (e.g. failRun).
+	 */
+	dispose(outcome: WorkspaceDisposeOutcome): string {
+		if (!this.prepared) return "";
+		return this.prepared.dispose(outcome)?.resultAddendum ?? "";
+	}
+}

package/src/lifecycle/workspace.ts

@@ -0,0 +1,47 @@
+/**
+ * workspace.ts — The single generative extension seam (ADR 0002, Phase 16 Step 2).
+ *
+ * "Where does a child run, and what brackets the run?" is a strategy (git
+ * worktree, container, tmpdir, remote sandbox), not core behavior. The core
+ * needs only a working directory plus a disposal hook; the default — the
+ * parent's cwd, with no setup/teardown — is always correct.
+ *
+ * Unlike the observational lifecycle events in child-lifecycle.ts, this is a
+ * *generative* seam: a registered provider returns a value the core consumes
+ * synchronously at run-start. The core has no knowledge of git or worktrees.
+ */
+
+import type { SubagentStatus } from "../lifecycle/subagent";
+import type { AgentInvocation, SubagentType } from "../types";
+
+/** Context the core hands a provider when a child run starts. */
+export interface WorkspacePrepareContext {
+	agentId: string;
+	agentType: SubagentType;
+	baseCwd: string;
+	invocation?: AgentInvocation;
+}
+
+/** Outcome the core reports to a workspace when the run ends. */
+export interface WorkspaceDisposeOutcome {
+	status: SubagentStatus;
+	description: string;
+}
+
+/** What dispose may hand back for the core to fold into the child result. */
+export interface WorkspaceDisposeResult {
+	/** Appended verbatim to the child's result text — the provider owns the wording. */
+	resultAddendum?: string;
+}
+
+/** A prepared working directory plus its bracketed teardown. Born complete. */
+export interface Workspace {
+	/** The working directory — already exists when the workspace is handed back. */
+	readonly cwd: string;
+	dispose(outcome: WorkspaceDisposeOutcome): WorkspaceDisposeResult | undefined;
+}
+
+/** The single generative seam: supplies a child's workspace. */
+export interface WorkspaceProvider {
+	prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
+}

package/src/observation/composite-subagent-observer.ts

@@ -0,0 +1,49 @@
+import { debugLog } from "../debug";
+import type { SubagentManagerObserver } from "../lifecycle/subagent-manager";
+import type { CompactionInfo, Subagent } from "../types";
+
+/**
+ * Fans out SubagentManager lifecycle notifications to multiple observers.
+ *
+ * Lets the manager keep its single-observer contract while several independent
+ * consumers (event/notification dispatch, the reactive widget) subscribe.
+ * Each delegate is isolated: a throw in one does not suppress the others.
+ */
+export class CompositeSubagentObserver implements SubagentManagerObserver {
+	private readonly delegates: SubagentManagerObserver[];
+
+	constructor(delegates: SubagentManagerObserver[]) {
+		this.delegates = [...delegates];
+	}
+
+	/** Register an additional observer (breaks the widget↔manager construction cycle). */
+	add(observer: SubagentManagerObserver): void {
+		this.delegates.push(observer);
+	}
+
+	onSubagentStarted(record: Subagent): void {
+		this.dispatch((o) => o.onSubagentStarted(record), "onSubagentStarted");
+	}
+
+	onSubagentCreated(record: Subagent): void {
+		this.dispatch((o) => o.onSubagentCreated(record), "onSubagentCreated");
+	}
+
+	onSubagentCompleted(record: Subagent): void {
+		this.dispatch((o) => o.onSubagentCompleted(record), "onSubagentCompleted");
+	}
+
+	onSubagentCompacted(record: Subagent, info: CompactionInfo): void {
+		this.dispatch((o) => o.onSubagentCompacted(record, info), "onSubagentCompacted");
+	}
+
+	private dispatch(call: (o: SubagentManagerObserver) => void, label: string): void {
+		for (const o of this.delegates) {
+			try {
+				call(o);
+			} catch (err) {
+				debugLog(`CompositeSubagentObserver.${label}`, err);
+			}
+		}
+	}
+}

package/src/observation/notification-state.ts

@@ -0,0 +1,27 @@
+/**
+ * notification-state.ts — NotificationState: notification-scoped tracking per background agent.
+ *
+ * Constructed once when agent-tool assigns the tool call ID (background agents only).
+ * Foreground agents never get a NotificationState — record.notification stays undefined.
+ */
+
+export class NotificationState {
+	/** The tool call ID that spawned this background agent. Used in task-notification XML. */
+	readonly toolCallId: string;
+
+	private _resultConsumed = false;
+
+	constructor(toolCallId: string) {
+		this.toolCallId = toolCallId;
+	}
+
+	/** Whether the parent agent has already consumed this result (suppresses duplicate notifications). */
+	get resultConsumed(): boolean {
+		return this._resultConsumed;
+	}
+
+	/** Mark the result as consumed — suppresses the completion notification. */
+	markConsumed(): void {
+		this._resultConsumed = true;
+	}
+}

package/src/observation/notification.ts

@@ -0,0 +1,186 @@
+import { debugLog } from "../debug";
+import { getLifetimeTotal } from "../lifecycle/usage";
+import type { Subagent } from "../types";
+
+/** Details attached to custom notification messages for visual rendering. */
+export interface NotificationDetails {
+	id: string;
+	description: string;
+	status: string;
+	toolUses: number;
+	turnCount: number;
+	maxTurns?: number;
+	totalTokens: number;
+	durationMs: number;
+	outputFile?: string;
+	error?: string;
+	resultPreview: string;
+}
+
+// ---- Pure helpers (exported for unit testing) ----
+
+/** Escape XML special characters to prevent injection in structured notifications. */
+export function escapeXml(s: string): string {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Human-readable status label for agent completion. */
+export function getStatusLabel(status: string, error?: string): string {
+	switch (status) {
+		case "error":
+			return `Error: ${error ?? "unknown"}`;
+		case "aborted":
+			return "Aborted (max turns exceeded)";
+		case "steered":
+			return "Wrapped up (turn limit)";
+		case "stopped":
+			return "Stopped";
+		default:
+			return "Done";
+	}
+}
+
+/** Format a structured <task-notification> XML block for the parent agent to parse. */
+export function formatTaskNotification(record: Subagent, resultMaxLen: number): string {
+	const status = getStatusLabel(record.status, record.error);
+	const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
+	const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+	const contextPercent = record.getContextPercent();
+	const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
+	const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
+
+	const resultPreview = record.result
+		? record.result.length > resultMaxLen
+			? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)"
+			: record.result
+		: "No output.";
+
+	const toolCallId = record.notification?.toolCallId;
+	const outputFile = record.outputFile;
+	return [
+		"<task-notification>",
+		`<task-id>${record.id}</task-id>`,
+		toolCallId ? `<tool-use-id>${escapeXml(toolCallId)}</tool-use-id>` : null,
+		outputFile ? `<output-file>${escapeXml(outputFile)}</output-file>` : null,
+		`<status>${escapeXml(status)}</status>`,
+		`<summary>Subagent "${escapeXml(record.description)}" ${record.status}</summary>`,
+		`<result>${escapeXml(resultPreview)}</result>`,
+		`<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
+		"</task-notification>",
+	]
+		.filter(Boolean)
+		.join("\n");
+}
+
+/** Build notification details for the custom message renderer. */
+export function buildNotificationDetails(record: Subagent, resultMaxLen: number): NotificationDetails {
+	const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+
+	return {
+		id: record.id,
+		description: record.description,
+		status: record.status,
+		toolUses: record.toolUses,
+		turnCount: record.turnCount,
+		maxTurns: record.maxTurns,
+		totalTokens,
+		durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
+		outputFile: record.outputFile,
+		error: record.error,
+		resultPreview: record.result
+			? record.result.length > resultMaxLen
+				? record.result.slice(0, resultMaxLen) + "…"
+				: record.result
+			: "No output.",
+	};
+}
+
+/** Build event data for lifecycle events from a Subagent. */
+export function buildEventData(record: Subagent) {
+	const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;
+	const u = record.lifetimeUsage;
+	const total = getLifetimeTotal(u);
+	const tokens = total > 0 ? { input: u.input, output: u.output, total } : undefined;
+	return {
+		id: record.id,
+		type: record.type,
+		description: record.description,
+		result: record.result,
+		error: record.error,
+		status: record.status,
+		toolUses: record.toolUses,
+		durationMs,
+		tokens,
+	};
+}
+
+// ---- Notification system factory ----
+
+export interface NotificationSystem {
+	cancelNudge: (key: string) => void;
+	sendCompletion: (record: Subagent) => void;
+	dispose: () => void;
+}
+
+const NUDGE_HOLD_MS = 200;
+
+export class NotificationManager implements NotificationSystem {
+	private pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
+
+	constructor(
+		private sendMessage: (
+			msg: { customType: string; content: string; display: boolean; details?: unknown },
+			opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+		) => void,
+	) {}
+
+	cancelNudge(key: string): void {
+		const timer = this.pendingNudges.get(key);
+		if (timer != null) {
+			clearTimeout(timer);
+			this.pendingNudges.delete(key);
+		}
+	}
+
+	sendCompletion(record: Subagent): void {
+		this.scheduleNudge(record.id, () => this.emitIndividualNudge(record));
+	}
+
+	dispose(): void {
+		for (const timer of this.pendingNudges.values()) clearTimeout(timer);
+		this.pendingNudges.clear();
+	}
+
+	private scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS): void {
+		this.cancelNudge(key);
+		this.pendingNudges.set(
+			key,
+			setTimeout(() => {
+				this.pendingNudges.delete(key);
+				try {
+					send();
+				} catch (err) {
+					debugLog("notification render", err);
+				}
+			}, delay),
+		);
+	}
+
+	private emitIndividualNudge(record: Subagent): void {
+		if (record.notification?.resultConsumed) return;
+
+		const notification = formatTaskNotification(record, 500);
+		const outputFile = record.outputFile;
+		const footer = outputFile ? `\nFull transcript available at: ${outputFile}` : "";
+
+		this.sendMessage(
+			{
+				customType: "subagent-notification",
+				content: notification + footer,
+				display: true,
+				details: buildNotificationDetails(record, 500),
+			},
+			{ deliverAs: "followUp", triggerTurn: true },
+		);
+	}
+}

package/src/observation/record-observer.ts

@@ -0,0 +1,75 @@
+/**
+ * record-observer.ts — Subscribes to session events and accumulates SubagentState stats.
+ *
+ * Replaces the scattered callback-wrapping logic in SubagentManager's startAgent()
+ * and resume() with a single direct subscription. The observer targets the
+ * SubagentState value object directly, so it carries no dependency on Subagent;
+ * the caller forwards itself to its own lifecycle observer via onCompact.
+ */
+
+import type { SubagentState } from "../lifecycle/subagent-state";
+import type { CompactionInfo, SubscribableSession } from "../types";
+
+export interface SubagentObserverOptions {
+	onCompact?: (info: CompactionInfo) => void;
+}
+
+/**
+ * Subscribe to session events and accumulate stats on the subagent state.
+ *
+ * Handles:
+ * - `tool_execution_start` → `state.addActiveTool(name)`
+ * - `tool_execution_end` → `state.removeActiveTool(name)`, `state.incrementToolUses()`
+ * - `message_start` → `state.resetResponseText()`
+ * - `message_update` (text_delta) → `state.appendResponseText(delta)`
+ * - `message_end` (assistant, with usage) → `state.addUsage(…)`
+ * - `turn_end` → `state.incrementTurnCount()`
+ * - `compaction_end` (not aborted) → `state.incrementCompactions()`, call `onCompact`
+ *
+ * @returns An unsubscribe function.
+ */
+export function subscribeSubagentObserver(
+	session: SubscribableSession,
+	state: SubagentState,
+	options?: SubagentObserverOptions,
+): () => void {
+	return session.subscribe((event) => {
+		if (event.type === "tool_execution_start") {
+			state.addActiveTool(event.toolName);
+		}
+
+		if (event.type === "tool_execution_end") {
+			state.removeActiveTool(event.toolName);
+			state.incrementToolUses();
+		}
+
+		if (event.type === "message_start") {
+			state.resetResponseText();
+		}
+
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			state.appendResponseText(event.assistantMessageEvent.delta);
+		}
+
+		if (event.type === "turn_end") {
+			state.incrementTurnCount();
+		}
+
+		if (event.type === "message_end" && event.message.role === "assistant") {
+			const u = event.message.usage;
+			state.addUsage({
+				input: u.input,
+				output: u.output,
+				cacheWrite: u.cacheWrite,
+			});
+		}
+
+		if (event.type === "compaction_end" && !event.aborted && event.result) {
+			state.incrementCompactions();
+			options?.onCompact?.({
+				reason: event.reason,
+				tokensBefore: event.result.tokensBefore,
+			});
+		}
+	});
+}

package/src/observation/renderer.ts

@@ -0,0 +1,63 @@
+import { Text } from "@earendil-works/pi-tui";
+import type { NotificationDetails } from "../observation/notification";
+import { formatMs, formatTokens, formatTurns } from "../ui/display";
+
+/** Narrow theme interface — only the methods the renderer actually calls. */
+interface RendererTheme {
+	fg(style: string, text: string): string;
+	bold(text: string): string;
+}
+
+/** Narrow message interface — only the fields the renderer reads. */
+interface RendererMessage {
+	details?: NotificationDetails;
+}
+
+/** Narrow render options — only the fields the renderer reads. */
+interface RenderOptions {
+	expanded: boolean;
+}
+
+/**
+ * Create the notification renderer callback for `pi.registerMessageRenderer`.
+ * Returns a factory so the renderer is independently testable without the Pi SDK.
+ */
+export function createNotificationRenderer() {
+	return (message: RendererMessage, { expanded }: RenderOptions, theme: RendererTheme): Text | undefined => {
+		const d = message.details;
+		if (!d) return undefined;
+
+		const isError = d.status === "error" || d.status === "stopped" || d.status === "aborted";
+		const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
+		const statusText = isError ? d.status : d.status === "steered" ? "completed (steered)" : "completed";
+
+		// Line 1: icon + agent description + status
+		let line = `${icon} ${theme.bold(d.description)} ${theme.fg("dim", statusText)}`;
+
+		// Line 2: stats
+		const parts: string[] = [];
+		if (d.turnCount > 0) parts.push(formatTurns(d.turnCount, d.maxTurns));
+		if (d.toolUses > 0) parts.push(`${d.toolUses} tool use${d.toolUses === 1 ? "" : "s"}`);
+		if (d.totalTokens > 0) parts.push(formatTokens(d.totalTokens));
+		if (d.durationMs > 0) parts.push(formatMs(d.durationMs));
+		if (parts.length) {
+			line += "\n  " + parts.map((p) => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
+		}
+
+		// Line 3: result preview (collapsed) or full (expanded)
+		if (expanded) {
+			const lines = d.resultPreview.split("\n").slice(0, 30);
+			for (const l of lines) line += "\n" + theme.fg("dim", `  ${l}`);
+		} else {
+			const preview = d.resultPreview.split("\n")[0]?.slice(0, 80) ?? "";
+			line += "\n  " + theme.fg("dim", `⎿  ${preview}`);
+		}
+
+		// Line 4: output file link (if present)
+		if (d.outputFile) {
+			line += "\n  " + theme.fg("muted", `transcript: ${d.outputFile}`);
+		}
+
+		return new Text(line, 0, 0);
+	};
+}

package/src/observation/subagent-events-observer.ts

@@ -0,0 +1,94 @@
+import type { SubagentManagerObserver } from "../lifecycle/subagent-manager";
+import { buildEventData, type NotificationSystem } from "../observation/notification";
+import type { CompactionInfo, Subagent } from "../types";
+
+/** Emit callback — a subset of `pi.events.emit`. */
+export type EventEmit = (channel: string, data: unknown) => void;
+
+/** Append callback — a subset of `pi.appendEntry`. */
+export type AppendEntry = (customType: string, data: unknown) => void;
+
+export interface SubagentEventsObserverDeps {
+	emit: EventEmit;
+	appendEntry: AppendEntry;
+	notifications: NotificationSystem;
+}
+
+/**
+ * Receives agent lifecycle notifications from SubagentManager and dispatches
+ * them to three concerns: pi.events lifecycle events, session-entry persistence,
+ * and completion notifications.
+ *
+ * Constructed with narrow deps (emit, appendEntry, NotificationSystem) so all
+ * three concerns are unit-testable without booting the extension.
+ */
+export class SubagentEventsObserver implements SubagentManagerObserver {
+	private readonly emit: EventEmit;
+	private readonly appendEntry: AppendEntry;
+	private readonly notifications: NotificationSystem;
+
+	constructor(deps: SubagentEventsObserverDeps) {
+		this.emit = deps.emit;
+		this.appendEntry = deps.appendEntry;
+		this.notifications = deps.notifications;
+	}
+
+	onSubagentStarted(record: Subagent): void {
+		// Emit started event when agent transitions to running (including from queue).
+		this.emit("subagents:started", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+		});
+	}
+
+	onSubagentCompleted(record: Subagent): void {
+		// Emit lifecycle event based on terminal status.
+		const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
+		const eventData = buildEventData(record);
+		if (isError) {
+			this.emit("subagents:failed", eventData);
+		} else {
+			this.emit("subagents:completed", eventData);
+		}
+
+		// Persist final record for cross-extension history reconstruction.
+		this.appendEntry("subagents:record", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			status: record.status,
+			result: record.result,
+			error: record.error,
+			startedAt: record.startedAt,
+			completedAt: record.completedAt,
+		});
+
+		// Skip notification if result was already consumed via get_subagent_result.
+		if (record.notification?.resultConsumed) return;
+
+		this.notifications.sendCompletion(record);
+	}
+
+	onSubagentCompacted(record: Subagent, info: CompactionInfo): void {
+		// Emit compacted event when agent's session compacts (preserves count on record).
+		this.emit("subagents:compacted", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			reason: info.reason,
+			tokensBefore: info.tokensBefore,
+			compactionCount: record.compactionCount,
+		});
+	}
+
+	onSubagentCreated(record: Subagent): void {
+		// Emit created event for background agents (before limiter admission).
+		this.emit("subagents:created", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			isBackground: true,
+		});
+	}
+}