@aeondave/pi-persona 1.17.3 → 1.17.4

package/src/engine/inproc.ts

@@ -26,21 +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 };
@@ -49,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. */
@@ -71,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;
@@ -157,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
@@ -172,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
@@ -199,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),
@@ -219,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 {
@@ -237,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);
@@ -316,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;
@@ -333,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 {
@@ -342,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".
@@ -368,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
@@ -398,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(
@@ -420,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
@@ -429,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);
@@ -578,6 +610,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 					error: `${tag} agent aborted`,
 					...(resolvedRef ? { modelUsed: resolvedRef } : {}),
 					failureKind: "abort",
+					...thinkingMetadata,
 				};
 			}
 
@@ -649,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;
@@ -774,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)
@@ -796,6 +831,8 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 				releaseHandle();
 				unsub?.();
 				steerable = false;
+				const observed = session.thinkingLevel;
+				if (isThinkingLevel(observed)) thinkingEffective = observed;
 				session.dispose();
 			}
 
@@ -824,7 +861,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") };
+}

package/src/exocom/collaboration.ts

@@ -0,0 +1,148 @@
+/** Voluntary peer work. Pure domain rules; claims and persistence stay in the ledger transaction. */
+import { writeSetPathError } from "../core/ownership.ts";
+import { isSemanticFrame, type ExocomSemanticFrame, type ExocomCollaborationFrame, type ExocomOffer, type ExocomProgress, type ExocomPublish, type ExocomTaskCreate, type ExocomTaskFinish, type ExocomTaskTake } from "./envelope.ts";
+
+export interface CollaborationTask {
+	created: ExocomTaskCreate;
+	taken?: ExocomTaskTake;
+	progress?: ExocomProgress;
+	finished?: ExocomTaskFinish;
+	/** Loss of the owning registry lease is visible and never permits automatic pickup. */
+	stale?: true;
+	/** Receiver clock at the first lease-loss reconciliation, or release timestamp. */
+	staleAt?: number;
+}
+export interface CollaborationState { tasks: CollaborationTask[]; offers: ExocomOffer[]; evidence: ExocomPublish[]; }
+export const COLLABORATION_LIMITS = { tasks: 64, offers: 64, evidence: 64, maxBytes: 131_072 } as const;
+export function emptyCollaboration(): CollaborationState { return { tasks: [], offers: [], evidence: [] }; }
+export function collaborationStatus(task: CollaborationTask): "open" | "taken" | "done" | "abandoned" | "stale" {
+	return task.finished?.outcome ?? (task.stale ? "stale" : task.taken ? "taken" : "open");
+}
+export function offerStatus(offer: ExocomOffer, now: number): "open" | "expired" {
+	return Date.parse(offer.expires_at) <= now ? "expired" : "open";
+}
+/** Time expiry is authoritative even after the exact task generation becomes unavailable. */
+export function collaborationOfferStatus(offer: ExocomOffer, tasks: readonly CollaborationTask[], now: number): "open" | "expired" | "stale" {
+	if (offerStatus(offer, now) === "expired") return "expired";
+	const task = tasks.find((candidate) => candidate.created.work_key === offer.work_key && candidate.created.msg_id === offer.task_id);
+	return task && collaborationStatus(task) === "open" ? "open" : "stale";
+}
+function bounded(state: CollaborationState, reserveLifecycle = true): boolean {
+	// Local ledger lifecycle events are unsigned. Reserve their largest identity metadata and a
+	// minimal terminal note, as well as lease loss, before admitting optional prose. A full note
+	// can hit quota; taking work, finishing with a short note and release must remain available.
+	const reserved = { ...state, tasks: state.tasks.map((task) => {
+		if (task.finished) return task;
+		const future = { work_key: task.created.work_key, task_id: task.created.msg_id, from_session: "x".repeat(128),
+			from_name: "界".repeat(256), msg_id: "x".repeat(128), ts: "9999-12-31T23:59:59.999Z" };
+		return { ...task, stale: true, staleAt: -Number.MAX_VALUE,
+			taken: task.taken ?? { ...future, kind: "task_take" }, finished: { ...future, kind: "task_finish", outcome: "abandoned", note: "x" } };
+	}) };
+	return state.tasks.length <= COLLABORATION_LIMITS.tasks && state.offers.length <= COLLABORATION_LIMITS.offers
+		&& state.evidence.length <= COLLABORATION_LIMITS.evidence && Buffer.byteLength(JSON.stringify(reserveLifecycle ? reserved : state), "utf8") <= COLLABORATION_LIMITS.maxBytes;
+}
+/** Retained facts outlive the rolling transport-id window; they must never acquire duplicate identities. */
+export function retainedCollaborationEvent(state: CollaborationState, msgId: string): ExocomSemanticFrame | undefined {
+	for (const task of state.tasks) {
+		for (const event of [task.created, task.taken, task.progress, task.finished]) if (event?.msg_id === msgId) return event;
+	}
+	return state.offers.find((event) => event.msg_id === msgId) ?? state.evidence.find((event) => event.msg_id === msgId);
+}
+type Transition = { ok: true; state: CollaborationState } | { ok: false; error: string };
+function transition(state: CollaborationState, event: ExocomCollaborationFrame | ExocomProgress, reserveLifecycle: boolean): Transition {
+	if (event.kind === "progress" && event.task_id === undefined) return { ok: true, state };
+	const task = state.tasks.find((value) => value.created.work_key === event.work_key);
+	let next = state;
+	if (event.kind === "task_create") {
+		if (task) return { ok: false, error: "task work_key already exists" };
+		for (const path of event.write_set) {
+			const error = writeSetPathError(path);
+			if (error) return { ok: false, error: `task write_set path is ${error}` };
+		}
+		next = { ...state, tasks: [...state.tasks, { created: event }] };
+	} else {
+		if (!task) return { ok: false, error: "unknown collaboration task" };
+		if (event.task_id !== task.created.msg_id) return { ok: false, error: "task_id does not match this work key's retained generation" };
+		if (event.kind === "publish") next = { ...state, evidence: [...state.evidence, event] };
+		else if (event.kind === "offer") {
+			if (state.offers.some((offer) => offer.offer_id === event.offer_id)) return { ok: false, error: "offer_id already exists" };
+			if (event.to_session === event.from_session) return { ok: false, error: "offer cannot target self" };
+			if (collaborationStatus(task) !== "open") return { ok: false, error: "offers require an open task" };
+			next = { ...state, offers: [...state.offers, event] };
+		} else {
+			const status = collaborationStatus(task);
+			if (event.kind === "task_take") {
+				if (status !== "open") return { ok: false, error: `task is ${status}; pickup refused` };
+				next = { ...state, tasks: state.tasks.map((value) => value === task ? { ...task, taken: event } : value) };
+			} else {
+				if (status !== "taken" || task.taken?.from_session !== event.from_session) return { ok: false, error: "only the active task taker may report progress or finish" };
+				if (event.kind === "progress" && Date.parse(event.ts) < Date.parse(task.progress?.ts ?? task.taken.ts)) return { ok: false, error: "task progress predates its latest observation" };
+				const updated = event.kind === "progress" ? { ...task, progress: event } : { ...task, finished: event };
+				next = { ...state, tasks: state.tasks.map((value) => value === task ? updated : value) };
+			}
+		}
+	}
+	return bounded(next, reserveLifecycle) ? { ok: true, state: next } : { ok: false, error: "collaboration retention budget reached; shorten optional report text" };
+}
+export function applyCollaborationEvent(state: CollaborationState, event: ExocomCollaborationFrame | ExocomProgress): Transition {
+	return transition(state, event, true);
+}
+
+export function staleCollaboration(state: CollaborationState, isLive: (session: string) => boolean, now: number): CollaborationState {
+	return { ...state, tasks: state.tasks.map((task) => task.finished || task.stale || isLive(task.taken?.from_session ?? task.created.from_session)
+		? task : { ...task, stale: true, staleAt: now }) };
+}
+export function releaseCollaboration(state: CollaborationState, session: string, workKey: string, now: number): CollaborationState {
+	return { ...state, tasks: state.tasks.map((task) => task.created.work_key === workKey && !task.finished && !task.stale
+		&& (task.taken?.from_session ?? task.created.from_session) === session ? { ...task, stale: true, staleAt: now } : task) };
+}
+export function pruneCollaboration(state: CollaborationState, now: number, ttlMs: number, isLive: (session: string) => boolean): CollaborationState {
+	const reconciled = staleCollaboration(state, isLive, now);
+	const tasks = reconciled.tasks.filter((task) => {
+		const terminalAt = task.finished ? Date.parse(task.finished.ts) : task.staleAt;
+		return terminalAt === undefined || now - terminalAt <= ttlMs;
+	});
+	const retained = new Set(tasks.map((task) => task.created.work_key));
+	return {
+		tasks,
+		offers: state.offers.filter((offer) => retained.has(offer.work_key) && now - Date.parse(offer.expires_at) <= ttlMs),
+		evidence: state.evidence.filter((item) => retained.has(item.work_key) && now - Date.parse(item.ts) <= ttlMs),
+	};
+}
+
+/** Reconstruct snapshots through the same rules. No malformed ownership record is silently skipped. */
+export function parseCollaboration(raw: unknown): CollaborationState | undefined {
+	if (!raw || typeof raw !== "object") return undefined;
+	const value = raw as CollaborationState;
+	if (!Array.isArray(value.tasks) || !Array.isArray(value.offers) || !Array.isArray(value.evidence) || !bounded(value)) return undefined;
+	let state = emptyCollaboration();
+	const seen = new Set<string>();
+	function replay(event: unknown, kind: string): boolean {
+		if (!isSemanticFrame(event) || event.kind !== kind || seen.has(event.msg_id)) return false;
+		if (!(event.kind === "task_create" || event.kind === "task_take" || event.kind === "task_finish" || event.kind === "progress" || event.kind === "offer" || event.kind === "publish")) return false;
+		// Definitions must precede historical offers. Replay checks physical bounds; reserve
+		// future lifecycle only on the final state, once completed tasks are terminal again.
+		const applied = transition(state, event, false);
+		if (!applied.ok) return false;
+		seen.add(event.msg_id);
+		state = applied.state;
+		return true;
+	}
+	// All definitions precede offers/evidence; a finished task's historical offer is valid.
+	for (const task of value.tasks) {
+		if (!task || typeof task !== "object" || !replay(task.created, "task_create")) return undefined;
+	}
+	for (const offer of value.offers) if (!replay(offer, "offer")) return undefined;
+	for (const task of value.tasks) {
+		for (const [event, kind] of [[task.taken, "task_take"], [task.progress, "progress"], [task.finished, "task_finish"]] as const) {
+			if (event !== undefined && (event.work_key !== task.created.work_key || !replay(event, kind))) return undefined;
+		}
+		if (task.stale !== undefined && task.stale !== true) return undefined;
+		if (task.stale) {
+			if (task.finished || typeof task.staleAt !== "number" || !Number.isFinite(task.staleAt)) return undefined;
+			state = releaseCollaboration(state, task.taken?.from_session ?? task.created.from_session, task.created.work_key, task.staleAt);
+		} else if (task.staleAt !== undefined) return undefined;
+	}
+	for (const evidence of value.evidence) if (!replay(evidence, "publish")) return undefined;
+	return bounded(state) ? state : undefined;
+}