@aeondave/pi-persona 1.17.3 → 1.17.5

package/src/engine/inproc.ts

@@ -26,21 +26,29 @@ 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 { installFrozenMemoryOwner } from "../extension/memory-owner.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,13 +56,14 @@ export interface InProcSession {
 }
 
 export interface CreateSessionOptions {
+	/** Immutable owning supervisor persona; null explicitly means no persona. */
+	memoryPersona?: string | null;
 	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. */
@@ -71,12 +80,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;
@@ -88,6 +94,8 @@ function sharedModelRuntime(registry: ModelRegistry): unknown {
 }
 
 export interface InProcessDeps {
+	/** Frozen at buildEngine construction, independent of later persona changes or saved settings. */
+	memoryPersona?: string | null;
 	resolveAgent: (name: string) => AgentConfig | undefined;
 	contracts?: (name: string) => ContractDef | undefined;
 	/** The host session's registry — shared so the sub-agent reuses the loader's auth. */
@@ -157,6 +165,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
@@ -172,15 +185,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
@@ -188,9 +192,12 @@ export function mergeSessionToolAllowlist(tools: readonly string[] | undefined,
  *  the orchestration tools excluded as a second line of defense. */
 const createPiSession: CreateInProcSession = async (opts) => {
 	if (opts.signal?.aborted) throw new DOMException("Session initialization aborted", "AbortError");
+	const manager = SessionManager.inMemory(opts.cwd);
+	const memoryPersona = opts.memoryPersona;
 	const loader = new DefaultResourceLoader({
 		cwd: opts.cwd,
 		agentDir: opts.agentDir,
+		...(memoryPersona !== undefined ? { extensionFactories: [(pi) => installFrozenMemoryOwner(pi, manager, memoryPersona)] } : {}),
 		...(opts.systemPrompt ? { appendSystemPrompt: [opts.systemPrompt] } : {}),
 	});
 	await loader.reload();
@@ -199,17 +206,11 @@ 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),
+		sessionManager: manager,
 		resourceLoader: loader,
 		cwd: opts.cwd,
 		agentDir: opts.agentDir,
@@ -219,14 +220,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 {
@@ -237,6 +233,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);
@@ -293,6 +293,7 @@ function popDisableGuard(): void {
 }
 
 export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
+	const memoryPersona = deps.memoryPersona;
 	const createSession = deps.createSession ?? createPiSession;
 	const supervisorHandle = deps.supervisorHandle ?? "supervisor";
 	// Per-run contract pinning (I3), mirroring the child adapter.
@@ -316,6 +317,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;
@@ -333,7 +341,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 {
@@ -342,16 +350,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".
@@ -368,20 +400,20 @@ 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 (memoryPersona !== undefined) sessionOpts.memoryPersona = memoryPersona;
 			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
@@ -398,20 +430,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(
@@ -420,8 +453,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
@@ -429,6 +466,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);
@@ -578,6 +620,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 					error: `${tag} agent aborted`,
 					...(resolvedRef ? { modelUsed: resolvedRef } : {}),
 					failureKind: "abort",
+					...thinkingMetadata,
 				};
 			}
 
@@ -649,6 +692,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 					error: `${initError}${cleanupHint}`,
 					...(resolvedRef ? { modelUsed: resolvedRef } : {}),
 					failureKind: hardTimedOut || timedOut || startupTimedOut ? "timeout" : "abort",
+					...thinkingMetadata,
 				};
 			}
 			session = initializationOutcome.session;
@@ -774,6 +818,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)
@@ -796,6 +841,8 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 				releaseHandle();
 				unsub?.();
 				steerable = false;
+				const observed = session.thinkingLevel;
+				if (isThinkingLevel(observed)) thinkingEffective = observed;
 				session.dispose();
 			}
 
@@ -824,7 +871,11 @@ 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 (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

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;
@@ -306,6 +310,8 @@ export function applyEvent(state: StreamState, event: unknown): ToolEvent | unde
 	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;

package/src/engine/worktree.ts

@@ -76,11 +76,14 @@ export async function worktreePreflight(root: string, exec: GitExec = defaultGit
 	return { ok: true };
 }
 
-/** Capture the complete post-run worktree state as a portable unified diff. Tracked edits use
- * `git diff HEAD`; files newly created by a coding leg are added with `git diff --no-index`.
+/** Capture the complete post-run worktree state as a portable unified diff from its pinned
+ * starting commit. Files newly created by a coding leg are added with `git diff --no-index`.
  * Exit code 1 is the normal "files differ" result for --no-index. */
-export async function captureWorktreeArtifact(root: string, exec: GitExec = defaultGitExec): Promise<WorktreeArtifact> {
-	const tracked = await exec(["-C", root, "diff", "--no-ext-diff", "--binary", "HEAD", "--"]);
+export async function captureWorktreeArtifact(root: string, baseCommit: string, exec: GitExec = defaultGitExec): Promise<WorktreeArtifact> {
+	if (!baseCommit.trim()) {
+		return { ok: false, error: "could not export the isolated worktree diff: starting commit is missing" };
+	}
+	const tracked = await exec(["-C", root, "diff", "--no-ext-diff", "--binary", baseCommit, "--"]);
 	if (tracked.code !== 0) {
 		return { ok: false, error: `could not export the isolated worktree diff: ${tracked.stderr.trim() || `git exited ${tracked.code}`}` };
 	}
@@ -107,8 +110,9 @@ export async function captureWorktreeArtifact(root: string, exec: GitExec = defa
 	return { ok: true, diff: parts.join("\n") };
 }
 
-/** Create a detached worktree off `root`'s HEAD, run `body(worktreeDir)`, then force-remove it. */
-export async function withWorktree<T>(root: string, exec: GitExec, body: (dir: string) => Promise<T>): Promise<T> {
+/** Create a detached worktree off `root`'s HEAD, pin its starting commit, run
+ * `body(worktreeDir, baseCommit)`, then force-remove it. */
+export async function withWorktree<T>(root: string, exec: GitExec, body: (dir: string, baseCommit: string) => Promise<T>): Promise<T> {
 	const preflight = await worktreePreflight(root, exec);
 	if (!preflight.ok) throw new Error(preflight.error);
 	const dir = await mkdtemp(join(tmpdir(), "pi-persona-wt-"));
@@ -120,7 +124,13 @@ export async function withWorktree<T>(root: string, exec: GitExec, body: (dir: s
 		throw new Error(`could not create git worktree: ${add.stderr.trim() || `git exited ${add.code}`}`);
 	}
 	try {
-		return await body(dir);
+		const initial = await exec(["-C", dir, "rev-parse", "--verify", "HEAD^{commit}"]);
+		const baseCommit = initial.stdout.trim();
+		if (initial.code !== 0 || !baseCommit) {
+			const reason = initial.stderr.trim() || (initial.code !== 0 ? `git exited ${initial.code}` : "Git returned an empty commit id");
+			throw new Error(`could not resolve the initial worktree commit: ${reason}`);
+		}
+		return await body(dir, baseCommit);
 	} finally {
 		// Remove the worktree registration, then the dir (force: it may carry the agent's edits).
 		// Never throw: cleanup must not replace the body's result (or its error) — `defaultGitExec`

package/src/exocom/collaboration-delivery.ts

@@ -0,0 +1,29 @@
+/** Signed offer wakes project retained ledger data; the envelope is never its authority. */
+import { attributePeer } from "../core/fence.ts";
+import { collaborationOfferStatus } from "./collaboration.ts";
+import { frameSigningPayload, type ExocomOffer, type ExocomSemanticFrame } from "./envelope.ts";
+import type { LedgerState } from "./ledger.ts";
+
+export function collaborationWriteIntent(frame: ExocomSemanticFrame, state: LedgerState): boolean {
+	if (frame.kind === "claim" || frame.kind === "task_create") return frame.write_set.length > 0;
+	return frame.kind === "task_take" && (state.collaboration?.tasks.find((task) => task.created.work_key === frame.work_key)?.created.write_set.length ?? 0) > 0;
+}
+
+export function deliverCollaborationOffer(
+	frame: ExocomOffer, state: LedgerState, sessionId: string, label: string, now: number,
+): { accepted: true; notice?: string } | { accepted: false; reason: string } {
+	if (frame.to_session !== sessionId) return { accepted: false, reason: "offer addressed to another session" };
+	const stored = state.collaboration?.offers.find((offer) => offer.offer_id === frame.offer_id);
+	if (!stored || frameSigningPayload(stored) !== frameSigningPayload(frame)) {
+		return { accepted: false, reason: "offer is not durable with this sender and payload" };
+	}
+	const tasks = state.collaboration?.tasks ?? [];
+	if (collaborationOfferStatus(stored, tasks, now) !== "open") return { accepted: true };
+	const task = tasks.find((candidate) => candidate.created.work_key === stored.work_key && candidate.created.msg_id === stored.task_id);
+	if (!task) return { accepted: true };
+	return { accepted: true, notice: [
+		`[pi-persona] Optional peer invitation · task=${stored.work_key} · offer=${stored.offer_id} · expires ${stored.expires_at}`,
+		"This creates no response obligation or permission. Inspect the task and take it voluntarily only within your authorized scope; otherwise continue your work.",
+		attributePeer(frame.from_session === task.created.from_session ? label : task.created.from_session, task.created.description),
+	].join("\n") };
+}