pi-subagents 0.65.0 → 0.66.0

package/src/runs/shared/child-hooks.ts

@@ -1,8 +1,14 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { listBackgroundWorkProviders } from "../../api/background-work.ts";
+import { ReadonlyDrainObservation } from "./readonly-drain-observation.ts";
 import registerFanoutChildSubagentExtension from "../../extension/fanout-child.ts";
 import registerSubagentFastModeExtension from "./fast-mode-extension.ts";
 import registerSubagentPromptRuntime from "./subagent-prompt-runtime.ts";
 import type { ChildRuntimeConfig } from "./child-runtime-config.ts";
+import type { ChildToolDiagnostic } from "./tool-availability.ts";
+import type { ChildSessionLaunch } from "./child-session.ts";
+import type { ChildTranscriptWriter } from "../../shared/child-transcript.ts";
+import { projectRuntimeAcknowledgedExtensions } from "./runtime-acknowledged-extensions.ts";
 
 /** Inline extension shape accepted by pi's resource loader (`extensionFactories`). */
 export interface ChildHookExtension {
@@ -10,15 +16,158 @@ export interface ChildHookExtension {
 	factory: (pi: ExtensionAPI) => void;
 }
 
+type OwnedCapture = Required<Pick<ChildRuntimeConfig, "toolDiagnostic" | "runtimeAcknowledgements">>;
+type PromptProof = { config: ChildRuntimeConfig; snapshot: string; factories?: ChildHookExtension["factory"][]; observeNext?: ReadonlyDrainObservation; observation?: ReadonlyDrainObservation; capture?: OwnedCapture; reporting?: { launch: ChildSessionLaunch; callback: ChildSessionLaunch["onExtensionError"] } };
+const promptProofs = new WeakMap<ChildHookExtension["factory"], PromptProof>();
+
+function ownedProof(hooks: ChildHookExtension[]): PromptProof | undefined {
+	const proof = hooks[0] && promptProofs.get(hooks[0].factory);
+	return proof?.factories?.length === hooks.length && proof.factories.every((factory, index) => hooks[index]?.factory === factory) ? proof : undefined;
+}
+
+/** The host's mandatory transcript reporting, owned by the existing hook certificate. */
+export function withChildSessionErrorReporting(session: Omit<ChildSessionLaunch, "onExtensionError">, transcriptWriter: ChildTranscriptWriter | undefined): ChildSessionLaunch {
+	const launch: ChildSessionLaunch = { ...session, onExtensionError: (error) => {
+		transcriptWriter?.writeStderrLine(`Extension error (${error.extensionPath}, ${error.event}): ${error.error instanceof Error ? error.error.message : String(error.error)}`);
+	} };
+	const proof = ownedProof(launch.hooks);
+	if (proof?.capture && proof.config === launch.runtime) proof.reporting = { launch, callback: launch.onExtensionError };
+	return launch;
+}
+
+export function isReadonlyChildSessionReporting(launch: ChildSessionLaunch): boolean {
+	const proof = ownedProof(launch.hooks);
+	const descriptor = Object.getOwnPropertyDescriptor(launch, "onExtensionError");
+	if (descriptor && (!descriptor.enumerable || !("value" in descriptor))) return false;
+	return proof?.reporting ? proof.reporting.launch === launch && proof.reporting.callback === descriptor?.value : !descriptor && !("onExtensionError" in launch);
+}
+
+/** Admit only own enumerable data: inspecting descriptors must not invoke getters. */
+function dataKeys(value: unknown): string[] | undefined {
+	if (!value || typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype) return undefined;
+	const keys = Reflect.ownKeys(value);
+	for (const key of keys) {
+		const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+		if (typeof key !== "string" || !descriptor.enumerable || !("value" in descriptor)) return undefined;
+	}
+	return keys as string[];
+}
+
+/** Only reviewed data and the capture callbacks constructed below; no caller callback opt-in. */
+function readonlyConfig(config: ChildRuntimeConfig, capture?: OwnedCapture): string | undefined {
+	const strings = ["runId", "agent", "sessionName", "forkCacheKey", "parentSessionId", "orchestratorSessionId"];
+	const numbers = ["childIndex", "depth", "maxDepth"];
+	const booleans = ["inheritProjectContext", "inheritGlobalContext", "inheritSkills"];
+	const keys = dataKeys(config);
+	if (!keys) return undefined;
+	if (capture && (config.toolDiagnostic !== capture.toolDiagnostic || config.runtimeAcknowledgements !== capture.runtimeAcknowledgements)) return undefined;
+	const waitKeys = dataKeys(config.waitTool);
+	if (!waitKeys || waitKeys.some((key) => key !== "enabled")) return undefined;
+	if (config.fast !== false || config.fanoutChild !== false || config.waitTool.enabled !== false) return undefined;
+	for (const key of keys) {
+		const value = Object.getOwnPropertyDescriptor(config, key)!.value;
+		if (["fast", "fanoutChild", "waitTool"].includes(key)) continue;
+		if (capture && (key === "toolDiagnostic" || key === "runtimeAcknowledgements")) continue;
+		if (capture && key === "requiredTools" && Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype) {
+			const descriptors = Object.getOwnPropertyDescriptors(value);
+			if (Reflect.ownKeys(descriptors).length !== value.length + 1) return undefined;
+			for (let i = 0; i < value.length; i++) {
+				const descriptor = descriptors[String(i)];
+				if (!descriptor?.enumerable || !("value" in descriptor) || !["read", "ls"].includes(descriptor.value)) return undefined;
+			}
+			continue;
+		}
+		if (strings.includes(key) && (value === undefined || typeof value === "string")) continue;
+		if (numbers.includes(key) && (value === undefined || (typeof value === "number" && Number.isInteger(value) && value >= 0))) continue;
+		if (booleans.includes(key) && (value === undefined || typeof value === "boolean")) continue;
+		return undefined;
+	}
+	return JSON.stringify(config);
+}
+
+function noBackgroundProviders(): boolean {
+	try {
+		return listBackgroundWorkProviders().length === 0;
+	} catch { return false; }
+}
+
+/** Internal proof of the captured closure/config, not its caller-controlled display name. */
+export function isReadonlyChildHookProfile(hooks: ChildHookExtension[], config: ChildRuntimeConfig): boolean {
+	const proof = ownedProof(hooks);
+	if (!proof) return false;
+	const valid = proof.config === config && readonlyConfig(config, proof.capture) === proof.snapshot && noBackgroundProviders();
+	if (!valid) proof.observation?.deny();
+	return valid && (proof.observation?.check() ?? true);
+}
+
+/** Arm just the next installation; ordinary installations retain the original API/handlers. */
+export function observeReadonlyChildHookDrain(hooks: ChildHookExtension[], enabled: boolean, sessionFile: string): void {
+	const proof = ownedProof(hooks);
+	if (!proof) return;
+	if (enabled) {
+		proof.observation?.deny();
+		proof.observation = undefined;
+	}
+	proof.observeNext = enabled ? new ReadonlyDrainObservation(sessionFile, () => readonlyConfig(proof.config, proof.capture) === proof.snapshot && noBackgroundProviders()) : undefined;
+}
+
+export function captureReadonlyChildDrain(hooks: ChildHookExtension[]): (() => boolean) {
+	const proof = ownedProof(hooks);
+	const observation = proof?.observation;
+	return () => !!observation && proof?.observation === observation && observation.settled();
+}
+
 /**
  * The child-side hooks pi-subagents installs in every child, keyed off the
  * launch config. The registrations live in `subagent-prompt-runtime.ts`,
  * `fast-mode-extension.ts`, and `fanout-child.ts`.
  */
 export function createChildHooks(config: ChildRuntimeConfig): ChildHookExtension[] {
+	return childHooks(config);
+}
+
+/** Launch-owned bookkeeping, paired with the same private hook certificate (no callback registration API). */
+export function createCapturedChildHooks(config: ChildRuntimeConfig, runner = false) {
+	let diagnostic: ChildToolDiagnostic | undefined;
+	let acknowledgedIds: string[] | undefined;
+	let completionIntentContext: Pick<ExtensionContext, "model" | "modelRegistry"> | undefined;
+	const capture: OwnedCapture = {
+		toolDiagnostic: (value) => { diagnostic = value; },
+		runtimeAcknowledgements: (ids) => { acknowledgedIds = ids; },
+	};
+	Object.assign(config, capture);
+	const hooks = childHooks(config, capture);
+	if (runner) {
+		hooks.push({ name: "pi-subagents:completion-intent", factory: (pi) => pi.on("session_start", (_event, childCtx) => {
+			// Retain only attempt model services, not the live child session.
+			completionIntentContext = { model: childCtx.model, modelRegistry: childCtx.modelRegistry };
+		}) });
+		const proof = promptProofs.get(hooks[0]!.factory);
+		if (proof) proof.factories = hooks.map((hook) => hook.factory);
+	}
+	return {
+		hooks,
+		completionIntentContext: () => completionIntentContext,
+		toolDiagnostic: () => diagnostic,
+		runtimeAcknowledgedExtensions: () => acknowledgedIds ? projectRuntimeAcknowledgedExtensions(acknowledgedIds) : undefined,
+	};
+}
+
+function childHooks(config: ChildRuntimeConfig, capture?: OwnedCapture): ChildHookExtension[] {
+	const snapshot = readonlyConfig(config, capture);
+	const proof: PromptProof | undefined = snapshot === undefined ? undefined : { config, snapshot, capture };
 	const hooks: ChildHookExtension[] = [
-		{ name: "pi-subagents:prompt-runtime", factory: (pi) => registerSubagentPromptRuntime(pi, config) },
+		{ name: "pi-subagents:prompt-runtime", factory: function promptRuntime(pi) {
+			if (!proof?.observeNext) return registerSubagentPromptRuntime(pi, config);
+			proof.observation = proof.observeNext;
+			proof.observeNext = undefined;
+			registerSubagentPromptRuntime(pi, config, proof.observation);
+		} },
 	];
+	if (proof) {
+		proof.factories = hooks.map((hook) => hook.factory);
+		promptProofs.set(hooks[0]!.factory, proof);
+	}
 	if (config.fast) hooks.push({ name: "pi-subagents:fast-mode", factory: (pi) => registerSubagentFastModeExtension(pi) });
 	if (config.fanoutChild) hooks.push({ name: "pi-subagents:fanout-child", factory: (pi) => registerFanoutChildSubagentExtension(pi, config) });
 	return hooks;

package/src/runs/shared/child-launch.ts

@@ -6,12 +6,13 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ChildWatchdogConfig, ChildWatchdogStatusEvent } from "../../watchdog/child-status.ts";
 import type { ThinkingLevel } from "../../shared/model-info.ts";
 import { intersectThinkingCeilings } from "../../shared/thinking-ceiling.ts";
 import {
 	resolveChildDepth,
-	type LaunchResolvedChildExtensionsV1,
+	type LaunchResolvedChildExtensions,
 	type ResolvedToolBudget,
 	type RunFanoutBudgetDescriptor,
 } from "../../shared/types.ts";
@@ -20,8 +21,7 @@ import type { McpRuntimeSnapshotHost } from "./mcp-direct-tool-allowlist.ts";
 import type { PermissionRules } from "./permissions.ts";
 import type { StructuredOutputRuntime } from "./structured-output.ts";
 import type { ChildToolDiagnostic } from "./tool-availability.ts";
-import type { RuntimeAcknowledgedChildExtensionsV1 } from "../../shared/types.ts";
-import { projectRuntimeAcknowledgedExtensions } from "./runtime-acknowledged-extensions.ts";
+import type { RuntimeAcknowledgedChildExtensions } from "../../shared/types.ts";
 import { encodeExtensionBindings, PI_SUBAGENT_EXTENSION_BINDINGS_ENV, type ExtensionBindings } from "./extension-bindings.ts";
 import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "./capability-ceiling.ts";
 import {
@@ -32,7 +32,8 @@ import {
 	type PiLaunchToolPlan,
 } from "./child-tool-plan.ts";
 import type { ChildRuntimeConfig } from "./child-runtime-config.ts";
-import { createChildHooks } from "./child-hooks.ts";
+import { createCapturedChildHooks, withChildSessionErrorReporting } from "./child-hooks.ts";
+import type { ChildTranscriptWriter } from "../../shared/child-transcript.ts";
 import type { ChildSessionLaunch, ChildSessionStorage } from "./child-session.ts";
 
 /** Environment variable pi-mcp-adapter reads for the tools a child may expose. */
@@ -114,9 +115,10 @@ export interface BuildInProcessChildLaunchInput {
 }
 
 export interface InProcessChildCapture {
+	completionIntentContext?(): Pick<ExtensionContext, "model" | "modelRegistry"> | undefined;
 	structuredOutput(): { called: boolean; value?: unknown; acceptanceReport?: unknown; acceptanceReportProvided: boolean };
 	toolDiagnostic(): ChildToolDiagnostic | undefined;
-	runtimeAcknowledgedExtensions(): RuntimeAcknowledgedChildExtensionsV1 | undefined;
+	runtimeAcknowledgedExtensions(): RuntimeAcknowledgedChildExtensions | undefined;
 }
 
 export interface InProcessChildLaunch {
@@ -124,11 +126,16 @@ export interface InProcessChildLaunch {
 	config: ChildRuntimeConfig;
 	session: Omit<ChildSessionLaunch, "onExtensionError">;
 	capture: InProcessChildCapture;
-	launchResolvedExtensions: LaunchResolvedChildExtensionsV1;
+	launchResolvedExtensions: LaunchResolvedChildExtensions;
 	warnings: string[];
 	capabilityAudit?: SubagentCapabilityAudit;
 }
 
+/** Actual host create-input boundary. Evidence remains explicitly opt-in and dormant in production. */
+export function createReportedChildSessionInput(launch: InProcessChildLaunch, transcriptWriter?: ChildTranscriptWriter): ChildSessionLaunch {
+	return withChildSessionErrorReporting(launch.session, transcriptWriter);
+}
+
 /** Escape XML-significant characters in a string for safe attribute interpolation. */
 function escapeXmlAttr(value: string): string {
 	return value
@@ -214,8 +221,6 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
 	let structuredAcceptanceReport: unknown;
 	let structuredCalled = false;
 	let structuredAcceptanceProvided = false;
-	let toolDiagnostic: ChildToolDiagnostic | undefined;
-	let acknowledgedIds: string[] | undefined;
 
 	const config: ChildRuntimeConfig = {
 		...(input.runId ? { runId: input.runId } : {}),
@@ -264,10 +269,9 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
 			: {}),
 		...(toolPlan.requiredChildTools.length > 0 ? { requiredTools: toolPlan.requiredChildTools } : {}),
 		...(toolPlan.effectiveMcpTools.length > 0 ? { mcpDirectTools: toolPlan.effectiveMcpTools } : {}),
-		toolDiagnostic: (diagnostic) => { toolDiagnostic = diagnostic; },
-		runtimeAcknowledgements: (ids) => { acknowledgedIds = ids; },
 		fast: input.fast === true,
 	};
+	const capturedHooks = createCapturedChildHooks(config, input.host === "runner");
 
 	const extensionPaths = toolPlan.extensionArgs.filter((extensionPath) => !isSubagentRuntimeExtensionPath(extensionPath));
 	const ambientExtensions = input.host === "runner" && !toolPlan.disableAmbientExtensions;
@@ -288,7 +292,7 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
 		...(!toolPlan.explicitToolAllowlist && toolPlan.excludeTools.length > 0 ? { excludeTools: toolPlan.excludeTools } : {}),
 		extensionPaths,
 		ambientExtensions,
-		hooks: createChildHooks(config),
+		hooks: capturedHooks.hooks,
 		...(input.host === "runner" ? { processEnv: childProcessEnv(input, toolPlan) } : {}),
 		runtime: config,
 		noSkills: !input.inheritSkills,
@@ -303,9 +307,10 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
 		config,
 		session,
 		capture: {
+			completionIntentContext: capturedHooks.completionIntentContext,
 			structuredOutput: () => ({ called: structuredCalled, value: structuredValue, acceptanceReport: structuredAcceptanceReport, acceptanceReportProvided: structuredAcceptanceProvided }),
-			toolDiagnostic: () => toolDiagnostic,
-			runtimeAcknowledgedExtensions: () => (acknowledgedIds ? projectRuntimeAcknowledgedExtensions(acknowledgedIds) : undefined),
+			toolDiagnostic: capturedHooks.toolDiagnostic,
+			runtimeAcknowledgedExtensions: capturedHooks.runtimeAcknowledgedExtensions,
 		},
 		launchResolvedExtensions,
 		warnings: toolPlan.warnings,

package/src/runs/shared/child-session.ts

@@ -12,6 +12,14 @@ import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "../../shared/utils.ts";
 import type { ChildRuntimeConfig } from "./child-runtime-config.ts";
+import { prepareReadonlySessionEvidence } from "./readonly-session-evidence.ts";
+import { toModelInfo, type ModelInfo } from "../../shared/model-info.ts";
+
+// Private runtime authority for host continuation planning; injected factories have none.
+const readonlyModels = new WeakMap<ChildSession, { current: ModelInfo; resolve(reference: string): ModelInfo | undefined; requestBytes: number }>();
+export function getReadonlyChildModels(child: ChildSession) {
+	return readonlyModels.get(child);
+}
 
 export interface ChildSessionEvent {
 	type: string;
@@ -115,17 +123,6 @@ export interface DefaultChildSessionFactoryOptions {
 }
 
 type ModelRuntimeInstance = Awaited<ReturnType<PiCodingAgentModule["ModelRuntime"]["create"]>>;
-type QueuedProviderRegistration = { name: string; config: Parameters<ModelRuntimeInstance["registerProvider"]>[1]; extensionPath: string };
-type QueuedNativeProviderRegistration = { provider: Parameters<ModelRuntimeInstance["registerNativeProvider"]>[0]; extensionPath: string };
-
-interface LoaderWithExtensions {
-	getExtensions(): {
-		runtime: {
-			pendingProviderRegistrations: QueuedProviderRegistration[];
-			pendingNativeProviderRegistrations: QueuedNativeProviderRegistration[];
-		};
-	};
-}
 
 /** One launch at a time from env application through `session_start`, so parallel launches never observe each other's `processEnv` while their extensions load and start. */
 let loading: Promise<unknown> = Promise.resolve();
@@ -151,25 +148,29 @@ function applyProcessEnv(values: Record<string, string | undefined> | undefined)
 	}
 }
 
-function flushQueuedProviderRegistrations(loader: object, modelRuntime: ModelRuntimeInstance, onError: ((error: ChildSessionExtensionError) => void) | undefined): void {
+async function flushQueuedProviderRegistrations(loader: InstanceType<PiCodingAgentModule["DefaultResourceLoader"]>, modelRuntime: ModelRuntimeInstance, onError: ((error: ChildSessionExtensionError) => void) | undefined): Promise<void> {
 	if (!("getExtensions" in loader) || typeof loader.getExtensions !== "function") return;
-	const { runtime } = (loader as LoaderWithExtensions).getExtensions();
-	for (const { name, config, extensionPath } of runtime.pendingProviderRegistrations) {
+	const { runtime } = loader.getExtensions();
+	let registered = false;
+	for (const { name, config, extensionPath } of runtime.pendingProviderRegistrations ?? []) {
 		try {
 			modelRuntime.registerProvider(name, config);
+			registered = true;
 		} catch (error) {
 			onError?.({ extensionPath, event: "register_provider", error });
 		}
 	}
-	runtime.pendingProviderRegistrations = [];
-	for (const { provider, extensionPath } of runtime.pendingNativeProviderRegistrations) {
+	if (Array.isArray(runtime.pendingProviderRegistrations)) runtime.pendingProviderRegistrations = [];
+	for (const { provider, extensionPath } of runtime.pendingNativeProviderRegistrations ?? []) {
 		try {
 			modelRuntime.registerNativeProvider(provider);
+			registered = true;
 		} catch (error) {
 			onError?.({ extensionPath, event: "register_provider", error });
 		}
 	}
-	runtime.pendingNativeProviderRegistrations = [];
+	if (Array.isArray(runtime.pendingNativeProviderRegistrations)) runtime.pendingNativeProviderRegistrations = [];
+	if (registered) await modelRuntime.refresh({ allowNetwork: false });
 }
 
 /**
@@ -192,10 +193,13 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 	};
 	return {
 		async create(launch) {
+			const observeReadonly = prepareReadonlySessionEvidence(launch);
 			const pi = await loadPiCodingAgent();
 			const modelRuntime = await sharedRuntime(pi);
 			const agentDir = getAgentDir();
 			const settingsManager = pi.SettingsManager.create(launch.cwd, agentDir);
+			// Headless sessions skip Pi's CLI theme setup; extensions still need ctx.ui.theme.
+			if (typeof pi.initTheme === "function") pi.initTheme(settingsManager.getTheme());
 			const loader = new pi.DefaultResourceLoader({
 				cwd: launch.cwd,
 				agentDir,
@@ -213,8 +217,11 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 			const open = async () => {
 				applyProcessEnv(launch.processEnv);
 				if (!resetExtensionCacheOnReload(loader) && (launch.ambientExtensions || launch.extensionPaths.length)) launch.onExtensionError?.({ extensionPath: "<loader>", event: "load", error: new Error("pi's extension cache reset is unavailable; extensions loaded into this child share module state with other sessions in this process.") });
-				await loader.reload();
-				flushQueuedProviderRegistrations(loader, modelRuntime, launch.onExtensionError);
+				observeReadonly?.loadingHooks(true);
+				try { await loader.reload(); } finally { observeReadonly?.loadingHooks(false); }
+				await flushQueuedProviderRegistrations(loader, modelRuntime, launch.onExtensionError);
+				// No await between receipt validation and the SDK's permissive file open.
+				observeReadonly?.beforeOpen();
 				const sessionManager = launch.storage.kind === "file"
 					? pi.SessionManager.open(launch.storage.sessionFile, undefined, launch.cwd)
 					: launch.storage.kind === "dir"
@@ -222,6 +229,7 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 						: launch.storage.kind === "memory"
 							? pi.SessionManager.inMemory(launch.cwd)
 							: pi.SessionManager.create(launch.cwd);
+				observeReadonly?.opened(sessionManager);
 				const resolvedModel = launch.model
 					? pi.resolveCliModel({ cliModel: launch.model, modelRuntime })
 					: undefined;
@@ -253,6 +261,9 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 			const opened = loading.catch(() => {}).then(open);
 			loading = opened;
 			const session = await opened;
+			let evidence: ReturnType<NonNullable<typeof observeReadonly>["observe"]>;
+			try { evidence = observeReadonly?.observe(pi, modelRuntime, session); }
+			catch (error) { session.dispose(); throw error; }
 			let pending: Promise<void> | undefined;
 			// pi's own hosts emit `session_shutdown` before disposing a session so the
 			// extensions loaded into it (ambient extensions included) release their
@@ -260,19 +271,29 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 			const shutdown = async (): Promise<void> => {
 				try {
 					const runner = session.extensionRunner;
-					if (runner.hasHandlers("session_shutdown")) await Promise.race([runner.emit({ type: "session_shutdown", reason: "quit" }), new Promise((resolve) => setTimeout(resolve, shutdownTimeoutMs).unref?.())]);
+					if (runner.hasHandlers("session_shutdown")) {
+						evidence?.beforeShutdown();
+						const settled = await Promise.race([runner.emit({ type: "session_shutdown", reason: "quit" }).then(() => true), new Promise<false>((resolve) => setTimeout(() => resolve(false), shutdownTimeoutMs).unref?.())]);
+						if (!settled) evidence?.invalidate();
+					}
 				} catch (error) {
+					evidence?.invalidate();
 					launch.onExtensionError?.({ extensionPath: "<session>", event: "session_shutdown", error });
 				} finally {
 					session.dispose();
+					evidence?.finish(child);
 				}
 			};
 			const child: ChildSession = {
 				subscribe: (listener) => session.subscribe((event) => listener(event as unknown as ChildSessionEvent)),
-				prompt: (text) => session.prompt(text),
-				steer: (text) => session.steer(text),
-				followUp: (text) => session.followUp(text),
-				abort: () => session.abort(),
+				prompt: (text) => {
+					if (!evidence) return session.prompt(text);
+					try { evidence.start(); } catch (error) { return Promise.reject(error); }
+					return session.prompt(text).then(() => evidence?.settled(), (error) => { evidence?.invalidate(); throw error; });
+				},
+				steer: (text) => { evidence?.invalidate(); return session.steer(text); },
+				followUp: (text) => { evidence?.invalidate(); return session.followUp(text); },
+				abort: () => { evidence?.invalidate(); return session.abort(); },
 				dispose: () => {
 					if (!pending) {
 						live.delete(child);
@@ -288,6 +309,16 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 				get sessionId() { return session.sessionId; },
 				get modelId() { return session.model ? `${session.model.provider}/${session.model.id}` : undefined; },
 			};
+			if (evidence && session.model) readonlyModels.set(child, {
+				current: toModelInfo(session.model),
+				requestBytes: Buffer.byteLength(session.systemPrompt) + Buffer.byteLength(JSON.stringify(session.agent.state.tools)),
+				resolve(reference) {
+					try {
+						const resolved = pi.resolveCliModel({ cliModel: reference, modelRuntime });
+						return !resolved.error && resolved.model ? toModelInfo(resolved.model) : undefined;
+					} catch { return undefined; }
+				},
+			});
 			live.add(child);
 			return child;
 		},

package/src/runs/shared/child-tool-plan.ts

@@ -16,7 +16,7 @@ import {
 import {
 	TEMP_ROOT_DIR,
 	type JsonSchemaObject,
-	type LaunchResolvedChildExtensionsV1,
+	type LaunchResolvedChildExtensions,
 } from "../../shared/types.ts";
 import { THINKING_LEVELS } from "../../shared/model-info.ts";
 import { getAgentDir } from "../../shared/utils.ts";
@@ -214,7 +214,7 @@ export function projectLaunchResolvedChildExtensions(
 		| "extensionArgs"
 		| "disableAmbientExtensions"
 	>,
-): LaunchResolvedChildExtensionsV1 {
+): LaunchResolvedChildExtensions {
 	const runtime = boundedExtensionIdentifiers(toolPlan.runtimeExtensions);
 	const configured = boundedExtensionIdentifiers(toolPlan.configuredExtensions);
 	const effective = boundedExtensionIdentifiers(toolPlan.extensionArgs);

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

@@ -26,7 +26,7 @@ export function planCompletionEvidence(input: {
 	mutationAttemptObserved: boolean;
 	mutationEvidence?: TrackedMutationEvidence;
 	arbiterRescued?: boolean;
-	agentContractV1: boolean;
+	agentContractEnabled: boolean;
 }): CompletionEvidencePlan {
 	const guardBlocked = input.guard?.blocked === true;
 	const guardTriggered = input.guardTriggered
@@ -59,7 +59,7 @@ export function planCompletionEvidence(input: {
 		mutationExpected,
 		mutationAttempted,
 		fileMutation,
-		legacyFailureError: guardTriggered && !input.agentContractV1
+		legacyFailureError: guardTriggered && !input.agentContractEnabled
 			? MISSING_IMPLEMENTATION_MUTATION_ERROR
 			: undefined,
 	};

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

@@ -13,6 +13,7 @@ const READ_ONLY_BUILTIN_TOOLS = new Set([
 	"web_search",
 	"fetch_content",
 	"get_search_content",
+	"source_check",
 	"intercom",
 	"contact_supervisor",
 	"structured_output",

package/src/runs/shared/host-step-status.ts

@@ -1,6 +1,6 @@
 import type {
 	AsyncStatus,
-	HostStepNodeV1,
+	HostStepNode,
 	HostStepState,
 	HostStepVerdict,
 	WorkflowGraphNode,
@@ -57,7 +57,7 @@ function assertTimestamp(value: unknown, field: string, source: string, required
 	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`Invalid host step '${source}': ${field} must be a non-negative safe integer.`);
 }
 
-function assertFreshness(value: unknown, source: string): asserts value is HostStepNodeV1["freshness"] {
+function assertFreshness(value: unknown, source: string): asserts value is HostStepNode["freshness"] {
 	if (!isRecord(value)) throw new Error(`Invalid host step '${source}': freshness must be an object.`);
 	const unknownFields = Object.keys(value).filter((field) => !FRESHNESS_FIELDS.has(field));
 	if (unknownFields.length > 0) throw new Error(`Invalid host step '${source}': freshness has unsupported fields: ${unknownFields.join(", ")}.`);
@@ -70,7 +70,7 @@ function assertFreshness(value: unknown, source: string): asserts value is HostS
  * Validate the persisted host-step contract. This deliberately rejects unknown
  * fields and unbounded values so status and receipt loaders fail closed.
  */
-export function assertHostStepNode(value: unknown, source = "status"): asserts value is HostStepNodeV1 {
+export function assertHostStepNode(value: unknown, source = "status"): asserts value is HostStepNode {
 	if (!isRecord(value)) throw new Error(`Invalid host step '${source}': expected an object.`);
 	const unknownFields = Object.keys(value).filter((field) => !HOST_STEP_FIELDS.has(field));
 	if (unknownFields.length > 0) throw new Error(`Invalid host step '${source}': unsupported fields: ${unknownFields.join(", ")}.`);
@@ -105,7 +105,7 @@ export function assertHostStepNode(value: unknown, source = "status"): asserts v
 	assertTimestamp(value.deadlineAt, "deadlineAt", source);
 }
 
-export function parseHostStepNode(value: unknown, source = "status"): HostStepNodeV1 {
+export function parseHostStepNode(value: unknown, source = "status"): HostStepNode {
 	assertHostStepNode(value, source);
 	return {
 		...value,
@@ -113,7 +113,7 @@ export function parseHostStepNode(value: unknown, source = "status"): HostStepNo
 	};
 }
 
-export function assertUniqueHostStepIds(hostSteps: readonly HostStepNodeV1[], source = "status"): void {
+export function assertUniqueHostStepIds(hostSteps: readonly HostStepNode[], source = "status"): void {
 	const ids = new Set<string>();
 	for (const hostStep of hostSteps) {
 		if (ids.has(hostStep.id)) throw new Error(`Invalid host step '${source}': duplicate host step id '${hostStep.id}'.`);
@@ -122,11 +122,11 @@ export function assertUniqueHostStepIds(hostSteps: readonly HostStepNodeV1[], so
 }
 
 /** Return only valid host nodes so an untrusted in-memory projection fails closed. */
-export function validHostStepNodes(graph: WorkflowGraphSnapshot | undefined): HostStepNodeV1[] {
+export function validHostStepNodes(graph: WorkflowGraphSnapshot | undefined): HostStepNode[] {
 	const nodes = graph?.nodes ?? [];
 	const nodeIdCounts = new Map<string, number>();
 	for (const node of nodes) nodeIdCounts.set(node.id, (nodeIdCounts.get(node.id) ?? 0) + 1);
-	const hostSteps: HostStepNodeV1[] = [];
+	const hostSteps: HostStepNode[] = [];
 	for (const [index, node] of nodes.entries()) {
 		if (node.kind !== "host-step") continue;
 		try {
@@ -147,7 +147,7 @@ export function assertWorkflowGraphHostSteps(graph: WorkflowGraphSnapshot | unde
 	if (!Array.isArray(graph.nodes)) throw new Error(`Invalid host step '${source}.workflowGraph': nodes must be an array.`);
 	const hostStepCount = graph.nodes.filter((node) => node.kind === "host-step").length;
 	if (hostStepCount > HOST_STEP_MAX_COUNT) throw new Error(`Invalid host step '${source}': workflowGraph contains more than ${HOST_STEP_MAX_COUNT} host steps.`);
-	const hostSteps: HostStepNodeV1[] = [];
+	const hostSteps: HostStepNode[] = [];
 	for (const [index, node] of graph.nodes.entries()) {
 		if (node.kind !== "host-step") continue;
 		const hostStep = parseHostStepNode(node.hostStep, `${source}.workflowGraph.nodes[${index}].hostStep`);
@@ -161,7 +161,7 @@ export function assertWorkflowGraphHostSteps(graph: WorkflowGraphSnapshot | unde
 	}
 }
 
-export function hostStepWorkflowNode(hostStep: HostStepNodeV1): WorkflowGraphNode {
+export function hostStepWorkflowNode(hostStep: HostStepNode): WorkflowGraphNode {
 	assertHostStepNode(hostStep, hostStep.id);
 	return {
 		id: hostStep.id,
@@ -172,7 +172,7 @@ export function hostStepWorkflowNode(hostStep: HostStepNodeV1): WorkflowGraphNod
 	};
 }
 
-function workflowNodeStatus(hostStep: HostStepNodeV1): WorkflowNodeStatus {
+function workflowNodeStatus(hostStep: HostStepNode): WorkflowNodeStatus {
 	if (hostStep.state === "pending") return "pending";
 	if (hostStep.state === "running") return "running";
 	if (hostStep.state === "cancelled") return "stopped";
@@ -187,7 +187,7 @@ function workflowNodeStatus(hostStep: HostStepNodeV1): WorkflowNodeStatus {
  */
 export function upsertHostStep(input: {
 	status: AsyncStatus;
-	hostStep: HostStepNodeV1;
+	hostStep: HostStepNode;
 	persist: (status: AsyncStatus) => void;
 }): AsyncStatus {
 	const hostStep = parseHostStepNode(input.hostStep, input.hostStep.id);