@narumitw/pi-subagents 2.0.5 → 2.1.0

package/src/consult-resources.ts

@@ -1,7 +1,7 @@
 import type { ConsultResourcePolicy } from "./agents/types.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
 import { resolvePiPromptResources } from "./prompt-resources.js";
-import type { ChildLaunchPolicy } from "./runner.js";
+import type { ChildLaunchPolicy } from "./runner-types.js";
 
 const MINIMAL_CONSULT_SYSTEM_PROMPT =
 	"You are a read-only consultation assistant. Analyze the delegated task using only executor-provided capabilities and return a grounded answer.";

package/src/consult.ts

@@ -34,20 +34,15 @@ import {
 	DEFAULT_MAX_STDERR_BYTES,
 	MAX_SUBAGENT_TIMEOUT_MS,
 } from "./limits.js";
-import {
-	type ChildLaunchPolicy,
-	getResultFinalOutput,
-	isResultError,
-	runSingleAgent,
-	type SingleResult,
-	type SubagentDetails,
-} from "./runner.js";
+import { getResultFinalOutput, isResultError, runSingleAgent } from "./runner.js";
+import type { ChildLaunchPolicy, SingleResult } from "./runner-types.js";
 import { boundedPrivateText, boundText, safeDisplayPath, safeTerminalLine } from "./safe-text.js";
 import {
 	DEFAULT_CONSULT_RESOURCE_POLICY,
 	DEFAULT_CONSULTATION_CWD_POLICY,
 } from "./settings/inspection.js";
 import { resolveSubagentThinkingLevel } from "./settings.js";
+import type { SubagentDetails } from "./subagent-details.js";
 
 export { registerSubagentConsult } from "./consult-registration.js";
 export type {

package/src/delegation-contract.ts

@@ -39,14 +39,51 @@ export const DelegationContractSchema = Type.Object(
 		requestedAuthority: Type.Optional(
 			Type.Object(
 				{
-					capabilities: Type.Optional(BoundedItems),
-					tools: Type.Optional(BoundedItems),
-					readPaths: Type.Optional(BoundedItems),
-					writePaths: Type.Optional(BoundedItems),
-					network: Type.Optional(StringEnum(AUTHORITY_REQUIREMENTS)),
-					secrets: Type.Optional(StringEnum(AUTHORITY_REQUIREMENTS)),
+					capabilities: Type.Optional(
+						Type.Array(BoundedItem, {
+							maxItems: MAX_ITEMS,
+							description: "Capabilities requested from the selected agent manifest.",
+						}),
+					),
+					tools: Type.Optional(
+						Type.Array(BoundedItem, {
+							maxItems: MAX_ITEMS,
+							description:
+								"Tools that enforcement may narrow to the selected agent's available set.",
+						}),
+					),
+					readPaths: Type.Optional(
+						Type.Array(BoundedItem, {
+							maxItems: MAX_ITEMS,
+							description:
+								'Audit metadata only; enforcement "enforce" rejects non-empty readPaths because path scope is unsupported.',
+						}),
+					),
+					writePaths: Type.Optional(
+						Type.Array(BoundedItem, {
+							maxItems: MAX_ITEMS,
+							description:
+								'Audit metadata only; enforcement "enforce" rejects non-empty writePaths because path scope is unsupported.',
+						}),
+					),
+					network: Type.Optional(
+						StringEnum(AUTHORITY_REQUIREMENTS, {
+							description:
+								'Audit metadata only; enforcement "enforce" rejects denied or required network guarantees as unsupported.',
+						}),
+					),
+					secrets: Type.Optional(
+						StringEnum(AUTHORITY_REQUIREMENTS, {
+							description:
+								'Audit metadata only; enforcement "enforce" rejects denied or required secret guarantees as unsupported.',
+						}),
+					),
+				},
+				{
+					additionalProperties: false,
+					description:
+						"Only capabilities and tools have executor enforcement; readPaths, writePaths, network, and secrets are unsupported guarantees.",
 				},
-				{ additionalProperties: false },
 			),
 		),
 		acceptanceCriteria: Type.Optional(BoundedItems),
@@ -76,9 +113,18 @@ export const DelegationContractSchema = Type.Object(
 			),
 		),
 		sideEffectPolicy: Type.Optional(StringEnum(DELEGATION_SIDE_EFFECT_POLICIES)),
-		enforcement: Type.Optional(StringEnum(DELEGATION_ENFORCEMENT_MODES)),
+		enforcement: Type.Optional(
+			StringEnum(DELEGATION_ENFORCEMENT_MODES, {
+				description:
+					"Defaults to audit; enforce rejects unsupported requestedAuthority guarantees before child launch.",
+			}),
+		),
+	},
+	{
+		additionalProperties: false,
+		description:
+			"Advanced delegation contract. For ordinary delegation omit this object; use it only for explicit acceptance, authority, evidence, or admission semantics.",
 	},
-	{ additionalProperties: false },
 );
 
 export interface DelegationDependency {

package/src/execution-plan.ts

@@ -201,7 +201,7 @@ export function acknowledgeExecutionPlan(plan: ExecutionPlan): ExecutionAcknowle
 	}
 	if (plan.unsupportedGuarantees.length > 0) {
 		reasonCodes.push("unsupported-guarantee");
-		recoveryActions.push("stop");
+		recoveryActions.push("repair-contract", "stop");
 	}
 	return {
 		version: EXECUTION_ACKNOWLEDGEMENT_VERSION,

package/src/execution-ui.ts

@@ -8,8 +8,8 @@ export function executionAgentPickerScreen(agents: readonly AgentConfig[]) {
 	const configured = readSubagentSettings()?.agents ?? {};
 	return {
 		kind: "actions" as const,
-		title: "Agent Execution Defaults",
-		lines: ["Choose an agent to edit its inherited model, thinking, or timeout."],
+		title: "Model, Thinking, and Time Limit",
+		lines: ["Choose a subagent. A specific request can override these starting values."],
 		items: [
 			...agents.map((agent) => {
 				const value = configured[agent.name];
@@ -17,7 +17,7 @@ export function executionAgentPickerScreen(agents: readonly AgentConfig[]) {
 					id: agent.name,
 					label: safeTerminalText(agent.name),
 					description: safeTerminalText(
-						`${agent.source} · model ${value?.model ?? agent.model ?? "inherited"} · thinking ${value?.thinkingLevel ?? agent.thinkingLevel ?? "inherited"} · timeout ${value?.timeoutMs ?? agent.timeoutMs ?? "inherited"}`,
+						`${agent.source} · model ${value?.model ?? agent.model ?? "default"} · thinking ${value?.thinkingLevel ?? agent.thinkingLevel ?? "default"} · time limit ${value?.timeoutMs ?? agent.timeoutMs ?? "default"}`,
 					),
 					action: "pick-execution-agent" as const,
 				};
@@ -32,8 +32,8 @@ export function executionAgentScreen(agent: AgentConfig | undefined) {
 	if (!agent) {
 		return {
 			kind: "actions" as const,
-			title: "Agent Execution Defaults",
-			lines: ["No agent selected."],
+			title: "Model, Thinking, and Time Limit",
+			lines: ["No subagent selected."],
 			items: [{ id: "back", label: "Back", action: "back" as const }],
 			hint: "back" as const,
 		};
@@ -41,21 +41,21 @@ export function executionAgentScreen(agent: AgentConfig | undefined) {
 	const configured = readSubagentSettings()?.agents?.[agent.name];
 	return {
 		kind: "actions" as const,
-		title: `${safeTerminalText(agent.name)} execution`,
+		title: `${safeTerminalText(agent.name)} defaults`,
 		lines: [
-			`Model: ${safeTerminalText(configured?.model ?? agent.model ?? "inherited")}`,
-			`Thinking: ${configured?.thinkingLevel ?? agent.thinkingLevel ?? "inherited"}`,
-			`Timeout: ${configured?.timeoutMs ?? agent.timeoutMs ?? "inherited"}`,
-			"Explicit tool-call values remain authoritative.",
+			`Model: ${safeTerminalText(configured?.model ?? agent.model ?? "agent or Pi default")}`,
+			`Thinking: ${configured?.thinkingLevel ?? agent.thinkingLevel ?? "agent or Pi default"}`,
+			`Time limit: ${configured?.timeoutMs ?? agent.timeoutMs ?? "agent or Pi default"}`,
+			"A specific subagent request can override these defaults.",
 		],
 		items: [
 			{ id: "thinking", label: "Thinking level", to: "execution-thinking" as const },
 			{ id: "model", label: "Model", to: "execution-model" as const },
-			{ id: "timeout", label: "Timeout", to: "execution-timeout" as const },
+			{ id: "timeout", label: "Time limit", to: "execution-timeout" as const },
 			{
 				id: "reset",
-				label: "Reset execution defaults",
-				description: "Restore frontmatter or Pi inheritance without changing tools",
+				label: "Use agent or Pi defaults",
+				description: "Remove custom model, thinking, and time limit without changing tools",
 				action: "reset-agent-execution" as const,
 			},
 			{ id: "back", label: "Back", action: "back" as const },
@@ -74,9 +74,19 @@ export function executionThinkingScreen(agent: AgentConfig | undefined) {
 					{
 						id: "thinking",
 						label: "Default thinking level",
-						description: "Explicit spawn or blocking call values still win.",
-						currentValue: configured?.thinkingLevel ?? agent.thinkingLevel ?? "Inherited",
-						values: ["Inherited", "off", "minimal", "low", "medium", "high", "xhigh", "max"],
+						description: "A specific subagent request can override this value.",
+						currentValue:
+							configured?.thinkingLevel ?? agent.thinkingLevel ?? "Use agent or Pi default",
+						values: [
+							"Use agent or Pi default",
+							"off",
+							"minimal",
+							"low",
+							"medium",
+							"high",
+							"xhigh",
+							"max",
+						],
 						action: "set-agent-thinking" as const,
 					},
 				]
@@ -96,15 +106,15 @@ export function executionModelScreen(agent: AgentConfig | undefined, ctx: Extens
 		kind: "actions" as const,
 		title: agent ? `${safeTerminalText(agent.name)} model` : "Agent model",
 		lines: [
-			`Current: ${safeTerminalText(configured?.model ?? agent?.model ?? "inherited")}`,
-			"Choose a session-available model or enter a custom Pi model pattern.",
+			`Current: ${safeTerminalText(configured?.model ?? agent?.model ?? "agent or Pi default")}`,
+			"Choose an available model or enter a custom Pi model pattern.",
 		],
 		items: agent
 			? [
 					{
 						id: "model:__inherited__",
-						label: "Inherited",
-						description: "Use frontmatter or active Pi model resolution",
+						label: "Use agent or Pi default",
+						description: "Remove the custom model setting",
 						action: "set-agent-model" as const,
 					},
 					...models.map((model) => ({
@@ -131,9 +141,9 @@ export function executionModelInputScreen(agent: AgentConfig | undefined) {
 		kind: "input" as const,
 		title: agent ? `${safeTerminalText(agent.name)} model` : "Agent model",
 		lines: [
-			`Current: ${safeTerminalText(configured?.model ?? agent?.model ?? "inherited")}`,
+			`Current: ${safeTerminalText(configured?.model ?? agent?.model ?? "agent or Pi default")}`,
 			"Enter a Pi CLI model pattern, including an optional :thinking suffix.",
-			"Use Reset execution defaults to restore inheritance.",
+			"Use agent or Pi defaults to remove this custom value.",
 		],
 		placeholder: "provider/model or model pattern",
 		action: "set-agent-model" as const,
@@ -145,13 +155,13 @@ export function executionTimeoutInputScreen(agent: AgentConfig | undefined) {
 	const configured = agent ? readSubagentSettings()?.agents?.[agent.name] : undefined;
 	return {
 		kind: "input" as const,
-		title: agent ? `${safeTerminalText(agent.name)} timeout` : "Agent timeout",
+		title: agent ? `${safeTerminalText(agent.name)} time limit` : "Agent time limit",
 		lines: [
-			`Current: ${configured?.timeoutMs ?? agent?.timeoutMs ?? "inherited"}`,
+			`Current: ${configured?.timeoutMs ?? agent?.timeoutMs ?? "agent or Pi default"}`,
 			`Allowed: 1-${MAX_SUBAGENT_TIMEOUT_MS} milliseconds.`,
-			"Use Reset execution defaults to restore inheritance.",
+			"Use agent or Pi defaults to remove this custom value.",
 		],
-		placeholder: "Timeout in milliseconds",
+		placeholder: "Time limit in milliseconds",
 		action: "set-agent-timeout" as const,
 		hint: "back" as const,
 	};
@@ -163,7 +173,8 @@ export function applyAgentThinking(
 	ctx: ExtensionCommandContext,
 ) {
 	if (!agent) return { kind: "rejected" as const };
-	const thinkingLevel = value === "Inherited" ? undefined : (value as SubagentThinkingLevel);
+	const thinkingLevel =
+		value === "Use agent or Pi default" ? undefined : (value as SubagentThinkingLevel);
 	if (
 		thinkingLevel !== undefined &&
 		!["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(thinkingLevel)
@@ -196,12 +207,12 @@ export function applyAgentTimeout(
 	if (!agent) return { kind: "rejected" as const };
 	const normalized = value?.trim() ?? "";
 	if (!/^\d+$/u.test(normalized)) {
-		ctx.ui.notify("Timeout must be a whole number of milliseconds.", "warning");
+		ctx.ui.notify("Time limit must be a whole number of milliseconds.", "warning");
 		return { kind: "rejected" as const };
 	}
 	const timeoutMs = Number(normalized);
 	if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_SUBAGENT_TIMEOUT_MS) {
-		ctx.ui.notify(`Timeout must be between 1 and ${MAX_SUBAGENT_TIMEOUT_MS}.`, "warning");
+		ctx.ui.notify(`Time limit must be between 1 and ${MAX_SUBAGENT_TIMEOUT_MS}.`, "warning");
 		return { kind: "rejected" as const };
 	}
 	return saveAgentPatch(agent.name, { timeoutMs }, ctx, "timeout");

package/src/execution.ts

@@ -65,17 +65,16 @@ import {
 	getResultFinalOutput,
 	isResultError,
 	mapWithConcurrencyLimit,
-	type OnUpdateCallback,
 	runSingleAgent,
-	type SingleResult,
-	type SubagentDetails,
 } from "./runner.js";
+import type { SingleResult } from "./runner-types.js";
 import { safeTerminalLine } from "./safe-text.js";
 import {
 	DEFAULT_DELEGATION_CWD_POLICY,
 	resolveBlockingMaxParallelTasks,
 } from "./settings/inspection.js";
 import { readSubagentSettings, resolveSubagentThinkingLevel } from "./settings.js";
+import type { OnUpdateCallback, SubagentDetails } from "./subagent-details.js";
 import { isRetryableResult, runHedgedAttempt, supervisionDelay } from "./supervision.js";
 import { TimeoutProgressJournal, TURN_TERMINATION_VERSION } from "./timeout-checkpoint.js";
 import type { TurnLimits } from "./turn-budget.js";

package/src/inspect.ts

@@ -25,8 +25,10 @@ import {
 	inspectStatefulLimitSettings,
 	inspectStatefulTransportSettings,
 	inspectSubagentSettings,
+	inspectUsageRecordingSettings,
 } from "./settings.js";
 import type { StatefulSubagentRuntimeStatus } from "./stateful.js";
+import type { UsageRecordingStatus } from "./usage-recording.js";
 import type { WorkItemLedgerSnapshot } from "./work-item-ledger.js";
 import { inspectSessionWorkflows } from "./work-item-persistence.js";
 
@@ -41,6 +43,7 @@ export interface SubagentInspectRuntime {
 	getConsultResourcePolicy(): "project-context" | "none" | "all";
 	getConsultationCwdPolicy(): ConsultationCwdPolicy;
 	getDelegationCwdPolicy(): DelegationCwdPolicy;
+	getUsageRecordingStatus?(): UsageRecordingStatus;
 	getRuntimeStatus(): StatefulSubagentRuntimeStatus;
 	listRunInspection(includeClosed?: boolean): AgentRunInspectionSummary[];
 	getRunInspection(agentId: string): AgentRunInspectionDetail | undefined;
@@ -344,6 +347,9 @@ function projectRunSummary(run: AgentRunInspectionSummary): Record<string, unkno
 		unreadMessages: run.unreadMessages,
 		turnGeneration: run.turnGeneration,
 		pendingCompletionCount: run.pendingCompletionCount,
+		...(run.pendingRequiredCompletionCount === undefined
+			? {}
+			: { pendingRequiredCompletionCount: run.pendingRequiredCompletionCount }),
 	};
 }
 
@@ -379,6 +385,9 @@ function projectRun(run: AgentRunInspectionDetail, ctx: ExtensionContext): Recor
 				}
 			: undefined,
 		resultFormat: run.resultFormat ?? "text",
+		completionRequirements: (run.completionRequirements ?? []).map((requirement) => ({
+			...requirement,
+		})),
 		structuredResult: run.structuredResult,
 		termination: run.termination,
 		outcome: run.outcome,
@@ -577,6 +586,8 @@ function projectStatus(runtime: SubagentInspectRuntime): Record<string, unknown>
 	const parallelLimit = inspectBlockingParallelLimitSettings();
 	const detachedLimits = inspectStatefulLimitSettings();
 	const transport = inspectStatefulTransportSettings();
+	const usageRecording = inspectUsageRecordingSettings();
+	const usageStatus = runtime.getUsageRecordingStatus?.();
 	const configuredDetachedLimits = detachedLimits.values
 		? Object.fromEntries(
 				Object.entries(detachedLimits.values).map(([field, snapshot]) => [field, snapshot.value]),
@@ -599,6 +610,16 @@ function projectStatus(runtime: SubagentInspectRuntime): Record<string, unknown>
 		configuredStatefulLimitSources: configuredDetachedLimitSources,
 		configuredCompletionDelivery: completion.value,
 		configuredCompletionDeliverySource: completion.source,
+		usageRecording: usageStatus
+			? {
+					enabled: usageStatus.enabled,
+					retentionDays: usageStatus.retentionDays,
+					recordedEvents: usageStatus.recordedEvents,
+					writeFailure: usageStatus.writeFailure,
+				}
+			: { enabled: false },
+		configuredUsageRecording: usageRecording.enabled,
+		configuredUsageRecordingSource: usageRecording.source,
 		maxParallelTasks: runtime.getMaxParallelTasks(),
 		configuredMaxParallelTasks: parallelLimit.value,
 		configuredMaxParallelTasksSource: parallelLimit.source,
@@ -619,7 +640,8 @@ function projectStatus(runtime: SubagentInspectRuntime): Record<string, unknown>
 			completion.error ||
 			parallelLimit.error ||
 			detachedLimits.error ||
-			transport.error
+			transport.error ||
+			usageRecording.error
 				? boundedPrivateText(
 						configured.error ??
 							resources.error ??
@@ -628,6 +650,7 @@ function projectStatus(runtime: SubagentInspectRuntime): Record<string, unknown>
 							parallelLimit.error ??
 							detachedLimits.error ??
 							transport.error ??
+							usageRecording.error ??
 							"",
 						2 * 1024,
 					)

package/src/orchestration-metrics.ts

@@ -1,4 +1,4 @@
-import type { SingleResult } from "./runner.js";
+import type { SingleResult } from "./runner-types.js";
 import type { WorkItemLedgerSnapshot } from "./work-item-ledger.js";
 
 export interface OrchestrationMetrics {

package/src/panel-execution.ts

@@ -31,15 +31,14 @@ import { buildPanelReviewerPrompt, buildPanelSynthesisPrompt } from "./panel-pro
 import { reconcilePanel } from "./panel-reconciliation.js";
 import type { SubagentParams } from "./params.js";
 import {
-	type ChildLaunchPolicy,
 	getResultFinalOutput,
 	isResultError,
 	mapWithConcurrencyLimit,
 	runSingleAgent,
-	type SingleResult,
-	type SubagentDetails,
 } from "./runner.js";
+import type { ChildLaunchPolicy, SingleResult } from "./runner-types.js";
 import { boundedPrivateText, boundText } from "./safe-text.js";
+import type { SubagentDetails } from "./subagent-details.js";
 import { createSessionWorkItemPersistence } from "./work-item-persistence.js";
 import { assertWorkspaceIsolationReady } from "./workspace.js";
 

package/src/panel-failure.ts

@@ -1,4 +1,4 @@
-import type { SingleResult } from "./runner.js";
+import type { SingleResult } from "./runner-types.js";
 
 export const PANEL_FAILURE_KINDS = [
 	"transient-launch",

package/src/panel-render.ts

@@ -2,7 +2,7 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import type { SubagentParams } from "./params.js";
 import { safeBlock, safeLine } from "./render-common.js";
-import type { SubagentDetails } from "./runner.js";
+import type { SubagentDetails } from "./subagent-details.js";
 
 export function renderPanelCall(args: SubagentParams, theme: Theme): Text | undefined {
 	const panel = args.panel;

package/src/parallel-limit-ui.ts

@@ -14,11 +14,12 @@ export function blockingParallelLimitScreen(runtime: BlockingParallelLimitRuntim
 	const limit = inspectBlockingParallelLimitSettings();
 	return {
 		kind: "input" as const,
-		title: "Maximum Parallel Workers",
+		title: "Blocking Worker Limit",
 		lines: [
-			`Current: ${runtime.getMaxParallelTasks()} worker tasks per blocking call`,
+			"This applies only to requests that make Pi wait for delegated work.",
+			`Current: ${runtime.getMaxParallelTasks()} subagents per blocking request`,
 			`Allowed: 1-${MAX_CONFIGURABLE_PARALLEL_TASKS}`,
-			`Parallel execution still starts at most ${MAX_BLOCKING_PARALLEL_CONCURRENCY} workers at once.`,
+			`Pi still starts at most ${MAX_BLOCKING_PARALLEL_CONCURRENCY} of them at once.`,
 			safeTerminalText(limit.path),
 		],
 		placeholder: "Enter a whole number",
@@ -89,7 +90,7 @@ export function applyBlockingParallelLimitSetting(
 		}
 	}
 	ctx.ui.notify(
-		`${settingsChanged ? "Saved and " : ""}applied: maximum ${next} parallel workers per blocking call.`,
+		`${settingsChanged ? "Saved and " : ""}applied: maximum ${next} subagents per blocking request.`,
 		"info",
 	);
 	return { kind: "back" as const };
@@ -97,7 +98,7 @@ export function applyBlockingParallelLimitSetting(
 
 function notifyValidationError(ctx: ExtensionCommandContext): void {
 	ctx.ui.notify(
-		`Maximum parallel workers must be a whole number from 1 to ${MAX_CONFIGURABLE_PARALLEL_TASKS}.`,
+		`Blocking worker limit must be a whole number from 1 to ${MAX_CONFIGURABLE_PARALLEL_TASKS}.`,
 		"warning",
 	);
 }

package/src/params.ts

@@ -5,6 +5,7 @@ import { DelegationContractSchema } from "./delegation-contract.js";
 import { MAX_CONFIGURABLE_PARALLEL_TASKS, MAX_SUBAGENT_TIMEOUT_MS } from "./limits.js";
 import { PANEL_PRESETS } from "./panel-presets.js";
 import { SUBAGENT_RESULT_FORMATS } from "./result-contract.js";
+import { grammarSafeToolObject } from "./tool-schema-compatibility.js";
 import { MAX_SUBAGENT_TOOL_CALLS, MAX_SUBAGENT_TURNS } from "./turn-budget.js";
 import { VerifiedExecutionContractSchema } from "./verified-execution-schema.js";
 
@@ -202,7 +203,7 @@ const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
 	default: "user",
 });
 
-export const SubagentParams = Type.Object({
+export const SubagentParams = grammarSafeToolObject({
 	agent: Type.Optional(
 		Type.String({ description: "Name of the agent to invoke (for single mode)" }),
 	),

package/src/persistence.ts

@@ -5,6 +5,7 @@ import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-ag
 import { projectAgentRecords } from "./agent-projection.js";
 import { isThinkingLevel } from "./agents/types.js";
 import { isCapabilityGrant, revokeCapabilityGrant } from "./capability-grant.js";
+import { isCompletionRequirementRecord } from "./completion-requirement.js";
 import { redactPrivateText } from "./context.js";
 import { normalizeDelegationContract } from "./delegation-contract.js";
 import { copyExecutionPlan, isExecutionPlan } from "./execution-plan.js";
@@ -171,6 +172,10 @@ function sanitizeAgent(agent: ManagedAgent): ManagedAgent {
 				output: redactPrivateText(completion.output),
 				error: completion.error ? redactPrivateText(completion.error) : undefined,
 			})),
+		completionRequirements: (agent.completionRequirements ?? [])
+			.filter(isCompletionRequirementRecord)
+			.slice(-MAX_STORED_COMPLETIONS_PER_AGENT)
+			.map((record) => ({ ...record })),
 		currentTimeoutMs: undefined,
 		currentIdleTimeoutMs: undefined,
 		currentMaxTurns: undefined,
@@ -261,6 +266,10 @@ function isStoredState(value: unknown): value is StoredState {
 			(record.turnGeneration === undefined || isNonNegativeInteger(record.turnGeneration)) &&
 			(record.pendingCompletions === undefined ||
 				isCompletionOutbox(record.pendingCompletions, record.turnGeneration ?? 0)) &&
+			(record.completionRequirements === undefined ||
+				(Array.isArray(record.completionRequirements) &&
+					record.completionRequirements.length <= MAX_STORED_COMPLETIONS_PER_AGENT &&
+					record.completionRequirements.every(isCompletionRequirementRecord))) &&
 			(record.spawnIdempotencyKey === undefined ||
 				(typeof record.spawnIdempotencyKey === "string" &&
 					record.spawnIdempotencyKey.length > 0 &&

package/src/process-control.ts

@@ -0,0 +1,43 @@
+import type { spawn } from "node:child_process";
+
+export const KILL_GRACE_MS = 5000;
+
+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);
+	};
+}

package/src/registry-types.ts

@@ -1,5 +1,6 @@
 import type { SubagentThinkingLevel } from "./agents/types.js";
 import type { CapabilityGrant } from "./capability-grant.js";
+import type { CompletionRequirementRecord } from "./completion-requirement.js";
 import type { TargetPolicyAudit } from "./cwd-policy.js";
 import type { DelegationContract } from "./delegation-contract.js";
 import type { ExecutionPlan } from "./execution-plan.js";
@@ -14,6 +15,7 @@ export type AgentLifecycleState =
 	| "running"
 	| "idle"
 	| "completed"
+	| "partial"
 	| "blocked"
 	| "needs-input"
 	| "abstained"
@@ -85,6 +87,7 @@ export interface ManagedAgent {
 	currentRunId?: string;
 	currentTurnGeneration?: number;
 	pendingCompletions?: PersistedAgentCompletion[];
+	completionRequirements?: CompletionRequirementRecord[];
 	history: AgentTurn[];
 	error?: string;
 	context?: string;
@@ -123,6 +126,7 @@ export interface AgentRunInspectionSummary {
 	unreadMessages: number;
 	turnGeneration: number;
 	pendingCompletionCount: number;
+	pendingRequiredCompletionCount?: number;
 }
 
 export interface AgentRunInspectionDetail extends AgentRunInspectionSummary {
@@ -156,6 +160,7 @@ export interface AgentRunInspectionDetail extends AgentRunInspectionSummary {
 	semanticSnapshot?: SemanticSnapshot;
 	semanticCompatibility?: SemanticCompatibility;
 	termination?: TurnTerminationReport;
+	completionRequirements?: CompletionRequirementRecord[];
 	telemetry?: TransportTelemetry;
 }