@iowarp/clio-coder 0.3.3 → 0.3.4

package/src/tools/monitor.ts

@@ -4,13 +4,18 @@ import { renderAgentLedgerBoard } from "../domains/dispatch/agent-ledger-store.j
 import type { DurableAssignmentRecord } from "../domains/dispatch/assignment-store.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";
@@ -333,14 +338,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 +359,7 @@ function runReceipt(deps: MonitorToolDeps, runId: string): ToolResult {
 			runId,
 			receiptPath: run.receiptPath,
 			receiptIntegrity,
+			trustStatus,
 			...(receipt !== null && receiptIntegrity.ok
 				? {
 						evidenceVerification: receipt.verification,
@@ -366,6 +376,7 @@ interface DurableRunEvidence {
 	output: RunReceipt["output"] | null;
 	verification: RunReceiptVerification;
 	integrity: ReceiptIntegrityResult;
+	trustStatus: CanonicalTrustStatus;
 	integrityNote: string | null;
 	integrityFailure: boolean;
 }
@@ -376,6 +387,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 +422,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 +541,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 +550,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 +700,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

@@ -27,7 +27,8 @@ import { detectValidationCommand } from "../domains/safety/protected-artifacts.j
 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 { ToolResultDisposition } from "./result-disposition.js";
+import { DEFAULT_TOOL_RESULT_MAX_BYTES, shapeToolResult } from "./result-shaping.js";
 
 /**
  * Tool registry. Admission point for every tool call. Delegates classification
@@ -56,6 +57,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 +71,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 +119,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 +150,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 +161,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;
@@ -384,6 +400,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 +419,18 @@ export function createRegistry(deps: RegistryDeps): ToolRegistry {
 			}
 			try {
 				const preparedArgs = prepareToolArgs(spec, call.args ?? {});
-				const result = shapeToolResult(spec, await spec.run(preparedArgs, options), options);
+				resultDisposition = resolveToolResultDisposition(spec, preparedArgs);
+				const result = await spec.run(preparedArgs, options);
 				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result);
-				const finalResult = shapeToolResult(spec, applyToolResultEffects(result, afterEffects), options);
+				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 result: ToolResult = { kind: "error", message };
 				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result);
 				return {
 					kind: "ok",
-					result: shapeToolResult(spec, applyToolResultEffects(result, afterEffects), options),
+					result: shapeToolResult(spec, applyToolResultEffects(result, afterEffects), options, resultDisposition),
 					decision,
 				};
 			}
@@ -857,6 +875,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);
@@ -1161,7 +1211,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[] {