pi-subagents 0.21.2 → 0.21.3

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [0.21.3] - 2026-04-30
+
+### Fixed
+- Debounce foreground `needs_attention` notices, make them non-triggering, and cancel them when the run finishes so stale chain-step alerts do not launch parent turns after completion.
+
 ## [0.21.2] - 2026-04-30
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.21.2",
+  "version": "0.21.3",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/skills/pi-subagents/SKILL.md

@@ -261,6 +261,8 @@ without forcing each step to rediscover everything.
 
 ### Async/background
 
+Use async mode whenever the parent agent should keep working while a child runs. A normal foreground `subagent(...)` call blocks the parent until the child completes; it is appropriate when the next parent step depends on the child result. If you say you will "ask a reviewer while I continue auditing" or otherwise run local work in parallel with a child, launch with `async: true`. Do not end your turn immediately after launching that async child if you promised to keep working; continue the local inspection or other independent work, then check the async run when its result is needed.
+
 ```typescript
 subagent({
   agent: "worker",
@@ -269,6 +271,18 @@ subagent({
 })
 ```
 
+For review fanout where the parent continues a local audit:
+
+```typescript
+const run = subagent({
+  agent: "reviewer",
+  task: "Review the current diff for correctness issues. Do not edit files.",
+  async: true,
+  context: "fresh"
+})
+// Continue local inspection, then later call status with the returned id.
+```
+
 Inspect async runs with `subagent({ action: "status", id: "..." })`, `subagent({ action: "status" })` for active runs, or the `/subagents-status` slash command.
 
 Use diagnostics when setup or child startup looks wrong:

package/src/extension/control-notices.ts

@@ -0,0 +1,92 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { controlNotificationKey, formatControlNoticeMessage } from "../runs/shared/subagent-control.ts";
+import type { ControlEvent, SubagentState } 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;
+}
+
+export function controlNoticeTarget(details: SubagentControlMessageDetails): string | undefined {
+	return details.childIntercomTarget;
+}
+
+export function formatSubagentControlNotice(details: SubagentControlMessageDetails, content?: string): string {
+	return details.noticeText ?? content ?? formatControlNoticeMessage(details.event, controlNoticeTarget(details));
+}
+
+function noticeTimerKey(details: SubagentControlMessageDetails): string {
+	const childIntercomTarget = controlNoticeTarget(details);
+	return `${details.event.runId}:${controlNotificationKey(details.event, childIntercomTarget)}`;
+}
+
+export function clearPendingForegroundControlNotices(state: SubagentState, runId?: string): void {
+	const pending = state.pendingForegroundControlNotices;
+	if (!pending) return;
+	for (const [key, timer] of pending) {
+		if (runId !== undefined && !key.startsWith(`${runId}:`)) continue;
+		clearTimeout(timer);
+		pending.delete(key);
+	}
+}
+
+function deliverControlNotice(input: {
+	pi: Pick<ExtensionAPI, "sendMessage">;
+	visibleControlNotices: Set<string>;
+	details: SubagentControlMessageDetails;
+}): void {
+	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 },
+		},
+		{ triggerTurn: input.details.source !== "foreground" },
+	);
+}
+
+function isForegroundNoticeStillActionable(state: SubagentState, details: SubagentControlMessageDetails): boolean {
+	const control = state.foregroundControls.get(details.event.runId);
+	if (!control) return false;
+	if (control.currentAgent && control.currentAgent !== details.event.agent) return false;
+	if (details.event.index !== undefined && control.currentIndex !== details.event.index) return false;
+	return control.currentActivityState === "needs_attention";
+}
+
+export function handleSubagentControlNotice(input: {
+	pi: Pick<ExtensionAPI, "sendMessage">;
+	state: SubagentState;
+	visibleControlNotices: Set<string>;
+	details: SubagentControlMessageDetails;
+	foregroundDelayMs?: number;
+}): void {
+	if (!input.details?.event || input.details.event.type === "active_long_running") return;
+	if (input.details.source !== "foreground") {
+		deliverControlNotice(input);
+		return;
+	}
+
+	const pending = input.state.pendingForegroundControlNotices ?? new Map<string, ReturnType<typeof setTimeout>>();
+	input.state.pendingForegroundControlNotices = pending;
+	const timerKey = noticeTimerKey(input.details);
+	const existing = pending.get(timerKey);
+	if (existing) clearTimeout(existing);
+	const timer = setTimeout(() => {
+		pending.delete(timerKey);
+		if (!isForegroundNoticeStillActionable(input.state, input.details)) return;
+		deliverControlNotice(input);
+	}, input.foregroundDelayMs ?? 1000);
+	timer.unref?.();
+	pending.set(timerKey, timer);
+}

package/src/extension/index.ts

@@ -25,7 +25,6 @@ import { renderWidget, renderSubagentResult, stopResultAnimations, stopWidgetAni
 import { SubagentParams } from "./schemas.ts";
 import { createSubagentExecutor } from "../runs/foreground/subagent-executor.ts";
 import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
-import { controlNotificationKey, formatControlNoticeMessage } from "../runs/shared/subagent-control.ts";
 import { createResultWatcher } from "../runs/background/result-watcher.ts";
 import { registerSlashCommands } from "../slash/slash-commands.ts";
 import { registerPromptTemplateDelegationBridge } from "../slash/prompt-template-bridge.ts";
@@ -36,7 +35,6 @@ import registerSubagentNotify, { type SubagentNotifyDetails } from "../runs/back
 import { SUBAGENT_CHILD_ENV } from "../runs/shared/pi-args.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
 import {
-	type ControlEvent,
 	type Details,
 	type ExtensionConfig,
 	type SubagentState,
@@ -49,6 +47,13 @@ import {
 	SUBAGENT_CONTROL_EVENT,
 	WIDGET_KEY,
 } from "../shared/types.ts";
+import {
+	clearPendingForegroundControlNotices,
+	formatSubagentControlNotice,
+	handleSubagentControlNotice,
+	SUBAGENT_CONTROL_MESSAGE_TYPE,
+	type SubagentControlMessageDetails,
+} from "./control-notices.ts";
 
 /**
  * Derive subagent session base directory from parent session file.
@@ -153,24 +158,6 @@ function createSlashResultComponent(
 	return container;
 }
 
-const SUBAGENT_CONTROL_MESSAGE_TYPE = "subagent_control_notice";
-
-interface SubagentControlMessageDetails {
-	event: ControlEvent;
-	source?: "foreground" | "async";
-	asyncDir?: string;
-	childIntercomTarget?: string;
-	noticeText?: string;
-}
-
-function controlNoticeTarget(details: SubagentControlMessageDetails): string | undefined {
-	return details.childIntercomTarget;
-}
-
-function formatSubagentControlNotice(details: SubagentControlMessageDetails, content?: string): string {
-	return details.noticeText ?? content ?? formatControlNoticeMessage(details.event, controlNoticeTarget(details));
-}
-
 function parseSubagentNotifyContent(content: string): SubagentNotifyDetails | undefined {
 	const lines = content.split("\n");
 	const header = lines[0] ?? "";
@@ -259,6 +246,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		asyncJobs: new Map(),
 		foregroundControls: new Map(),
 		lastForegroundControlId: null,
+		pendingForegroundControlNotices: new Map(),
 		cleanupTimers: new Map(),
 		lastUiContext: null,
 		poller: null,
@@ -283,6 +271,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const runtimeCleanup = () => {
 		stopWidgetAnimation();
 		stopResultAnimations();
+		clearPendingForegroundControlNotices(state);
 		if (state.poller) {
 			clearInterval(state.poller);
 			state.poller = null;
@@ -497,22 +486,12 @@ DIAGNOSTICS:
 	const visibleControlNotices = existingVisibleControlNotices instanceof Set ? existingVisibleControlNotices as Set<string> : new Set<string>();
 	globalStore[controlNoticeSeenStoreKey] = visibleControlNotices;
 	const controlEventHandler = (payload: unknown) => {
-		const details = payload as SubagentControlMessageDetails;
-		if (!details?.event || details.event.type === "active_long_running") return;
-		const childIntercomTarget = controlNoticeTarget(details);
-		const key = controlNotificationKey(details.event, childIntercomTarget);
-		if (visibleControlNotices.has(key)) return;
-		visibleControlNotices.add(key);
-		const noticeText = details.noticeText ?? formatControlNoticeMessage(details.event, childIntercomTarget);
-		pi.sendMessage(
-			{
-				customType: SUBAGENT_CONTROL_MESSAGE_TYPE,
-				content: noticeText,
-				display: true,
-				details: { ...details, childIntercomTarget, noticeText },
-			},
-			{ triggerTurn: true },
-		);
+		handleSubagentControlNotice({
+			pi,
+			state,
+			visibleControlNotices,
+			details: payload as SubagentControlMessageDetails,
+		});
 	};
 	const eventUnsubscribes = [
 		pi.events.on(SUBAGENT_ASYNC_STARTED_EVENT, handleStarted),
@@ -547,6 +526,7 @@ DIAGNOSTICS:
 		state.currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 		state.lastUiContext = ctx;
 		cleanupSessionArtifacts(ctx);
+		clearPendingForegroundControlNotices(state);
 		resetJobs(ctx);
 		restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
 	};
@@ -569,6 +549,7 @@ DIAGNOSTICS:
 		stopResultWatcher();
 		if (state.poller) clearInterval(state.poller);
 		state.poller = null;
+		clearPendingForegroundControlNotices(state);
 		for (const timer of state.cleanupTimers.values()) {
 			clearTimeout(timer);
 		}

package/src/runs/foreground/subagent-executor.ts

@@ -10,6 +10,7 @@ import { executeChain } from "./chain-execution.ts";
 import { resolveExecutionAgentScope } from "../../agents/agent-scope.ts";
 import { handleManagementAction } from "../../agents/agent-management.ts";
 import { buildDoctorReport } from "../../extension/doctor.ts";
+import { clearPendingForegroundControlNotices } from "../../extension/control-notices.ts";
 import { runSync } from "./execution.ts";
 import { resolveModelCandidate } from "../shared/model-fallback.ts";
 import { aggregateParallelOutputs } from "../shared/parallel-utils.ts";
@@ -2067,6 +2068,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 			return toExecutionErrorResult(effectiveParams, error);
 		} finally {
 			if (foregroundControl) {
+				clearPendingForegroundControlNotices(deps.state, runId);
 				deps.state.foregroundControls.delete(runId);
 				if (deps.state.lastForegroundControlId === runId) {
 					deps.state.lastForegroundControlId = null;

package/src/shared/types.ts

@@ -356,6 +356,7 @@ export interface SubagentState {
 		interrupt?: () => boolean;
 	}>;
 	lastForegroundControlId: string | null;
+	pendingForegroundControlNotices?: Map<string, ReturnType<typeof setTimeout>>;
 	cleanupTimers: Map<string, ReturnType<typeof setTimeout>>;
 	lastUiContext: ExtensionContext | null;
 	poller: NodeJS.Timeout | null;