@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/engine/worker-runtime.ts

@@ -4,6 +4,7 @@ import { createWorkerObservationStore } from "../domains/context/worker/recall.j
 import { seededWorkerMessages } from "../worker/context-seed.js";
 import { engineStreamSimple } from "./api-registry.js";
 import { estimateInputTokensFromContext, resolveReservedOutputTokens } from "./apis/output-budget.js";
+import { resolvedRequestContext } from "./context.js";
 /**
  * Worker-subprocess engine boundary.
  *
@@ -16,6 +17,7 @@ import { estimateInputTokensFromContext, resolveReservedOutputTokens } from "./a
  */
 
 import path from "node:path";
+import { Type } from "typebox";
 import {
 	configureGuardrails,
 	guardrailValuesFromSettings,
@@ -27,13 +29,18 @@ import { readLayeredSettings } from "../core/settings-layers.js";
 import { agentSkillToolPolicy } from "../core/skill-activation.js";
 import { type ToolName, ToolNames } from "../core/tool-names.js";
 import {
+	internalHelperResultSchema,
 	type ObservedReadRanges,
 	type ObservedRunEffects,
 	parseWorkerResultContract,
 	RESULT_CONTRACT_REPAIR_LIMIT,
 	type ResultContract,
 	resultContractRepairMessages,
+	resultContractRepairUserMessage,
+	resultContractShape,
+	type StructuredHelperResult,
 	validateResultContract,
+	validateStructuredHelperResult,
 } from "../domains/agents/result-contract.js";
 import { nodeResultContractFilesystem } from "../domains/agents/result-contract-filesystem.js";
 import type { AgentProduct } from "../domains/agents/spec.js";
@@ -54,9 +61,10 @@ import {
 	type KnowledgeBase,
 	type KnowledgeBaseHit,
 } from "../domains/providers/types/knowledge-base.js";
-import type { ActionClass } from "../domains/safety/action-classifier.js";
+import type { ActionClass, ClassifierCall } from "../domains/safety/action-classifier.js";
 import type { AutonomyLevel } from "../domains/safety/autonomy.js";
 import { describeCallTarget } from "../domains/safety/call-target.js";
+import type { SafetyDecision } from "../domains/safety/contract.js";
 import { createProtectedArtifactsRegistration } from "../domains/safety/protected-artifacts-registration.js";
 import { createRunEffectsRecorder } from "../domains/safety/run-effects.js";
 import { resolveAgentTools, type ToolTelemetry } from "../tools/agent-tools.js";
@@ -83,14 +91,28 @@ import {
 	isLoopGuardSynthesisBackstopReason,
 	lockedSynthesisFallbackText,
 	lockedSynthesisRepromptMessages,
+	lockedSynthesisSystemPrompt,
 	resolveDeliveryTools,
 	sanitizeLockedSynthesisMessage,
 	workerLoopBlockBudget,
 } from "./loop-guard.js";
-import { patchWorkerRequestPayload } from "./provider-payload.js";
+import { patchWorkerRequestPayload, supportsNamedToolChoice } from "./provider-payload.js";
 import type { AgentEvent, AgentMessage, EngineModel } from "./types.js";
 import type { ClioWorkerEvent } from "./worker-events.js";
-import { createWorkerSafety, createWorkerToolRegistry } from "./worker-tools.js";
+import { createWorkerSafety, createWorkerToolRegistry, INTERNAL_HELPER_RESULT_TOOL } from "./worker-tools.js";
+
+/** Exact call and enforced permission conditions; never reuse an answer across asking axes. */
+export function workerPermissionCacheKey(call: ClassifierCall, decision: SafetyDecision, axis: string): string {
+	return canonicalJson({
+		tool: call.tool,
+		args: call.args ?? {},
+		axis,
+		actionClass: decision.classification.actionClass,
+		policyReason: decision.policy?.reasonCode,
+		policySource: decision.policy?.policySource,
+		policyHash: decision.policy?.policyHash,
+	});
+}
 
 export interface WorkerRunInput {
 	sessionId?: string;
@@ -116,6 +138,8 @@ export interface WorkerRunInput {
 	 * orchestrator for a recoverable shape mistake it was never told about.
 	 */
 	resultContract?: ResultContract;
+	/** Host-declared internal helper protocol; never inferred from agent names. */
+	helperResult?: true;
 	/** What this run delivers; decides which delivery tools the reserve keeps live. */
 	product?: AgentProduct;
 	/**
@@ -143,6 +167,7 @@ export interface WorkerRunInput {
 	protectedArtifactState?: WorkerProtectedArtifactState;
 	signal?: AbortSignal;
 	noSkills?: boolean;
+	turnConstraints?: import("../core/turn-constraints.js").TurnConstraints;
 	skillPaths?: ReadonlyArray<string>;
 	/** Recipe-bound skill names; context(scope=skills) admits exactly these for the run. */
 	agentSkills?: ReadonlyArray<string>;
@@ -255,7 +280,7 @@ function terminalContractViolation(
 	// through 45 tool calls and lost its answer to the lockout was reported as
 	// "result must be valid JSON".
 	if (text.trim() === lockedSynthesisFallbackText()) {
-		return "the reply after the tool-call lockout held only tool-call markup and was removed; tools are off, so state the final result as plain text";
+		return "the reply after the tool-call lockout held only tool-call markup and was removed; tools are off, so emit the required terminal result format";
 	}
 	const stopReason = message.stopReason;
 	if (
@@ -326,7 +351,13 @@ function taskMessage(task: string): AgentMessage {
 
 function promptMessagesForWorker(input: WorkerRunInput): AgentMessage[] {
 	const messages = (input.dynamicPromptMessages ?? []).map(promptMessage);
-	messages.push(taskMessage(input.task));
+	messages.push(
+		taskMessage(
+			input.contextSeed
+				? `# Your worker assignment\nYou are already the dispatched ${input.agentId} worker. The preceding conversation is inherited background; its requests to dispatch a worker were addressed to the parent. Carry out the assignment below, preserving safety and operator scope constraints. Do not dispatch yourself again.\n\n${input.task}`
+				: input.task,
+		),
+	);
 	return messages;
 }
 
@@ -376,6 +407,11 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 	// with a kind the coordinator authors, and the recipe parser refusing those
 	// killed every council vote member with a fatal spec error.
 	if (input.resultContract !== undefined) parseWorkerResultContract(input.resultContract, "WorkerSpec.resultContract");
+	const helperSchema =
+		input.helperResult === true && input.resultContract ? internalHelperResultSchema(input.resultContract) : null;
+	if (input.helperResult === true && (helperSchema === null || input.runtime.kind !== "http")) {
+		throw new Error("helperResult requires a supported internal JSON contract and native HTTP worker");
+	}
 	if (input.runtime.id === "claude-sdk") {
 		return startClaudeSdkWorkerRun(input, emit);
 	}
@@ -389,7 +425,7 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 	// pi-ai is process-local. The orchestrator registers Clio API providers in
 	// providers/extension.ts, but the worker subprocess starts a fresh process,
 	// so it must register them here before any agent.prompt() touches a local
-	// runtime (lmstudio, ollama-native).
+	// runtime (lmstudio, ollama).
 	registerClioApiProviders();
 	// The worker is a fresh process. Resolve its workspace's trusted settings
 	// layers so project output limits and guardrails survive dispatch. Keep the
@@ -458,6 +494,7 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 	let workerModelRound = 0;
 	const loopGuardRegistration = createLoopGuardRegistration({
 		safety,
+		readResultMaxBytes: workerSettings.context.toolResultMaxBytes,
 		toolCallCap: workerBudget.hardCap,
 		toolBudgetAdvisory: workerBudget.mode === "advisory",
 		toolCallSoftLimit: workerBudget.toolCalls,
@@ -527,12 +564,31 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 	const contractCwd = input.cwd ?? process.cwd();
 	let resultContractRepairsQueued = 0;
 	let resultContractRevisionActive = false;
+	let acceptedHelperResult: StructuredHelperResult | null = null;
+	let helperTerminalPhase = false;
+	let helperTurnFailure: string | null = null;
 	/** 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]>>();
 	// The write-side equivalent: what this run changed and what it validated,
 	// so a mutation report is judged against the run instead of believed.
 	const runEffects = createRunEffectsRecorder(contractCwd);
+	const acceptHelperResult = (data: unknown): string | null => {
+		if (!input.resultContract) return "missing helper result contract";
+		const checked = validateStructuredHelperResult({
+			contract: input.resultContract,
+			data,
+			cwd: contractCwd,
+			observedReadRanges,
+			observedRunEffects: runEffects.snapshot(),
+			networkAllowed: true,
+			filesystem: nodeResultContractFilesystem(),
+		});
+		if (checked.structured === null) return checked.validation.reason ?? "invalid helper result";
+		acceptedHelperResult = checked.structured;
+		emit({ type: "clio_coder_helper_result", payload: checked.structured });
+		return null;
+	};
 
 	/**
 	 * Fold one successful read into the observed spans. The request says where
@@ -612,12 +668,14 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 	};
 	const tools = resolveAgentTools({
 		registry,
+		...(input.turnConstraints ? { turnConstraints: input.turnConstraints } : {}),
 		telemetry,
 		allowedTools: activeWorkerTools,
 		agentId: input.agentId,
 		task: input.task,
 		includeInteractiveTools: false,
 		invokeOptions: () => ({
+			...(input.turnConstraints ? { turnConstraints: input.turnConstraints } : {}),
 			correlationId: `worker-model-round-${workerModelRound}`,
 			toolResultMaxBytes: workerSettings.context.toolResultMaxBytes,
 			supportsImages: model.input.includes("image"),
@@ -627,6 +685,33 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 			...(agentSkillPolicy ? { pendingSkillPolicy: agentSkillPolicy } : {}),
 		}),
 	});
+	const helperToolAvailable = helperSchema !== null && workerProviderSupportsTools(input);
+	const helperForcedChoiceAvailable = helperToolAvailable && supportsNamedToolChoice(model.api);
+	if (helperToolAvailable) {
+		tools.push({
+			name: INTERNAL_HELPER_RESULT_TOOL,
+			label: "Submit helper result",
+			description:
+				"Submit the final internal result as this tool's arguments. Call alone, after gathering evidence. A validated submission finishes the run; no prose response follows.",
+			parameters: Type.Unsafe<Record<string, unknown>>(helperSchema),
+			async execute(_id, args) {
+				if (acceptedHelperResult !== null || workerBoundFailure !== null) {
+					return {
+						content: [{ type: "text", text: "The terminal result is already sealed." }],
+						details: { kind: "error" },
+						terminate: true,
+					};
+				}
+				helperTerminalPhase = true;
+				synthesisToolLock = true;
+				helperTurnFailure = acceptHelperResult(args);
+				if (helperTurnFailure !== null) {
+					return { content: [{ type: "text", text: helperTurnFailure }], details: { kind: "error" } };
+				}
+				return { content: [{ type: "text", text: "Internal result accepted." }], details: { kind: "ok" }, terminate: true };
+			},
+		});
+	}
 	if (tools.length === 0 && activeWorkerTools.length > 0) {
 		process.stderr.write(`[worker] warning: no tools resolved for allowed=[${activeWorkerTools.join(",")}]\n`);
 	}
@@ -636,16 +721,50 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 	);
 
 	const inheritedMessages = seededWorkerMessages(input.contextSeed);
-	const inheritedCount = inheritedMessages.length;
 	const contextGuard = createWorkerContextGuard(observations.archive);
 	const options: EngineAgentOptions = {
-		streamFn: (currentModel, currentContext, streamOptions) => {
+		beforeToolCall: async ({ assistantMessage, toolCall }) => {
+			if (helperSchema === null) return undefined;
+			if (acceptedHelperResult !== null || workerBoundFailure !== null)
+				return { block: true, reason: "The helper result is sealed.", terminate: true };
+			const calls = assistantMessage.content.filter((block) => block.type === "toolCall");
+			if (calls.some((call) => call.name === INTERNAL_HELPER_RESULT_TOOL) && calls.length !== 1) {
+				helperTurnFailure =
+					"Submit exactly one terminal handoff, alone; mixed or duplicate handoff batches are rejected without executing work.";
+				return { block: true, reason: helperTurnFailure };
+			}
+			if ((helperTerminalPhase || synthesisToolLock) && toolCall.name !== INTERNAL_HELPER_RESULT_TOOL) {
+				helperTurnFailure = "Work tools are disabled. Submit only the internal terminal result.";
+				return { block: true, reason: helperTurnFailure };
+			}
+			return undefined;
+		},
+		afterToolCall: async ({ toolCall, result }) =>
+			toolCall.name === INTERNAL_HELPER_RESULT_TOOL && (result.details as { kind?: string } | undefined)?.kind === "error"
+				? { isError: true }
+				: undefined,
+		shouldStopAfterTurn: () => helperSchema !== null && (acceptedHelperResult !== null || workerBoundFailure !== null),
+		streamFn: (currentModel, transcript, streamOptions) => {
+			const currentContext = resolvedRequestContext(transcript);
+			const helperPrompt =
+				helperToolAvailable && (!(synthesisToolLock || helperTerminalPhase) || helperForcedChoiceAvailable)
+					? `${currentContext.systemPrompt ?? ""}\n\n# Internal helper protocol\nReturn the result by calling ${INTERNAL_HELPER_RESULT_TOOL} alone with the result object as arguments. Successful submission ends the run; no narrative report is needed.${synthesisToolLock || helperTerminalPhase ? " Work tools are disabled. Earlier tool-use instructions apply only to the completed work phase; only the terminal handoff remains available. Do not invent missing evidence." : ""}`
+					: currentContext.systemPrompt;
+			const systemPrompt =
+				helperToolAvailable && (!(synthesisToolLock || helperTerminalPhase) || helperForcedChoiceAvailable)
+					? helperPrompt
+					: synthesisToolLock
+						? lockedSynthesisSystemPrompt(
+								currentContext.systemPrompt ?? "",
+								input.resultContract ? resultContractShape(input.resultContract) : undefined,
+							)
+						: currentContext.systemPrompt;
 			const window = input.runtimeResolution?.capabilities.contextWindow ?? currentModel.contextWindow;
 			let messages: AgentMessage[];
 			try {
 				messages = contextGuard({
 					messages: currentContext.messages,
-					systemPrompt: currentContext.systemPrompt ?? "",
+					systemPrompt: systemPrompt ?? "",
 					tools: currentContext.tools ?? [],
 					contextWindow: window,
 					threshold: workerSettings.context.compaction.threshold,
@@ -665,7 +784,11 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 			}
 			return engineStreamSimple(
 				currentModel,
-				{ ...currentContext, messages: messages as typeof currentContext.messages },
+				{
+					...currentContext,
+					...(systemPrompt !== undefined ? { systemPrompt } : {}),
+					messages: messages as typeof currentContext.messages,
+				},
 				streamOptions,
 			);
 		},
@@ -683,6 +806,9 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 				thinkingLevel: effectiveThinkingLevel,
 				...(input.responseSchema !== undefined ? { responseSchema: input.responseSchema } : {}),
 				toolSurfaceLocked: synthesisToolLock,
+				...(helperToolAvailable && (synthesisToolLock || helperTerminalPhase) && supportsNamedToolChoice(currentModel.api)
+					? { terminalToolName: INTERNAL_HELPER_RESULT_TOOL }
+					: {}),
 				toolChoiceNone: middlewareChoice.kind === "none",
 				...(middlewareChoice.kind === "required" ? { toolChoiceName: middlewareChoice.toolName } : {}),
 			});
@@ -692,12 +818,65 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 	if (input.sessionId) options.sessionId = input.sessionId;
 
 	const { agent } = createEngineAgent(options);
+	// Pi adds a leading prompt/tool declaration; exclude the entire inherited baseline.
+	const inheritedCount = agent.state.messages.length;
 	// The result-contract repair queues a call/result pair that must land in
 	// one drain, or the provider sees a lone assistant tool call.
 	agent.followUpMode = "all";
 	abortWorkerForBound = () => agent.abort();
+	const repairHelperResult = (reason: string): void => {
+		if (!input.resultContract || acceptedHelperResult !== null || workerBoundFailure !== null) return;
+		helperTerminalPhase = true;
+		synthesisToolLock = true;
+		if (resultContractRepairsQueued >= RESULT_CONTRACT_REPAIR_LIMIT) {
+			workerBoundFailure = `result contract failed after ${RESULT_CONTRACT_REPAIR_LIMIT} bounded repair rounds: ${reason}`;
+			emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "result_contract_exhausted" } });
+			return;
+		}
+		resultContractRepairsQueued += 1;
+		const instruction = helperForcedChoiceAvailable
+			? `${reason} Work tools remain disabled. Repair the result by calling ${INTERNAL_HELPER_RESULT_TOOL} exactly once, alone, with the complete result object. Do not emit prose.`
+			: reason;
+		for (const message of resultContractRepairMessages(
+			{
+				contract: input.resultContract,
+				reason: instruction,
+				attempt: resultContractRepairsQueued,
+				anchors: observedReadAnchors(),
+			},
+			{ provider: model.provider, api: model.api, model: model.id },
+		)) {
+			const repairMessage =
+				helperForcedChoiceAvailable && message.role === "toolResult"
+					? {
+							...message,
+							content: [
+								{
+									type: "text" as const,
+									text: `${instruction}\nRequired arguments schema: ${JSON.stringify(helperSchema)}\nObserved read ranges: ${observedReadAnchors().join(", ") || "none"}`,
+								},
+							],
+						}
+					: message;
+			agent.followUp(repairMessage as unknown as AgentMessage);
+		}
+	};
 	const unsubscribe = agent.subscribe(async (event) => {
-		if (event.type === "turn_start") workerModelRound += 1;
+		if (event.type === "turn_start") {
+			workerModelRound += 1;
+			helperTurnFailure = null;
+		}
+		// Detect the whole terminal batch before any call is prepared/executed.
+		// beforeToolCall rejects every sibling, regardless of ordering or parallelism.
+		if (helperSchema !== null && event.type === "message_end" && isAssistantMessage(event.message)) {
+			const calls = event.message.content.filter((block) => block.type === "toolCall");
+			if (calls.some((call) => call.name === INTERNAL_HELPER_RESULT_TOOL)) {
+				helperTerminalPhase = true;
+				synthesisToolLock = true;
+				if (calls.length !== 1)
+					helperTurnFailure = "Submit exactly one terminal handoff, alone; mixed or duplicate batches cannot execute work.";
+			}
+		}
 		if (event.type === "tool_execution_start") middlewareToolChoice.toolStarted(event.toolName);
 		// Read spans this run actually observed. They ground the terminal result
 		// (a cited line has to fall inside one) and they are handed back verbatim
@@ -734,24 +913,27 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 		// the same message and the run then ran out of repairs on a later
 		// grounding violation).
 		let repromptedThisMessage = false;
-		if (synthesisToolLock && event.type === "message_end") {
+		if (synthesisToolLock && !helperToolAvailable && event.type === "message_end") {
 			const stripped = sanitizeLockedSynthesisMessage(event.message);
 			// A model that calls a tool anyway hands its markup back as text and
 			// the sanitizer leaves only the fallback notice: the training habit
 			// survives the strip (Qwen3.8 did it in 1 of 5 stripped runs). One
 			// re-prompt, delivered as a tool exchange like the result-contract
-			// repair, asks for the answer in prose; a second markup-only reply
+			// repair, asks for the required result format; a second markup-only reply
 			// keeps the notice.
 			if (stripped && lockedSynthesisReprompts < 1 && isLockedSynthesisFallbackOnly(event.message)) {
 				lockedSynthesisReprompts += 1;
 				repromptedThisMessage = true;
-				process.stderr.write("[worker] synthesis lock: reply was tool-call markup only; re-prompting once for prose\n");
-				for (const message of lockedSynthesisRepromptMessages(lockedSynthesisReprompts, {
-					provider: model.provider,
-					api: model.api,
-					model: model.id,
-				})) {
-					agent.followUp(message as unknown as AgentMessage);
+				process.stderr.write(
+					"[worker] synthesis lock: reply was tool-call markup only; re-prompting once for the required final format\n",
+				);
+				const directive = lockedSynthesisRepromptMessages(
+					lockedSynthesisReprompts,
+					{ provider: model.provider, api: model.api, model: model.id },
+					input.resultContract ? resultContractShape(input.resultContract) : undefined,
+				).find((message) => message.role === "toolResult");
+				if (directive?.role === "toolResult") {
+					agent.followUp({ role: "user", content: directive.content, timestamp: Date.now() } as AgentMessage);
 				}
 			}
 		}
@@ -762,7 +944,46 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 		// same contract against the sealed receipt; this is the only point at
 		// which the model can still act on the validator's reason.
 		const contract = input.resultContract;
-		if (contract && !repromptedThisMessage && event.type === "message_end" && isTerminalAssistantMessage(event.message)) {
+		if (
+			helperSchema !== null &&
+			contract &&
+			!repromptedThisMessage &&
+			event.type === "message_end" &&
+			isTerminalAssistantMessage(event.message)
+		) {
+			const text = assistantMessageText(event.message);
+			let reason: string | null;
+			try {
+				reason = acceptHelperResult(JSON.parse(text ?? ""));
+			} catch {
+				reason = "The internal result must be a JSON object conforming to the declared contract.";
+			}
+			if (reason !== null) repairHelperResult(reason);
+		}
+		if (
+			helperSchema !== null &&
+			event.type === "turn_end" &&
+			acceptedHelperResult === null &&
+			event.toolResults.length > 0 &&
+			(helperTerminalPhase || synthesisToolLock)
+		) {
+			const error = event.toolResults.find((result) => result.isError);
+			const reason =
+				helperTurnFailure ??
+				error?.content
+					.filter((block) => block.type === "text")
+					.map((block) => block.text)
+					.join("\n") ??
+				"The terminal handoff was not accepted.";
+			repairHelperResult(reason);
+		}
+		if (
+			helperSchema === null &&
+			contract &&
+			!repromptedThisMessage &&
+			event.type === "message_end" &&
+			isTerminalAssistantMessage(event.message)
+		) {
 			const violation = terminalContractViolation(
 				contract,
 				event.message,
@@ -785,23 +1006,24 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 						(workerBudget.mode === "advisory" || resultContractRevisionActive) && !synthesisToolLock;
 					// Legacy enforced budgets need preauthorized growth to retain repair tools.
 					if (!revisionToolsAvailable) synthesisToolLock = true;
-					// Delivered as a paired tool exchange, never a user turn. Templates
+					// Active revision retains the paired tool exchange. Final-only
+					// repair starts a fresh user turn to break local tool-call fixation. Templates
 					// that key history rendering off the last `user` message re-render
 					// every earlier assistant turn when one is appended mid-run, which
 					// invalidates the whole prompt cache: Nemotron reprocessed 11,352
 					// tokens for this directive as `user` against 407 for the same
 					// 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(),
-							...(revisionToolsAvailable ? { toolsAvailable: true } : {}),
-						},
-						{ provider: model.provider, api: model.api, model: model.id },
-					);
+					const repairInput = {
+						contract,
+						reason: violation,
+						attempt: resultContractRepairsQueued,
+						anchors: observedReadAnchors(),
+						toolsAvailable: revisionToolsAvailable,
+					};
+					const repair = revisionToolsAvailable
+						? resultContractRepairMessages(repairInput, { provider: model.provider, api: model.api, model: model.id })
+						: [resultContractRepairUserMessage(repairInput)];
 					for (const message of repair) agent.followUp(message as unknown as AgentMessage);
 				} else if (workerBoundFailure === null) {
 					workerBoundFailure = `result contract failed after ${RESULT_CONTRACT_REPAIR_LIMIT} bounded repair rounds: ${violation}`;
@@ -853,20 +1075,22 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 		requestId: string;
 		tool: string;
 		actionClass: ActionClass;
-		/** Identity of the parked call (tool plus canonical args) for the answered-escalation memory. */
+		/** Identity of the exact call and permission conditions for the answered-escalation memory. */
 		callKey: string;
 		timer: ReturnType<typeof setTimeout>;
 	}
 	let activeEscalation: ActiveEscalation | null = null;
-	// Answered escalations, keyed by the exact call. A worker that re-issues
+	// Answered escalations, keyed by the exact call and permission conditions. A worker that re-issues
 	// the identical call after the operator already decided it gets the same
 	// answer without a new card: a live coder re-asked one bash approval eight
 	// times after its edits were done, and each approval only bought the next
 	// identical card (#79). The memory is per run and per exact (tool, args)
-	// tuple; a different command is a new decision.
-	const answeredEscalations = new Map<string, { decision: "approve" | "deny"; requestId: string }>();
-	const escalationCallKey = (tool: string, args: Record<string, unknown> | undefined): string =>
-		`${tool}\u0000${canonicalJson(args ?? {})}`;
+	// tuple and asking axis/classification; a different command or safety-net
+	// requirement is a new decision. Denials have the same bounded identity.
+	const answeredEscalations = new Map<
+		string,
+		{ decision: "approve" | "deny"; requestId: string; source: "operator" | "timeout" }
+	>();
 	const clearActiveEscalation = (): void => {
 		if (activeEscalation) {
 			clearTimeout(activeEscalation.timer);
@@ -887,7 +1111,7 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 		const active = activeEscalation;
 		if (!active || active.requestId !== requestId) return false;
 		clearActiveEscalation();
-		answeredEscalations.set(active.callKey, { decision, requestId });
+		answeredEscalations.set(active.callKey, { decision, requestId, source });
 		if (decision === "approve") {
 			emit({
 				type: "clio_coder_permission_resolved",
@@ -962,13 +1186,13 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 	const unsubscribePermission = registry.onPermissionRequired((call, decision, meta) => {
 		const actionClass = decision.classification.actionClass;
 		if (escalationConfig) {
-			const callKey = escalationCallKey(call.tool, call.args);
+			const callKey = workerPermissionCacheKey(call, decision, meta.axis);
 			const remembered = answeredEscalations.get(callKey);
 			if (remembered !== undefined) {
 				const approved = remembered.decision === "approve";
 				const reason = approved
-					? `operator approved an identical ${call.tool} call earlier in this run (request ${remembered.requestId}); the answer stands without a new prompt`
-					: `permission denied by operator: an identical ${call.tool} call was already denied earlier in this run (request ${remembered.requestId}); the answer stands, so do not repeat this call`;
+					? `operator approved an identical ${call.tool} call under the same permission conditions earlier in this run (request ${remembered.requestId}); the answer stands without a new prompt`
+					: `permission denied by ${remembered.source === "timeout" ? "escalation timeout fallback" : "operator"}: an identical ${call.tool} call under the same permission conditions was already denied earlier in this run (request ${remembered.requestId}); the answer stands, so do not repeat this call`;
 				emit({
 					type: "clio_coder_permission_resolved",
 					payload: {
@@ -1056,6 +1280,9 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 				return { messages: agent.state.messages.slice(inheritedCount), exitCode: WORKER_EXIT_PERMISSION_REQUIRED };
 			}
 			const messages = agent.state.messages.slice(inheritedCount);
+			if (helperSchema !== null && acceptedHelperResult === null) {
+				return { messages, exitCode: 1 };
+			}
 			const errorMessage = getTerminalAgentError(messages);
 			if (errorMessage !== null) {
 				if (errorMessage.length > 0) {

package/src/engine/worker-tools.ts

@@ -37,6 +37,9 @@ import { type AgentLedgerPort, toolSignatureOf } from "../worker/protocol.js";
 
 export { WORKER_RUNTIME_MEDIATES_CLIO_DISPATCH } from "./worker-runtime-capabilities.js";
 
+/** Host-owned terminal protocol, never an additional workspace capability. */
+export const INTERNAL_HELPER_RESULT_TOOL = "clio_submit_result";
+
 /**
  * Build a worker-local SafetyContract that owns its own loop-detector state.
  * The state is per-worker-run (one subprocess per run) so two concurrent
@@ -192,6 +195,7 @@ export function createWorkerToolRegistry(
  */
 export interface AttestedToolIdentityInput {
 	allowedTools: ReadonlyArray<ToolName>;
+	helperResult?: true;
 	/** False when the resolved runtime mediates no tool calls at all. */
 	toolsSupported: boolean;
 	toolProfile?: ToolProfileName;
@@ -206,8 +210,8 @@ export interface AttestedToolIdentityInput {
  */
 export function attestedToolSignature(input: AttestedToolIdentityInput): string {
 	const registry = createWorkerToolRegistry();
-	return toolSignatureOf(
-		effectiveToolNames({
+	return toolSignatureOf([
+		...effectiveToolNames({
 			registry,
 			allowedTools: input.toolsSupported ? input.allowedTools : [],
 			includeInteractiveTools: false,
@@ -215,5 +219,6 @@ export function attestedToolSignature(input: AttestedToolIdentityInput): string
 			...(input.agentId !== undefined ? { agentId: input.agentId } : {}),
 			...(input.task !== undefined ? { task: input.task } : {}),
 		}),
-	);
+		...(input.helperResult === true && input.toolsSupported ? [INTERNAL_HELPER_RESULT_TOOL] : []),
+	]);
 }

package/src/entry/boot-options.ts

@@ -1,6 +1,7 @@
 /** Type-only boot contract kept outside the heavyweight orchestrator graph. */
 
 import type { ClioSettings } from "../core/config.js";
+import type { TurnConstraints } from "../core/turn-constraints.js";
 import type { ThinkingLevel } from "../domains/providers/index.js";
 import type { AutonomyLevel } from "../domains/safety/index.js";
 import type { AcpJsonRpcPeerTransport, StdioServerTransportOptions } from "../engine/acp/transport.js";
@@ -17,7 +18,24 @@ export interface HeadlessSamplingOverrides {
 	repeatPenalty?: number;
 }
 
+/**
+ * The wall-clock limit `clio-coder run --timeout` arms before boot. The CLI owns
+ * the timer; on expiry it starts the same coordinated shutdown a SIGTERM does,
+ * with exit code 124. The headless turn reads it to seal a timed-out receipt
+ * rather than a canceled one, and settles it once the turn has settled so a
+ * late expiry cannot contradict a receipt already sealed.
+ */
+export interface HeadlessRunDeadline {
+	readonly seconds: number;
+	/** True once the limit elapsed and the deadline started the shutdown. */
+	expired(): boolean;
+	/** Disarm the timer; a run that settled on its own is no longer bounded. */
+	settle(): void;
+}
+
 export interface BootOptions {
+	/** Interactive demo guidance override for this session. */
+	demo?: boolean;
 	apiKey?: string;
 	noContextFiles?: boolean;
 	noSkills?: boolean;
@@ -32,6 +50,7 @@ export interface BootOptions {
 	autonomy?: AutonomyLevel;
 	headless?: {
 		prompt: string;
+		constraints?: TurnConstraints;
 		images?: ReadonlyArray<ImageContent>;
 		workingContextPaths?: ReadonlyArray<string>;
 		mode?: "text" | "json";
@@ -45,6 +64,10 @@ export interface BootOptions {
 		skillPaths?: ReadonlyArray<string>;
 		steerChannel?: string;
 		resumeSession?: { kind: "id"; id: string } | { kind: "latest" };
+		/** `clio-coder run --fail-on-noop`: a no-op run exits 1 with outcome failed. */
+		failOnNoop?: boolean;
+		/** `clio-coder run --timeout`: the armed wall-clock limit for the whole run. */
+		deadline?: HeadlessRunDeadline;
 	};
 	acp?: {
 		transport?: AcpJsonRpcPeerTransport;