@iowarp/clio-coder 0.3.3 → 0.3.6

package/src/tools/dispatch-runner.ts

@@ -41,6 +41,7 @@ import { type ReceiptIntegrityResult, verifyReceiptIntegrity } from "../domains/
 import { explainRouteDecision } from "../domains/dispatch/routing-intent.js";
 import type { RunGateProvenance, RunGateSubjectRef, RunPlanProvenance, RunReceipt } from "../domains/dispatch/types.js";
 import { extractRunProvenance, provenanceCompactSuffix } from "../domains/evidence/provenance.js";
+import { adaptRunReceiptTrustStatus } from "../domains/evidence/trust-status.js";
 import type { AutonomyLevel } from "../domains/safety/autonomy.js";
 import {
 	type CandidateWorktree,
@@ -458,8 +459,8 @@ function formatDispatchOutput(
 		.map((run) => integrityFailureBanner(run))
 		.filter((banner): banner is string => banner !== null);
 	const needsSpotCheck = runs.some((run) => {
-		const state = run.receipt.verification.state;
-		return state === "unverified" || state === "unknown";
+		const state = adaptRunReceiptTrustStatus(run.receipt, { integrity: run.integrity }).validationGrounding.state;
+		return state === "absent" || state === "unknown" || state === "ungrounded";
 	});
 	const lines = [
 		`dispatch (${mode}) total=${runs.length} failed=${failed.length}`,
@@ -486,9 +487,8 @@ function formatDispatchOutput(
 			// Evidence confidence comes from the sealed receipt. A receipt that fails
 			// integrity cannot be read as evidence at all.
 			const verification = run.integrity.ok ? receipt.verification : UNVERIFIABLE_RECEIPT_VERIFICATION;
-			const evidenceSuffix = ` ${receiptEvidenceLabels(receipt, verification, run.integrity).join(" ")}${
-				run.integrity.ok ? "" : " evidence_verification=unknown/receipt-integrity-failed"
-			}`;
+			const trustStatus = adaptRunReceiptTrustStatus({ ...receipt, verification }, { integrity: run.integrity });
+			const evidenceSuffix = ` ${receiptEvidenceLabels(receipt, verification, run.integrity).join(" ")}`;
 			const routingSuffix =
 				run.integrity.ok && receipt.routeDecision !== undefined && receipt.routingIntent !== undefined
 					? ` route_decision=${receipt.routeDecision.decisionHash} route_mode=${receipt.routeDecision.mode}`
@@ -509,9 +509,9 @@ function formatDispatchOutput(
 						: "(worker text withheld because receipt integrity failed)";
 			return [
 				`- ${stepLabel}${receipt.runId} agent=${receipt.agentId} exit=${receipt.exitCode} target=${receipt.targetId} model=${receipt.wireModelId} tokens=${receipt.tokenCount} receipt=${receiptPath ?? "n/a"}${evidenceSuffix}${outcomeSuffix}${noteSuffix}${failure}${provenance}${routingSuffix}`,
-				`  ${workerTextLabel(verification)}`,
+				`  ${workerTextLabel(trustStatus)}`,
 				...output.split("\n").map((line) => `  ${line}`),
-				...workerTextNonEvidenceNotices(receipt, verification, answerText).map((notice) => `  ${notice}`),
+				...workerTextNonEvidenceNotices(receipt, trustStatus, answerText).map((notice) => `  ${notice}`),
 			];
 		}),
 	];
@@ -555,6 +555,7 @@ function dispatchDetails(
 			// Additive provenance keys only; folded in when the receipt carries the
 			// field so a run entry without them keeps its exact shape.
 			const provenance = extractRunProvenance(receipt);
+			const trustStatus = adaptRunReceiptTrustStatus(receipt, { integrity });
 			return {
 				runId: receipt.runId,
 				agentId: receipt.agentId,
@@ -566,6 +567,7 @@ function dispatchDetails(
 				// receipt is machine-visible here too.
 				verification: integrity.ok ? receipt.verification : UNVERIFIABLE_RECEIPT_VERIFICATION,
 				receiptIntegrity: integrity,
+				trustStatus,
 				...(receipt.outcome !== undefined && receipt.outcome !== "succeeded"
 					? { outcome: receipt.outcome, outcomeDetail: receipt.outcomeDetail ?? null }
 					: {}),

package/src/tools/dispatch.ts

@@ -25,6 +25,27 @@ export type { DispatchToolDeps } from "./dispatch-types.js";
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 
+const DispatchBudgetPhaseSchema = Type.Object(
+	{
+		toolCalls: Type.Integer({ minimum: 1 }),
+		readReserve: Type.Integer({ minimum: 0 }),
+	},
+	{ additionalProperties: false },
+);
+
+const DispatchBudgetSchema = Type.Object(
+	{
+		toolCalls: Type.Integer({ minimum: 1, description: "Requested tool-call phase boundary." }),
+		readReserve: Type.Integer({ minimum: 0, description: "Requested tail reserve for canonical read calls." }),
+		retryRevision: Type.Optional(DispatchBudgetPhaseSchema),
+	},
+	{
+		additionalProperties: false,
+		description:
+			"Invocation budget inside the recipe policy. retryRevision preauthorizes one ceiling for retry, result-contract revision, or review revision phases.",
+	},
+);
+
 /**
  * Stable, lightweight dispatch surface. Admission remains synchronous so the
  * policy decision and provisional reservation are bound to the exact argument
@@ -62,7 +83,7 @@ export function createDispatchTool(
 	return {
 		name: ToolNames.Dispatch,
 		description:
-			'Dispatch one bounded task with task, or a batch with tasks (never both). Singular example: {agent:"debugger", task:"Verify the receipt boundary", briefing:"Prior receipt evidence...", detach:true}. task is the worker assignment; briefing is separate bounded parent context/data and cannot replace task. Ordinary calls auto-wait; detach:true returns ids for monitoring/steering, and collect is the authoritative terminal batch operation before final synthesis. Batch modes are parallel (default), sequential, pipeline, or compete. Task objects may include persona and tool_profile. Sealed receipts are durable evidence; report receipt integrity, evidence verification, briefing provenance, and project-context provenance separately. Call with list:true to see agents. Do not repeat an identical successful dispatch in the same user turn. Prefer this tool over inline exploration whenever work is read-only fan-out, parallel investigation, or the operator asked for a worker by name; if you cannot dispatch, say so plainly and name the reason, and never narrate or summarize a worker you did not actually dispatch.',
+			'Dispatch one bounded task with task, or a batch with tasks (never both). Singular example: {agent:"debugger", task:"Verify the receipt boundary", briefing:"Prior receipt evidence...", detach:true}. task is the worker assignment; briefing is separate bounded parent context/data and cannot replace task. Ordinary calls auto-wait; detach:true returns ids for monitoring/steering, and collect is the authoritative terminal batch operation before final synthesis. Batch modes are parallel (default), sequential, pipeline, or compete. Task objects may include persona, tool_profile, and a recipe-admitted budget envelope. Sealed receipts are durable evidence; report receipt integrity, evidence verification, briefing provenance, and project-context provenance separately. Call with list:true to see agents. Do not repeat an identical successful dispatch in the same user turn. Prefer this tool over inline exploration whenever work is read-only fan-out, parallel investigation, or the operator asked for a worker by name; if you cannot dispatch, say so plainly and name the reason, and never narrate or summarize a worker you did not actually dispatch.',
 		parameters: Type.Object({
 			list: Type.Optional(Type.Boolean({ description: "List available agents instead of dispatching." })),
 			from_scout: Type.Optional(
@@ -105,6 +126,7 @@ export function createDispatchTool(
 							tool_profile: Type.Optional(
 								StringEnum(TOOL_PROFILE_NAMES, { description: "Narrow this worker's available tools." }),
 							),
+							budget: Type.Optional(DispatchBudgetSchema),
 							target: Type.Optional(Type.String()),
 							model: Type.Optional(Type.String()),
 							node: Type.Optional(Type.String({ description: "Fleet node pin: local or a fleet.nodes id." })),
@@ -190,6 +212,7 @@ export function createDispatchTool(
 				Type.String({ description: "Default ad-hoc specialist persona for dispatched tasks, max 8000 chars." }),
 			),
 			tool_profile: Type.Optional(StringEnum(TOOL_PROFILE_NAMES, { description: "Default worker tool profile." })),
+			budget: Type.Optional(DispatchBudgetSchema),
 			target: Type.Optional(Type.String({ description: "Default configured target id (omit for fleet default)." })),
 			model: Type.Optional(Type.String({ description: "Default model override." })),
 			node: Type.Optional(

package/src/tools/monitor.ts

@@ -2,15 +2,26 @@ import { readFileSync } from "node:fs";
 import { sleep } from "../core/timers.js";
 import { renderAgentLedgerBoard } from "../domains/dispatch/agent-ledger-store.js";
 import type { DurableAssignmentRecord } from "../domains/dispatch/assignment-store.js";
+import {
+	formatBudgetPolicy,
+	formatBudgetReasons,
+	formatBudgetRequest,
+	formatEffectiveBudget,
+} from "../domains/dispatch/budget-envelope.js";
 import type { DispatchContract } from "../domains/dispatch/contract.js";
 import { UNVERIFIABLE_RECEIPT_VERIFICATION } from "../domains/dispatch/receipt-findings.js";
-import { type ReceiptIntegrityResult, verifyReceiptIntegrity } from "../domains/dispatch/receipt-integrity.js";
+import type { ReceiptIntegrityResult } from "../domains/dispatch/receipt-integrity.js";
 import {
 	isTerminalRunEnvelope,
 	type RunEnvelope,
 	type RunReceipt,
 	type RunReceiptVerification,
 } from "../domains/dispatch/types.js";
+import {
+	adaptRunReceiptTrustStatus,
+	type CanonicalTrustStatus,
+	inspectRunReceiptTrustStatus,
+} from "../domains/evidence/trust-status.js";
 import { COST_NOT_MEASURED, costAggregateForAmount, formatCostAggregate } from "../domains/observability/index.js";
 import type { DispatchRunEventRegistry } from "./dispatch.js";
 import { monitorToolSurface } from "./monitor-surface.js";
@@ -112,6 +123,14 @@ function runStatus(deps: MonitorToolDeps, runId: string): ToolResult {
 		`started=${run.startedAt} ended=${run.endedAt ?? "n/a"} exit=${run.exitCode ?? "n/a"}`,
 		`tokens=${run.tokenCount} cost=${formatCostAggregate(costAggregateForAmount(run.costUsd, run.costProvenance)) ?? COST_NOT_MEASURED} receipt=${run.receiptPath ?? "n/a"}`,
 	];
+	if (run.budget !== undefined) {
+		lines.push(
+			`recipe policy: ${formatBudgetPolicy(run.budget)}`,
+			`requested envelope: ${formatBudgetRequest(run.budget)}`,
+			`effective envelope: ${formatEffectiveBudget(run.budget)}`,
+			`clamp or escalation reason: ${formatBudgetReasons(run.budget)}`,
+		);
+	}
 	if (live) {
 		lines.push(
 			`live: phase=${live.outcomePhase} heartbeat=${live.heartbeat} elapsed=${Math.round(live.elapsedMs / 1000)}s tokens=${live.tokens.total}`,
@@ -138,6 +157,7 @@ function runStatus(deps: MonitorToolDeps, runId: string): ToolResult {
 			tokenCount: run.tokenCount,
 			costUsd: run.costUsd,
 			costProvenance: run.costProvenance ?? "unknown",
+			budget: run.budget ?? null,
 			receiptPath: run.receiptPath,
 			running: live !== null,
 		},
@@ -333,14 +353,18 @@ function runReceipt(deps: MonitorToolDeps, runId: string): ToolResult {
 	const body = truncateUtf8(raw, RECEIPT_MAX_BYTES, `\n[receipt truncated; read ${run.receiptPath} for the rest]`);
 	let receipt: RunReceipt | null = null;
 	let receiptIntegrity: ReceiptIntegrityResult;
+	let trustStatus: CanonicalTrustStatus;
 	try {
 		receipt = JSON.parse(raw) as RunReceipt;
-		receiptIntegrity = verifyReceiptIntegrity(receipt, run);
+		const inspection = inspectRunReceiptTrustStatus(receipt, run);
+		receiptIntegrity = inspection.integrity;
+		trustStatus = inspection.status;
 	} catch (err) {
 		receiptIntegrity = {
 			ok: false,
 			reason: `receipt invalid: ${err instanceof Error ? err.message : String(err)}`,
 		};
+		trustStatus = adaptRunReceiptTrustStatus(null, { integrity: receiptIntegrity });
 	}
 	return {
 		kind: "ok",
@@ -350,6 +374,7 @@ function runReceipt(deps: MonitorToolDeps, runId: string): ToolResult {
 			runId,
 			receiptPath: run.receiptPath,
 			receiptIntegrity,
+			trustStatus,
 			...(receipt !== null && receiptIntegrity.ok
 				? {
 						evidenceVerification: receipt.verification,
@@ -366,6 +391,7 @@ interface DurableRunEvidence {
 	output: RunReceipt["output"] | null;
 	verification: RunReceiptVerification;
 	integrity: ReceiptIntegrityResult;
+	trustStatus: CanonicalTrustStatus;
 	integrityNote: string | null;
 	integrityFailure: boolean;
 }
@@ -376,6 +402,7 @@ function unavailableRunEvidence(reason: string, note: string, integrityFailure =
 		output: null,
 		verification: UNVERIFIABLE_RECEIPT_VERIFICATION,
 		integrity: { ok: false, reason },
+		trustStatus: adaptRunReceiptTrustStatus(null, { integrity: { ok: false, reason } }),
 		integrityNote: note,
 		integrityFailure,
 	};
@@ -410,29 +437,24 @@ function durableRunEvidence(run: RunEnvelope | null): DurableRunEvidence {
 			`receipt integrity unavailable: cannot read or parse ${run.receiptPath} (${detail}); worker text is unavailable and validation is unknown.`,
 		);
 	}
-	let integrity: ReceiptIntegrityResult;
-	try {
-		integrity = verifyReceiptIntegrity(receipt, run);
-	} catch (err) {
-		const detail = err instanceof Error ? err.message : String(err);
-		return unavailableRunEvidence(
-			`receipt invalid: ${detail}`,
-			`receipt integrity failed: invalid receipt (${detail}); worker text is withheld as untrusted and validation is unknown.`,
-			true,
-		);
-	}
+	const inspection = inspectRunReceiptTrustStatus(receipt, run);
+	const integrity = inspection.integrity;
 	if (!integrity.ok) {
-		return unavailableRunEvidence(
-			integrity.reason,
-			`receipt integrity failed: ${integrity.reason}; worker text is withheld as untrusted and validation is unknown.`,
-			true,
-		);
+		return {
+			...unavailableRunEvidence(
+				integrity.reason,
+				`receipt integrity failed: ${integrity.reason}; worker text is withheld as untrusted and validation is unknown.`,
+				true,
+			),
+			trustStatus: inspection.status,
+		};
 	}
 	return {
 		receipt,
 		output: receipt.output ?? null,
 		verification: receipt.verification,
 		integrity,
+		trustStatus: inspection.status,
 		integrityNote: null,
 		integrityFailure: false,
 	};
@@ -534,7 +556,7 @@ function collectRunLine(row: CollectedRunRow): string[] {
 		);
 	}
 	if (row.evidence.integrityNote) lines.push(`  ${row.evidence.integrityNote}`);
-	lines.push(`  ${workerTextLabel(row.evidence.verification)}`);
+	lines.push(`  ${workerTextLabel(row.evidence.trustStatus)}`);
 	const output = row.evidence.output;
 	if (output) {
 		const capped = truncateUtf8(output.text, COLLECT_TEXT_BYTES, "...");
@@ -543,7 +565,7 @@ function collectRunLine(row: CollectedRunRow): string[] {
 		lines.push(`  agent output${qualifier}${truncatedNote}:`, ...capped.split("\n").map((line) => `  ${line}`));
 		if (row.evidence.receipt) {
 			lines.push(
-				...workerTextNonEvidenceNotices(row.evidence.receipt, row.evidence.verification, output.text).map(
+				...workerTextNonEvidenceNotices(row.evidence.receipt, row.evidence.trustStatus, output.text).map(
 					(notice) => `  ${notice}`,
 				),
 			);
@@ -693,6 +715,7 @@ async function runCollect(
 					exitCode: row.run?.exitCode ?? null,
 					receiptPath: row.run?.receiptPath ?? null,
 					receiptIntegrity: row.evidence.integrity,
+					trustStatus: row.evidence.trustStatus,
 					evidenceVerification: row.evidence.verification,
 					briefing: row.evidence.receipt?.briefing ?? null,
 					projectContext: row.evidence.receipt?.projectContext ?? null,

package/src/tools/registry.ts

@@ -22,12 +22,14 @@ import {
 	mapAutonomy,
 } from "../domains/safety/autonomy.js";
 import type { SafetyContract, SafetyDecision } from "../domains/safety/contract.js";
+import type { DecisionPresentation } from "../domains/safety/decision-presentation.js";
 import { hashToolCall } from "../domains/safety/loop-detector.js";
 import { detectValidationCommand } from "../domains/safety/protected-artifacts.js";
 import { askUserExposure } from "./ask-user.js";
 import { type DispatchPlanView, describeDispatchPlan } from "./dispatch-plan.js";
 import type { ToolPresentationPolicy } from "./presentation.js";
-import { shapeToolResult } from "./result-shaping.js";
+import type { ToolResultDigest, ToolResultDisposition } from "./result-disposition.js";
+import { DEFAULT_TOOL_RESULT_MAX_BYTES, shapeToolResult, toolResultDigestFor } from "./result-shaping.js";
 
 /**
  * Tool registry. Admission point for every tool call. Delegates classification
@@ -56,6 +58,8 @@ export interface ToolSourceInfo {
 export interface ToolResultSizePolicy {
 	kind: "exact" | "bounded" | "summary" | "truncate";
 	maxBytes?: number;
+	/** Scratch retention ceiling for this tool; defaults to the generic 10 MiB cap. */
+	offloadMaxBytes?: number;
 	followUpHint?: string;
 }
 
@@ -68,6 +72,8 @@ export interface ToolMetadata {
 	retrySafety: ToolRetrySafety;
 	/** Expected result-size behavior at the registry boundary. */
 	resultSizePolicy: ToolResultSizePolicy;
+	/** Independent operator-presentation and model-context policy for this result. */
+	resultDisposition?: ToolResultDisposition;
 	/** Coarse cost/latency bucket for dashboard diagnostics. */
 	costLatency: ToolCostLatencyClass;
 	/**
@@ -114,6 +120,15 @@ export interface ToolSpec {
 	 * the same function at the top of `run`.
 	 */
 	prepareArguments?(args: Record<string, unknown>): Record<string, unknown>;
+	/**
+	 * Resolve an argument-sensitive canonical disposition after normalization
+	 * and before execution. The registry applies the result exactly once after
+	 * middleware has annotated the terminal result.
+	 */
+	resolveResultDisposition?(
+		args: Record<string, unknown>,
+		declared: ToolResultDisposition | undefined,
+	): ToolResultDisposition | undefined;
 	/**
 	 * Synchronous admission planner. Unlike `prepareArguments`, this runs before
 	 * safety/autonomy mapping so approval-sensitive tools can attach the exact
@@ -136,6 +151,8 @@ export type ToolResult =
 			kind: "ok";
 			output: string;
 			details?: ToolResultDetails;
+			/** Internal registry projection consumed only by the agent-tool adapter. */
+			modelContext?: string;
 			/**
 			 * Early-termination hint propagated to pi-agent-core's
 			 * `AgentToolResult.terminate`. When every finalized tool result in
@@ -145,7 +162,7 @@ export type ToolResult =
 			 */
 			terminate?: boolean;
 	  }
-	| { kind: "error"; message: string; details?: ToolResultDetails };
+	| { kind: "error"; message: string; details?: ToolResultDetails; modelContext?: string };
 
 export interface RegistryDeps {
 	safety: SafetyContract;
@@ -184,6 +201,8 @@ export interface ToolInvokeOptions {
 	correlationId?: string;
 	pendingSkillPolicy?: PendingSkillToolPolicy;
 	askUserPolicy?: AskUserToolPolicy;
+	/** Host-derived display copy for an ask_user round. It has no admission authority. */
+	decisionPresentation?: DecisionPresentation;
 	/** Registry-authenticated one-shot operator approval for this execution. */
 	approval?: { requestId: string; requestedBy: string; actionClass: ActionClass };
 	/**
@@ -243,6 +262,8 @@ export interface AskUserToolPolicy {
 	sessionId?: string;
 	turnId?: string;
 	transcriptPath?: string;
+	/** Monotonic exposure fact for live presentation and durable replay. */
+	exposure?: AutonomyExposure;
 	summary?: string;
 	rounds: AskUserTranscriptRound[];
 	decisions: AskUserTranscriptDecision[];
@@ -384,6 +405,7 @@ export function createRegistry(deps: RegistryDeps): ToolRegistry {
 		decision: SafetyDecision,
 		options?: ToolInvokeOptions,
 	): Promise<RegistryVerdict> => {
+		let resultDisposition = spec.metadata?.resultDisposition;
 		try {
 			// The hook layer is the only control stage past safety admission. Guards
 			// (loop, protected artifacts, dispatch dedup) are before_tool
@@ -402,17 +424,20 @@ export function createRegistry(deps: RegistryDeps): ToolRegistry {
 			}
 			try {
 				const preparedArgs = prepareToolArgs(spec, call.args ?? {});
-				const result = shapeToolResult(spec, await spec.run(preparedArgs, options), options);
-				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result);
-				const finalResult = shapeToolResult(spec, applyToolResultEffects(result, afterEffects), options);
+				resultDisposition = resolveToolResultDisposition(spec, preparedArgs);
+				const result = await spec.run(preparedArgs, options);
+				const digest = toolResultDigestFor(spec, result, resultDisposition);
+				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result, digest);
+				const finalResult = shapeToolResult(spec, applyToolResultEffects(result, afterEffects), options, resultDisposition);
 				return { kind: "ok", result: finalResult, decision };
 			} catch (err) {
 				const message = err instanceof Error ? err.message : String(err);
-				const result = shapeToolResult(spec, { kind: "error", message }, options);
-				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result);
+				const result: ToolResult = { kind: "error", message };
+				const digest = toolResultDigestFor(spec, result, resultDisposition);
+				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result, digest);
 				return {
 					kind: "ok",
-					result: shapeToolResult(spec, applyToolResultEffects(result, afterEffects), options),
+					result: shapeToolResult(spec, applyToolResultEffects(result, afterEffects), options, resultDisposition),
 					decision,
 				};
 			}
@@ -428,9 +453,10 @@ export function createRegistry(deps: RegistryDeps): ToolRegistry {
 		decision: SafetyDecision,
 		options: ToolInvokeOptions | undefined,
 		result?: ToolResult,
+		resultDigest?: ToolResultDigest,
 	): ReadonlyArray<MiddlewareEffect> => {
 		if (!deps.middleware) return [];
-		const input = buildToolHookInput(hook, spec, call, decision, "operating", options, result);
+		const input = buildToolHookInput(hook, spec, call, decision, "operating", options, result, resultDigest);
 		const effects = deps.middleware.runHook(input).effects;
 		try {
 			deps.onMiddlewareEffects?.(effects, input);
@@ -857,6 +883,38 @@ function prepareToolArgs(spec: ToolSpec, args: Record<string, unknown>): Record<
 	}
 }
 
+/**
+ * Resolve the argument-sensitive disposition, failing closed. A throwing
+ * resolver cannot fall back to the declared disposition: the caller may have
+ * asked for a narrower context than the tool declares, and silently restoring
+ * the declared mode would widen model context while recording the declared mode
+ * as the requested one. The failure keeps the declared presentation and applies
+ * the narrowest context instead, so the applied and recorded modes stay honest.
+ */
+function resolveToolResultDisposition(
+	spec: ToolSpec,
+	args: Record<string, unknown>,
+): ToolResultDisposition | undefined {
+	const declared = spec.metadata?.resultDisposition;
+	if (!spec.resolveResultDisposition) return declared;
+	try {
+		return spec.resolveResultDisposition(args, declared);
+	} catch (error) {
+		const maxBytes =
+			declared !== undefined && declared.context.maxBytes !== undefined
+				? declared.context.maxBytes
+				: DEFAULT_TOOL_RESULT_MAX_BYTES;
+		return {
+			presentation: declared?.presentation ?? { foldDefault: "folded", showDiffWhenFolded: false, failureExcerpt: true },
+			context: { mode: "metadata-only", maxBytes },
+			// The narrowing is recorded with the result, so a resolver bug shows up
+			// on the transcript row and in the model's header instead of reading as
+			// a deliberate metadata-only request.
+			fallback: { reason: "resolver-error", message: error instanceof Error ? error.message : String(error) },
+		};
+	}
+}
+
 function disposeAdmissionArgs(spec: ToolSpec | undefined, args: Record<string, unknown>): void {
 	try {
 		spec?.disposeAdmissionArguments?.(args);
@@ -1085,6 +1143,7 @@ function buildToolHookInput(
 	posture: string,
 	options: ToolInvokeOptions | undefined,
 	result: ToolResult | undefined,
+	resultDigest: ToolResultDigest | undefined,
 ): MiddlewareHookInput {
 	const metadata: Record<string, MiddlewareMetadataValue> = {
 		posture,
@@ -1121,6 +1180,7 @@ function buildToolHookInput(
 	};
 	if (call.args !== undefined) input.toolArgs = call.args;
 	if (result?.details !== undefined) input.toolResultDetails = result.details;
+	if (resultDigest !== undefined) input.toolResultDigest = resultDigest;
 	if (options?.runId !== undefined) input.runId = options.runId;
 	if (options?.sessionId !== undefined) input.sessionId = options.sessionId;
 	if (options?.turnId !== undefined) input.turnId = options.turnId;
@@ -1161,7 +1221,9 @@ function applyToolResultEffects(result: ToolResult, effects: ReadonlyArray<Middl
 		if (result.terminate === true) annotated.terminate = true;
 		return annotated;
 	}
-	return { kind: "error", message: `${result.message}${suffix}` };
+	const annotated: ToolResult = { kind: "error", message: `${result.message}${suffix}` };
+	if (result.details !== undefined) annotated.details = result.details;
+	return annotated;
 }
 
 function annotationMessages(effects: ReadonlyArray<MiddlewareEffect>): string[] {