@iowarp/clio-coder 0.3.3 → 0.3.6

package/src/engine/apis/openai-completions.ts

@@ -1,3 +1,4 @@
+import { TextDecoder } from "node:util";
 import {
 	type Api,
 	type AssistantMessage,
@@ -15,6 +16,7 @@ import {
 	type Usage,
 } from "@earendil-works/pi-ai";
 import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
+import type { ResponseModelIdObservation } from "../../core/response-model-id.js";
 import {
 	type AppliedThinking,
 	type ResolvedModelRuntimeCapabilities,
@@ -35,6 +37,13 @@ import { residencyManagedFor } from "./residency.js";
 import { mergeSamplingOverride } from "./sampling-overrides.js";
 import type { EngineApiProvider } from "./types.js";
 
+declare module "@earendil-works/pi-ai" {
+	interface AssistantMessage {
+		/** Direct observation of model-id presence in an OpenAI-compatible response. */
+		responseModelIdObservation?: ResponseModelIdObservation;
+	}
+}
+
 const piOpenAICompletions = openAICompletionsApi();
 
 /**
@@ -83,6 +92,124 @@ function isPlainRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+interface ResponseModelIdCapture {
+	reportedModelId: string | null;
+	observed: boolean;
+	done: boolean;
+	buffer: string;
+	decoder: TextDecoder | null;
+}
+
+function observeResponseModelIdLine(line: string, capture: ResponseModelIdCapture): void {
+	if (capture.done) return;
+	const normalized = line.endsWith("\r") ? line.slice(0, -1) : line;
+	if (!normalized.startsWith("data:")) return;
+	const data = normalized.slice("data:".length).trimStart();
+	if (data.length === 0 || data === "[DONE]") return;
+	try {
+		const payload = JSON.parse(data) as unknown;
+		if (!isPlainRecord(payload)) return;
+		const model = payload.model;
+		if (typeof model === "string" && model.trim().length > 0) {
+			capture.reportedModelId = model.trim();
+			capture.done = true;
+		}
+	} catch {
+		// A partial or vendor-specific event is pi-ai's parsing concern. This
+		// observer records only complete OpenAI-compatible JSON data lines.
+	}
+}
+
+function observeResponseModelIdBytes(
+	chunk: Uint8Array | undefined,
+	capture: ResponseModelIdCapture,
+	flush = false,
+): void {
+	if (capture.done || !capture.decoder) return;
+	capture.buffer += chunk ? capture.decoder.decode(chunk, { stream: !flush }) : capture.decoder.decode();
+	let newline = capture.buffer.indexOf("\n");
+	while (newline >= 0) {
+		const line = capture.buffer.slice(0, newline);
+		capture.buffer = capture.buffer.slice(newline + 1);
+		observeResponseModelIdLine(line, capture);
+		if (capture.done) {
+			capture.buffer = "";
+			capture.decoder = null;
+			return;
+		}
+		newline = capture.buffer.indexOf("\n");
+	}
+	if (flush && capture.buffer.length > 0) {
+		observeResponseModelIdLine(capture.buffer, capture);
+		capture.buffer = "";
+	}
+	if (capture.done || flush) capture.decoder = null;
+}
+
+function captureResponseModelId(response: Response, capture: ResponseModelIdCapture): Response {
+	if (!response.body || !response.headers.get("content-type")?.toLowerCase().includes("text/event-stream")) {
+		return response;
+	}
+	const body = response.body.pipeThrough(
+		new TransformStream<Uint8Array, Uint8Array>({
+			transform(chunk, controller) {
+				capture.observed = true;
+				if (!capture.done) observeResponseModelIdBytes(chunk, capture);
+				controller.enqueue(chunk);
+			},
+			flush() {
+				capture.observed = true;
+				if (!capture.done) observeResponseModelIdBytes(undefined, capture, true);
+			},
+		}),
+	);
+	return new Response(body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers,
+	});
+}
+
+function withResponseModelIdCapture<TOptions extends StreamOptions>(
+	options: TOptions,
+	sourceFactory: (capturedOptions: TOptions) => AssistantMessageEventStream,
+): AssistantMessageEventStream {
+	const capture: ResponseModelIdCapture = {
+		reportedModelId: null,
+		observed: false,
+		done: false,
+		buffer: "",
+		decoder: new TextDecoder(),
+	};
+	const fetchImpl: NonNullable<StreamOptions["fetch"]> =
+		options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+	const capturedOptions = {
+		...options,
+		fetch: async (input, init) => captureResponseModelId(await fetchImpl(input, init), capture),
+	} as TOptions;
+	const source = sourceFactory(capturedOptions);
+	const annotated = createAssistantMessageEventStream();
+	(async () => {
+		try {
+			for await (const event of source) {
+				const observation: ResponseModelIdObservation = capture.observed
+					? capture.reportedModelId === null
+						? { state: "not-reported" }
+						: { state: "reported", reportedModelId: capture.reportedModelId }
+					: { state: "not-observed" };
+				if (event.type === "done") event.message.responseModelIdObservation = observation;
+				else if (event.type === "error") event.error.responseModelIdObservation = observation;
+				annotated.push(event as AssistantMessageEvent);
+			}
+			annotated.end();
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			throw new Error(message);
+		}
+	})();
+	return annotated;
+}
+
 function samplingParamsFromProfile(profile: SamplingProfile): Record<string, unknown> {
 	return {
 		...(profile.topP !== undefined ? { top_p: profile.topP } : {}),
@@ -735,17 +862,16 @@ export const openAICompletionsApiProvider: EngineApiProvider<"openai-completions
 				stripSentinelsFromStream(
 					stripNeverReasoningFromStream(
 						filterGemmaChannelStream(
-							withLocalResidency(
-								model,
-								{
-									...(options?.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
-									...(options?.signal !== undefined ? { signal: options.signal } : {}),
-								},
-								(requestModel) =>
-									piOpenAICompletions.stream(
-										requestModel,
-										effectiveContext,
-										withRemainingContextBudget(model, effectiveContext, withSamplers),
+							withResponseModelIdCapture(
+								withRemainingContextBudget(model, effectiveContext, withSamplers),
+								(capturedOptions) =>
+									withLocalResidency(
+										model,
+										{
+											...(options?.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
+											...(options?.signal !== undefined ? { signal: options.signal } : {}),
+										},
+										(requestModel) => piOpenAICompletions.stream(requestModel, effectiveContext, capturedOptions),
 									),
 							),
 							resolved.family === "gemma-4",
@@ -768,17 +894,16 @@ export const openAICompletionsApiProvider: EngineApiProvider<"openai-completions
 				stripSentinelsFromStream(
 					stripNeverReasoningFromStream(
 						filterGemmaChannelStream(
-							withLocalResidency(
-								model,
-								{
-									...(options?.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
-									...(options?.signal !== undefined ? { signal: options.signal } : {}),
-								},
-								(requestModel) =>
-									piOpenAICompletions.streamSimple(
-										requestModel,
-										effectiveContext,
-										withRemainingContextBudget(model, effectiveContext, withSamplers),
+							withResponseModelIdCapture(
+								withRemainingContextBudget(model, effectiveContext, withSamplers),
+								(capturedOptions) =>
+									withLocalResidency(
+										model,
+										{
+											...(options?.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
+											...(options?.signal !== undefined ? { signal: options.signal } : {}),
+										},
+										(requestModel) => piOpenAICompletions.streamSimple(requestModel, effectiveContext, capturedOptions),
 									),
 							),
 							resolved.family === "gemma-4",

package/src/engine/claude/sdk-runtime.ts

@@ -413,9 +413,15 @@ function permissionResultForDecision(
 	return result;
 }
 
-function decideToolUse(input: PermissionGateInput, toolName: string, toolInput: unknown): ClaudeToolPermissionDecision {
+function decideToolUse(
+	input: PermissionGateInput,
+	toolCallId: string | undefined,
+	toolName: string,
+	toolInput: unknown,
+): ClaudeToolPermissionDecision {
 	return emitClaudeToolPermissionDecision({
 		toolName,
+		...(toolCallId !== undefined ? { toolCallId } : {}),
 		input: coerceToolInput(toolInput),
 		safety: input.safety,
 		cwd: input.cwd,
@@ -447,7 +453,7 @@ function decideToolUseOnce(
 	toolInput: unknown,
 ): ClaudeToolPermissionDecision {
 	return decideClaudeSdkToolUseOnce(input.handledToolDecisions, toolUseID, () =>
-		decideToolUse(input, toolName, toolInput),
+		decideToolUse(input, toolUseID, toolName, toolInput),
 	);
 }
 

package/src/engine/claude/tool-safety.ts

@@ -8,6 +8,7 @@ import {
 	DEFAULT_AUTONOMY_LEVEL,
 	mapAutonomy,
 } from "../../domains/safety/autonomy.js";
+import { describeCallAction } from "../../domains/safety/call-target.js";
 import type { SafetyContract, SafetyDecision } from "../../domains/safety/contract.js";
 import type { RejectionMessage } from "../../domains/safety/rejection-feedback.js";
 import type { ToolFinishEvent, ToolStartEvent } from "../../tools/agent-tools.js";
@@ -68,6 +69,8 @@ export interface EvaluateClaudeToolPermissionInput {
 export interface EmitClaudeToolPermissionInput extends EvaluateClaudeToolPermissionInput {
 	emit(event: ClioWorkerEvent): void;
 	onPermission?: "deny" | "fail";
+	/** SDK tool-use id shared by the start and finish telemetry events. */
+	toolCallId?: string;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -324,9 +327,11 @@ function emitToolFinish(
 	outcome: ToolFinishEvent["outcome"],
 	reason: string,
 	reasonCode?: string,
+	toolCallId?: string,
 ): void {
 	const event: ToolFinishEvent = {
 		tool: mapped.clioToolName,
+		...(toolCallId !== undefined ? { toolCallId } : {}),
 		posture: "operating",
 		durationMs: Math.round(performance.now() - startedAtClock),
 		outcome,
@@ -350,10 +355,16 @@ export function emitClaudeToolPermissionDecision(input: EmitClaudeToolPermission
 	const startedAt = Date.now();
 	const startedAtClock = performance.now();
 	const decision = evaluateClaudeToolPermission(input);
+	const toolCallId = input.toolCallId?.trim() ? input.toolCallId : undefined;
+	// Mapped args are this side's own translation of the subprocess call, so the
+	// descriptor is composed from them here rather than downstream of the seam.
+	const action = describeCallAction(decision.mapped.clioToolName, decision.mapped.args);
 	const start: ToolStartEvent = {
 		tool: decision.mapped.clioToolName,
+		...(toolCallId !== undefined ? { toolCallId } : {}),
 		posture: "operating",
 		startedAt,
+		...(action !== null ? { action } : {}),
 	};
 	input.emit({ type: "clio_tool_start", payload: start });
 	if (decision.kind === "allow") {
@@ -365,6 +376,7 @@ export function emitClaudeToolPermissionDecision(input: EmitClaudeToolPermission
 			"ok",
 			decision.reason,
 			decision.reasonCode,
+			toolCallId,
 		);
 		return decision;
 	}
@@ -391,6 +403,7 @@ export function emitClaudeToolPermissionDecision(input: EmitClaudeToolPermission
 		"blocked",
 		decision.reason,
 		decision.reasonCode,
+		toolCallId,
 	);
 	return decision;
 }

package/src/engine/loop-guard.ts

@@ -458,12 +458,14 @@ export interface CreateLoopGuardRegistrationOptions {
 export interface LoopGuardRegistration extends MiddlewareHookRegistration {
 	/** Read-only attempt counter for tests and telemetry. */
 	callCount(): number;
+	/** One-way worker phase growth admitted before launch for a result-contract revision. */
+	extendWorkerToolCallPhase(phase: { toolCalls: number; readReserve: number }): boolean;
 }
 
 export function createLoopGuardRegistration(options: CreateLoopGuardRegistrationOptions): LoopGuardRegistration {
 	const budget = options.turnBlockBudget ?? INTERACTIVE_LOOP_BLOCK_BUDGET;
 	const cap = options.toolCallCap;
-	const softLimit =
+	let softLimit =
 		options.toolCallSoftLimit !== undefined &&
 		Number.isSafeInteger(options.toolCallSoftLimit) &&
 		options.toolCallSoftLimit > 0 &&
@@ -472,8 +474,8 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 			: undefined;
 	const turnBudget = options.turnToolCallBudget;
 	const synthesisLockout = options.turnSynthesisLockout === true;
-	const softReadReserve = options.toolCallSoftReadReserve ?? 0;
-	const softReadReserveThreshold =
+	let softReadReserve = options.toolCallSoftReadReserve ?? 0;
+	let softReadReserveThreshold =
 		softLimit !== undefined && softReadReserve > 0 && softLimit > softReadReserve ? softLimit - softReadReserve : null;
 	const deliveryTools = [...new Set(options.deliveryTools ?? [])];
 	const reserveAdmits = (tool: string | undefined): boolean => isReserveAdmittedTool(tool, deliveryTools);
@@ -850,6 +852,28 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 			"blocks repeated tool calls, enforces tool-call caps, and annotates substantial identical read results across distinct arguments",
 		hooks: ["before_tool", "after_tool"],
 		callCount: () => count,
+		extendWorkerToolCallPhase(phase): boolean {
+			if (
+				softLimit === undefined ||
+				!Number.isSafeInteger(phase.toolCalls) ||
+				!Number.isSafeInteger(phase.readReserve) ||
+				phase.toolCalls <= 0 ||
+				phase.readReserve < 0 ||
+				phase.readReserve >= phase.toolCalls ||
+				(cap !== undefined && phase.toolCalls > cap) ||
+				phase.toolCalls < softLimit ||
+				(phase.toolCalls === softLimit && phase.readReserve <= softReadReserve)
+			) {
+				return false;
+			}
+			softLimit = phase.toolCalls;
+			softReadReserve = phase.readReserve;
+			softReadReserveThreshold = softReadReserve > 0 && softLimit > softReadReserve ? softLimit - softReadReserve : null;
+			softReadReserveEntered = false;
+			softLockout = null;
+			reserveDenials = { denials: 0 };
+			return true;
+		},
 		evaluate(input): ReadonlyArray<MiddlewareEffect> {
 			if (input.hook === "after_tool") {
 				recordSuccessfulResult(input);

package/src/engine/session.ts

@@ -57,13 +57,19 @@ export interface ClioSessionMeta {
 	platform: string;
 	nodeVersion: string;
 	/**
-	 * Version 3 on every new session. Readers reject earlier versions and
-	 * sessions that omit this field.
+	 * Version 4 on every new session. Readers reject earlier versions, sessions
+	 * that omit this field, and versions from the future.
 	 */
 	sessionFormatVersion?: number;
 }
 
-export const CURRENT_SESSION_FORMAT_VERSION = 3;
+/**
+ * Version 4 adds the working-set ledger kinds (`contextEviction`,
+ * `contextRecall`). A version-3 reader would parse those entries as unknown
+ * kinds and replay a session as if nothing had been evicted, so the bump is
+ * what makes an older Clio refuse the file instead of misreading it.
+ */
+export const CURRENT_SESSION_FORMAT_VERSION = 4;
 
 export interface ClioSessionJsonlHeader {
 	type: "session";

package/src/engine/worker-events.ts

@@ -53,9 +53,10 @@ export interface ClioPermissionEscalatedEvent {
 		tool: string;
 		summary: string;
 		/**
-		 * Sanitized one-line preview of the call's object (command, path, or
-		 * compact args), so the operator's approval overlay can show what the
-		 * call will touch. The args themselves never cross the stdout seam.
+		 * Sanitized one-line preview of the call's allowlisted object fields, so
+		 * the operator's approval overlay can show what the call will touch.
+		 * Unlisted fields carry only type-and-size summaries, and the args
+		 * themselves never cross the stdout seam.
 		 */
 		target?: string;
 		axis?: string;

package/src/engine/worker-runtime.ts

@@ -443,6 +443,42 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 	// loop guard counts synthesis-lock noncompliance by model round, preventing
 	// one wide parallel batch from consuming the entire denial backstop.
 	let workerModelRound = 0;
+	const loopGuardRegistration = createLoopGuardRegistration({
+		safety,
+		toolCallCap: workerBudget.hardCap,
+		toolCallSoftLimit: workerBudget.toolCalls,
+		// A worker's blocks all land in one run-long bucket, so the bound on
+		// them is a statement about this run's length, not about a turn.
+		turnBlockBudget: workerLoopBlockBudget(workerBudget.revision?.toolCalls ?? workerBudget.toolCalls),
+		toolCallSoftReadReserve: readReserve,
+		...(deliveryTools.length > 0 ? { deliveryTools } : {}),
+		turnSynthesisLockout: workerBudget.synthesis,
+		// Once locked, the next model round is forced text-only at the
+		// request level. The lockout directive alone relies on model compliance.
+		onSynthesisLockout: () => {
+			if (workerBudget.synthesis) synthesisToolLock = true;
+		},
+		...(!workerBudget.synthesis
+			? {
+					onSoftLimitFinalCallAdmitted: (toolCallId: string | undefined) => {
+						if (workerBoundFailure === null) {
+							workerBoundFailure = `worker agent budget reached (${workerBudget.toolCalls}); synthesis is disabled`;
+						}
+						// Native agent tool calls carry a stable provider id. The wildcard
+						// keeps even an invariant violation on the post-result path.
+						stopAfterToolResultCallId = toolCallId ?? STOP_AFTER_ANY_TOOL_RESULT;
+					},
+				}
+			: {}),
+		// Requiring read is correct only when reading is the whole reserve.
+		...(readReserve > 0 && deliveryTools.length === 0
+			? {
+					onSoftReadReserve: () => {
+						middlewareToolChoice.apply([{ kind: "require_tool", toolName: ToolNames.Read }]);
+					},
+				}
+			: {}),
+	});
 	const registry = createWorkerToolRegistry(
 		input.middlewareSnapshot,
 		safety,
@@ -461,52 +497,7 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 		// and has no persistence sink. It can still absorb worker-local
 		// protect_path effects from snapshot rules for the rest of this run.
 		[
-			createLoopGuardRegistration({
-				safety,
-				toolCallCap: workerBudget.hardCap,
-				toolCallSoftLimit: workerBudget.toolCalls,
-				// A worker's blocks all land in one run-long bucket, so the bound on
-				// them is a statement about this run's length, not about a turn.
-				turnBlockBudget: workerLoopBlockBudget(workerBudget.toolCalls),
-				toolCallSoftReadReserve: readReserve,
-				...(deliveryTools.length > 0 ? { deliveryTools } : {}),
-				turnSynthesisLockout: workerBudget.synthesis,
-				// Once locked, the next model round is forced text-only at the
-				// request level (the tool surface is removed in onPayload below):
-				// the lockout directive alone relies on model compliance, and
-				// measured local models kept calling tools until the backstop
-				// aborted the run, or answered the forced round with tool-call
-				// markup that the loop guard then removed.
-				onSynthesisLockout: () => {
-					if (workerBudget.synthesis) {
-						synthesisToolLock = true;
-					}
-				},
-				...(!workerBudget.synthesis
-					? {
-							onSoftLimitFinalCallAdmitted: (toolCallId: string | undefined) => {
-								if (workerBoundFailure === null) {
-									workerBoundFailure = `worker agent budget reached (${workerBudget.toolCalls}); synthesis is disabled`;
-								}
-								// Native agent tool calls carry a stable provider id. The wildcard
-								// keeps even an invariant violation on the post-result path
-								// instead of reintroducing a before_tool abort.
-								stopAfterToolResultCallId = toolCallId ?? STOP_AFTER_ANY_TOOL_RESULT;
-							},
-						}
-					: {}),
-				// Forcing the next round to `read` is only correct when reading is
-				// the whole reserve. An agent with delivery tools must be able to
-				// write in its own reserve window, so it gets the steering directive
-				// without the request-level lock.
-				...(readReserve > 0 && deliveryTools.length === 0
-					? {
-							onSoftReadReserve: () => {
-								middlewareToolChoice.apply([{ kind: "require_tool", toolName: ToolNames.Read }]);
-							},
-						}
-					: {}),
-			}),
+			loopGuardRegistration,
 			createProtectedArtifactsRegistration({
 				...(input.protectedArtifactState !== undefined
 					? { initialState: { artifacts: [...input.protectedArtifactState.artifacts] } }
@@ -519,6 +510,7 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 	);
 	const contractCwd = input.cwd ?? process.cwd();
 	let resultContractRepairsQueued = 0;
+	let resultContractRevisionActive = false;
 	/** Read tool call id -> what was asked for, pending that call's result. */
 	const pendingReadCitations = new Map<string, { path: string; offset: number | null; tail: boolean }>();
 	const observedReadRanges = new Map<string, Array<readonly [number, number]>>();
@@ -702,10 +694,17 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 			if (violation !== null) {
 				if (resultContractRepairsQueued < RESULT_CONTRACT_REPAIR_LIMIT) {
 					resultContractRepairsQueued += 1;
-					// A repair round is terminal by construction, so enforce the
-					// directive's own claim that tool use is over at the request
-					// level instead of trusting the model to honor it.
-					synthesisToolLock = true;
+					if (!resultContractRevisionActive && workerBudget.revision !== undefined) {
+						resultContractRevisionActive = loopGuardRegistration.extendWorkerToolCallPhase(workerBudget.revision);
+						if (resultContractRevisionActive) {
+							synthesisToolLock = false;
+							middlewareToolChoice.reset();
+							stopAfterToolResultCallId = null;
+						}
+					}
+					const revisionToolsAvailable = resultContractRevisionActive && !synthesisToolLock;
+					// A repair without preauthorized growth remains terminal and text-only.
+					if (!revisionToolsAvailable) synthesisToolLock = true;
 					// Delivered as a paired tool exchange, never a user turn. Templates
 					// that key history rendering off the last `user` message re-render
 					// every earlier assistant turn when one is appended mid-run, which
@@ -714,7 +713,13 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 					// bytes as a tool result (#55). The synthetic assistant call gives
 					// the result a real tool_call_id for strict endpoints (#62).
 					const repair = resultContractRepairMessages(
-						{ contract, reason: violation, attempt: resultContractRepairsQueued, anchors: observedReadAnchors() },
+						{
+							contract,
+							reason: violation,
+							attempt: resultContractRepairsQueued,
+							anchors: observedReadAnchors(),
+							...(revisionToolsAvailable ? { toolsAvailable: true } : {}),
+						},
 						{ provider: model.provider, api: model.api, model: model.id },
 					);
 					for (const message of repair) agent.followUp(message as unknown as AgentMessage);
@@ -915,9 +920,9 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 			const timer = setTimeout(() => resolveEscalation(requestId, "deny", "timeout"), escalationConfig.timeoutMs);
 			activeEscalation = { requestId, tool: call.tool, actionClass, callKey, timer };
 			// The operator decides on this exact call, so the escalation carries a
-			// sanitized preview of its object; the args stay inside the worker. The
-			// cap bounds the NDJSON line, and the overlay truncates further.
-			const target = describeCallTarget(call.args).slice(0, 200);
+			// sanitized allowlisted preview of its object. Unlisted fields cross only
+			// as type-and-size summaries, and the args stay inside the worker.
+			const target = describeCallTarget(call.tool, call.args);
 			emit({
 				type: "clio_permission_escalated",
 				payload: {

package/src/entry/orchestrator.ts

@@ -161,8 +161,8 @@ import {
 import { openSession, readSessionTailTurns, sessionCurrentPath, sessionPaths } from "../engine/session.js";
 import type { EngineModel } from "../engine/types.js";
 import { createChatLoop } from "../interactive/chat-loop.js";
-import { buildReplayAgentMessagesFromTurns } from "../interactive/chat-renderer.js";
 import { type RunIo, startInteractive } from "../interactive/index.js";
+import { buildModelReplayAgentMessagesFromTurns } from "../interactive/model-session-replay.js";
 import type { BootOptions } from "./boot-options.js";
 
 export type { BootOptions, HeadlessSamplingOverrides } from "./boot-options.js";
@@ -183,6 +183,7 @@ import { isGitRepository, recoverCleanupReadyCompeteGroups } from "../tools/comp
 import { createDispatchBackgroundRegistry } from "../tools/dispatch-background.js";
 import { createFileMutationObserver, createSkillActivationObserver } from "../tools/observers.js";
 import { createRegistry } from "../tools/registry.js";
+import { sweepExpiredToolOffloads } from "../tools/result-shaping.js";
 
 export interface BootResult {
 	exitCode: number;
@@ -726,6 +727,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	termination.installSignalHandlers();
 
 	ensureClioState();
+	sweepExpiredToolOffloads();
 	timer.mark("install check");
 
 	// A hard-killed coordinator cannot run domain drains. Reconcile its compete
@@ -1236,7 +1238,16 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	// one object the dispatch tool and the keypress both hold.
 	const dispatchBackground = createDispatchBackgroundRegistry();
 	registerAllTools(toolRegistry, {
-		...(session ? { session } : {}),
+		...(session
+			? {
+					session,
+					readSessionEntries: () => {
+						const meta = session.current();
+						return meta ? readSessionEntriesForCompact(meta.id) : [];
+					},
+					onContextRecalled: (payload) => bus.emit(BusChannels.ContextRecalled, payload),
+				}
+			: {}),
 		taskBoard,
 		userTasks,
 		dispatch,
@@ -1544,8 +1555,13 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		getMemorySection: () => {
 			try {
 				const records = loadMemoryRecordsSync(clioDataDir());
+				const settings = getCurrentSettings();
+				const targetId = session?.current()?.target ?? settings.orchestrator?.target;
+				const runtimeId = targetId ? providers.getTarget(targetId)?.runtime : undefined;
 				return buildMemoryPromptSection(records, {
+					scopes: ["global", "repo", "runtime"],
 					activeRepository: canonicalMemoryRepositoryIdentity(process.cwd()),
+					activeRuntime: runtimeId === undefined ? null : { kind: "runtime", key: runtimeId },
 				}).section;
 			} catch {
 				return "";
@@ -1553,7 +1569,17 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		},
 		getTaskMemoryHandoffSource: () => {
 			ensureTaskMemorySession();
-			return renderTaskMemoryHandoffSource(taskMemoryBank.snapshot());
+			const meta = session?.current();
+			if (!meta) throw new Error("task memory handoff requires an active session");
+			const settings = getCurrentSettings();
+			const targetId = meta.target ?? settings.orchestrator?.target;
+			const runtimeId = targetId ? providers.getTarget(targetId)?.runtime : undefined;
+			return renderTaskMemoryHandoffSource(taskMemoryBank.snapshot(), {
+				sessionId: meta.id,
+				evidenceRefs: [`session-${meta.id}`],
+				runtimeIds: runtimeId === undefined ? [] : [runtimeId],
+				agentIds: [],
+			});
 		},
 		registerDeferredReminderSink: (sink) => {
 			deferredMemoryReminderSink = sink;
@@ -1612,7 +1638,10 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 				// parent onto.
 				chat.resetForSession(
 					leafTurnId,
-					buildReplayAgentMessagesFromTurns(readCurrentSessionEntries(), leafTurnId ? { activeLeafTurnId: leafTurnId } : {}),
+					buildModelReplayAgentMessagesFromTurns(
+						readCurrentSessionEntries(),
+						leafTurnId ? { activeLeafTurnId: leafTurnId } : {},
+					),
 				);
 			} catch (err) {
 				chat.resetForSession(leafTurnId);
@@ -1664,7 +1693,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 					? {
 							readSessionEntries: readSessionEntriesForCompact,
 							buildReplayMessages: (entries: ReadonlyArray<SessionEntry>, leafTurnId: string | null) =>
-								buildReplayAgentMessagesFromTurns(entries, leafTurnId === null ? {} : { activeLeafTurnId: leafTurnId }),
+								buildModelReplayAgentMessagesFromTurns(entries, leafTurnId === null ? {} : { activeLeafTurnId: leafTurnId }),
 						}
 					: {}),
 				providers,