@iowarp/clio-coder 0.3.4 → 0.3.6

package/src/engine/acp/server.ts

@@ -5,12 +5,18 @@ import { BusChannels, type LoopBlockedPayload } from "../../core/bus-events.js";
 import { DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS } from "../../core/defaults.js";
 import type { SafeEventBus } from "../../core/event-bus.js";
 import { MAX_TIMER_DELAY_MS } from "../../core/timers.js";
+import { ToolNames } from "../../core/tool-names.js";
 import type { ProvidersContract } from "../../domains/providers/contract.js";
 import { isOrchestratorEligibleRuntime } from "../../domains/providers/eligibility.js";
 import { type AutonomyLevel, DEFAULT_AUTONOMY_LEVEL } from "../../domains/safety/autonomy.js";
+import {
+	classifyDecisionPresentation,
+	decisionFactsForPermission,
+} from "../../domains/safety/decision-presentation.js";
 import type { SessionContract, SessionMeta } from "../../domains/session/contract.js";
 import type { MessageEntry, SessionEntry } from "../../domains/session/entries.js";
 import { filterEntriesToActivePath } from "../../domains/session/tree/active-path.js";
+import { askUserExposure } from "../../tools/ask-user.js";
 import type { ToolRegistry } from "../../tools/registry.js";
 import { toolResultPresentationText } from "../../tools/result-disposition.js";
 import type { AgentMessage } from "../types.js";
@@ -1265,6 +1271,19 @@ function installPermissionBridge(input: {
 	const queuedRequestDetails = new Map<string, { tool: string; actionClass: string }>();
 	const unregister = input.toolRegistry.onPermissionRequired((call, decision, meta) => {
 		if (queuedRequestIds.has(meta.requestId)) return;
+		const presentation = classifyDecisionPresentation(
+			decisionFactsForPermission({
+				tool: call.tool,
+				actionClass: decision.classification.actionClass,
+				axis: meta.axis.startsWith("net:")
+					? { kind: "safety-net", ruleId: meta.axis.slice("net:".length) || "unknown" }
+					: { kind: "autonomy", level: meta.axis.slice("autonomy:".length) || DEFAULT_AUTONOMY_LEVEL },
+				origin: { kind: "main" },
+				...(call.tool === ToolNames.AskUser ? { exposure: askUserExposure(call.args) } : {}),
+			}),
+		);
+		const approveAction = presentation.requiredActions.find((action) => action.id === "approve-once");
+		const denyAction = presentation.requiredActions.find((action) => action.id === "deny");
 		queuedRequestIds.add(meta.requestId);
 		queuedRequestDetails.set(meta.requestId, {
 			tool: call.tool,
@@ -1381,8 +1400,16 @@ function installPermissionBridge(input: {
 									...(snapshot.locations !== undefined ? { locations: snapshot.locations } : {}),
 								},
 								options: [
-									{ optionId: "allow-once", name: "Allow once", kind: "allow_once" },
-									{ optionId: "reject-once", name: "Reject", kind: "reject_once" },
+									{
+										optionId: "allow-once",
+										name: approveAction?.label ?? "Approve once",
+										kind: "allow_once",
+									},
+									{
+										optionId: "reject-once",
+										name: denyAction?.label ?? "Deny this request",
+										kind: "reject_once",
+									},
 								],
 							},
 							input.permissionTimeoutMs,

package/src/engine/apis/lmstudio.ts

@@ -130,6 +130,25 @@ async function loadOwnedInstance(
 	return instanceId;
 }
 
+/**
+ * Residency runs before every request, and the same co-residency facts held
+ * every turn, so the peer warning printed once per turn (issue #185). Each
+ * distinct fact is said once per process; a new target, model, or peer set is
+ * a new fact.
+ */
+const announcedResidencyFacts = new Set<string>();
+
+function emitResidencyNoticeOnce(key: string, notice: Parameters<typeof emitResidencyNotice>[0]): void {
+	if (announcedResidencyFacts.has(key)) return;
+	announcedResidencyFacts.add(key);
+	emitResidencyNotice(notice);
+}
+
+/** Test seam: forget which residency facts were announced. */
+export function resetAnnouncedResidencyFacts(): void {
+	announcedResidencyFacts.clear();
+}
+
 export async function ensureLmStudioResidency(
 	model: Model<"openai-completions">,
 	options: { apiKey?: string; signal?: AbortSignal } = {},
@@ -155,7 +174,7 @@ export async function ensureLmStudioResidency(
 		);
 	}
 	if (resolution.wireModelId !== model.id) {
-		emitResidencyNotice({
+		emitResidencyNoticeOnce(`resolved|${info.targetId}|${model.id}|${resolution.wireModelId}`, {
 			kind: "co-resident",
 			level: "info",
 			targetId: info.targetId,
@@ -166,14 +185,16 @@ export async function ensureLmStudioResidency(
 		});
 	}
 	if (resolution.peerTargets.length > 0) {
-		emitResidencyNotice({
+		const peers = resolution.peerTargets.join(", ");
+		const requested = resolution.wireModelId === model.id ? "" : ` (requested '${model.id}')`;
+		emitResidencyNoticeOnce(`peer|${info.targetId}|${model.id}|${resolution.wireModelId}|${peers}`, {
 			kind: "co-resident",
 			level: "warning",
 			targetId: info.targetId,
 			runtimeId: "lmstudio",
 			model: resolution.wireModelId,
-			message: `LM Studio instance '${resolution.wireModelId}' is also loaded on ${resolution.peerTargets.join(", ")}; this request may be served by that LM Link peer.`,
-			detail: { peerTargets: resolution.peerTargets.join(", ") },
+			message: `LM Studio instance '${resolution.wireModelId}'${requested} is also loaded on ${peers}; a request may be served by that LM Link peer, and the footer and usage ledger name the id that answered when it differs.`,
+			detail: { requestedModel: model.id, wireModel: resolution.wireModelId, peerTargets: peers },
 		});
 	}
 	if (!load || Object.keys(load).length === 0 || resolution.instance) return resolution.wireModelId;

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/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: {