pi-subagents 0.65.1 → 0.67.0

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

@@ -1,8 +1,15 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import registerFanoutChildSubagentExtension from "../../extension/fanout-child.ts";
+import { listBackgroundWorkProviders } from "../../api/background-work.ts";
+import { ReadonlyDrainObservation } from "./readonly-drain-observation.ts";
+import registerFanoutChildSubagentExtension, { createChildSafeState } 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 { ArbiterModelContext } from "./llm-intent-arbiter.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,16 +17,173 @@ 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: ArbiterModelContext | undefined;
+	let finalDrainHeld = false;
+	const capture: OwnedCapture = {
+		toolDiagnostic: (value) => { diagnostic = value; },
+		runtimeAcknowledgements: (ids) => { acknowledgedIds = ids; },
+	};
+	Object.assign(config, capture);
+	const hooks = childHooks(config, capture, (held) => { finalDrainHeld = held; });
+	if (runner) {
+		hooks.push({ name: "pi-subagents:completion-intent", factory: (pi) => pi.on("session_start", (_event, childCtx) => {
+			// Retain only attempt model services and the session id string, not the live child session.
+			completionIntentContext = {
+				model: childCtx.model,
+				modelRegistry: childCtx.modelRegistry,
+				sessionId: childCtx.sessionManager.getSessionId(),
+			};
+		}) });
+		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,
+		finalDrainHeld: () => finalDrainHeld,
+	};
+}
+
+function childHooks(config: ChildRuntimeConfig, capture?: OwnedCapture, holdFinalDrain?: (held: boolean) => void): ChildHookExtension[] {
+	const snapshot = readonlyConfig(config, capture);
+	const proof: PromptProof | undefined = snapshot === undefined ? undefined : { config, snapshot, capture };
+	const runtime = Object.create(config) as ChildRuntimeConfig;
+	const ownedState = Object.getOwnPropertyDescriptor(config, "runtimeState");
+	if (!ownedState || !("value" in ownedState) || ownedState.value == null) {
+		Object.defineProperty(runtime, "runtimeState", { configurable: true, enumerable: true, writable: true, value: createChildSafeState() });
+	}
+	if (holdFinalDrain) {
+		Object.defineProperty(runtime, "holdFinalDrain", { configurable: true, enumerable: true, writable: true, value: holdFinalDrain });
+	}
 	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, runtime);
+			proof.observation = proof.observeNext;
+			proof.observeNext = undefined;
+			registerSubagentPromptRuntime(pi, runtime, 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) });
+	if (config.fanoutChild) hooks.push({ name: "pi-subagents:fanout-child", factory: (pi) => registerFanoutChildSubagentExtension(pi, runtime) });
 	return hooks;
 }

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

@@ -11,7 +11,7 @@ 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 +20,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,8 +31,10 @@ 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";
+import type { ArbiterModelContext } from "./llm-intent-arbiter.ts";
 
 /** Environment variable pi-mcp-adapter reads for the tools a child may expose. */
 export const MCP_DIRECT_TOOLS_ENV = "MCP_DIRECT_TOOLS";
@@ -111,12 +112,21 @@ export interface BuildInProcessChildLaunchInput {
 	 * them and exposes the child environment external extensions read.
 	 */
 	host: "parent" | "runner";
+	/**
+	 * Builtin tool names the host runtime provides. When set, child tool plans
+	 * intersect declared agent tools with this set, omitting tools the host
+	 * cannot provide. Review/scout lanes fail closed when a requested,
+	 * still-permitted repository inspection tool is missing from that set.
+	 */
+	hostAvailableBuiltins?: readonly string[];
 }
 
 export interface InProcessChildCapture {
+	completionIntentContext?(): ArbiterModelContext | undefined;
 	structuredOutput(): { called: boolean; value?: unknown; acceptanceReport?: unknown; acceptanceReportProvided: boolean };
 	toolDiagnostic(): ChildToolDiagnostic | undefined;
-	runtimeAcknowledgedExtensions(): RuntimeAcknowledgedChildExtensionsV1 | undefined;
+	runtimeAcknowledgedExtensions(): RuntimeAcknowledgedChildExtensions | undefined;
+	finalDrainHeld(): boolean;
 }
 
 export interface InProcessChildLaunch {
@@ -124,11 +134,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
@@ -185,6 +200,7 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
 		agentName: input.childAgentName,
 		permissionRules: input.permissionRules,
 		runtimeSnapshotHost: input.runtimeSnapshotHost,
+		hostAvailableBuiltins: input.hostAvailableBuiltins,
 	});
 
 	const inherited = input.inherited;
@@ -214,8 +230,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 +278,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 +301,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 +316,11 @@ 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,
+			finalDrainHeld: capturedHooks.finalDrainHeld,
 		},
 		launchResolvedExtensions,
 		warnings: toolPlan.warnings,

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

@@ -14,11 +14,14 @@ export function projectChildLifecycle(event: { type?: string; willRetry?: unknow
 		if (state) state.compactionRetryActive = event.willRetry === true;
 		return event.willRetry === true ? "cancel-drain" : "none";
 	}
-	if (event.type === "agent_start" || event.type === "auto_retry_start") {
+	if (event.type === "agent_start" || event.type === "auto_retry_start" || event.type === "turn_start") {
 		if (state) state.compactionRetryActive = false;
+		return "cancel-drain";
+	}
+	if (event.type === "agent_end") {
+		if (event.willRetry !== true && state) state.compactionRetryActive = false;
+		return "cancel-drain";
 	}
-	if (event.type === "agent_end" && event.willRetry === true) return "cancel-drain";
-	if (event.type === "agent_end" && state) state.compactionRetryActive = false;
 	if (event.type === "agent_settled") return state?.compactionRetryActive ? "none" : "start-drain";
 	if (terminalAssistantStop) return "start-drain";
 	return "none";

package/src/runs/shared/child-runtime-config.ts

@@ -1,4 +1,4 @@
-import type { JsonSchemaObject, ResolvedToolBudget, RunFanoutBudgetDescriptor } from "../../shared/types.ts";
+import type { JsonSchemaObject, ResolvedToolBudget, RunFanoutBudgetDescriptor, SubagentState } from "../../shared/types.ts";
 import type { ThinkingLevel } from "../../shared/model-info.ts";
 import type { NestedPathEntry } from "./nested-path.ts";
 import type { PermissionRules } from "./permissions.ts";
@@ -86,6 +86,8 @@ export interface ChildRuntimeConfig {
 	/** Receives child watchdog status events. */
 	watchdogStatus?: (event: ChildWatchdogStatusEvent) => void;
 	waitTool: ResolvedWaitToolConfig;
+	runtimeState?: SubagentState;
+	holdFinalDrain?: (held: boolean) => void;
 	structuredOutput?: ChildStructuredOutput;
 	requiredTools?: string[];
 	mcpDirectTools?: string[];

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;
@@ -85,6 +93,8 @@ export interface ChildSession {
 	abort(): Promise<void>;
 	/** Emits `session_shutdown` to the child's extensions and disposes the session; resolves once that shutdown work is done. */
 	dispose(): Promise<void>;
+	/** True while Pi still has steering or follow-up input that has not started a turn. */
+	hasQueuedMessages?(): boolean;
 	readonly messages: readonly AgentMessage[];
 	readonly sessionFile: string | undefined;
 	readonly sessionId: string;
@@ -95,6 +105,14 @@ export interface ChildSession {
 	shutDown?: boolean;
 }
 
+export function childSessionHasQueuedMessages(session: ChildSession | undefined): boolean {
+	try {
+		return session?.hasQueuedMessages?.() === true;
+	} catch {
+		return false;
+	}
+}
+
 export interface ChildSessionFactory {
 	create(launch: ChildSessionLaunch): Promise<ChildSession>;
 	/** Abort and dispose every live attached child; detached children keep running and hold the shared runtime. */
@@ -116,6 +134,21 @@ export interface DefaultChildSessionFactoryOptions {
 
 type ModelRuntimeInstance = Awaited<ReturnType<PiCodingAgentModule["ModelRuntime"]["create"]>>;
 
+const CHILD_PROMPT_RUNTIME_EXTENSION_PATH = "<inline:pi-subagents:prompt-runtime>";
+
+/** The prompt runtime filters parent-only context before ambient extensions inspect
+ *  the child prompt. Other inline hooks keep their normal position after ambient
+ *  extensions, and ambient extension order stays unchanged. */
+function prioritizeChildPromptRuntime<T extends { extensions: Array<{ path: string }> }>(result: T): T {
+	const index = result.extensions.findIndex(({ path }) => path === CHILD_PROMPT_RUNTIME_EXTENSION_PATH);
+	if (index <= 0) return result;
+	const extensions = [...result.extensions];
+	const [promptRuntime] = extensions.splice(index, 1);
+	if (!promptRuntime) return result;
+	extensions.unshift(promptRuntime);
+	return { ...result, extensions };
+}
+
 /** 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();
 
@@ -185,12 +218,17 @@ 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());
+			// Foreground children share Pi's global theme with the parent, so reinitializing it
+			// would overwrite the parent's active light/dark appearance. Detached runners have
+			// no initialized theme and must initialize one for headless extension renderers.
+			const themeKey = Symbol.for("@earendil-works/pi-coding-agent:theme");
+			const themeInitialized = Boolean((globalThis as Record<symbol, unknown>)[themeKey]);
+			if (!themeInitialized && typeof pi.initTheme === "function") pi.initTheme(settingsManager.getTheme());
 			const loader = new pi.DefaultResourceLoader({
 				cwd: launch.cwd,
 				agentDir,
@@ -202,14 +240,18 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 				noContextFiles: launch.noContextFiles,
 				additionalExtensionPaths: launch.extensionPaths,
 				extensionFactories: launch.hooks,
+				extensionsOverride: prioritizeChildPromptRuntime,
 				...(launch.systemPrompt !== undefined ? { systemPrompt: launch.systemPrompt } : {}),
 				...(launch.appendSystemPrompt !== undefined ? { appendSystemPrompt: [launch.appendSystemPrompt] } : {}),
 			});
 			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();
+				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"
@@ -217,6 +259,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;
@@ -248,6 +291,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
@@ -255,19 +301,30 @@ 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(); },
+				hasQueuedMessages: () => session.agent?.hasQueuedMessages?.() === true,
 				dispose: () => {
 					if (!pending) {
 						live.delete(child);
@@ -283,6 +340,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;
 		},