@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/extension/compact-tools.ts

@@ -1,9 +1,12 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "../shared/native-typebox.ts";
-import { createSubagentExecutor, normalizeSubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
-import type { SubagentExecutionResult, SubagentState } from "../shared/types.ts";
+import {
+  type createSubagentExecutor,
+  normalizeSubagentParamsLike,
+} from "../runs/foreground/subagent-executor.ts";
+import type { SubagentExecutionResult } from "../shared/types.ts";
+import type { ReadonlyInput } from "../shared/types/inputs.ts";
 import { activateTools, restoreLazyTools } from "../shared/lazy-tools.ts";
-import { runHistoryIndex } from "../runs/shared/history-index.ts";
 import type { HistoryRunOptions } from "../history/types.ts";
 import { listSupervisorQuestionsAsync } from "../runs/shared/supervisor-questions.ts";
 import { renderSubagentResult } from "../tui/render.ts";
@@ -11,104 +14,258 @@ import { AgentRunsParams, DelegateParams } from "./schemas.ts";
 import { normalizeEverydayParams } from "./tool-input.ts";
 
 type Executor = ReturnType<typeof createSubagentExecutor>;
-type AdaptResult = (result: SubagentExecutionResult, ctx: ExtensionContext) => SubagentExecutionResult;
+type AdaptResult = (
+  result: ReadonlyInput<SubagentExecutionResult>,
+  ctx: ExtensionContext,
+) => SubagentExecutionResult;
+type ControlsIndex = { readonly needsControls: () => Promise<boolean> };
+interface RunControlsState {
+  readonly ownedRuns?: { readonly size: number };
+  readonly lastUiContext: ExtensionContext | null;
+  readonly currentSessionId: string | null;
+  readonly historyIndex?: unknown;
+}
+interface ExecutionOptions {
+  readonly executor: Readonly<Executor>;
+  readonly adapt: AdaptResult;
+  readonly listRuns?: (
+    params: ReadonlyInput<HistoryRunOptions>,
+    ctx: ExtensionContext,
+  ) => Promise<SubagentExecutionResult>;
+}
+interface CompactOptions extends ExecutionOptions {
+  readonly state: RunControlsState;
+  readonly getHistoryIndex: () => Promise<ControlsIndex>;
+  readonly guidelines: readonly string[];
+  readonly childSafe?: boolean;
+  readonly keepAdvancedActive?: boolean;
+  readonly asyncByDefault: boolean;
+}
+
+function hasOwnedRunsFor(state: RunControlsState, owner: string | null): boolean {
+  return (
+    (state.lastUiContext?.sessionManager.getSessionId() ?? state.currentSessionId) === owner &&
+    (state.ownedRuns?.size ?? 0) > 0
+  );
+}
+
+async function activateOwnedControls(
+  pi: ExtensionAPI,
+  state: RunControlsState,
+  getHistoryIndex: () => Promise<ControlsIndex>,
+  owner: string | null,
+): Promise<void> {
+  try {
+    const index = await getHistoryIndex();
+    const needed = await index.needsControls();
+    if (state.historyIndex === index && needed) {
+      activateTools(pi, ["agent_runs"]);
+    }
+  } catch {
+    // An unavailable browse index cannot establish that genuine owned work is inert.
+    if (hasOwnedRunsFor(state, owner)) {
+      activateTools(pi, ["agent_runs"]);
+    }
+  }
+}
+
+function createRunControlsReconciler(
+  pi: ExtensionAPI,
+  state: RunControlsState,
+  getHistoryIndex: () => Promise<ControlsIndex>,
+): () => Promise<void> {
+  let checking: { readonly owner: string | null; readonly promise: Promise<void> } | undefined;
+  return (): Promise<void> => {
+    if (pi.getActiveTools().includes("agent_runs") || (state.ownedRuns?.size ?? 0) === 0) {
+      return Promise.resolve();
+    }
+    const owner = state.lastUiContext?.sessionManager.getSessionId() ?? state.currentSessionId;
+    if (checking?.owner === owner) {
+      return checking.promise;
+    }
+    const promise = activateOwnedControls(pi, state, getHistoryIndex, owner);
+    checking = { owner, promise };
+    promise
+      .finally(() => {
+        if (checking?.promise === promise) {
+          checking = undefined;
+        }
+      })
+      .catch((error: unknown) => {
+        console.error("Could not reconcile owned subagent controls:", error);
+      });
+    return promise;
+  };
+}
+
+function registerDelegate(
+  pi: ExtensionAPI,
+  options: Pick<
+    CompactOptions,
+    "executor" | "adapt" | "guidelines" | "childSafe" | "asyncByDefault"
+  >,
+  checkRuns: () => Promise<void>,
+): void {
+  const asyncDescription = options.asyncByDefault
+    ? "Background by default; false waits for the result."
+    : "Foreground by default; true detaches work. Use false when the result must appear in your report.";
+  pi.registerTool({
+    name: "delegate",
+    label: "Delegate",
+    description: `Delegate one bounded task to a configured agent. For profiles/history, load_subagent({advanced:false}) enables agent_runs. Delegation enables run controls automatically. ${asyncDescription} Use worktree for an isolated writer, acceptance for explicit requirements, and fresh context for independent review. Fresh handoffs must include relevant exact user instructions and settled decisions or readable source references, not just summaries, alongside the bounded task. Advanced workflows remain behind load_subagent.`,
+    ...(options.childSafe === true ? { promptGuidelines: [...options.guidelines] } : {}),
+    parameters: Type.Object(
+      {
+        ...DelegateParams.properties,
+        async: Type.Optional(Type.Boolean({ description: asyncDescription })),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(id, params, signal, onUpdate, ctx) {
+      const { worktree, context, async: background, ...task } = normalizeEverydayParams(params);
+      const request =
+        worktree === true
+          ? { tasks: [task], worktree: true, context, async: background, cwd: task.cwd }
+          : { ...task, context, async: background };
+      const result = await options.executor.execute({
+        toolCallId: id,
+        params: normalizeSubagentParamsLike(request),
+        signal,
+        onUpdate,
+        ctx,
+      });
+      await checkRuns();
+      return options.adapt(result, ctx);
+    },
+    renderResult: renderSubagentResult,
+  });
+}
+
+function registerRuns(pi: ExtensionAPI, options: ExecutionOptions, childSafe: boolean): void {
+  pi.registerTool({
+    name: "agent_runs",
+    defaultActive: false,
+    label: "Agent Runs",
+    description: `List ${childSafe ? "only this child's directly owned" : "your delegated"} runs across working directories (questions/failures, then live work, then unreviewed results; 20 per page). Filter globally by agent/state/text, sort, and page with the returned cursor. history reads 100 bounded native-entry previews; search finds saved visible text using words or quoted phrases, not operators or prefixes. questions pages 20 compact previews (offset/limit); questionId selects one, and questionPath/answerPath retain full records. Browse freshness is not completion or delivery proof. Inspect concise results, paths and continuations; full:true includes the full task/configuration. Answer durable questions, nudge, stop, continue, or save parent-only review. Review notes are not sent to children; put actionable instructions in continue/nudge. Inspect/review/nudge never restart finished work. Continue/answer can launch a saved child; async:false waits for its actual result. Saved continuations keep settings unless agent selects a current profile; model overrides win. Live guidance never mutates model or acceptance. profiles lists roles, sources, context and model/thinking/fallback defaults. History survives reload.`,
+    parameters: AgentRunsParams,
+    async execute(id, params, signal, onUpdate, ctx) {
+      const normalized = normalizeEverydayParams(params, true);
+      if (params.action === "list" && params.id === undefined && options.listRuns) {
+        return options.adapt(await options.listRuns({ ...normalized, signal }, ctx), ctx);
+      }
+      const actions = {
+        list: "status",
+        inspect: "status",
+        history: "history",
+        search: "search",
+        nudge: "nudge",
+        stop: "interrupt",
+        continue: "resume",
+        profiles: "list",
+        questions: "questions",
+        answer: "answer",
+        review: "review",
+      };
+      return options.adapt(
+        await options.executor.execute({
+          toolCallId: id,
+          params: normalizeSubagentParamsLike({ ...normalized, action: actions[params.action] }),
+          signal,
+          onUpdate,
+          ctx,
+        }),
+        ctx,
+      );
+    },
+    renderResult: renderSubagentResult,
+  });
+}
+
+function requireAvailableTool(pi: ExtensionAPI, name: string, error: string): void {
+  if (
+    !pi.getAllTools().some((tool) => tool.name === name && !("namespace" in tool && tool.namespace))
+  ) {
+    throw new Error(error);
+  }
+}
+
+function registerLoader(
+  pi: ExtensionAPI,
+  options: Pick<CompactOptions, "guidelines" | "childSafe">,
+): void {
+  pi.registerTool({
+    name: "load_subagent",
+    label: "Load Subagent",
+    description: `Enable agent_runs for profiles, history and run controls; advanced:false loads only those controls. By default also enable advanced subagent orchestration: parallel groups, chains, saved workflows, detailed overrides, get, extend and doctor.${options.childSafe === true ? " Agent-definition mutations remain blocked." : " Includes agent-definition management."} Ordinary delegation and control use delegate and agent_runs. After loading advanced workflows, call subagent with { action: "list" } before execution.`,
+    promptSnippet:
+      "Discover profiles/history with advanced:false, or load full subagent orchestration by default.",
+    parameters: Type.Object({
+      advanced: Type.Optional(
+        Type.Boolean({
+          description:
+            "Also enable advanced orchestration (default true); false loads only agent_runs for profiles, history and controls.",
+        }),
+      ),
+    }),
+    async execute(_id, params) {
+      const advanced = params.advanced !== false;
+      requireAvailableTool(
+        pi,
+        advanced ? "subagent" : "agent_runs",
+        advanced
+          ? "Subagent is unavailable because the full tool is excluded from this session."
+          : "Run controls are excluded from this session.",
+      );
+      const added = !pi.getActiveTools().includes(advanced ? "subagent" : "agent_runs");
+      activateTools(pi, advanced ? ["agent_runs", "subagent"] : ["agent_runs"]);
+      return {
+        content: [
+          {
+            type: "text",
+            text: advanced
+              ? [
+                  `Subagent ${added ? "enabled" : "already enabled"}.`,
+                  ...options.guidelines.map((line) => `- ${line}`),
+                ].join("\n")
+              : "Run controls enabled. Use agent_runs({action:'profiles'}) to discover agents; list, history, or search browses owned saved work.",
+          },
+        ],
+        details: {},
+      };
+    },
+  });
+}
 
-export function registerCompactSubagentTools(pi: ExtensionAPI, options: {
-	executor: Executor;
-	state: SubagentState;
-	adapt: AdaptResult;
-	guidelines: readonly string[];
-	childSafe?: boolean;
-	keepAdvancedActive?: boolean;
-	listRuns?: (params: HistoryRunOptions, ctx: ExtensionContext) => Promise<SubagentExecutionResult>;
-	asyncByDefault: boolean;
-}): () => Promise<void> {
-	const { executor, adapt, guidelines, childSafe, asyncByDefault, state } = options;
-	let checking: { owner: string | null | undefined; promise: Promise<void> } | undefined;
-	const checkRuns = (): Promise<void> => {
-		if (pi.getActiveTools().includes("agent_runs") || !state.ownedRuns?.size) return Promise.resolve();
-		const owner = state.lastUiContext?.sessionManager.getSessionId() ?? state.currentSessionId;
-		if (checking?.owner === owner) return checking.promise;
-		const promise = Promise.resolve().then(async () => {
-			try {
-				const index = await runHistoryIndex(state);
-				const needed = await index.needsControls();
-				if (state.historyIndex === index && needed) activateTools(pi, ["agent_runs"]);
-			} catch {
-				// An unavailable browse index cannot establish that genuine owned work is inert.
-				if ((state.lastUiContext?.sessionManager.getSessionId() ?? state.currentSessionId) === owner && state.ownedRuns?.size) activateTools(pi, ["agent_runs"]);
-			} finally { if (checking?.promise === promise) checking = undefined; }
-		});
-		checking = { owner, promise };
-		return promise;
-	};
-	const reconcileRuns = () => checkRuns();
-	const onRunsChanged = state.onRunsChanged;
-	state.onRunsChanged = () => { reconcileRuns(); onRunsChanged?.(); };
-	const asyncDescription = asyncByDefault ? "Background by default; false waits for the result." : "Foreground by default; true detaches work. Use false when the result must appear in your report.";
-	pi.registerTool({
-		name: "delegate",
-		label: "Delegate",
-		description: `Delegate one bounded task to a configured agent. For profiles/history, load_subagent({advanced:false}) enables agent_runs. Delegation enables run controls automatically. ${asyncDescription} Use worktree for an isolated writer, acceptance for explicit requirements, and fresh context for independent review. Fresh handoffs must include relevant exact user instructions and settled decisions or readable source references, not just summaries, alongside the bounded task. Advanced workflows remain behind load_subagent.`,
-		...(childSafe ? { promptGuidelines: [...guidelines] } : {}),
-		parameters: Type.Object({ ...DelegateParams.properties, async: Type.Optional(Type.Boolean({ description: asyncDescription })) }, { additionalProperties: false }),
-		async execute(id, params, signal, onUpdate, ctx) {
-			const { worktree, context, async: background, ...task } = normalizeEverydayParams(params);
-			const request = worktree
-				? { tasks: [task], worktree: true, context, async: background, cwd: task.cwd }
-				: { ...task, context, async: background };
-			const result = await executor.execute(id, normalizeSubagentParamsLike(request), signal, onUpdate, ctx);
-			await checkRuns();
-			return adapt(result, ctx);
-		},
-		renderResult: renderSubagentResult,
-	});
-	pi.registerTool({
-		name: "agent_runs",
-		defaultActive: false,
-		label: "Agent Runs",
-		description: `List ${childSafe ? "only this child's directly owned" : "your delegated"} runs across working directories (questions/failures, then live work, then unreviewed results; 20 per page). Filter globally by agent/state/text, sort, and page with the returned cursor. history reads 100 bounded native-entry previews; search finds saved visible text using words or quoted phrases, not operators or prefixes. questions pages 20 compact previews (offset/limit); questionId selects one, and questionPath/answerPath retain full records. Browse freshness is not completion or delivery proof. Inspect concise results, paths and continuations; full:true includes the full task/configuration. Answer durable questions, nudge, stop, continue, or save parent-only review. Review notes are not sent to children; put actionable instructions in continue/nudge. Inspect/review/nudge never restart finished work. Continue/answer can launch a saved child; async:false waits for its actual result. Saved continuations keep settings unless agent selects a current profile; model overrides win. Live guidance never mutates model or acceptance. profiles lists roles, sources, context and model/thinking/fallback defaults. History survives reload.`,
-		parameters: AgentRunsParams,
-		async execute(id, params, signal, onUpdate, ctx) {
-			const normalized = normalizeEverydayParams(params, true);
-			if (params.action === "list" && !params.id && options.listRuns) return adapt(await options.listRuns({ ...normalized, signal }, ctx), ctx);
-			const actions = { list: "status", inspect: "status", history: "history", search: "search", nudge: "nudge", stop: "interrupt", continue: "resume", profiles: "list", questions: "questions", answer: "answer", review: "review" };
-			return adapt(await executor.execute(id, normalizeSubagentParamsLike({ ...normalized, action: actions[params.action] }), signal, onUpdate, ctx), ctx);
-		},
-		renderResult: renderSubagentResult,
-	});
-	pi.registerTool({
-		name: "load_subagent",
-		label: "Load Subagent",
-		description: `Enable agent_runs for profiles, history and run controls; advanced:false loads only those controls. By default also enable advanced subagent orchestration: parallel groups, chains, saved workflows, detailed overrides, get, extend and doctor.${childSafe ? " Agent-definition mutations remain blocked." : " Includes agent-definition management."} Ordinary delegation and control use delegate and agent_runs. After loading advanced workflows, call subagent with { action: "list" } before execution.`,
-		promptSnippet: "Discover profiles/history with advanced:false, or load full subagent orchestration by default.",
-		parameters: Type.Object({ advanced: Type.Optional(Type.Boolean({ description: "Also enable advanced orchestration (default true); false loads only agent_runs for profiles, history and controls." })) }),
-		async execute(_id, params) {
-			const advanced = params.advanced !== false;
-			if (advanced && !pi.getAllTools().some((tool) => tool.name === "subagent" && !("namespace" in tool && tool.namespace))) {
-				throw new Error("Subagent is unavailable because the full tool is excluded from this session.");
-			}
-			if (!advanced && !pi.getAllTools().some((tool) => tool.name === "agent_runs" && !("namespace" in tool && tool.namespace))) throw new Error("Run controls are excluded from this session.");
-			const added = !pi.getActiveTools().includes(advanced ? "subagent" : "agent_runs");
-			activateTools(pi, advanced ? ["agent_runs", "subagent"] : ["agent_runs"]);
-			return {
-				content: [{ type: "text" as const, text: advanced ? [`Subagent ${added ? "enabled" : "already enabled"}.`, ...guidelines.map((line) => `- ${line}`)].join("\n") : "Run controls enabled. Use agent_runs({action:'profiles'}) to discover agents; list, history, or search browses owned saved work." }],
-				details: {},
-			};
-		},
-	});
-	const reconcile = async (ctx: ExtensionContext) => {
-		if (options.keepAdvancedActive) activateTools(pi, ["subagent"]);
-		await checkRuns();
-		if (!pi.getActiveTools().includes("agent_runs") && (await listSupervisorQuestionsAsync(ctx.sessionManager.getSessionId())).some((question) => question.state === "awaiting_input" || question.state === "answer_pending")) activateTools(pi, ["agent_runs"]);
-	};
-	const restore = async (event: { reason?: string }, ctx: ExtensionContext) => {
-		if (event.reason !== "reload") restoreLazyTools(pi, ctx, "load_subagent", ["subagent", "agent_runs"]);
-		await reconcile(ctx);
-	};
-	pi.on("session_start", restore);
-	pi.on("session_tree", (_event, ctx) => reconcile(ctx));
-	pi.on("session_compact", (_event, ctx) => reconcile(ctx));
-	pi.on("before_agent_start", (_event, ctx) => reconcile(ctx));
-	return reconcileRuns;
+export function registerCompactSubagentTools(
+  pi: ExtensionAPI,
+  options: CompactOptions,
+): () => Promise<void> {
+  const checkRuns = createRunControlsReconciler(pi, options.state, options.getHistoryIndex);
+  registerDelegate(pi, options, checkRuns);
+  registerRuns(pi, options, options.childSafe === true);
+  registerLoader(pi, options);
+  const reconcile = async (ctx: ExtensionContext): Promise<void> => {
+    if (options.keepAdvancedActive === true) {
+      activateTools(pi, ["subagent"]);
+    }
+    await checkRuns();
+    if (
+      !pi.getActiveTools().includes("agent_runs") &&
+      (await listSupervisorQuestionsAsync(ctx.sessionManager.getSessionId())).some(
+        (question) => question.state === "awaiting_input" || question.state === "answer_pending",
+      )
+    ) {
+      activateTools(pi, ["agent_runs"]);
+    }
+  };
+  pi.on("session_start", async (event, ctx) => {
+    if (event.reason !== "reload") {
+      restoreLazyTools(pi, ctx, "load_subagent", ["subagent", "agent_runs"]);
+    }
+    await reconcile(ctx);
+  });
+  pi.on("session_tree", (_event, ctx) => reconcile(ctx));
+  pi.on("session_compact", (_event, ctx) => reconcile(ctx));
+  pi.on("before_agent_start", (_event, ctx) => reconcile(ctx));
+  return checkRuns;
 }

package/src/extension/config-schema.ts

@@ -0,0 +1,59 @@
+import { Compile, Type } from "../shared/native-typebox.ts";
+
+const policy = Type.Enum(["inherit", "approve", "no-approve"] as const, { type: "string" });
+const optionalNumber = Type.Optional(Type.Number());
+const optionalBoolean = Type.Optional(Type.Boolean());
+const optionalString = Type.Optional(Type.String());
+
+export const extensionConfig = Compile(
+  Type.Object(
+    {
+      compactChildTools: optionalBoolean,
+      asyncByDefault: optionalBoolean,
+      forceTopLevelAsync: optionalBoolean,
+      defaultSessionDir: optionalString,
+      maxSubagentDepth: optionalNumber,
+      worktreeSetupHook: optionalString,
+      worktreeSetupHookTimeoutMs: optionalNumber,
+      projectTrust: Type.Optional(
+        Type.Union([
+          policy,
+          Type.Object({ childRuns: Type.Optional(policy) }, { additionalProperties: true }),
+        ]),
+      ),
+      parallel: Type.Optional(
+        Type.Object(
+          { maxTasks: optionalNumber, concurrency: optionalNumber },
+          { additionalProperties: true },
+        ),
+      ),
+      chain: Type.Optional(
+        Type.Object(
+          {
+            dynamicFanout: Type.Optional(
+              Type.Object({ maxItems: optionalNumber }, { additionalProperties: true }),
+            ),
+          },
+          { additionalProperties: true },
+        ),
+      ),
+      control: Type.Optional(
+        Type.Object(
+          {
+            enabled: optionalBoolean,
+            needsAttentionAfterMs: optionalNumber,
+            failedToolAttemptsBeforeAttention: optionalNumber,
+            notifyOn: Type.Optional(
+              Type.Array(Type.Enum(["needs_attention"] as const, { type: "string" })),
+            ),
+            notifyChannels: Type.Optional(
+              Type.Array(Type.Enum(["event", "async", "intercom"] as const, { type: "string" })),
+            ),
+          },
+          { additionalProperties: true },
+        ),
+      ),
+    },
+    { additionalProperties: true },
+  ),
+);

package/src/extension/config.ts

@@ -1,23 +1,45 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionConfig } from "../shared/types.ts";
-import { getAgentDir } from "../shared/utils.ts";
+import { getAgentDir } from "../shared/agent-dir.ts";
+import { isRecord } from "../shared/unknown.ts";
+import { extensionConfig } from "./config-schema.ts";
+
+function normalizedTrust(
+  config: Readonly<Record<string, unknown>>,
+  configPath: string,
+): Readonly<Record<string, unknown>> {
+  const trust = config.projectTrust;
+  const childRuns = isRecord(trust) ? trust.childRuns : trust;
+  if (
+    childRuns !== undefined &&
+    childRuns !== "inherit" &&
+    childRuns !== "approve" &&
+    childRuns !== "no-approve"
+  ) {
+    console.error(`Invalid projectTrust in '${configPath}'; child runs will use no-approve.`);
+    return { ...config, projectTrust: "no-approve" };
+  }
+  return config;
+}
 
 export function loadConfig(): ExtensionConfig {
-	const configPath = path.join(getAgentDir(), "extensions", "subagent", "config.json");
-	try {
-		if (fs.existsSync(configPath)) {
-			const config = JSON.parse(fs.readFileSync(configPath, "utf-8")) as ExtensionConfig;
-			const trust = config.projectTrust;
-			const childRuns = typeof trust === "object" && trust !== null ? trust.childRuns : trust;
-			if (childRuns !== undefined && childRuns !== "inherit" && childRuns !== "approve" && childRuns !== "no-approve") {
-				console.error(`Invalid projectTrust in '${configPath}'; child runs will use no-approve.`);
-				config.projectTrust = "no-approve";
-			}
-			return config;
-		}
-	} catch (error) {
-		console.error(`Failed to load subagent config from '${configPath}':`, error);
-	}
-	return {};
+  const configPath = path.join(getAgentDir(), "extensions", "subagent", "config.json");
+  try {
+    if (!fs.existsSync(configPath)) {
+      return {};
+    }
+    const parsed: unknown = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    if (!isRecord(parsed)) {
+      throw new Error("Subagent configuration must be an object.");
+    }
+    const config = normalizedTrust(parsed, configPath);
+    if (!extensionConfig.Check(config)) {
+      throw new Error([...extensionConfig.Errors(config)].map((error) => error.message).join("; "));
+    }
+    return config;
+  } catch (error) {
+    console.error(`Failed to load subagent config from '${configPath}':`, error);
+    return {};
+  }
 }

package/src/extension/control-notice-schema.ts

@@ -0,0 +1,55 @@
+import { Compile, Type } from "../shared/native-typebox.ts";
+import type { SubagentControlMessageDetails } from "./control-notices.ts";
+
+const optionalString = Type.Optional(Type.String());
+const optionalNumber = Type.Optional(Type.Number());
+const attention = Type.Enum(["needs_attention"] as const, { type: "string" });
+const notice = Compile(
+  Type.Object(
+    {
+      event: Type.Object(
+        {
+          type: attention,
+          from: Type.Optional(attention),
+          to: attention,
+          ts: Type.Number(),
+          agent: Type.String(),
+          runId: Type.String(),
+          message: Type.String(),
+          index: optionalNumber,
+          reason: Type.Optional(
+            Type.Enum(["idle", "completion_guard", "tool_failures"] as const, { type: "string" }),
+          ),
+          turns: optionalNumber,
+          tokens: optionalNumber,
+          toolCount: optionalNumber,
+          currentTool: optionalString,
+          currentToolDurationMs: optionalNumber,
+          currentPath: optionalString,
+          elapsedMs: optionalNumber,
+          recentFailureSummary: optionalString,
+          supervisorQuestion: Type.Optional(
+            Type.Object(
+              {
+                questionId: Type.String(),
+                state: Type.Enum(["awaiting_input", "answer_pending"] as const, { type: "string" }),
+                answer: optionalString,
+              },
+              { additionalProperties: true },
+            ),
+          ),
+        },
+        { additionalProperties: true },
+      ),
+      source: Type.Optional(Type.Enum(["foreground", "async"] as const, { type: "string" })),
+      asyncDir: optionalString,
+      childIntercomTarget: optionalString,
+      noticeText: optionalString,
+    },
+    { additionalProperties: true },
+  ),
+);
+
+export function parseControlNotice(value: unknown): SubagentControlMessageDetails | undefined {
+  return notice.Check(value) ? value : undefined;
+}

package/src/extension/control-notices.ts

@@ -1,47 +1,71 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { controlNotificationKey, formatControlNoticeMessage, isObsoleteIdleNotice } from "../runs/shared/subagent-control.ts";
+import {
+  controlNotificationKey,
+  formatControlNoticeMessage,
+  isObsoleteIdleNotice,
+} from "../runs/shared/subagent-control.ts";
 import type { ControlEvent } from "../shared/types.ts";
 
 export const SUBAGENT_CONTROL_MESSAGE_TYPE = "subagent_control_notice";
 
 export interface SubagentControlMessageDetails {
-	event: ControlEvent;
-	source?: "foreground" | "async";
-	asyncDir?: string;
-	childIntercomTarget?: string;
-	noticeText?: string;
+  readonly event: ControlEvent;
+  readonly source?: "foreground" | "async";
+  readonly asyncDir?: string;
+  readonly childIntercomTarget?: string;
+  readonly noticeText?: string;
 }
 
 export function controlNoticeTarget(details: SubagentControlMessageDetails): string | undefined {
-	return details.childIntercomTarget;
+  return details.childIntercomTarget;
 }
 
-export function formatSubagentControlNotice(details: SubagentControlMessageDetails, content?: string): string {
-	return details.noticeText ?? content ?? formatControlNoticeMessage(details.event, controlNoticeTarget(details));
+export function formatSubagentControlNotice(
+  details: SubagentControlMessageDetails,
+  content?: string,
+): string {
+  return (
+    details.noticeText ??
+    content ??
+    formatControlNoticeMessage(details.event, controlNoticeTarget(details))
+  );
 }
 
-export function handleSubagentControlNotice(input: {
-	pi: Pick<ExtensionAPI, "sendMessage">;
-	visibleControlNotices: Set<string>;
-	details: SubagentControlMessageDetails;
-}): void {
-	if (!input.details?.event || isObsoleteIdleNotice(input.details)) return;
-	const childIntercomTarget = controlNoticeTarget(input.details);
-	const key = controlNotificationKey(input.details.event, childIntercomTarget);
-	if (input.visibleControlNotices.has(key)) return;
-	input.visibleControlNotices.add(key);
-	const noticeText = input.details.noticeText ?? formatControlNoticeMessage(input.details.event, childIntercomTarget);
-	input.pi.sendMessage(
-		{
-			customType: SUBAGENT_CONTROL_MESSAGE_TYPE,
-			content: noticeText,
-			display: true,
-			details: { ...input.details, childIntercomTarget, noticeText },
-		},
-		// Async completion-guard notices stay visible but let the matching completion
-		// result deliver the single automatic wakeup. In a parallel group that result
-		// arrives only after all siblings finish, so reaction to a mid-group guard
-		// notice is bounded by the longest-running sibling.
-		{ triggerTurn: !(input.details.source === "async" && input.details.event.reason === "completion_guard") },
-	);
+/** The runtime supplies its mutable dedup owner; delivery adds exactly one visible-notice key. */
+interface ControlNoticeDeliveryInput {
+  readonly pi: Pick<ExtensionAPI, "sendMessage">;
+  readonly visibleControlNotices: Set<string>;
+  readonly details: SubagentControlMessageDetails;
+}
+
+export function handleSubagentControlNotice(input: ControlNoticeDeliveryInput): void {
+  if (isObsoleteIdleNotice(input.details)) {
+    return;
+  }
+  const childIntercomTarget = controlNoticeTarget(input.details);
+  const key = controlNotificationKey(input.details.event, childIntercomTarget);
+  if (input.visibleControlNotices.has(key)) {
+    return;
+  }
+  input.visibleControlNotices.add(key);
+  const noticeText =
+    input.details.noticeText ??
+    formatControlNoticeMessage(input.details.event, childIntercomTarget);
+  input.pi.sendMessage(
+    {
+      customType: SUBAGENT_CONTROL_MESSAGE_TYPE,
+      content: noticeText,
+      display: true,
+      details: { ...input.details, childIntercomTarget, noticeText },
+    },
+    // Async completion-guard notices stay visible but let the matching completion
+    // result deliver the single automatic wakeup. In a parallel group that result
+    // arrives only after all siblings finish, so reaction to a mid-group guard
+    // notice is bounded by the longest-running sibling.
+    {
+      triggerTurn: !(
+        input.details.source === "async" && input.details.event.reason === "completion_guard"
+      ),
+    },
+  );
 }