pi-subagents 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [0.34.0] - 2026-07-07
+
+### Added
+- Added `waitTool` config and `PI_SUBAGENT_WAIT_TOOL_ENABLED` so interactive users can keep the `wait` tool registered while making it return immediately instead of blocking on background subagents.
+
+### Fixed
+- Coerce agent frontmatter `thinking: false` to disabled thinking so child model IDs do not gain invalid `:false` suffixes.
+- Suppress stale native supervisor-channel asks after replies, expiry, or inactive child runs, and clean cancelled child requests so `subagent_supervisor` and visible intercom notices stay aligned.
+- Avoid completion-guard failures for read-only issue-drafting tasks that mention suggested fixes while preserving mutation expectations for real implementation tasks.
+- Prune stale empty native supervisor-channel directories before polling while preserving fresh or non-empty channels.
+
+## [0.33.1] - 2026-07-03
+
+### Fixed
+- Avoid native supervisor-channel tool conflicts when `pi-intercom` is also installed by deferring native tool registration until runtime startup and keeping a namespaced native supervisor reply tool.
+
 ## [0.33.0] - 2026-07-03
 
 ### Added

package/README.md

@@ -267,7 +267,7 @@ Add `autofix` to `/parallel-review` or `/parallel-cleanup` to apply only the syn
 
 ## Native supervisor coordination
 
-Child agents can talk back to the parent Pi session without installing `pi-intercom`. `pi-subagents` now provides the child-facing `contact_supervisor` tool and the parent-facing `intercom({ action: "reply" })` path natively.
+Child agents can talk back to the parent Pi session without installing `pi-intercom`. `pi-subagents` now provides the child-facing `contact_supervisor` tool and the parent-facing `subagent_supervisor({ action: "reply" })` path natively. If no external `pi-intercom` tool owns the `intercom` name, the native channel also exposes `intercom` as a compatibility fallback.
 
 Use it for work where the child might need a decision instead of guessing:
 
@@ -283,7 +283,7 @@ The child can use one dedicated coordination tool:
 
 - `contact_supervisor`: the child contacts the parent/supervisor session that delegated the task. Use `reason: "need_decision"` for blocking decisions or clarification, `reason: "interview_request"` for structured input, and `reason: "progress_update"` for short non-blocking updates when a discovery changes the plan. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing or artifact-writing instructions; no-edit wins.
 
-Supervisor messages are scoped to the exact Pi session id that spawned the child. A second Pi session in the same repository does not receive those requests.
+The parent replies with `subagent_supervisor({ action: "reply", replyTo, message })` or checks pending requests with `subagent_supervisor({ action: "pending" })`. Supervisor messages are scoped to the exact Pi session id that spawned the child. A second Pi session in the same repository does not receive those requests.
 
 Child-side routine completion handoffs are still not expected. If a child appears stalled, needs-attention notices can show up in the parent session with useful next actions, such as checking `subagent({ action: "status" })`, interrupting the run, or nudging the child.
 
@@ -1154,6 +1154,14 @@ Controls the parent-facing `subagent` tool description registered at startup. `f
 
 Makes top-level calls use background execution when the request does not explicitly set `async`. Callers can still force foreground with `async: false` unless `forceTopLevelAsync` is enabled.
 
+### `waitTool`
+
+```json
+{ "waitTool": { "enabled": false } }
+```
+
+Keeps the `wait` tool registered but makes it return immediately instead of blocking on active async runs. Use this in interactive sessions where background completions should arrive as notifications while the main conversation stays steerable. The default is enabled. You can also set `"waitTool": false`; set `PI_SUBAGENT_WAIT_TOOL_ENABLED=false` (or `0`, `off`, `disabled`) to override config for one process. Invalid `waitTool` config or env values fail instead of being coerced.
+
 ### `forceTopLevelAsync`
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "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

@@ -550,18 +550,20 @@ contact_supervisor({
 })
 ```
 
-The parent replies with:
+The parent replies with the native supervisor tool:
 
 ```typescript
-intercom({ action: "reply", message: "Optimize for readability." })
+subagent_supervisor({ action: "reply", message: "Optimize for readability." })
 ```
 
 Or inspects unresolved asks first:
 
 ```typescript
-intercom({ action: "pending" })
+subagent_supervisor({ action: "pending" })
 ```
 
+If no external `pi-intercom` tool owns the `intercom` name, native supervisor coordination may also expose `intercom` as a compatibility fallback. Prefer `subagent_supervisor` for parent replies because it never overrides installed `pi-intercom`.
+
 If intercom messages do not show up, run `subagent({ action: "doctor" })` or `/subagents-doctor`.
 
 ## Management Mode

package/src/agents/agents.ts

@@ -57,7 +57,7 @@ export function defaultInheritSkills(): boolean {
 export interface BuiltinAgentOverrideBase {
 	model?: string;
 	fallbackModels?: string[];
-	thinking?: string;
+	thinking?: string | false;
 	systemPromptMode: SystemPromptMode;
 	inheritProjectContext: boolean;
 	inheritSkills: boolean;
@@ -111,7 +111,7 @@ export interface AgentConfig {
 	mcpDirectTools?: string[];
 	model?: string;
 	fallbackModels?: string[];
-	thinking?: string;
+	thinking?: string | false;
 	systemPromptMode: SystemPromptMode;
 	inheritProjectContext: boolean;
 	inheritSkills: boolean;
@@ -1283,7 +1283,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			mcpDirectTools: mcpDirectTools.length > 0 ? mcpDirectTools : undefined,
 			model: frontmatter.model,
 			fallbackModels: fallbackModels && fallbackModels.length > 0 ? fallbackModels : undefined,
-			thinking: frontmatter.thinking,
+			thinking: frontmatter.thinking === "false" ? false : frontmatter.thinking,
 			systemPromptMode,
 			inheritProjectContext,
 			inheritSkills,

package/src/extension/index.ts

@@ -36,7 +36,7 @@ import { createNativeSupervisorChannel } from "../intercom/native-supervisor-cha
 import { registerSubagentRpcBridge } from "./rpc.ts";
 import { clearSlashSnapshots, getSlashRenderableSnapshot, resolveSlashMessageDetails, restoreSlashFinalSnapshots, type SlashMessageDetails } from "../slash/slash-live-state.ts";
 import { inspectSubagentStatus } from "../runs/background/run-status.ts";
-import { waitForSubagents } from "../runs/background/wait.ts";
+import { resolveWaitToolConfig, waitForSubagents } from "../runs/background/wait.ts";
 import registerSubagentNotify, { type SubagentNotifyDetails } from "../runs/background/notify.ts";
 import { SUBAGENT_CHILD_ENV, SUBAGENT_PARENT_SESSION_ENV } from "../runs/shared/pi-args.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
@@ -257,6 +257,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	cleanupOldChainDirs();
 
 	const config = loadConfig();
+	const waitToolConfig = resolveWaitToolConfig(config.waitTool);
 	const asyncByDefault = config.asyncByDefault === true;
 	const tempArtifactsDir = getArtifactsDir(null);
 	cleanupAllArtifactDirs(DEFAULT_ARTIFACT_CONFIG.cleanupDays);
@@ -517,10 +518,10 @@ Use this after launching async subagents when you have no independent work left
 • { id: "..." } — wait for one specific run (id or prefix) to finish.
 • { timeoutMs: 600000 } — stop waiting after N ms (the runs keep going regardless; default 30 min)
 
-wait also returns when a run needs attention (a child that went idle or blocked for a decision), not only on completion — so a stuck child never stalls the loop; the summary names the run(s) to inspect/nudge/resume/interrupt. It wakes the instant a completion or control event arrives (subscribed to Pi's event bus, with a poll fallback that reconciles crashed runners), keeps the turn alive for normal notification delivery, and resolves early if the turn is aborted.`,
+wait also returns when a run needs attention (a child that went idle or blocked for a decision), not only on completion — so a stuck child never stalls the loop; the summary names the run(s) to inspect/nudge/resume/interrupt. It wakes the instant a completion or control event arrives (subscribed to Pi's event bus, with a poll fallback that reconciles crashed runners), keeps the turn alive for normal notification delivery, and resolves early if the turn is aborted.${waitToolConfig.enabled ? "" : "\n\nConfigured behavior: wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED and returns immediately without blocking."}`,
 		parameters: WaitParams,
 		execute(_id, params, signal, _onUpdate, _ctx) {
-			return waitForSubagents(params, signal, { state, events: pi.events });
+			return waitForSubagents(params, signal, { state, events: pi.events, enabled: waitToolConfig.enabled });
 		},
 	};
 	pi.registerTool(waitTool);

package/src/intercom/native-supervisor-channel.ts

@@ -18,9 +18,12 @@ import { writeAtomicJson } from "../shared/atomic-json.ts";
 const SUPERVISOR_CHANNEL_ROOT = path.join(TEMP_ROOT_DIR, "supervisor-channels");
 const REQUESTS_DIR = "requests";
 const REPLIES_DIR = "replies";
+export const NATIVE_SUPERVISOR_TOOL_NAME = "subagent_supervisor";
 const MAX_MESSAGE_BYTES = 64 * 1024;
 const DEFAULT_ASK_TIMEOUT_MS = 10 * 60 * 1000;
 const CHANNEL_POLL_MS = Math.min(POLL_INTERVAL_MS, 500);
+const STALE_EMPTY_CHANNEL_AGE_MS = 60 * 1000;
+const STALE_EMPTY_CHANNEL_CLEANUP_INTERVAL_MS = 60 * 1000;
 
 type SupervisorReason = "need_decision" | "interview_request" | "progress_update";
 
@@ -28,6 +31,7 @@ interface SupervisorRequest {
 	type: "subagent.supervisor.request";
 	id: string;
 	createdAt: number;
+	expiresAt?: number;
 	reason: SupervisorReason;
 	message: string;
 	expectsReply: boolean;
@@ -202,9 +206,8 @@ function delay(ms: number, signal?: AbortSignal): Promise<void> {
 	});
 }
 
-async function waitForReply(channelDir: string, requestId: string, signal?: AbortSignal): Promise<SupervisorReply> {
+async function waitForReply(channelDir: string, requestId: string, deadline: number, signal?: AbortSignal): Promise<SupervisorReply> {
 	const file = replyPath(channelDir, requestId);
-	const deadline = Date.now() + askTimeoutMs();
 	while (Date.now() <= deadline) {
 		if (signal?.aborted) throw new Error("Supervisor request cancelled.");
 		if (fs.existsSync(file)) {
@@ -227,11 +230,15 @@ async function sendSupervisorRequest(params: ContactSupervisorParams, signal?: A
 	ensureSupervisorChannelDir(metadata.channelDir);
 	const requestId = randomUUID();
 	const expectsReply = params.reason !== "progress_update";
+	const createdAt = Date.now();
+	const replyDeadline = createdAt + askTimeoutMs();
+	const expiresAt = expectsReply ? replyDeadline : undefined;
 	const message = formatChildMessage({ ...metadata, reason: params.reason, message: params.message, interview: params.interview });
 	const request: SupervisorRequest = {
 		type: "subagent.supervisor.request",
 		id: requestId,
-		createdAt: Date.now(),
+		createdAt,
+		...(expiresAt !== undefined ? { expiresAt } : {}),
 		reason: params.reason,
 		message,
 		expectsReply,
@@ -254,17 +261,22 @@ async function sendSupervisorRequest(params: ContactSupervisorParams, signal?: A
 		};
 	}
 
-	const reply = await waitForReply(metadata.channelDir, requestId, signal);
-	const details: Record<string, unknown> = { requestId, reason: params.reason };
-	if (params.reason === "interview_request") {
-		const structured = parseStructuredReply(reply.message);
-		if (structured.error) details.structuredReplyParseError = structured.error;
-		else details.structuredReply = structured.value;
+	try {
+		const reply = await waitForReply(metadata.channelDir, requestId, replyDeadline, signal);
+		const details: Record<string, unknown> = { requestId, reason: params.reason };
+		if (params.reason === "interview_request") {
+			const structured = parseStructuredReply(reply.message);
+			if (structured.error) details.structuredReplyParseError = structured.error;
+			else details.structuredReply = structured.value;
+		}
+		return {
+			content: [{ type: "text", text: `**Reply from supervisor:**\n${reply.message}` }],
+			details,
+		};
+	} catch (error) {
+		removeRequestFile(requestPath(metadata.channelDir, requestId));
+		throw error;
 	}
-	return {
-		content: [{ type: "text", text: `**Reply from supervisor:**\n${reply.message}` }],
-		details,
-	};
 }
 
 function hasTool(pi: ExtensionAPI, name: string): boolean {
@@ -275,8 +287,9 @@ function hasTool(pi: ExtensionAPI, name: string): boolean {
 	}
 }
 
-export function registerNativeSupervisorClient(pi: ExtensionAPI): void {
+export function registerNativeSupervisorClient(pi: ExtensionAPI, options: { includeIntercomFallback?: boolean } = {}): void {
 	if (!readChildMetadata()) return;
+	const includeIntercomFallback = options.includeIntercomFallback !== false;
 	if (!hasTool(pi, "contact_supervisor")) {
 		const tool: ToolDefinition<typeof ContactSupervisorParamsSchema, Record<string, unknown>> = {
 			name: "contact_supervisor",
@@ -289,7 +302,7 @@ export function registerNativeSupervisorClient(pi: ExtensionAPI): void {
 		};
 		pi.registerTool(tool);
 	}
-	if (!hasTool(pi, "intercom")) {
+	if (includeIntercomFallback && !hasTool(pi, "intercom")) {
 		const tool: ToolDefinition<typeof IntercomParamsSchema, Record<string, unknown>> = {
 			name: "intercom",
 			label: "Intercom",
@@ -348,13 +361,85 @@ function listRequestFiles(): Array<{ channelDir: string; file: string }> {
 	return files;
 }
 
+function readDirectoryEntries(dir: string): fs.Dirent[] | undefined {
+	try {
+		return fs.readdirSync(dir, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		return undefined;
+	}
+}
+
+function directoryMtimeMs(dir: string): number {
+	try {
+		return fs.statSync(dir).mtimeMs;
+	} catch {
+		return 0;
+	}
+}
+
+function removeEmptyDirectory(dir: string): boolean {
+	try {
+		fs.rmdirSync(dir);
+		return true;
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") return true;
+		if (code === "ENOTEMPTY" || code === "EEXIST" || code === "EPERM" || code === "EBUSY") return false;
+		throw error;
+	}
+}
+
+function removeStaleEmptySupervisorChannel(channelDir: string, nowMs: number): boolean {
+	const requestsDir = path.join(channelDir, REQUESTS_DIR);
+	const repliesDir = path.join(channelDir, REPLIES_DIR);
+	const newestKnownMtimeMs = Math.max(
+		directoryMtimeMs(channelDir),
+		directoryMtimeMs(requestsDir),
+		directoryMtimeMs(repliesDir),
+	);
+	if (nowMs - newestKnownMtimeMs < STALE_EMPTY_CHANNEL_AGE_MS) return false;
+
+	const requestEntries = readDirectoryEntries(requestsDir);
+	if (!requestEntries || requestEntries.length > 0) return false;
+	const replyEntries = readDirectoryEntries(repliesDir);
+	if (!replyEntries || replyEntries.length > 0) return false;
+
+	if (!removeEmptyDirectory(requestsDir)) return false;
+	if (!removeEmptyDirectory(repliesDir)) return false;
+	if (!removeEmptyDirectory(channelDir)) return false;
+	return true;
+}
+
+function cleanupStaleEmptySupervisorChannels(nowMs = Date.now()): number {
+	let channelEntries: fs.Dirent[];
+	try {
+		channelEntries = fs.readdirSync(SUPERVISOR_CHANNEL_ROOT, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return 0;
+		throw error;
+	}
+
+	let removed = 0;
+	for (const entry of channelEntries) {
+		if (!entry.isDirectory()) continue;
+		try {
+			if (removeStaleEmptySupervisorChannel(path.join(SUPERVISOR_CHANNEL_ROOT, entry.name), nowMs)) removed++;
+		} catch {
+			// Cleanup is opportunistic; active writers can race with us and will be picked up by a later pass.
+		}
+	}
+	return removed;
+}
+
 function currentContextSessionId(state: Pick<SubagentState, "currentSessionId">, ctx: ExtensionContext): string | undefined {
-	if (state.currentSessionId) return state.currentSessionId;
 	try {
-		return ctx.sessionManager.getSessionId();
+		const sessionId = ctx.sessionManager.getSessionId();
+		if (sessionId) return sessionId;
 	} catch {
-		return undefined;
+		// Fall through to the last known identity.
 	}
+	return state.currentSessionId ?? undefined;
 }
 
 function requestMatchesContext(request: SupervisorRequest, state: Pick<SubagentState, "currentSessionId">, ctx: ExtensionContext): boolean {
@@ -362,15 +447,68 @@ function requestMatchesContext(request: SupervisorRequest, state: Pick<SubagentS
 	return Boolean(currentSessionId && request.orchestratorSessionId === currentSessionId);
 }
 
+function removeRequestFile(file: string): void {
+	try {
+		fs.rmSync(file, { force: true });
+	} catch {
+		// Request cleanup is best-effort; reply files and timeout errors remain authoritative.
+	}
+}
+
+type SupervisorRequestLifecycle = "pending" | "resolved" | "expired" | "inactive" | "missing" | "wrong-session";
+
+function requestExpiresAt(request: SupervisorRequest, now: number): number {
+	const expiresAt = (request as { expiresAt?: unknown }).expiresAt;
+	if (typeof expiresAt === "number" && Number.isFinite(expiresAt)) return expiresAt;
+	return Number.isFinite(request.createdAt) ? request.createdAt + askTimeoutMs() : now;
+}
+
+function requestRunInactive(request: SupervisorRequest, state: SubagentState): boolean {
+	if (state.foregroundControls.has(request.runId)) return false;
+	const foregroundRun = state.foregroundRuns?.get(request.runId);
+	const foregroundChild = foregroundRun?.children.find((child) => child.index === request.childIndex && child.agent === request.agent)
+		?? foregroundRun?.children[request.childIndex];
+	if (foregroundChild) return foregroundChild.status !== "detached";
+
+	const asyncJob = state.asyncJobs.get(request.runId);
+	if (!asyncJob) return false;
+	if (asyncJob.status === "complete" || asyncJob.status === "failed" || asyncJob.status === "paused") return true;
+	const stepStatus = asyncJob.steps?.[request.childIndex]?.status;
+	return stepStatus === "complete" || stepStatus === "completed" || stepStatus === "failed" || stepStatus === "paused";
+}
+
+function requestLifecycle(request: PendingSupervisorRequest, state: SubagentState, ctx: ExtensionContext | undefined, now: number): SupervisorRequestLifecycle {
+	if (ctx && !requestMatchesContext(request, state, ctx)) return "wrong-session";
+	if (!fs.existsSync(request.requestFile)) return "missing";
+	if (request.expectsReply && fs.existsSync(replyPath(request.channelDir, request.id))) return "resolved";
+	if (request.expectsReply && now > requestExpiresAt(request, now)) return "expired";
+	if (request.expectsReply && requestRunInactive(request, state)) return "inactive";
+	return "pending";
+}
+
+function cleanupRequestLifecycle(request: PendingSupervisorRequest, lifecycle: SupervisorRequestLifecycle): void {
+	if (lifecycle === "resolved" || lifecycle === "expired" || lifecycle === "inactive") removeRequestFile(request.requestFile);
+}
+
+function refreshPendingRequests(pending: Map<string, PendingSupervisorRequest>, state: SubagentState, ctx: ExtensionContext | undefined): void {
+	const now = Date.now();
+	for (const request of pending.values()) {
+		const lifecycle = requestLifecycle(request, state, ctx, now);
+		if (lifecycle === "pending") continue;
+		pending.delete(request.id);
+		cleanupRequestLifecycle(request, lifecycle);
+	}
+}
+
 function formatPendingLine(request: PendingSupervisorRequest): string {
-	const replyHint = request.expectsReply ? ` Reply: intercom({ action: "reply", replyTo: "${request.id}", message: "..." })` : "";
+	const replyHint = request.expectsReply ? ` Reply: ${NATIVE_SUPERVISOR_TOOL_NAME}({ action: "reply", replyTo: "${request.id}", message: "..." })` : "";
 	return `- ${request.id}: ${request.agent} [${request.runId}#${request.childIndex}] ${request.reason}.${replyHint}`;
 }
 
 function requestVisibleText(request: PendingSupervisorRequest): string {
 	const lines = [request.message];
 	if (request.expectsReply) {
-		lines.push("", `Reply with: intercom({ action: "reply", replyTo: "${request.id}", message: "..." })`);
+		lines.push("", `Reply with: ${NATIVE_SUPERVISOR_TOOL_NAME}({ action: "reply", replyTo: "${request.id}", message: "..." })`);
 	}
 	return lines.join("\n");
 }
@@ -384,11 +522,7 @@ function writeReply(request: PendingSupervisorRequest, message: string): void {
 		message: message.trim(),
 	};
 	writeAtomicJson(replyPath(request.channelDir, request.id), reply);
-	try {
-		fs.rmSync(request.requestFile, { force: true });
-	} catch {
-		// Best effort: the reply file is authoritative for the child.
-	}
+	removeRequestFile(request.requestFile);
 }
 
 function resolvePendingRequest(pending: Map<string, PendingSupervisorRequest>, params: IntercomParams): PendingSupervisorRequest {
@@ -424,13 +558,16 @@ function publicPendingRequests(pending: Map<string, PendingSupervisorRequest>):
 	}));
 }
 
-function buildParentIntercomTool(pending: Map<string, PendingSupervisorRequest>): ToolDefinition<typeof IntercomParamsSchema, Record<string, unknown>> {
+function buildParentIntercomTool(pending: Map<string, PendingSupervisorRequest>, state: SubagentState, name = "intercom"): ToolDefinition<typeof IntercomParamsSchema, Record<string, unknown>> {
 	return {
-		name: "intercom",
-		label: "Intercom",
-		description: "Native pi-subagents supervisor channel. Use reply/pending/status to answer child subagent requests.",
+		name,
+		label: name === "intercom" ? "Intercom" : "Subagent Supervisor",
+		description: name === "intercom"
+			? "Native pi-subagents supervisor channel. Use reply/pending/status to answer child subagent requests."
+			: "Native pi-subagents supervisor channel. Use reply/pending/status to answer child subagent requests without overriding pi-intercom.",
 		parameters: IntercomParamsSchema,
 		async execute(_id, params) {
+			refreshPendingRequests(pending, state, state.lastUiContext ?? undefined);
 			const input = params as IntercomParams;
 			if (input.action === "status") {
 				return { content: [{ type: "text", text: `Native supervisor channel active. Pending replies: ${pending.size}.` }], details: { active: true, pending: pending.size, root: SUPERVISOR_CHANNEL_ROOT } };
@@ -457,24 +594,44 @@ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentS
 	const pending = new Map<string, PendingSupervisorRequest>();
 	const seenFiles = new Set<string>();
 	let poller: ReturnType<typeof setInterval> | undefined;
+	let lastStaleCleanupAt = 0;
 
-	if (!hasTool(pi, "intercom")) pi.registerTool(buildParentIntercomTool(pending));
+	const registerParentTools = (): void => {
+		if (!hasTool(pi, NATIVE_SUPERVISOR_TOOL_NAME)) pi.registerTool(buildParentIntercomTool(pending, state, NATIVE_SUPERVISOR_TOOL_NAME));
+		if (!hasTool(pi, "intercom")) pi.registerTool(buildParentIntercomTool(pending, state));
+	};
+
+	const cleanupStaleChannelsIfDue = (): void => {
+		const nowMs = Date.now();
+		if (nowMs - lastStaleCleanupAt < STALE_EMPTY_CHANNEL_CLEANUP_INTERVAL_MS) return;
+		lastStaleCleanupAt = nowMs;
+		try {
+			cleanupStaleEmptySupervisorChannels(nowMs);
+		} catch {
+			// Supervisor delivery must not fail because best-effort temp cleanup failed.
+		}
+	};
 
 	const poll = (): void => {
+		cleanupStaleChannelsIfDue();
 		const ctx = state.lastUiContext;
 		if (!ctx) return;
+		refreshPendingRequests(pending, state, ctx);
+		const now = Date.now();
 		for (const { channelDir, file } of listRequestFiles()) {
 			if (seenFiles.has(file)) continue;
 			const request = parseRequestFile(file, channelDir);
 			if (!request || !requestMatchesContext(request, state, ctx)) continue;
+			const lifecycle = requestLifecycle(request, state, undefined, now);
+			if (lifecycle !== "pending") {
+				seenFiles.add(file);
+				cleanupRequestLifecycle(request, lifecycle);
+				continue;
+			}
 			seenFiles.add(file);
 			if (request.expectsReply) pending.set(request.id, request);
 			else {
-				try {
-					fs.rmSync(request.requestFile, { force: true });
-				} catch {
-					// Non-blocking progress updates are already delivered to this session.
-				}
+				removeRequestFile(request.requestFile);
 			}
 			pi.sendMessage({
 				customType: "subagent_supervisor_request",
@@ -495,6 +652,7 @@ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentS
 	return {
 		start: () => {
 			if (poller) return;
+			registerParentTools();
 			poll();
 			poller = setInterval(poll, CHANNEL_POLL_MS);
 			poller.unref?.();

package/src/runs/background/wait.ts

@@ -47,6 +47,7 @@ import {
 	SUBAGENT_RESULT_INTERCOM_EVENT,
 	type Details,
 	type SubagentState,
+	type WaitToolConfig,
 } from "../../shared/types.ts";
 import { formatDuration } from "../../shared/formatters.ts";
 
@@ -57,6 +58,41 @@ const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
 const MIN_POLL_INTERVAL_MS = 250;
 const DEFAULT_POLL_INTERVAL_MS = 1000;
 
+export const WAIT_TOOL_ENABLED_ENV = "PI_SUBAGENT_WAIT_TOOL_ENABLED";
+
+export interface ResolvedWaitToolConfig {
+	enabled: boolean;
+}
+
+const WAIT_TOOL_TRUE_VALUES = new Set(["1", "true", "yes", "on", "enabled"]);
+const WAIT_TOOL_FALSE_VALUES = new Set(["0", "false", "no", "off", "disabled"]);
+
+function parseWaitToolEnabledEnv(value: string | undefined): boolean | undefined {
+	if (value === undefined) return undefined;
+	const normalized = value.trim().toLowerCase();
+	if (WAIT_TOOL_TRUE_VALUES.has(normalized)) return true;
+	if (WAIT_TOOL_FALSE_VALUES.has(normalized)) return false;
+	throw new Error(`${WAIT_TOOL_ENABLED_ENV} must be one of true/false, 1/0, yes/no, on/off, or enabled/disabled.`);
+}
+
+function configWaitToolEnabled(config: unknown): boolean | undefined {
+	if (config === undefined) return undefined;
+	if (typeof config === "boolean") return config;
+	if (!config || typeof config !== "object" || Array.isArray(config)) {
+		throw new Error("config.waitTool must be a boolean or an object with optional enabled boolean.");
+	}
+	const enabled = (config as { enabled?: unknown }).enabled;
+	if (enabled === undefined) return undefined;
+	if (typeof enabled !== "boolean") throw new Error("config.waitTool.enabled must be a boolean.");
+	return enabled;
+}
+
+export function resolveWaitToolConfig(config?: WaitToolConfig, env: Record<string, string | undefined> = process.env): ResolvedWaitToolConfig {
+	return {
+		enabled: parseWaitToolEnabledEnv(env[WAIT_TOOL_ENABLED_ENV]) ?? configWaitToolEnabled(config) ?? true,
+	};
+}
+
 export interface WaitParams {
 	/** Optional run id/prefix to wait for. When omitted, waits across every active run in this session. */
 	id?: string;
@@ -83,6 +119,8 @@ export interface WaitDeps {
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	now?: () => number;
 	pollIntervalMs?: number;
+	/** False makes the tool return immediately without blocking active async runs. */
+	enabled?: boolean;
 	/** Injectable sleep for tests. */
 	sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
 	/**
@@ -228,6 +266,9 @@ export async function waitForSubagents(
 	signal: AbortSignal | undefined,
 	deps: WaitDeps,
 ): Promise<AgentToolResult<Details>> {
+	if (deps.enabled === false) {
+		return result("Wait tool is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED; returning immediately without blocking background subagent runs. Active runs keep going, and you can inspect them with subagent({ action: \"status\" }) or wait for completion notifications.");
+	}
 	const now = deps.now ?? Date.now;
 	const pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
 	const timeoutMs = params.timeoutMs !== undefined && params.timeoutMs > 0 ? params.timeoutMs : DEFAULT_TIMEOUT_MS;

package/src/runs/shared/completion-guard.ts

@@ -32,23 +32,41 @@ const SCOPED_NO_EDIT_CONSTRAINT_PATTERNS = [
 	/\bdo not modify\s+unrelated files?\b/i,
 ];
 
+const NO_TOOL_INTENT_PATTERNS = [
+	/\bno tools? needed\b/i,
+	/\bno tools? required\b/i,
+	/\bwithout using tools\b/i,
+	/\bdo not use tools\b/i,
+	/\bdon't use tools\b/i,
+];
+
+const READ_ONLY_DELIVERABLE_PATTERNS = [
+	/\b(?:draft|write|compose|prepare|produce)\s+(?:(?:a|an|the)\s+)?(?:github\s+)?(?:issue|bug report|issue draft|issue body|proposal|plan|report|summary|findings?|analysis|recommendations?)\b/i,
+	/\b(?:issue|bug report)\s+(?:draft|body|template)\b/i,
+	/\b(?:return|provide|produce)\s+(?:text|markdown|answer|findings?|recommendations?)\s+only\b/i,
+];
+
 const RESEARCH_AGENT_PATTERNS = [
 	/\binvestigate\b/i,
 	/\bscout\b/i,
 	/\bresearch(?:er)?\b/i,
 ];
 
+const FIX_OR_PATCH_IMPLEMENTATION_PATTERN = /\b(?:fix|patch)\s+(?:(?:it|this|that|them|each|any|all|these|those)\b|(?:(?:a|an|the|any|all)\s+)?(?:(?:failing|failed|broken|flaky|red|cold|start|current|existing|reported|approved|known|regression|unit|integration|e2e|source|typescript|type-?script|ts|type-?check|compiler)\s+)*(?:bug|defect|issues?|problems?|failures?|regressions?|tests?|errors?|items?|typos?|code|source|implementation|component|function|module|class|method|logic|file|files|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command|lint(?:ing)?|build|ci|type-?check|type\s+checking)\b)/i;
+
 const WORKER_IMPLEMENTATION_PATTERNS = [
-	/\b(?:implement|fix|edit|modify|patch|refactor|delete)\b/i,
+	/\b(?:implement|edit|modify|refactor|delete)\b/i,
+	FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
 	/\b(?:update|add|remove|replace|create)\b(?!\s+(?:(?:a|an|the)\s+)?(?:report|summary|findings?)(?:\b|$))/i,
-	/\bapply\s+(?:the\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
+	/\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
 	/\bmake\s+(?:the\s+)?changes\b/i,
 	/\bdo those fixes\b/i,
 ];
 
 const GENERAL_IMPLEMENTATION_PATTERNS = [
-	/\b(?:implement|fix|edit|modify|patch|refactor)\b/i,
-	/\bapply\s+(?:the\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
+	/\b(?:implement|edit|modify|refactor)\b/i,
+	FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
+	/\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
 	/\bmake\s+(?:the\s+)?changes\b/i,
 	/\bdo those fixes\b/i,
 	/\b(?:update|add|remove|replace|delete|create)\s+(?:the\s+)?(?:file|files|code|source|implementation|test|tests|component|function|module|class|method|logic|import|imports|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command)\b/i,
@@ -80,6 +98,10 @@ interface CompletionMutationGuardResult {
 	triggered: boolean;
 }
 
+type TaskMutationIntent = { kind: "implementation" } | { kind: "read-only" } | { kind: "unknown" };
+
+type ToolMutationCapability = { kind: "mutation-capable" } | { kind: "read-only" };
+
 function stripFrameworkInstructions(task: string): string {
 	return task
 		.split("\n")
@@ -96,26 +118,40 @@ function stripScopedNoEditConstraints(task: string): string {
 	return stripped;
 }
 
-function declaresOnlyReadOnlyTools(tools: string[] | undefined, mcpDirectTools: string[] | undefined): boolean {
-	return tools !== undefined
-		&& tools.length > 0
-		&& (mcpDirectTools?.length ?? 0) === 0
-		&& tools.every((tool) => READ_ONLY_BUILTIN_TOOLS.has(tool));
+function taskHasExplicitReadOnlyIntent(taskText: string): boolean {
+	return REVIEW_ONLY_PATTERNS.some((pattern) => pattern.test(taskText))
+		|| EXPLICIT_NO_EDIT_PATTERNS.some((pattern) => pattern.test(taskText))
+		|| NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText));
 }
 
-export function expectsImplementationMutation(agent: string, task: string): boolean {
+function taskHasReadOnlyDeliverable(taskText: string): boolean {
+	return READ_ONLY_DELIVERABLE_PATTERNS.some((pattern) => pattern.test(taskText));
+}
+
+function toolMutationCapability(tools: string[] | undefined, mcpDirectTools: string[] | undefined): ToolMutationCapability {
+	if (tools === undefined || tools.length === 0 || (mcpDirectTools?.length ?? 0) > 0) return { kind: "mutation-capable" };
+	return tools.every((tool) => READ_ONLY_BUILTIN_TOOLS.has(tool)) ? { kind: "read-only" } : { kind: "mutation-capable" };
+}
+
+function classifyTaskMutationIntent(agent: string, task: string): TaskMutationIntent {
 	const taskText = stripFrameworkInstructions(task);
 	const taskTextWithoutScopedConstraints = stripScopedNoEditConstraints(taskText);
-	if (REVIEW_ONLY_PATTERNS.some((pattern) => pattern.test(taskTextWithoutScopedConstraints))) return false;
-	if (EXPLICIT_NO_EDIT_PATTERNS.some((pattern) => pattern.test(taskTextWithoutScopedConstraints))) return false;
+	if (taskHasExplicitReadOnlyIntent(taskTextWithoutScopedConstraints)) return { kind: "read-only" };
 
-	if (RESEARCH_AGENT_PATTERNS.some((pattern) => pattern.test(agent))) return false;
-	if (/\breviewer\b/i.test(agent)) return REVIEWER_REQUIRED_EDIT_PATTERNS.some((pattern) => pattern.test(taskText));
+	if (RESEARCH_AGENT_PATTERNS.some((pattern) => pattern.test(agent))) return { kind: "read-only" };
+	if (/\breviewer\b/i.test(agent)) {
+		return REVIEWER_REQUIRED_EDIT_PATTERNS.some((pattern) => pattern.test(taskText)) ? { kind: "implementation" } : { kind: "read-only" };
+	}
 
 	const workerIntent = agent === "worker" && WORKER_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
-	if (workerIntent) return true;
+	if (workerIntent) return { kind: "implementation" };
+
+	if (GENERAL_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText))) return { kind: "implementation" };
+	return taskHasReadOnlyDeliverable(taskTextWithoutScopedConstraints) ? { kind: "read-only" } : { kind: "unknown" };
+}
 
-	return GENERAL_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
+export function expectsImplementationMutation(agent: string, task: string): boolean {
+	return classifyTaskMutationIntent(agent, task).kind === "implementation";
 }
 
 export function hasMutationToolCall(messages: Message[]): boolean {
@@ -135,7 +171,7 @@ export function hasMutationToolCall(messages: Message[]): boolean {
 }
 
 export function evaluateCompletionMutationGuard(input: CompletionMutationGuardInput): CompletionMutationGuardResult {
-	const expectedMutation = declaresOnlyReadOnlyTools(input.tools, input.mcpDirectTools)
+	const expectedMutation = toolMutationCapability(input.tools, input.mcpDirectTools).kind === "read-only"
 		? false
 		: expectsImplementationMutation(input.agent, input.task);
 	const attemptedMutation = hasMutationToolCall(input.messages);

package/src/runs/shared/pi-args.ts

@@ -39,7 +39,7 @@ interface BuildPiArgsInput {
 	sessionDir?: string;
 	sessionFile?: string;
 	model?: string;
-	thinking?: string;
+	thinking?: string | false;
 	systemPromptMode?: "append" | "replace";
 	inheritProjectContext: boolean;
 	inheritSkills: boolean;
@@ -87,7 +87,7 @@ function supervisorChannelDir(runId: string, agent: string, childIndex: number):
 	return path.join(TEMP_ROOT_DIR, "supervisor-channels", `${sanitizeSupervisorChannelSegment(runId)}-${sanitizeSupervisorChannelSegment(agent)}-${childIndex}`);
 }
 
-export function applyThinkingSuffix(model: string | undefined, thinking: string | undefined, replaceExisting = false): string | undefined {
+export function applyThinkingSuffix(model: string | undefined, thinking: string | false | undefined, replaceExisting = false): string | undefined {
 	if (!model || !thinking) return model;
 	const colonIdx = model.lastIndexOf(":");
 	if (colonIdx !== -1 && THINKING_LEVELS.includes(model.substring(colonIdx + 1))) {

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -261,7 +261,21 @@ function registerSteeringInbox(pi: ExtensionAPI): void {
 export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	registerSteeringInbox(pi);
 	registerToolBudget(pi, decodeToolBudgetEnv(process.env[TOOL_BUDGET_ENV]));
-	registerNativeSupervisorClient(pi);
+	let nativeSupervisorClientRegistered = false;
+	let nativeSupervisorFallbackRegistered = false;
+	const registerNativeSupervisorClientOnce = (): void => {
+		if (nativeSupervisorClientRegistered) return;
+		nativeSupervisorClientRegistered = true;
+		registerNativeSupervisorClient(pi, { includeIntercomFallback: false });
+	};
+	const registerNativeSupervisorFallbackOnce = (): void => {
+		registerNativeSupervisorClientOnce();
+		if (nativeSupervisorFallbackRegistered) return;
+		nativeSupervisorFallbackRegistered = true;
+		registerNativeSupervisorClient(pi);
+	};
+	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown) => unknown) => void;
+	onRuntimeEvent("session_start", registerNativeSupervisorClientOnce);
 	const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
 	const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
 	if (structuredOutputPath && structuredSchemaPath) {
@@ -300,7 +314,6 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 		});
 	}
 
-	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown) => unknown) => void;
 	onRuntimeEvent("context", (event: { messages: unknown[] }) => {
 		const messages = stripParentOnlySubagentMessages(event.messages);
 		if (messages === event.messages) return undefined;
@@ -308,6 +321,7 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	});
 
 	onRuntimeEvent("before_agent_start", async (event: { systemPrompt: string }) => {
+		registerNativeSupervisorFallbackOnce();
 		const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
 		if (intercomSessionName && typeof pi.setSessionName === "function") {
 			pi.setSessionName(intercomSessionName);

package/src/shared/model-info.ts

@@ -30,7 +30,7 @@ export function toModelInfo(model: RegistryModelLike): ModelInfo {
 /** Resolve the effective thinking level from a model string (which may contain a known suffix like `:high`)
  * and an explicit thinking config value. Returns `undefined` when no thinking is applicable
  * (e.g. no model was specified, or the model has no suffix and no config was provided). */
-export function resolveEffectiveThinking(model: string | undefined, configThinking: string | undefined): string | undefined {
+export function resolveEffectiveThinking(model: string | undefined, configThinking: string | false | undefined): string | undefined {
 	if (!model) return undefined;
 	const { thinkingSuffix } = splitKnownThinkingSuffix(model);
 	if (thinkingSuffix) return thinkingSuffix.slice(1);

package/src/shared/types.ts

@@ -181,6 +181,12 @@ export interface CompletionBatchConfig {
 	stragglerWindowMs?: number;
 }
 
+export interface WaitToolConfigObject {
+	enabled?: boolean;
+}
+
+export type WaitToolConfig = boolean | WaitToolConfigObject;
+
 export interface ControlEvent {
 	type: ControlEventType;
 	from?: ActivityState;
@@ -1000,6 +1006,7 @@ export interface ExtensionConfig {
 	/** Tool description variant registered for the parent-facing subagent tool. Defaults to full. */
 	toolDescriptionMode?: ToolDescriptionMode;
 	forceTopLevelAsync?: boolean;
+	waitTool?: WaitToolConfig;
 	defaultSessionDir?: string;
 	singleRunOutputBaseDir?: string;
 	maxSubagentDepth?: number;