@aeondave/pi-persona 1.17.1 → 1.17.4

package/src/engine/child.ts

@@ -10,11 +10,13 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
+import type { ThinkingLevel } from "../core/types.ts";
 import { applyEvent, type ChildUsage, createStreamState, feedLines, type ProgressSnapshot, snapshot } from "./stream.ts";
 
 export interface ChildRunSpec {
 	task: string;
 	model?: string;
+	thinking?: ThinkingLevel;
 	tools?: string[];
 	excludeTools?: string[];
 	systemPrompt?: string;
@@ -32,6 +34,7 @@ export interface ChildRunResult {
 	/** True when the idle watchdog OR the hard wall-clock cap fired. Disjoint from `aborted`. */
 	timedOut: boolean;
 	model?: string;
+	thinkingEffective?: ThinkingLevel;
 	stopReason?: string;
 	errorMessage?: string;
 }
@@ -166,6 +169,7 @@ export async function runChildAgent(
 
 	const args: string[] = ["--mode", "json", "-p", "--no-session"];
 	if (spec.model) args.push("--model", spec.model);
+	if (spec.thinking !== undefined) args.push("--thinking", spec.thinking);
 	if (spec.tools !== undefined) {
 		if (spec.tools.length > 0) args.push("--tools", spec.tools.join(","));
 		else args.push("--no-tools");
@@ -201,13 +205,16 @@ export async function runChildAgent(
 			const inv = resolveInvocation(args);
 			// A stale broker wiring in the SUPERVISOR's own environment must not leak into a
 			// plain child: PI_PERSONA_BUS would boot the child's bridge against a dead (or
-			// foreign) endpoint. The adapter re-adds these deliberately via opts.env when a
-			// broker is actually live for THIS run.
+			// foreign) endpoint, and a stale reader token would arm a read_result tool nobody
+			// granted. The adapter re-adds these deliberately via opts.env when a broker (and a
+			// result-reader grant) is actually live for THIS run.
 			const inherited = { ...process.env };
 			delete inherited.PI_PERSONA_BUS;
 			delete inherited.PI_PERSONA_HANDLE;
 			delete inherited.PI_PERSONA_PEERS;
 			delete inherited.PI_PERSONA_ALLOW_BLOCKING;
+			delete inherited.PI_PERSONA_BUS_TOOLS;
+			delete inherited.PI_PERSONA_RESULT_READER_TOKEN;
 			const proc = spawn(inv.command, inv.args, {
 				cwd: spec.cwd ?? process.cwd(),
 				shell: false,
@@ -242,7 +249,7 @@ export async function runChildAgent(
 			const onLine = (line: string) => {
 				if (!line.trim()) return;
 				try {
-					const toolEvent = applyEvent(state, JSON.parse(line), Date.now());
+					const toolEvent = applyEvent(state, JSON.parse(line));
 					// Ordinary stream progress stays coalesced to one snapshot per stdout chunk below.
 					// Tool lifecycle transitions are the exception: several can share one chunk and each
 					// authoritative transition must cross the progress seam exactly once.
@@ -496,6 +503,7 @@ export async function runChildAgent(
 			timedOut: timedOut || hardTimedOut || startupTimedOut,
 		};
 		if (state.model !== undefined) result.model = state.model;
+		if (state.thinkingEffective !== undefined) result.thinkingEffective = state.thinkingEffective;
 		if (state.stopReason !== undefined) result.stopReason = state.stopReason;
 		// errorMessage precedence: a timeout/abort is the *cause of death*, so label
 		// it explicitly and fold in any stream-level error rather than letting the
@@ -509,7 +517,7 @@ export async function runChildAgent(
 			// start and was waiting on a slow first response.
 			result.errorMessage = `agent produced no progress within the ${opts.startupTimeoutMs}ms startup window — either it never started (a stalled init, e.g. an MCP adapter hanging) or its first provider response was slower than the window (a queued or rate-limited provider, a cold local model); raise or disable the window with PI_PERSONA_AGENT_STARTUP_MS (0 disables)${streamErr ? ` (last error: ${streamErr})` : ""}`;
 		} else if (timedOut) {
-			result.errorMessage = `agent timed out — no output for ${opts.timeoutMs}ms${streamErr ? ` (last error: ${streamErr})` : ""}`;
+			result.errorMessage = `agent timed out — no output for ${opts.timeoutMs}ms (raise this leg's timeoutMs if its tool is legitimately silent)${streamErr ? ` (last error: ${streamErr})` : ""}`;
 		} else if (aborted) {
 			result.errorMessage = `agent aborted${streamErr ? ` (last error: ${streamErr})` : ""}`;
 		} else if (oversizedLine) {

package/src/engine/host-module.ts

@@ -0,0 +1,12 @@
+/** A missing hashed chunk in Pi's own bundle is a local host problem, not a provider outage.
+ * Pure and deliberately narrow: ordinary missing packages or a worker's own imports get no hint. */
+export function piHostModuleHint(error: string): string | undefined {
+	const normalized = error.replaceAll("\\", "/");
+	const match = /Cannot find module (["'])([^"'\r\n]+\/@earendil-works\/pi-coding-agent\/dist\/bundle\/chunks\/[A-Za-z0-9_-]+-[A-Z0-9]{8}\.js)\1 imported from ([^\r\n]+)/.exec(normalized);
+	const missing = match?.[2];
+	const importer = match?.[3]?.trim();
+	if (!missing || !importer) return undefined;
+	const directory = missing.slice(0, missing.lastIndexOf("/") + 1);
+	if (!importer.startsWith(directory) || !/^[^/]+\.js$/.test(importer.slice(directory.length))) return undefined;
+	return "A local Pi host bundle module could not load; the host may have been updated in place while this session was running. Retry in a fresh Pi process with the same provider/model; only if the fresh process also fails, repair the Pi installation. Switching provider/model does not repair a missing local module.";
+}

package/src/engine/inproc.ts

@@ -26,20 +26,28 @@ import { makeContactSupervisorTool } from "../bus/contact.ts";
 import { makeContactPeerTool } from "../bus/peers.ts";
 import { type ContractDef, contractInstructions, parseAndValidate, pinContract, type PinnedContract } from "../core/contract.ts";
 import { sanitizeDisplayLabel } from "../core/display-label.ts";
+import { resolveLegThinking } from "../core/leg-thinking.ts";
 import { assignedIdentityPrompt } from "../core/naming.ts";
 import { attributeInbound } from "../core/fence.ts";
 import { isThinkingLevel, type ThinkingLevel } from "../core/types.ts";
 import { roleHint } from "../orchestration/roster.ts";
 import { type AgentRunSpec, isPositiveFiniteMs, type SteerFn, type StrategyEngine } from "../orchestration/sdk.ts";
 import type { AgentResult } from "../orchestration/types.ts";
+import { makeReadResultTool } from "../tools/read-result.ts";
+import { admitResultReadTool, referenceHandoffFailure } from "./result-grant.ts";
+import { makeScopedResultReader, type ResultArchiveView } from "../results/retrieval.ts";
 import { looksLikeProviderError } from "./errors.ts";
+import { piHostModuleHint } from "./host-module.ts";
 import { nextChildHandle } from "./handles.ts";
 import { combineSignals } from "./signals.ts";
 import { toolModifierFailure, unknownAgentFailure, unknownContractFailure } from "./spec-preflight.ts";
+import { mergeSessionToolAllowlist } from "./session-tools.ts";
 import { applyEvent, createStreamState, emptyUsage, type ProgressSnapshot, snapshot } from "./stream.ts";
 
 /** The minimal slice of Pi's AgentSession the engine drives — also the test seam. */
 export interface InProcSession {
+	/** Host readback after Pi applies its capability clamp; injected test sessions may omit it. */
+	readonly thinkingLevel?: unknown;
 	subscribe(listener: (event: unknown) => void): () => void;
 	prompt(input: string): Promise<void>;
 	agent: { abort(): void; waitForIdle(): Promise<void>; steer(message: unknown): void };
@@ -48,12 +56,11 @@ export interface InProcSession {
 
 export interface CreateSessionOptions {
 	model: unknown;
-	modelRegistry: ModelRegistry;
 	/** Cooperative cancellation for resource/session initialization. Pi's loader does not
 	 * currently accept a signal itself, but injected factories can stop promptly and the
 	 * default factory checks it before/after each uncancellable Pi operation. */
 	signal?: AbortSignal;
-	/** The host's canonical runtime (Pi >=0.81); shared so auth/provider registrations survive. */
+	/** The host's canonical runtime; shared so auth/provider registrations survive. */
 	modelRuntime?: unknown;
 	cwd: string;
 	/** Pi's global agent dir (~/.pi/agent) for the sub-agent's resource loader. */
@@ -70,12 +77,9 @@ export interface CreateSessionOptions {
 export type CreateInProcSession = (opts: CreateSessionOptions) => Promise<InProcSession>;
 
 /**
- * Pi 0.81 moved the canonical auth/provider state from the extension-facing
- * ModelRegistry to a ModelRuntime passed directly to createAgentSession. The
- * compatibility facade still owns that runtime, but intentionally keeps it
- * private in its public TypeScript API. Read the runtime only when the expected
- * methods are present; old Pi versions and test facades then retain the legacy
- * modelRegistry path.
+ * The current Pi ModelRegistry facade owns the canonical ModelRuntime privately.
+ * Recover that runtime only when its expected methods are present, so native provider
+ * registrations and in-memory credentials remain shared with delegated sessions.
  */
 function sharedModelRuntime(registry: ModelRegistry): unknown {
 	const candidate = (registry as unknown as { runtime?: unknown }).runtime;
@@ -156,6 +160,11 @@ export interface InProcessDeps {
 	 *  there, and this deadline aborts such a leg outright (failureKind "timeout"); the idle
 	 *  watchdog would not, because any event at all re-arms it. */
 	startupTimeoutMs?: number;
+	/** The owning session's terminal archive (a GETTER — the owner can change across sessions).
+	 *  Required by any leg carrying `resultRefs` (flow reference handoff): the scoped
+	 *  `read_result` tool pages THIS archive, after a zero-usage preflight verified every
+	 *  granted ref is durably stored. Absent ⇒ such legs fail closed before the session factory. */
+	resultArchive?: () => ResultArchiveView | undefined;
 }
 
 // The sub-agent must never re-enter the supervisor's orchestration surface. This is the SECOND
@@ -171,15 +180,6 @@ export function withOrchestrationToolsExcluded(extra: readonly string[] | undefi
 	return [...new Set([...ORCHESTRATION_TOOLS, ...(extra ?? [])])];
 }
 
-/** Preserve the semantic difference between an absent allowlist (Pi defaults) and an explicit
- * empty one (no tools). Custom communication tools join only a non-empty allowlist; an empty
- * grant must not quietly grow capabilities during session construction. */
-export function mergeSessionToolAllowlist(tools: readonly string[] | undefined, customNames: readonly string[]): string[] | undefined {
-	if (tools === undefined) return undefined;
-	if (tools.length === 0) return [];
-	return [...new Set([...tools, ...customNames])];
-}
-
 /** Default factory: a real in-process Pi session. The resource loader appends the
  *  agent's persona to the base system prompt (the in-process `--append-system-prompt`).
  *  Extensions DO load (so auth providers like pi-claude work) — the fork-bomb guard is
@@ -198,14 +198,8 @@ const createPiSession: CreateInProcSession = async (opts) => {
 	// otherwise the allowlist would filter them out of the child's active set.
 	const customNames = (opts.customTools ?? []).map((t) => t.name);
 	const tools = mergeSessionToolAllowlist(opts.tools, customNames);
-	// Forward-compat with the model-runtime migration (pi > 0.80.7). pi <= 0.80.7 reads
-	// `CreateAgentSessionOptions.modelRegistry` to share the host's auth/model registry with the
-	// sub-session; newer pi takes the canonical `modelRuntime` instead. The extension-facing
-	// ModelRegistry keeps that runtime private in its type surface, so `sharedModelRuntime()` above
-	// recovers it only when the runtime shape is present. Passing it is important even when auth is
-	// on disk: native providers and runtime credentials can exist only in the supervisor's memory.
-	// `agentDir` remains a valid fallback for older/standalone SDKs, and the legacy key stays outside
-	// the object literal so current SDK types do not reject it.
+	// Current Pi consumes the canonical modelRuntime. Sharing it also preserves native providers
+	// and credentials that exist only in the supervisor's memory.
 	const sessionOptions: NonNullable<Parameters<typeof createAgentSession>[0]> = {
 		model: opts.model as NonNullable<NonNullable<Parameters<typeof createAgentSession>[0]>["model"]>,
 		sessionManager: SessionManager.inMemory(opts.cwd),
@@ -218,14 +212,9 @@ const createPiSession: CreateInProcSession = async (opts) => {
 		excludeTools: withOrchestrationToolsExcluded(opts.excludeTools),
 		...(tools !== undefined ? { tools } : {}),
 		...(opts.customTools && opts.customTools.length > 0 ? { customTools: opts.customTools } : {}),
-		// `opts.thinkingLevel` is our local ThinkingLevel superset — cast to pi's field type at the
-		// boundary (same rationale as PersonaHost.setThinkingLevel: a `max`-style level only reaches
-		// here on a pi that supports it, and pi clamps an unknown level regardless).
-		...(opts.thinkingLevel
-			? { thinkingLevel: opts.thinkingLevel as NonNullable<NonNullable<Parameters<typeof createAgentSession>[0]>["thinkingLevel"]> }
-			: {}),
+		// Pi owns capability clamping (which can move effort up as well as down).
+		...(opts.thinkingLevel !== undefined ? { thinkingLevel: opts.thinkingLevel } : {}),
 	};
-	(sessionOptions as { modelRegistry?: unknown }).modelRegistry = opts.modelRegistry;
 	const { session } = await createAgentSession(sessionOptions);
 	if (opts.signal?.aborted) {
 		try {
@@ -236,6 +225,10 @@ const createPiSession: CreateInProcSession = async (opts) => {
 		throw new DOMException("Session initialization aborted", "AbortError");
 	}
 	return {
+		get thinkingLevel() {
+			const level: unknown = session.thinkingLevel;
+			return isThinkingLevel(level) ? level : undefined;
+		},
 		subscribe: (l) => session.subscribe(l as Parameters<typeof session.subscribe>[0]),
 		prompt: async (input) => {
 			await session.prompt(input);
@@ -315,6 +308,13 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 		async run(spec: AgentRunSpec, onProgress?, callSignal?, onSteerable?): Promise<AgentResult> {
 			const cfg = deps.resolveAgent(spec.agent);
 			if (!cfg) return unknownAgentFailure(spec.agent, deps.listAgents?.() ?? []);
+			let thinkingRequested: ThinkingLevel | undefined;
+			try {
+				thinkingRequested = resolveLegThinking(spec, cfg, deps.childThinking);
+			} catch (error) {
+				return { agent: spec.agent, output: "", usage: emptyUsage(), ok: false, failureKind: "contract", error: `[${spec.agent}] ${error instanceof Error ? error.message : String(error)}` };
+			}
+			const thinkingMetadata = thinkingRequested !== undefined ? { thinkingRequested } : {};
 			const tools = spec.tools ?? cfg.tools;
 			const invalidTools = toolModifierFailure(spec.agent, tools);
 			if (invalidTools) return invalidTools;
@@ -332,7 +332,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 				// Make the failure self-correcting: name a few real registry refs (nearest
 				// matches first) so the supervisor's retry can pick a valid model at once.
 				const all = deps.modelRegistry.getAll().map((m) => `${m.provider}/${m.id}`);
-				const frag = (ref ?? "").split("/").pop()?.split(":")[0]?.toLowerCase() ?? "";
+				const frag = (ref ?? "").split("/").pop()?.toLowerCase() ?? "";
 				const near = frag ? all.filter((r) => r.toLowerCase().includes(frag)) : [];
 				const hint = (near.length > 0 ? near : all).slice(0, 5);
 				return {
@@ -341,16 +341,40 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 					usage: emptyUsage(),
 					ok: false,
 					error: `[${spec.agent} · ${ref ?? "(no model)"}] model not found in registry (from ${src})${hint.length > 0 ? ` — try e.g.: ${hint.join(", ")}` : ""}`,
-						failureKind: "unknown-model",
+					failureKind: "unknown-model",
+					...thinkingMetadata,
 				};
 			}
 			// The canonical provider/id this run resolved to — surfaced on every result (for the
 			// UI/cost) and, on a provider failure, used as the seed of the fallback chain.
 			const rm = model as { provider?: string; id?: string };
 			const resolvedRef = rm.provider && rm.id ? `${rm.provider}/${rm.id}` : ref;
-			const thinkingLevel = isThinkingLevel(deps.childThinking) ? deps.childThinking : undefined;
 			const excludeTools = cfg.excludeTools;
 
+			// ── reference handoff preflight (contract 3/4) — BEFORE the session factory, after every
+			// cheap zero-usage rejection above it. Admission uses the SAME shared rule as the child
+			// engine; storage is verified durable (session-entry); a failure is a zero-usage
+			// contract failure and the factory is never called. The revoke rides `releaseHandle()`
+			// (every exit path from here on drains it), so the scoped reader dies with the leg.
+			const legCleanups: Array<() => void> = [];
+			let resultReadTool: ToolDefinition | undefined;
+			let admittedTools = tools;
+			if (spec.resultRefs !== undefined && spec.resultRefs.length > 0) {
+				const grant = admitResultReadTool({
+					specTools: spec.tools, cfgTools: cfg.tools, excludeTools: cfg.excludeTools,
+					canUseBus: deps.canUseBus ?? true,
+				});
+				if (!grant.ok) return referenceHandoffFailure(spec.agent, grant.error);
+				const archive = deps.resultArchive?.();
+				if (archive === undefined) return referenceHandoffFailure(spec.agent, "terminal result archive unavailable for reference handoff");
+				const scoped = makeScopedResultReader(archive, spec.resultRefs);
+				const { missing } = scoped.preflight();
+				if (missing.length > 0) return referenceHandoffFailure(spec.agent, `archived results unavailable: ${missing.join(", ")}`);
+				resultReadTool = makeReadResultTool(scoped);
+				admittedTools = grant.tools;
+				legCleanups.push(() => scoped.revoke());
+			}
+
 			// Diagnostic tag: which agent + which model ref + whether it was dynamically
 			// specialised (skills / model / tools override on the spec). Users need this
 			// to tell "the delegate typo'd the model" from "the provider rejected it".
@@ -367,20 +391,19 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 			// Already cancelled (e.g. a queued async run stopped before its slot came up):
 			// don't build a session or burn a model call — settle as aborted right away.
 			if (signal?.aborted) {
-				return { agent: spec.agent, output: "", usage: emptyUsage(), ok: false, error: `${tag} agent aborted`, ...(resolvedRef ? { modelUsed: resolvedRef } : {}), failureKind: "abort" };
+				return { agent: spec.agent, output: "", usage: emptyUsage(), ok: false, error: `${tag} agent aborted`, ...(resolvedRef ? { modelUsed: resolvedRef } : {}), ...thinkingMetadata, failureKind: "abort" };
 			}
 
 			const modelRuntime = sharedModelRuntime(deps.modelRegistry);
 			const sessionOpts: CreateSessionOptions = {
 				model,
-				modelRegistry: deps.modelRegistry,
 				...(modelRuntime !== undefined ? { modelRuntime } : {}),
 				cwd: deps.cwd,
 				agentDir: deps.agentDir ?? deps.cwd,
 			};
-			if (tools !== undefined) sessionOpts.tools = tools;
+			if (admittedTools !== undefined) sessionOpts.tools = admittedTools;
 			if (excludeTools && excludeTools.length > 0) sessionOpts.excludeTools = excludeTools;
-			if (thinkingLevel) sessionOpts.thinkingLevel = thinkingLevel;
+			if (thinkingRequested !== undefined) sessionOpts.thinkingLevel = thinkingRequested;
 			// The shared behavioral layer (docs/SPINE.md) + the agent's own persona + any
 			// on-the-fly `role` specialisation from the spec. All three reach the session as the
 			// loader's `appendSystemPrompt`, so a leg keeps Pi's full base prompt either way — the
@@ -397,20 +420,21 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 			if (spec.peers === true && !wantsPeers && process.env.PI_PERSONA_DEBUG) {
 				process.stderr.write(`[pi-persona] peers requested for ${spec.agent} but bus/capability unavailable — running without contact_peer\n`);
 			}
-			if (deps.bus && (deps.coaching || wantsPeers)) {
+			const customTools: ToolDefinition[] = [];
+			const wantsCoaching = deps.coaching === true && (deps.canUseBus ?? true);
+			if (deps.bus && (wantsCoaching || wantsPeers)) {
 				childHandle = nextChildHandle(spec.agent);
 				deps.bus.register(supervisorHandle);
 				deps.bus.register(childHandle);
-				const customTools: ToolDefinition[] = [];
-				if (deps.coaching) {
+				if (wantsCoaching) {
 					customTools.push(
 						makeContactSupervisorTool(deps.bus, childHandle, supervisorHandle, { allowBlocking: deps.allowBlocking ?? false }),
 					);
 				}
 				if (wantsPeers) {
 					const label = spec.name?.trim()
-						? sanitizeDisplayLabel(spec.name, childHandle)
-						: spec.role ? `${childHandle} (${roleHint(spec.role)})` : childHandle;
+					? sanitizeDisplayLabel(spec.name, childHandle)
+					: spec.role ? `${childHandle} (${roleHint(spec.role)})` : childHandle;
 					peerLabels.set(childHandle, label);
 					const self = childHandle;
 					customTools.push(
@@ -419,8 +443,12 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 						}),
 					);
 				}
-				sessionOpts.customTools = customTools;
 			}
+			// A granted reference-handoff reader joins the SAME custom-tools surface (contract 3):
+			// literal `read_result` already admitted into a nonempty allowlist above; an absent
+			// allowlist stays absent and the injected tool rides Pi's session defaults.
+			if (resultReadTool !== undefined) customTools.push(resultReadTool);
+			if (customTools.length > 0) sessionOpts.customTools = customTools;
 
 			// The handle is live on the SESSION-LONG bus from here on, while the only unregister sits
 			// in the run's own finally below. Anything that throws before we reach it must release
@@ -428,6 +456,11 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 			// for the rest of the supervisor's session.
 			let handleReleased = false;
 			const releaseHandle = (): void => {
+				// Leg-scoped cleanups FIRST — the reference reader revoke must run even on a leg that
+				// never owned a bus handle (non-coaching, peer-less).
+				for (const cleanup of legCleanups.splice(0)) {
+					try { cleanup(); } catch { /* a throwing cleanup must never strand its siblings */ }
+				}
 				if (!childHandle || handleReleased) return;
 				handleReleased = true;
 				peerLabels.delete(childHandle);
@@ -577,6 +610,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 					error: `${tag} agent aborted`,
 					...(resolvedRef ? { modelUsed: resolvedRef } : {}),
 					failureKind: "abort",
+					...thinkingMetadata,
 				};
 			}
 
@@ -648,6 +682,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 					error: `${initError}${cleanupHint}`,
 					...(resolvedRef ? { modelUsed: resolvedRef } : {}),
 					failureKind: hardTimedOut || timedOut || startupTimedOut ? "timeout" : "abort",
+					...thinkingMetadata,
 				};
 			}
 			session = initializationOutcome.session;
@@ -666,7 +701,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 			// One progress tick, routed exactly as the subscription routes them: the per-call sink
 			// takes the AgentProgress shape (no `turns`), else the construction-time sink.
 			const emitProgress = (snap: ProgressSnapshot): void => {
-				if (onProgress) onProgress({ output: snap.output, tokens: snap.tokens, ...(snap.activity ? { activity: snap.activity } : {}), ...(snap.toolOutputAt !== undefined ? { toolOutputAt: snap.toolOutputAt } : {}), ...(snap.toolEvent ? { toolEvent: snap.toolEvent } : {}) });
+				if (onProgress) onProgress({ output: snap.output, tokens: snap.tokens, ...(snap.usage ? { usage: snap.usage } : {}), ...(snap.activity ? { activity: snap.activity } : {}), ...(snap.toolEvent ? { toolEvent: snap.toolEvent } : {}) });
 				else if (deps.onProgress) deps.onProgress(snap);
 			};
 			let contractDef: ContractDef | undefined = requestedDef;
@@ -674,7 +709,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 			try {
 				unsub = session.subscribe((ev) => {
 					armIdle(); // any event = activity → reset the idle clock
-					const toolEvent = applyEvent(state, ev, Date.now());
+					const toolEvent = applyEvent(state, ev);
 					// Track the open calls so an abandoned one can be closed once the run settles.
 					if (toolEvent) {
 						if (toolEvent.phase === "start") openToolCalls.set(toolEvent.callId, toolEvent.name);
@@ -735,7 +770,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 							// launch path (extension.ts) only has the latter.
 							const snap = snapshot(state);
 							const activity = `✉ from ${env.from}`;
-							if (onProgress) onProgress({ output: snap.output, tokens: snap.tokens, ...(snap.toolOutputAt !== undefined ? { toolOutputAt: snap.toolOutputAt } : {}), activity });
+							if (onProgress) onProgress({ output: snap.output, tokens: snap.tokens, ...(snap.usage ? { usage: snap.usage } : {}), activity });
 							else if (deps.onProgress) deps.onProgress({ ...snap, activity });
 						}
 					};
@@ -773,6 +808,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 			// folded into the AgentResult below. Otherwise the stream state stays empty
 			// and the user sees an opaque "agent failed (unknown)".
 			let thrownError: string | undefined;
+			let thinkingEffective: ThinkingLevel | undefined;
 			try {
 				armIdle(); // start the idle clock (reset on every session event)
 				armHard(); // start the lifetime ceiling (never reset)
@@ -795,6 +831,8 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 				releaseHandle();
 				unsub?.();
 				steerable = false;
+				const observed = session.thinkingLevel;
+				if (isThinkingLevel(observed)) thinkingEffective = observed;
 				session.dispose();
 			}
 
@@ -823,9 +861,13 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 				}
 			}
 
-			const result: AgentResult = { agent: spec.agent, output: state.output, usage: state.usage, ok, ...(resolvedRef ? { modelUsed: resolvedRef } : {}) };
+			const result: AgentResult = { agent: spec.agent, output: state.output, usage: state.usage, ok, ...(resolvedRef ? { modelUsed: resolvedRef } : {}), ...thinkingMetadata };
+			// The final message describes the effort of that request; session readback is the
+			// observed setting when a host emits no effort field. Neither proves provider cognition.
+			const observed = state.thinkingEffective ?? thinkingEffective;
+			if (observed !== undefined) result.thinkingEffective = observed;
 			// A timeout/abort is the *cause of death* — label it first (mirrors the child engine).
-			if (timedOut) result.error = `${tag} agent timed out — no events for ${watchdogMs}ms${state.errorMessage ? ` (last error: ${state.errorMessage})` : ""}`;
+			if (timedOut) result.error = `${tag} agent timed out — no events for ${watchdogMs}ms (raise this leg's timeoutMs if its tool is legitimately silent)${state.errorMessage ? ` (last error: ${state.errorMessage})` : ""}`;
 			// The deadline cannot tell the two causes apart, so the message names both: claiming
 			// "it never started" would misdirect the operator of a leg that did start and was
 			// simply waiting on a slow first response (mirrors the child engine's wording).
@@ -836,6 +878,8 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 			else if (state.errorMessage) result.error = `${tag} ${state.errorMessage}`;
 			else if (thrownError) result.error = `${tag} ${thrownError}`;
 			else if (!ok) result.error = `${tag} agent failed (${state.stopReason ?? "unknown"})`;
+			const hostModuleHint = !ok ? piHostModuleHint(state.errorMessage ?? thrownError ?? "") : undefined;
+			if (hostModuleHint && result.error) result.error += ` — ${hostModuleHint}`;
 			// Classify the failure so the fallback decorator can reroute ONLY provider errors,
 			// never an abort/timeout/hard-cap/agent miss. A stream `error` stop reason is pi's
 			// own report of an API failure → provider. A THROWN error is not automatically a
@@ -846,9 +890,11 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 						? "timeout"
 						: aborted
 							? "abort"
-							: state.stopReason === "error" || (thrownError !== undefined && looksLikeProviderError(thrownError))
-								? "provider"
-								: "agent";
+							: hostModuleHint
+								? "agent"
+								: state.stopReason === "error" || (thrownError !== undefined && looksLikeProviderError(thrownError))
+									? "provider"
+									: "agent";
 
 			if (contractDef) {
 				const v = parseAndValidate(state.output, contractDef);

package/src/engine/result-grant.ts

@@ -0,0 +1,62 @@
+/**
+ * The frozen `read_result` admission rule (flow reference handoff, contract 4) — ONE helper
+ * shared by BOTH engine backends, so the child-process and in-process paths can never drift.
+ *
+ * effective tools = spec.tools ?? cfg.tools. An explicit `[]` denies. A nonempty allowlist
+ * must already include `read` OR `read_result` (the grant builds on a leg that can read —
+ * it never widens a write-only specialist into a reader). Any deny (agent `excludeTools`,
+ * wildcards included) matching either name denies. The parent's `canUseBus` capability must
+ * be true for reference mode at all; explicit parent denies always win. Only after a grant:
+ * the literal `read_result` joins a nonempty allowlist; an absent allowlist stays absent
+ * (session defaults + the injected custom tool).
+ */
+
+import { isAllowed } from "../core/permissions.ts";
+import type { AgentResult } from "../orchestration/types.ts";
+import { emptyUsage } from "./stream.ts";
+
+/** The literal, never-renamed tool a reference-handoff leg reads archived results through. */
+export const RESULT_READ_TOOL = "read_result";
+
+export interface ResultToolAdmission {
+	specTools: readonly string[] | undefined;
+	cfgTools: readonly string[] | undefined;
+	/** The agent's own deny list (glob patterns allowed — the same matcher Pi's permission
+	 *  layer uses, so a `read*` deny here means what it means everywhere else). */
+	excludeTools: readonly string[] | undefined;
+	/** The persona-level bus capability (`EffectiveCapabilities.canUseBus`). */
+	canUseBus: boolean;
+}
+
+export type ResultToolGrant =
+	| { ok: false; error: string }
+	/** `tools` is the effective allowlist to run the leg with: undefined = an absent
+	 *  allowlist stays absent (session default + custom-tool injection). */
+	| { ok: true; tools: string[] | undefined };
+
+export function admitResultReadTool(input: ResultToolAdmission): ResultToolGrant {
+	if (!input.canUseBus) {
+		return { ok: false, error: "reference handoff requires the bus capability (this persona denies it)" };
+	}
+	const tools = input.specTools ?? input.cfgTools;
+	if (tools !== undefined && tools.length === 0) {
+		return { ok: false, error: "reference handoff requires the read tool; this leg's tool allowlist is empty" };
+	}
+	// Denies are evaluated by NAME against both spellings, wildcards included, before any
+	// allowlist reasoning — an explicit deny always wins over the grant below.
+	const deny = { deny: [...(input.excludeTools ?? [])] };
+	if (!isAllowed("read", deny) || !isAllowed(RESULT_READ_TOOL, deny)) {
+		return { ok: false, error: "reference handoff requires the read tool; read/read_result is denied for this leg" };
+	}
+	if (tools !== undefined && !tools.includes("read") && !tools.includes(RESULT_READ_TOOL)) {
+		return { ok: false, error: `reference handoff requires the read or ${RESULT_READ_TOOL} tool; the allowlist names neither` };
+	}
+	if (tools === undefined) return { ok: true, tools: undefined };
+	return { ok: true, tools: [...new Set([...tools, RESULT_READ_TOOL])] };
+}
+
+/** A reference-handoff preflight rejection: ZERO usage (nothing ran), terminal for the leg,
+ *  listing what is missing so the caller can report it honestly. */
+export function referenceHandoffFailure(agent: string, error: string): AgentResult {
+	return { agent, output: "", usage: emptyUsage(), ok: false, error: `[${agent}] ${error}`, failureKind: "contract" };
+}

package/src/engine/session-tools.ts

@@ -0,0 +1,6 @@
+/** Preserve absent/default and explicit empty grants when adding runtime-owned custom tools. */
+export function mergeSessionToolAllowlist(tools: readonly string[] | undefined, customNames: readonly string[]): string[] | undefined {
+	if (tools === undefined) return undefined;
+	if (tools.length === 0) return [];
+	return [...new Set([...tools, ...customNames])];
+}

package/src/engine/stream.ts

@@ -9,6 +9,8 @@
  * Mirrors the canonical recipe in Pi's reference subagent example.
  */
 
+import { isThinkingLevel, type ThinkingLevel } from "../core/types.ts";
+
 export interface ChildUsage {
 	input: number;
 	output: number;
@@ -53,6 +55,8 @@ export interface StreamState {
 	deltaTail: number;
 	usage: ChildUsage;
 	model?: string;
+	/** Final assistant-message Pi effort, not provider cognition. Unknown stays absent. */
+	thinkingEffective?: ThinkingLevel;
 	stopReason?: string;
 	errorMessage?: string;
 	sawAssistant: boolean;
@@ -61,8 +65,6 @@ export interface StreamState {
 	/** Calls whose start was surfaced but whose end has not arrived. This is not a retention
 	 *  cache: active ids are never evicted merely because completed calls churn. */
 	activeToolCalls?: Set<string>;
-	/** Timestamp of the latest textual tool_execution_update, used only as a liveness signal. */
-	toolOutputAt?: number;
 	/** Recently completed call ids whose start/end phase was surfaced. Both caches are bounded;
 	 *  they suppress duplicate wire events without growing for the lifetime of a long run. */
 	seenToolStarts?: Set<string>;
@@ -238,7 +240,7 @@ function appendTranscript(state: StreamState, chunk: string, sep: string): void
 
 /** Fold one parsed stream event into the accumulating state (in place), returning a
  * deduplicated structured lifecycle transition when the runtime supplied a stable call id. */
-export function applyEvent(state: StreamState, event: unknown, observedAt?: number): ToolEvent | undefined {
+export function applyEvent(state: StreamState, event: unknown): ToolEvent | undefined {
 	if (!isObject(event)) return undefined;
 
 	// Track the current tool so the UI can show "running: grep src/…" while a
@@ -273,20 +275,6 @@ export function applyEvent(state: StreamState, event: unknown, observedAt?: numb
 		return toolEvent;
 	}
 
-	if (event.type === "tool_execution_update") {
-		const callId = event.toolCallId;
-		const toolName = event.toolName;
-		const partialResult = event.partialResult;
-		const hasText = isObject(partialResult) && Array.isArray(partialResult.content)
-			&& partialResult.content.some((part) => isObject(part) && part.type === "text" && typeof part.text === "string" && part.text.length > 0);
-		if (typeof callId === "string" && callId.length > 0
-			&& typeof toolName === "string" && toolName.length > 0
-			&& state.activeToolCalls?.has(callId) === true && hasText && observedAt !== undefined) {
-			state.toolOutputAt = observedAt;
-		}
-		return undefined;
-	}
-
 	// Live partial: pi streams the growing message as `message_update` events. Surface
 	// its text (or reasoning) so a long-thinking agent shows progress, not just tokens.
 	// ONLY the assistant's own message counts: pi also emits message_start/message_end for
@@ -322,6 +310,8 @@ export function applyEvent(state: StreamState, event: unknown, observedAt?: numb
 	resetDeltaParts(state); // the next message's deltas start from an empty slate
 	state.sawAssistant = true;
 	state.usage.turns++;
+	if (isThinkingLevel(msg.thinkingLevel)) state.thinkingEffective = msg.thinkingLevel;
+	else delete state.thinkingEffective;
 
 	const text = firstText(msg.content);
 	if (text !== undefined) state.output = text;
@@ -355,10 +345,10 @@ export interface ProgressSnapshot {
 	output: string;
 	turns: number;
 	tokens: number;
+	/** Copied cumulative counters for display; optional for legacy/custom progress sources. */
+	usage?: ChildUsage;
 	/** The tool currently running (e.g. "grep src/…"), if any. */
 	activity?: string;
-	/** Timestamp of the latest textual tool output update, when available. */
-	toolOutputAt?: number;
 	/** One authoritative runtime tool lifecycle transition, when this snapshot is event-driven. */
 	toolEvent?: ToolEvent;
 }
@@ -370,9 +360,9 @@ export function snapshot(state: StreamState, toolEvent?: ToolEvent): ProgressSna
 		output: [state.transcript, state.partial].filter((s) => s).join("\n\n") || state.output,
 		turns: state.usage.turns,
 		tokens: state.usage.input + state.usage.output,
+		usage: { ...state.usage },
 	};
 	if (state.activity !== undefined) snap.activity = state.activity;
-	if (state.toolOutputAt !== undefined) snap.toolOutputAt = state.toolOutputAt;
 	if (toolEvent !== undefined) snap.toolEvent = toolEvent;
 	return snap;
 }