@narumitw/pi-subagents 2.0.5 → 2.1.0

package/src/runner.ts

@@ -2,20 +2,10 @@ import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
-import type { SchedulingDecision } from "./adaptive-scheduler.js";
-import type {
-	AgentConfig,
-	AgentScope,
-	AgentSource,
-	SubagentThinkingLevel,
-} from "./agents/types.js";
-import { type CapabilityGrant, revokeCapabilityGrant } from "./capability-grant.js";
-import type { TargetPolicyAudit } from "./cwd-policy.js";
-import type { DelegationContract } from "./delegation-contract.js";
-import type { ExecutionPlan } from "./execution-plan.js";
+import type { AgentConfig, SubagentThinkingLevel } from "./agents/types.js";
+import { revokeCapabilityGrant } from "./capability-grant.js";
 import {
 	appendBounded,
 	DEFAULT_MAX_CONTEXT_BYTES,
@@ -25,139 +15,51 @@ import {
 	MAX_SUBAGENT_TIMEOUT_MS,
 	truncateUtf8,
 } from "./limits.js";
-import type { OrchestrationMetrics } from "./orchestration-metrics.js";
-import { type ClassifiedSubagentOutcome, classifyStructuredOutcome } from "./outcome.js";
-import type { PanelSynthesis } from "./panel-contract.js";
-import type { PanelEvidenceArtifact } from "./panel-evidence.js";
-import type { PanelFailure } from "./panel-failure.js";
-import type { PanelPhaseBudgets, PanelPreset } from "./panel-planning.js";
+import { classifyStructuredOutcome } from "./outcome.js";
 import { buildPiArgs } from "./pi-args.js";
 import { resolvePiInvocation } from "./pi-invocation.js";
+import { KILL_GRACE_MS, terminateProcess } from "./process-control.js";
 import { JsonLineDecoder } from "./protocol.js";
-import {
-	type AnyStructuredSubagentResult,
-	parseAnyStructuredSubagentResult,
-	type SubagentResultFormat,
-} from "./result-contract.js";
+import { parseAnyStructuredSubagentResult } from "./result-contract.js";
 import { formatResultFailure, getResultFinalOutput, isResultError } from "./runner-outcome.js";
 import { getFinalOutput } from "./runner-result.js";
+import type { ChildLaunchPolicy, RecentActivityItem, SingleResult } from "./runner-types.js";
 import {
 	addUsageValue,
 	mergeUsageStats,
 	protocolUsageCost,
 	protocolUsageCount,
-	type UsageStats,
 } from "./runner-usage.js";
+import type { OnUpdateCallback, SubagentDetails } from "./subagent-details.js";
 import {
 	formatTimeoutCheckpoint,
 	formatTurnTerminationMessage,
 	journalMessages,
 	TimeoutProgressJournal,
 	TURN_TERMINATION_VERSION,
-	type TurnTerminationReport,
 } from "./timeout-checkpoint.js";
 import {
 	buildTimeoutFinalizationPrompt,
 	resolveTimeoutFinalizationMs,
 } from "./timeout-finalization.js";
-import { TurnBudgetMonitor, type TurnBudgetStop, type TurnLimits } from "./turn-budget.js";
-import type { WorkItemLedgerSnapshot } from "./work-item-ledger.js";
-
-export const KILL_GRACE_MS = 5000;
+import { TurnBudgetMonitor, type TurnBudgetStop } from "./turn-budget.js";
 
 export type { PiArgsOptions } from "./pi-args.js";
 export { buildPiArgs } from "./pi-args.js";
+export { KILL_GRACE_MS, terminateProcess } from "./process-control.js";
 export {
 	formatResultFailure,
 	getResultFinalOutput,
 	isResultError,
 } from "./runner-outcome.js";
+export type { ChildLaunchPolicy, RecentActivityItem, SingleResult } from "./runner-types.js";
 export type { UsageStats } from "./runner-usage.js";
-export type RecentActivityItem =
-	| { type: "text"; text: string }
-	| { type: "toolCall"; name: string; args: Record<string, unknown> };
+export type { OnUpdateCallback, PanelDetails, SubagentDetails } from "./subagent-details.js";
 
 const MAX_RECENT_ACTIVITY_ITEMS = 10;
 const MAX_RECENT_ACTIVITY_BYTES = 8 * 1024;
 const MAX_RECENT_ACTIVITY_ARGUMENT_BYTES = 1024;
 
-export interface SingleResult {
-	agent: string;
-	agentSource: AgentSource | "unknown";
-	task: string;
-	exitCode: number;
-	messages: Message[];
-	stderr: string;
-	usage: UsageStats;
-	model?: string;
-	actualProvider?: string;
-	actualModel?: string;
-	recentActivity?: RecentActivityItem[];
-	recentActivityTotal?: number;
-	thinkingLevel?: SubagentThinkingLevel;
-	stopReason?: string;
-	errorMessage?: string;
-	step?: number;
-	finalOutput?: string;
-	partialOutput?: string;
-	timeoutSummary?: string;
-	timeoutSummaryError?: string;
-	termination?: TurnTerminationReport;
-	timedOut?: boolean;
-	timeoutMs?: number;
-	aborted?: boolean;
-	truncated?: boolean;
-	malformedEvents?: number;
-	launchFailed?: boolean;
-	processStarted?: boolean;
-	target?: TargetPolicyAudit;
-	policy?: {
-		inherited: string[];
-		overridden: string[];
-		unsupported: string[];
-	};
-	contract?: DelegationContract;
-	resultFormat?: SubagentResultFormat;
-	structuredResult?: AnyStructuredSubagentResult;
-	resultContractInvalid?: boolean;
-	outcome?: ClassifiedSubagentOutcome;
-	attemptCount?: number;
-	hedged?: boolean;
-	executionPlan?: ExecutionPlan;
-	capabilityGrant?: CapabilityGrant;
-}
-
-export interface PanelDetails {
-	id: string;
-	preset: PanelPreset;
-	sharedTaskPreview: string;
-	state: "running" | "completed" | "degraded" | "insufficient-panel" | "failed" | "cancelled";
-	reviewerIds: string[];
-	validReviewCount: number;
-	failedReviewCount: number;
-	blockingObjectionCount: number;
-	dissentCount: number;
-	budgets: PanelPhaseBudgets;
-	evidence: PanelEvidenceArtifact[];
-	failures: PanelFailure[];
-	synthesis?: PanelSynthesis;
-	synthesizerResult?: SingleResult;
-	cleanupComplete: boolean;
-}
-
-export interface SubagentDetails {
-	mode: "single" | "parallel" | "chain" | "workflow" | "panel";
-	agentScope: AgentScope;
-	projectAgentsDir: string | null;
-	results: SingleResult[];
-	aggregator?: SingleResult;
-	workflow?: WorkItemLedgerSnapshot;
-	schedulerDecisions?: SchedulingDecision[];
-	metrics?: OrchestrationMetrics;
-	panel?: PanelDetails;
-	isError?: boolean;
-}
-
 function boundMessageText(
 	message: Message,
 	maxBytes: number,
@@ -338,89 +240,6 @@ async function writePromptToTempFile(
 	return { dir: tmpDir, filePath };
 }
 
-function signalProcess(proc: ReturnType<typeof spawn>, signal: NodeJS.Signals): void {
-	if (process.platform !== "win32" && proc.pid) {
-		try {
-			process.kill(-proc.pid, signal);
-			return;
-		} catch {
-			// Fall back to signaling the immediate child when process-group signaling is unavailable.
-		}
-	}
-	try {
-		proc.kill(signal);
-	} catch {
-		// The process may already have exited.
-	}
-}
-
-export function terminateProcess(
-	proc: ReturnType<typeof spawn>,
-	graceMs = KILL_GRACE_MS,
-): () => void {
-	const leaderExited = proc.exitCode !== null || proc.signalCode !== null;
-	const capturedOutputClosed = [proc.stdout, proc.stderr].every(
-		(stream) => !stream || stream.readableEnded || stream.destroyed,
-	);
-	let closed = leaderExited && capturedOutputClosed;
-	const onClose = () => {
-		closed = true;
-	};
-	proc.once("close", onClose);
-	if (!closed) signalProcess(proc, "SIGTERM");
-	const escalation = setTimeout(() => {
-		if (!closed) signalProcess(proc, "SIGKILL");
-	}, graceMs);
-	escalation.unref();
-	return () => {
-		clearTimeout(escalation);
-		proc.off("close", onClose);
-	};
-}
-
-export type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
-
-export interface ChildLaunchPolicy {
-	tools?: string[];
-	disableExtensions?: boolean;
-	disableSkills?: boolean;
-	disablePromptTemplates?: boolean;
-	disableContextFiles?: boolean;
-	projectTrust?: boolean;
-	baseSystemPrompt?: string;
-	appendSystemPromptPaths?: string[];
-	/** Package-owned explicit child extensions loaded even when unrelated extensions are disabled. */
-	extensionPaths?: string[];
-	/** Package-owned tools added to the child allowlist without changing delegated execution tools. */
-	additionalTools?: string[];
-	/** Ephemeral child-process environment consumed and cleared by a package-owned bridge. */
-	env?: NodeJS.ProcessEnv;
-	/** Internal timeout recovery control; omitted means enabled. */
-	finalizeOnTimeout?: boolean;
-	/** Internal hard deadline for the summary attempt. */
-	timeoutFinalizationMs?: number;
-	/** Optional stateful result contract retained during timeout finalization. */
-	timeoutResultFormat?: SubagentResultFormat;
-	/** Optional non-wall-clock limits for this turn. */
-	turnLimits?: TurnLimits;
-	/** Override the timeout reason when an orchestration deadline caps this child. */
-	workTimeoutReason?: "work_timeout" | "orchestration_timeout";
-	/** Public limit value reported when the effective child timeout is only the remaining budget. */
-	workTimeoutReportLimit?: number;
-	/** Absolute blocking-workflow deadline that also caps model finalization. */
-	orchestrationDeadlineAt?: number;
-	/** Completion contract requested for this turn. */
-	resultFormat?: SubagentResultFormat;
-	/** Normalized request contract retained in result details. */
-	contract?: DelegationContract;
-	/** Original task summary shown in result details when the executed prompt has contract metadata. */
-	displayTask?: string;
-	/** Immutable audit or enforcement decision made before launch. */
-	executionPlan?: ExecutionPlan;
-	/** Executor-owned authority lifetime bound to the accepted plan generation. */
-	capabilityGrant?: CapabilityGrant;
-}
-
 export async function runSingleAgent(
 	defaultCwd: string,
 	agents: AgentConfig[],

package/src/settings/inspection.ts

@@ -96,6 +96,13 @@ export interface SubagentSettingsSnapshot {
 	error?: string;
 }
 
+export interface UsageRecordingSettingsSnapshot {
+	path: string;
+	enabled: boolean;
+	source: SettingsSource;
+	error?: string;
+}
+
 export function resolveDelegationWorkflow(
 	blockingEnabled: boolean,
 	statefulEnabled: boolean,
@@ -121,6 +128,26 @@ export function buildSubagentSettingsSnapshot(
 	};
 }
 
+export function buildUsageRecordingSettingsSnapshot(
+	inspected: InspectedSubagentSettingsDocument,
+): UsageRecordingSettingsSnapshot {
+	if (!inspected.raw || !inspected.settings) {
+		return {
+			path: inspected.path,
+			enabled: false,
+			source: "default",
+			...(inspected.error ? { error: inspected.error } : {}),
+		};
+	}
+	const explicit =
+		isPlainObject(inspected.raw.usageRecording) && hasOwn(inspected.raw.usageRecording, "enabled");
+	return {
+		path: inspected.path,
+		enabled: inspected.settings.usageRecording?.enabled === true,
+		source: explicit ? "user settings" : "default",
+	};
+}
+
 export function buildConsultResourceSettingsSnapshot(
 	inspected: InspectedSubagentSettingsDocument,
 ): ConsultResourceSettingsSnapshot {

package/src/settings/schema.ts

@@ -182,5 +182,14 @@ export function normalizeSubagentSettings(value: unknown): SubagentSettings | un
 		}
 		settings.cwdPolicy = cwdPolicy;
 	}
+	if (hasOwn(value, "usageRecording")) {
+		if (!isPlainObject(value.usageRecording)) return undefined;
+		const usageRecording: NonNullable<SubagentSettings["usageRecording"]> = {};
+		if (hasOwn(value.usageRecording, "enabled")) {
+			if (typeof value.usageRecording.enabled !== "boolean") return undefined;
+			usageRecording.enabled = value.usageRecording.enabled;
+		}
+		settings.usageRecording = usageRecording;
+	}
 	return settings;
 }

package/src/settings-reader.ts

@@ -12,6 +12,7 @@ import {
 	buildStatefulLimitSettingsSnapshot,
 	buildStatefulTransportSettingsSnapshot,
 	buildSubagentSettingsSnapshot,
+	buildUsageRecordingSettingsSnapshot,
 	type CompletionDeliverySettingsSnapshot,
 	type ConsultResourceSettingsSnapshot,
 	type CwdPolicySettingsSnapshot,
@@ -20,6 +21,7 @@ import {
 	type StatefulLimitSettingsSnapshot,
 	type StatefulTransportSettingsSnapshot,
 	type SubagentSettingsSnapshot,
+	type UsageRecordingSettingsSnapshot,
 } from "./settings/inspection.js";
 import { isPlainObject, normalizeSubagentSettings } from "./settings/schema.js";
 
@@ -40,6 +42,7 @@ export {
 	type StatefulLimitSettingsSnapshot,
 	type StatefulTransportSettingsSnapshot,
 	type SubagentSettingsSnapshot,
+	type UsageRecordingSettingsSnapshot,
 } from "./settings/inspection.js";
 export { hasOwn, normalizeAgentSettings, normalizeSubagentSettings } from "./settings/schema.js";
 
@@ -162,6 +165,10 @@ export function inspectCompletionDeliverySettings(): CompletionDeliverySettingsS
 	return buildCompletionDeliverySettingsSnapshot(inspectSubagentSettingsDocument());
 }
 
+export function inspectUsageRecordingSettings(): UsageRecordingSettingsSnapshot {
+	return buildUsageRecordingSettingsSnapshot(inspectSubagentSettingsDocument());
+}
+
 export function inspectStatefulTransportSettings(): StatefulTransportSettingsSnapshot {
 	return buildStatefulTransportSettingsSnapshot(inspectSubagentSettingsDocument());
 }

package/src/settings.ts

@@ -57,6 +57,7 @@ export {
 	inspectStatefulLimitSettings,
 	inspectStatefulTransportSettings,
 	inspectSubagentSettings,
+	inspectUsageRecordingSettings,
 	normalizeAgentSettings,
 	normalizeSubagentSettings,
 	readSubagentSettings,
@@ -67,6 +68,7 @@ export {
 	type StatefulTransportSettingsSnapshot,
 	type SubagentSettingsSnapshot,
 	subagentSettingsFilePath,
+	type UsageRecordingSettingsSnapshot,
 } from "./settings-reader.js";
 
 const SETTINGS_FILE = SUBAGENT_SETTINGS_FILE;
@@ -162,6 +164,24 @@ export function updateCompletionDeliverySetting(value: CompletionDelivery): void
 	});
 }
 
+export function updateUsageRecordingSetting(enabled: boolean): void {
+	withSettingsMutationLock(() => {
+		const update = readSettingsObjectForUpdate();
+		const raw = update.document;
+		const usageRecording = raw.usageRecording;
+		if (usageRecording !== undefined && !isPlainObject(usageRecording)) {
+			throw new Error(`Cannot update invalid ${SETTINGS_FILE} usageRecording settings`);
+		}
+		writeSettingsObjectUnlocked(
+			{
+				...raw,
+				usageRecording: { ...(usageRecording ?? {}), enabled },
+			},
+			update.replaceCanonical,
+		);
+	});
+}
+
 export function updateBlockingMaxParallelTasksSetting(value: number): void {
 	if (!isPositiveInteger(value) || value > MAX_CONFIGURABLE_PARALLEL_TASKS) {
 		throw new Error(

package/src/spawn-idempotency.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import type { AgentScope, SubagentThinkingLevel } from "./agents/types.js";
+import type { CompletionRequirementMode } from "./completion-requirement.js";
 import type { DelegationContract } from "./delegation-contract.js";
 import type { SubagentResultFormat } from "./result-contract.js";
 
@@ -23,6 +24,7 @@ export interface CanonicalSpawnRequest {
 	allowConcurrentWrites: boolean;
 	contract?: DelegationContract;
 	resultFormat: SubagentResultFormat;
+	completionRequirement?: CompletionRequirementMode;
 }
 
 export function hashSpawnRequest(request: CanonicalSpawnRequest): string {
@@ -48,6 +50,9 @@ export function hashSpawnRequest(request: CanonicalSpawnRequest): string {
 				allowConcurrentWrites: request.allowConcurrentWrites,
 				...(request.contract === undefined ? {} : { contract: request.contract }),
 				resultFormat: request.resultFormat,
+				...(request.completionRequirement === "required"
+					? { completionRequirement: "required" }
+					: {}),
 			}),
 		)
 		.digest("hex");

package/src/stateful-agent-view.ts

@@ -3,28 +3,10 @@ import type { ManagedAgent } from "./registry.js";
 
 export function formatStatefulAgentLine(agent: ManagedAgent, now = Date.now()): string {
 	const elapsedSeconds = Math.max(0, Math.floor((now - agent.updatedAt) / 1000));
-	const actions =
-		agent.state === "running" || agent.state === "starting"
-			? "interrupt, close"
-			: agent.state === "closed"
-				? "inspect"
-				: "send, close";
 	const task = agent.currentTask ? ` — ${sanitizeStatusLine(agent.currentTask, 80)}` : "";
 	const unread = agent.mailbox.filter((message) => !message.readAt).length;
 	const indent = "  ".repeat(agent.depth);
-	const thinking = agent.thinkingLevel ? ` thinking:${agent.thinkingLevel}` : "";
-	const timeout = agent.currentTimeoutMs ?? agent.timeoutMs;
-	const timeoutText = timeout ? ` timeout:${timeout}ms` : "";
-	const idleTimeout = agent.currentIdleTimeoutMs ?? agent.idleTimeoutMs;
-	const idleText = idleTimeout ? ` idle:${idleTimeout}ms` : "";
-	const maxTurns = agent.currentMaxTurns ?? agent.maxTurns;
-	const turnsText = maxTurns ? ` turns:${maxTurns}` : "";
-	const maxToolCalls = agent.currentMaxToolCalls ?? agent.maxToolCalls;
-	const toolsText = maxToolCalls ? ` tools:${maxToolCalls}` : "";
-	const transport = agent.telemetry?.transport ? ` transport:${agent.telemetry.transport}` : "";
-	const phase = agent.telemetry?.phase ? ` phase:${agent.telemetry.phase}` : "";
-	const queued = agent.telemetry?.queuePosition ? ` queue:${agent.telemetry.queuePosition}` : "";
-	return `${indent}${sanitizeStatusLine(agent.taskPath ?? agent.id, 256)} (${sanitizeStatusLine(agent.id, 128)}) ${sanitizeStatusLine(agent.agent, 128)} ${agent.state} ${elapsedSeconds}s${thinking}${timeoutText}${idleText}${turnsText}${toolsText}${transport}${phase}${queued} unread:${unread} [${actions}]${task}`;
+	return `${indent}${sanitizeStatusLine(agent.taskPath ?? agent.id, 256)} · ${sanitizeStatusLine(agent.agent, 128)} · ${agentStateLabel(agent.state)} · updated ${elapsedSeconds}s ago · ${unread} unread${task}`;
 }
 
 export function summarizeStatefulAgent(agent: ManagedAgent) {
@@ -63,6 +45,9 @@ export function summarizeStatefulAgent(agent: ManagedAgent) {
 			truncated: agent.contextTruncated === true,
 		},
 		resultFormat: agent.resultFormat ?? "text",
+		completionRequirements: (agent.completionRequirements ?? []).map((record) => ({
+			...record,
+		})),
 		structuredResult: agent.structuredResult,
 		termination: agent.termination,
 		outcome: agent.outcome,
@@ -77,6 +62,17 @@ export function summarizeStatefulAgent(agent: ManagedAgent) {
 	};
 }
 
+function agentStateLabel(state: ManagedAgent["state"]): string {
+	switch (state) {
+		case "running":
+			return "working";
+		case "completed":
+			return "finished";
+		default:
+			return state;
+	}
+}
+
 function sanitizeStatusLine(value: string, maxLength: number): string {
 	return (
 		value

package/src/stateful-guidance.ts

@@ -10,26 +10,36 @@ export function createSpawnPromptGuidelines(
 				? "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or consequential independent review that covers related branches even when the final answer depends on its result; do not choose blocking parallel fan-out merely to keep delegation in the same turn."
 				: "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or consequential independent review that covers related branches even when the final answer depends on its result."
 			: blockingEnabled
-				? "With subagent_spawn completion delivery set to next-turn (the default), prefer one subagent_spawn for broad asynchronous research or consequential independent review only when the current response does not depend on its result; use the blocking subagent when the final answer depends on the detached result."
+				? "With subagent_spawn completion delivery set to next-turn (the default), prefer one subagent_spawn for broad asynchronous research or consequential independent review only when the current response does not depend on its result; when it does, use subagent_spawn only with useful overlap and call subagent_await after that overlap is complete. Do not migrate new work to the deprecated subagent tool."
 				: "With subagent_spawn completion delivery set to next-turn (the default), use subagent_spawn only when the current response does not depend on its result; complete final-answer-dependent work directly because an idle root is not awakened.";
 	return [
 		"Do not use subagent_spawn for simple or critical-path work that the main agent can perform directly. The main agent retains overall planning, immediate critical-path work, integration, final verification, and the final answer.",
 		"Before one ordinary subagent_spawn, identify concrete useful non-overlapping main-agent work you can start immediately and a supported completion integration path. If none exists, perform the task directly instead of calling subagent_spawn.",
 		"Give subagent_spawn a concise unique taskName using lowercase letters, digits, and underscores so the retained agent has a stable canonical task path.",
 		"Set subagent_spawn thinkingLevel to the lowest sufficient thinking level for the delegated task: use off or minimal for extraction, formatting, or mechanical work; low for straightforward bounded work; medium for ordinary multi-step research or implementation; high for complex debugging, design, review, or cross-file analysis; xhigh for highly ambiguous, cross-system, or high-risk analysis; and max only for the hardest tasks when quality clearly outweighs latency and cost. Omit subagent_spawn thinkingLevel only to preserve the agent or child default.",
-		"Set subagent_spawn timeoutMs to the shortest realistic work deadline for the task difficulty; use idleTimeoutMs for stalled work and maxTurns or maxToolCalls to stop repeated work without progress. Split oversized tasks instead of extending budgets merely to compensate for broad scope. Omit these fields only to preserve the retained agent or configured defaults.",
+		"Set subagent_spawn timeoutMs to the shortest realistic work deadline for the task difficulty; use idleTimeoutMs for stalled work and maxTurns or maxToolCalls to stop repeated work without progress. Scope the task to the smallest named files or questions. When setting subagent_spawn maxTurns or maxToolCalls, leave sufficient headroom for discovery, evidence reads, and final synthesis; otherwise omit them instead of guessing speculative tight values. Split oversized tasks instead of extending budgets merely to compensate for broad scope.",
+		"For an ordinary subagent_spawn, omit contract; use a delegation contract only when explicit acceptance, authority, evidence, or admission semantics are required.",
+		"Do not set subagent_spawn contract enforcement to enforce with requestedAuthority readPaths, writePaths, network, or secrets; those guarantees are unsupported and reject before child launch, while capabilities and tools remain enforceable.",
+		"If subagent_spawn rejects an unsupported guarantee, retry once with those fields removed or enforcement set to audit only when they were advisory; when any field is a required security boundary, stop instead of weakening it.",
 		deliveryGuidance,
+		...(completionDelivery === "auto-resume"
+			? [
+					'Track every final-answer-dependent subagent_spawn by setting completionRequirement to "required" and retaining its returned agentId or taskPath; treat interim output as progress, and synthesize only after every corresponding completion message is visible or terminal.',
+				]
+			: []),
 		"Keep ordinary review in the main agent with a review skill and deterministic checks; use subagent_spawn for detached review only when consequential independent verification has concrete parallel value.",
 		"Use a single subagent_spawn for a bounded implementation slice with clear ownership only when it can run beside the identified main-agent work.",
 		"Use a single subagent_spawn without concurrent main-agent work only for an explicit user-requested specialist model, tool profile, or isolation boundary.",
 		...(blockingEnabled
 			? [
-					"Use the blocking subagent instead of subagent_spawn when synchronous output is required before the main agent can continue and waiting is intentional; queued steering cannot be processed until that blocking call returns.",
-					"When subagent_spawn fits the completion-delivery policy, do not choose a blocking parallel subagent merely to keep delegation in the same turn.",
+					"The subagent tool is deprecated; do not select it merely because synchronous output is required. Prefer subagent_spawn with supported completion delivery, and use subagent_await only after useful overlapping main-agent work is complete and an intentional join is required.",
+					"Use deprecated subagent instead of subagent_spawn only for an existing caller or an explicit user request whose blocking chain, fan-in, panel, or workflow semantics do not yet have a detached replacement; queued steering cannot be processed until it returns.",
 				]
 			: []),
 		"Add another subagent_spawn only for truly independent work with safe workspace concurrency and disjoint write ownership; shared workspaces permit concurrent writes by default, so use workspaceMode worktree when repository isolation is required. The main agent still owns integration.",
 		"After subagent_spawn returns, immediately continue the identified local task; do not merely announce the spawn, wait, poll, or end the response while useful local work remains.",
+		"When completionRequirement required subagent_spawn work remains active after local work is exhausted, emit at most one brief progress sentence and end the turn; do not repeat waiting updates or use the requested final format, verdict, or conclusion until every required completion is visible or terminal. Current Pi versions do not enforce a hard pre-display barrier.",
+		"Do not duplicate assigned work from subagent_spawn while its retained agent is running; use a bounded parent fallback only after its completion reports failure or insufficient evidence.",
 		'Consume and synthesize available subagent_spawn completion messages; use subagent_manage with action "interrupt" or "close" for agents that are no longer needed.',
 		'Completion from subagent_spawn is delivered automatically. Do not poll with subagent_inspect or subagent_mailbox action "read", repeatedly check progress, or duplicate the delegated work.',
 	];

package/src/stateful-limit-ui.ts

@@ -28,10 +28,10 @@ export function statefulLimitListScreen(runtime: StatefulLimitRuntime) {
 	const current = runtime.getRuntimeStatus().limits;
 	return {
 		kind: "actions" as const,
-		title: "Detached Agent Limits",
+		title: "Background Agent Limits",
 		lines: [
-			"These limits apply after /reload or the next Pi session.",
-			"Reloading can interrupt retained detached work.",
+			"These advanced limits apply after /reload or the next Pi session.",
+			"Reloading can interrupt subagents saved for follow-up.",
 			...(inspected.error
 				? [
 						`Settings cannot be edited: ${safeTerminalText(inspected.error)}`,
@@ -46,7 +46,7 @@ export function statefulLimitListScreen(runtime: StatefulLimitRuntime) {
 						return {
 							id: definition.field,
 							label: definition.label,
-							description: `Current ${current[definition.field]} · configured ${configured?.value ?? "unavailable"} (${configured?.source ?? "unknown"})`,
+							description: `Current: ${current[definition.field]} · after reload: ${configured?.value ?? "unavailable"} (${configured?.source ?? "unknown"})`,
 							action: "pick-stateful-limit" as const,
 						};
 					})
@@ -67,7 +67,7 @@ export function statefulLimitInputScreen(field: StatefulLimitField, runtime: Sta
 		lines: [
 			definition.description,
 			`Current session: ${runtime.getRuntimeStatus().limits[field]}`,
-			`Configured after reload: ${configured?.value ?? "unavailable"} (${configured?.source ?? "unknown"})`,
+			`After reload: ${configured?.value ?? "unavailable"} (${configured?.source ?? "unknown"})`,
 			`Allowed: whole numbers ${definition.minimum === 0 ? "0 or greater" : "1 or greater"}`,
 			`Read from: ${safeTerminalText(inspected.path)}`,
 			...(inspected.writePath !== inspected.path
@@ -114,9 +114,9 @@ export async function applyStatefulLimitSetting(
 		const confirmed = await ctx.ui.confirm(
 			`Lower ${statefulLimitDefinition(field).label}?`,
 			[
-				`This configured value would omit ${affectedBefore.length} currently retained agent record${affectedBefore.length === 1 ? "" : "s"} from projected recovery after reload.`,
-				"No agent is closed now, and this menu will not reload Pi.",
-				"A later state rewrite can make omitted records unavailable for recovery.",
+				`After reload, this value could exclude ${affectedBefore.length} saved subagent record${affectedBefore.length === 1 ? "" : "s"} from recovery.`,
+				"No subagent is removed now, and this menu will not reload Pi.",
+				"A later state save can make excluded records unavailable for recovery.",
 			].join("\n\n"),
 			{ signal: options.signal },
 		);
@@ -127,7 +127,10 @@ export async function applyStatefulLimitSetting(
 			[field]: next,
 		});
 		if (!sameIds(affectedBefore, affectedAfter)) {
-			ctx.ui.notify("Detached agents changed while confirming; review the limit again.", "warning");
+			ctx.ui.notify(
+				"Current subagents changed while confirming; review the limit again.",
+				"warning",
+			);
 			return { kind: "rejected" as const };
 		}
 	}
@@ -138,7 +141,7 @@ export async function applyStatefulLimitSetting(
 	} catch (error) {
 		if (options.isCurrent() && !options.signal.aborted) {
 			ctx.ui.notify(
-				`Detached limit was not saved; the previous setting is unchanged: ${formatError(error)}`,
+				`Background-agent limit was not saved; the previous setting is unchanged: ${formatError(error)}`,
 				"error",
 			);
 		}
@@ -146,7 +149,7 @@ export async function applyStatefulLimitSetting(
 	}
 	if (options.signal.aborted || !options.isCurrent()) return { kind: "close" as const };
 	ctx.ui.notify(
-		`Saved ${statefulLimitDefinition(field).label.toLowerCase()}: ${next}. Applies after /reload; clear retained agents before reloading if their work must not be interrupted.`,
+		`Saved ${statefulLimitDefinition(field).label.toLowerCase()}: ${next}. Applies after /reload; clear current subagents first if their work must not be interrupted.`,
 		"info",
 	);
 	return { kind: "back" as const };
@@ -154,11 +157,11 @@ export async function applyStatefulLimitSetting(
 
 export function formatDetachedLimitSummary(status: StatefulSubagentRuntimeStatus): string {
 	return [
-		`${status.limits.maxAgents} retained`,
-		`${status.limits.maxActiveTurns} active turns`,
-		`${status.limits.maxChildrenPerAgent} children`,
-		`depth ${status.limits.maxDepth}`,
-		`${status.limits.maxStoredAgents} stored`,
+		`${status.limits.maxAgents} saved`,
+		`${status.limits.maxActiveTurns} working at once`,
+		`${status.limits.maxChildrenPerAgent} children each`,
+		`${status.limits.maxDepth} nested levels`,
+		`${status.limits.maxStoredAgents} stored records`,
 	].join(" · ");
 }
 
@@ -172,7 +175,7 @@ export function formatConfiguredDetachedLimitDivergence(
 			? []
 			: [`${definition.label.toLowerCase()} ${configured}`];
 	});
-	return changed.length > 0 ? `Configured after reload: ${changed.join(" · ")}` : undefined;
+	return changed.length > 0 ? `After /reload: ${changed.join(" · ")}` : undefined;
 }
 
 export function formatConfiguredDetachedLimits(
@@ -185,9 +188,9 @@ export function formatConfiguredDetachedLimits(
 }
 
 export function formatEmptyStatefulRuntime(status: StatefulSubagentRuntimeStatus): string {
-	if (!status.enabled) return "Stateful subagents are disabled in user settings.";
-	if (!status.initialized) return "Stateful subagents are not initialized for this session.";
-	return "No current-session subagents.";
+	if (!status.enabled) return "Background subagents are disabled in How subagents run.";
+	if (!status.initialized) return "Background subagents have not started in this session.";
+	return "No subagents are working or saved for follow-up in this session.";
 }
 
 function parseStatefulLimit(