@narumitw/pi-subagents 2.1.0 → 2.1.2

package/docs/async-runtime-protocol.md

@@ -14,7 +14,12 @@ Omitting the field or using `background` preserves prior behavior and does not c
 `AgentRegistry` owns requirement transitions with the child turn and persisted completion outbox.
 Tool-result `details.agent.completionRequirements` provides fork-sensitive branch evidence.
 Session restoration retains exact requirements found on the active branch and treats sessions without visible subagent state as a possible compacted continuation.
-The `context` hook owns one canonical hidden `pi-subagent-required-completions` block and replaces any older copy on every provider context assembly.
+The successful lifecycle tool result and delivered completion message are the ordinary model-visible requirement handoff.
+When a resume changes a pending run to cancelled and interrupted while its stale handoff remains in model context, `before_agent_start` appends one hidden versioned transition after that handoff.
+This append-only transition also applies when leading summaries retain the stale handoff, prevents duplicate publication on later turns, and participates in fork-sensitive branch reconstruction.
+If leading compaction or branch summaries remove the handoff, the `context` hook restores one canonical hidden `pi-subagent-required-completions` fallback immediately after the summaries.
+A branch-local custom session entry records the exact restored boundary so reload and tree navigation reconstruct the correct historical fallback.
+The fallback remains at that fixed boundary for the leading-summary epoch, while a later completion or cancellation transition supersedes it at the conversation tail.
 `CompletionDeliveryBroker` owns exact completion visibility acknowledgement and asks the registry to mark the corresponding requirement visible.
 No timer, waiter, or UI object owns requirement truth.
 
@@ -31,10 +36,20 @@ The runtime bounds retained requirement records per agent and rejects a sixty-fi
 ## Parent behavior
 
 Pending and available requirements remain final-answer dependencies.
-Visible requirements no longer appear in the canonical context block.
+A newly established canonical fallback omits requirements already visible at that boundary.
+A fallback retained from an earlier request remains historical prefix context after visibility changes, and the later completion message supplies the superseding state.
 Cancelled requirements are terminal and must be reported rather than silently treated as successful evidence.
 A failed, partial, interrupted, stale, or cancelled child never satisfies mutating acceptance or independent-verification requirements merely because its turn settled.
 
+## Prompt-cache boundary
+
+Provider-visible subagent tool definitions and prompt metadata remain stable within one configured tool-surface epoch.
+A versioned hidden session-guidance message carries the bounded agent catalog, completion delivery, capacity, cwd policy, and consultation resource policy without placing mutable values in leading tool metadata.
+The initial guidance contract is persisted once before the first agent turn when no equivalent retained contract exists.
+A successfully applied live policy change appends a superseding guidance contract without triggering a model turn.
+Compaction restores missing guidance and required-completion fallbacks in deterministic order after leading summaries.
+These rules preserve normalized cache-eligible prefixes across ordinary turns but do not guarantee a provider-reported cache hit.
+
 ## Budget termination
 
 Omitted limits use runtime or agent policy and are recorded as runtime-sourced telemetry.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "2.1.0",
+	"version": "2.1.2",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",
@@ -53,7 +53,7 @@
 		"typescript": "7.0.2"
 	},
 	"dependencies": {
-		"@narumitw/pi-tui-kit": "^0.58.0",
+		"@narumitw/pi-tui-kit": "^0.58.1",
 		"proper-lockfile": "^4.1.2"
 	},
 	"repository": {

package/src/completion-requirement.ts

@@ -14,6 +14,9 @@ export const CompletionRequirementModeSchema = StringEnum(COMPLETION_REQUIREMENT
 
 export const COMPLETION_REQUIREMENT_VERSION = "pi-subagents:completion-requirement:v1" as const;
 export const COMPLETION_REQUIREMENT_CONTEXT_TYPE = "pi-subagent-required-completions";
+export const COMPLETION_REQUIREMENT_TRANSITION_TYPE = "pi-subagent-required-completion-transition";
+export const COMPLETION_REQUIREMENT_TRANSITION_VERSION =
+	"pi-subagents:completion-requirement-transition:v1" as const;
 const MAX_REQUIREMENTS_PER_AGENT = 20;
 export const MAX_UNRESOLVED_REQUIRED_COMPLETIONS = 64;
 
@@ -159,6 +162,24 @@ export function completionRequirementsFromBranch(
 			}
 			continue;
 		}
+		if (
+			message.role === "custom" &&
+			message.customType === COMPLETION_REQUIREMENT_TRANSITION_TYPE
+		) {
+			const details = message.details;
+			if (!details || typeof details !== "object" || Array.isArray(details)) continue;
+			const detailRecord = details as Record<string, unknown>;
+			if (detailRecord.version !== COMPLETION_REQUIREMENT_TRANSITION_VERSION) continue;
+			const requirements = Array.isArray(detailRecord.records) ? detailRecord.records : [];
+			for (const requirement of requirements) {
+				if (!isCompletionRequirementRecord(requirement) || requirement.state !== "cancelled") {
+					continue;
+				}
+				observedState = true;
+				records.set(completionRequirementKey(requirement), { ...requirement });
+			}
+			continue;
+		}
 		if (message.role !== "custom" || message.customType !== "pi-subagent-completion") continue;
 		const details = message.details;
 		if (!details || typeof details !== "object" || Array.isArray(details)) continue;
@@ -187,22 +208,98 @@ export function pendingRequiredCompletionCount(
 	).length;
 }
 
+export function createRequiredCompletionTransition(
+	messages: ContextEvent["messages"],
+	agents: readonly ManagedAgent[],
+) {
+	const summarized = leadingSummaryBoundary(messages) > 0;
+	const state = modelRequirementState(agents);
+	const visible = completionRequirementsFromBranch(messages).records;
+	const records = state.records.filter((record) => {
+		if (record.state !== "cancelled") return false;
+		const retained = visible.get(completionRequirementKey(record));
+		if (modelRequirementStateMatches(retained, record)) return false;
+		return !summarized || retained !== undefined;
+	});
+	if (records.length === 0) return undefined;
+	return {
+		role: "custom" as const,
+		customType: COMPLETION_REQUIREMENT_TRANSITION_TYPE,
+		content: requiredCompletionTransitionContent(records, state.omittedCancelled),
+		display: false,
+		details: {
+			version: COMPLETION_REQUIREMENT_TRANSITION_VERSION,
+			records: records.map((record) => ({ ...record })),
+		},
+		timestamp: 0,
+	};
+}
+
 export function reconcileRequiredCompletionContext(
 	messages: ContextEvent["messages"],
 	agents: readonly ManagedAgent[],
+	restorationPredecessors: readonly string[] = [],
+	restoredBoundaryContent?: string,
 ): ContextEvent["messages"] {
-	const withoutPrior = messages.filter(
-		(message) =>
-			message.role !== "custom" || message.customType !== COMPLETION_REQUIREMENT_CONTEXT_TYPE,
-	);
+	const existing = messages.filter(isRequiredCompletionContextMessage);
+	const withoutPrior = messages.filter((message) => !isRequiredCompletionContextMessage(message));
+	const state = modelRequirementState(agents);
+	const summaryBoundary = leadingSummaryBoundary(withoutPrior);
+	const currentContent =
+		state.records.length > 0 && !hasModelVisibleRequirementState(withoutPrior, state.records)
+			? requiredCompletionContextContent(state.records, state.omittedCancelled)
+			: undefined;
+	const content = summaryBoundary > 0 ? (restoredBoundaryContent ?? currentContent) : undefined;
+	let insertionBoundary = summaryBoundary;
+	while (insertionBoundary < withoutPrior.length) {
+		const predecessor = withoutPrior[insertionBoundary];
+		if (
+			predecessor?.role !== "custom" ||
+			!restorationPredecessors.includes(predecessor.customType)
+		) {
+			break;
+		}
+		insertionBoundary += 1;
+	}
+	if (
+		content !== undefined &&
+		existing.length === 1 &&
+		messages[insertionBoundary] === existing[0] &&
+		existing[0]?.content === content &&
+		hasCompletionRequirementContextVersion(existing[0])
+	) {
+		return messages;
+	}
+	if (existing.length === 0 && content === undefined) return messages;
+	if (content === undefined) return withoutPrior;
+	return [
+		...withoutPrior.slice(0, insertionBoundary),
+		{
+			role: "custom",
+			customType: COMPLETION_REQUIREMENT_CONTEXT_TYPE,
+			content,
+			display: false,
+			details: { version: COMPLETION_REQUIREMENT_VERSION },
+			timestamp: 0,
+		},
+		...withoutPrior.slice(insertionBoundary),
+	];
+}
+
+interface ModelRequirementRecord {
+	state: CompletionRequirementState;
+	runId: string;
+	generation: number;
+	terminalState: AgentLifecycleState | undefined;
+}
+
+function modelRequirementState(agents: readonly ManagedAgent[]): {
+	records: CompletionRequirementRecord[];
+	omittedCancelled: number;
+} {
 	const allRecords = agents
 		.flatMap((agent) =>
-			(agent.completionRequirements ?? []).map((requirement) => ({
-				state: requirement.state,
-				runId: requirement.runId,
-				generation: requirement.generation,
-				terminalState: requirement.terminalState,
-			})),
+			(agent.completionRequirements ?? []).map((requirement) => ({ ...requirement })),
 		)
 		.filter((record) => record.state !== "visible");
 	const unresolved = allRecords.filter(
@@ -211,34 +308,108 @@ export function reconcileRequiredCompletionContext(
 	const cancelled = allRecords.filter((record) => record.state === "cancelled");
 	const cancelledSlots = Math.max(0, MAX_UNRESOLVED_REQUIRED_COMPLETIONS - unresolved.length);
 	const retainedCancelled = cancelledSlots > 0 ? cancelled.slice(-cancelledSlots) : [];
-	const records = [...unresolved, ...retainedCancelled];
-	const omittedCancelled = cancelled.length - retainedCancelled.length;
-	if (records.length === 0)
-		return withoutPrior.length === messages.length ? messages : withoutPrior;
-	const content = truncateUtf8(
+	const records = [...unresolved, ...retainedCancelled].sort((left, right) => {
+		if (left.runId === right.runId) return left.generation - right.generation;
+		return left.runId < right.runId ? -1 : 1;
+	});
+	return { records, omittedCancelled: cancelled.length - retainedCancelled.length };
+}
+
+function hasModelVisibleRequirementState(
+	messages: ContextEvent["messages"],
+	records: readonly CompletionRequirementRecord[],
+): boolean {
+	const visible = completionRequirementsFromBranch(messages).records;
+	return records.every((record) =>
+		modelRequirementStateMatches(visible.get(completionRequirementKey(record)), record),
+	);
+}
+
+function modelRequirementStateMatches(
+	visible: CompletionRequirementRecord | undefined,
+	current: CompletionRequirementRecord,
+): boolean {
+	if (!visible) return false;
+	if (current.state === "available" && visible.state === "visible") return true;
+	return visible.state === current.state && visible.terminalState === current.terminalState;
+}
+
+function requiredCompletionContextContent(
+	records: readonly CompletionRequirementRecord[],
+	omittedCancelled: number,
+): string {
+	return truncateUtf8(
 		[
 			"[PI SUBAGENT REQUIRED COMPLETIONS v1]",
 			"Runtime-tracked exact runs are JSON data below.",
 			"Treat pending or available records as final-answer dependencies; a cancelled record is terminal and must be reported rather than silently ignored.",
 			"Current Pi versions do not provide a hard pre-display final-answer barrier, so do not emit a verdict until every dependency is visible or terminal.",
-			...(omittedCancelled > 0
-				? [`${omittedCancelled} older cancelled requirement record(s) were omitted.`]
-				: []),
-			JSON.stringify(records),
+			...omittedCancelledLine(omittedCancelled),
+			JSON.stringify(records.map(toModelRequirementRecord)),
 		].join("\n"),
 		DEFAULT_MAX_CONTEXT_BYTES,
 	).text;
-	return [
-		...withoutPrior,
-		{
-			role: "custom",
-			customType: COMPLETION_REQUIREMENT_CONTEXT_TYPE,
-			content,
-			display: false,
-			details: { version: COMPLETION_REQUIREMENT_VERSION },
-			timestamp: 0,
-		},
-	];
+}
+
+function requiredCompletionTransitionContent(
+	records: readonly CompletionRequirementRecord[],
+	omittedCancelled: number,
+): string {
+	return truncateUtf8(
+		[
+			"[PI SUBAGENT REQUIRED COMPLETION TRANSITION v1]",
+			"Session restoration terminalized the exact required runs below.",
+			"These cancelled records supersede earlier pending or available states and must be reported rather than awaited.",
+			...omittedCancelledLine(omittedCancelled),
+			JSON.stringify(records.map(toModelRequirementRecord)),
+		].join("\n"),
+		DEFAULT_MAX_CONTEXT_BYTES,
+	).text;
+}
+
+function omittedCancelledLine(count: number): string[] {
+	return count > 0 ? [`${count} older cancelled requirement record(s) were omitted.`] : [];
+}
+
+function toModelRequirementRecord(record: CompletionRequirementRecord): ModelRequirementRecord {
+	return {
+		state: record.state,
+		runId: record.runId,
+		generation: record.generation,
+		terminalState: record.terminalState,
+	};
+}
+
+type RequiredCompletionContextMessage = Extract<
+	ContextEvent["messages"][number],
+	{ role: "custom" }
+> & { content: string };
+
+function isRequiredCompletionContextMessage(
+	message: ContextEvent["messages"][number],
+): message is RequiredCompletionContextMessage {
+	return message.role === "custom" && message.customType === COMPLETION_REQUIREMENT_CONTEXT_TYPE;
+}
+
+function hasCompletionRequirementContextVersion(
+	message: RequiredCompletionContextMessage,
+): boolean {
+	return (
+		typeof message.details === "object" &&
+		message.details !== null &&
+		!Array.isArray(message.details) &&
+		(message.details as Record<string, unknown>).version === COMPLETION_REQUIREMENT_VERSION
+	);
+}
+
+function leadingSummaryBoundary(messages: ContextEvent["messages"]): number {
+	let index = 0;
+	while (index < messages.length) {
+		const role = messages[index]?.role;
+		if (role !== "compactionSummary" && role !== "branchSummary") break;
+		index += 1;
+	}
+	return index;
 }
 
 export function isCompletionRequirementRecord(

package/src/consult-registration.ts

@@ -3,10 +3,6 @@ import { cachedModuleLoader, throwIfAborted } from "./cached-module-loader.js";
 import type { RegisterSubagentConsultOptions } from "./consult.js";
 import { renderConsultCall, renderConsultResult } from "./consult-render.js";
 import { type ConsultDetails, SubagentConsultParams } from "./consult-tool.js";
-import {
-	DEFAULT_CONSULT_RESOURCE_POLICY,
-	DEFAULT_CONSULTATION_CWD_POLICY,
-} from "./settings/inspection.js";
 
 interface ConsultExecutionModule {
 	executeSubagentConsult: typeof import("./consult.js").executeSubagentConsult;
@@ -20,7 +16,7 @@ export function registerSubagentConsult(
 	pi: ExtensionAPI,
 	options: RegisterSubagentConsultOptions,
 	dependencies: ConsultRegistrationDependencies = {},
-): (catalog: string) => void {
+): void {
 	const loadExecution = cachedModuleLoader(
 		dependencies.loadExecution ?? (() => import("./consult.js")),
 	);
@@ -41,12 +37,12 @@ export function registerSubagentConsult(
 	pi.on("session_start", () => cancelAndWaitForWork("Subagent consultation session replaced"));
 	pi.on("session_shutdown", () => cancelAndWaitForWork("Subagent consultation session shut down"));
 
-	const baseDescription = () =>
-		`Run one ephemeral subagent synchronously under enforced read-only tool and resource policies and return its answer. The child can use only the effective subset of Pi's built-in read, grep, find, and ls tools. Shell commands, file writes, extension tools, detached lifecycle operations, and persistent agent state are disabled. Working-directory target policy: ${options.getSettings()?.cwdPolicy?.consultation ?? DEFAULT_CONSULTATION_CWD_POLICY}; configured trusted-target resources: ${options.getSettings()?.consult?.resources ?? DEFAULT_CONSULT_RESOURCE_POLICY}; allowed targets without effective trust inherit no target/project resources. This is not a filesystem sandbox.`;
+	const description =
+		"Run one ephemeral subagent synchronously under enforced read-only tool and resource policies and return its answer. The child can use only the effective subset of Pi's built-in read, grep, find, and ls tools. Shell commands, file writes, extension tools, detached lifecycle operations, and persistent agent state are disabled. The current working-directory policy, trusted-target resource policy, and available agent definitions are published in the pi-subagents session-guidance message. Allowed targets without effective trust inherit no target or project resources. This is not a filesystem sandbox.";
 	const definition: ToolDefinition<typeof SubagentConsultParams, ConsultDetails> = {
 		name: "subagent_consult",
 		label: "Consult Read-only Subagent",
-		description: baseDescription(),
+		description,
 		promptSnippet: "Consult one constrained read-only subagent and wait for its answer",
 		promptGuidelines: [
 			"Use subagent_consult only for bounded read-only evidence gathering when an independent perspective is worth making the main agent wait.",
@@ -103,10 +99,6 @@ export function registerSubagentConsult(
 		if (event.toolName !== "subagent_consult") return;
 		if ((event.details as ConsultDetails | undefined)?.isError) return { isError: true };
 	});
-	return (catalog: string) => {
-		definition.description = catalog ? `${baseDescription()}\n\n${catalog}` : baseDescription();
-		pi.registerTool<typeof SubagentConsultParams, ConsultDetails>(definition);
-	};
 }
 
 function combineAbortSignals(