@iowarp/clio-coder 0.3.2 → 0.3.4

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/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/presentation.ts

@@ -0,0 +1,107 @@
+/**
+ * Typed tool presentation policy. Answers, per tool, what the transcript's
+ * balanced (`/output default`) view needs to know: does the block open folded
+ * or expanded, does the folded row keep a mutation diff visible, and does a
+ * failed folded row carry an output excerpt.
+ *
+ * The panel must not decide any of that by tool name. It asks this module,
+ * which resolves the answer from two inputs: the registered presentation
+ * metadata for the tool (declared once here and attached to `ToolMetadata` by
+ * the builtin catalog) and the argument-sensitive resource-read rule. The
+ * lookup is a plain object read, so it stays cheap enough to call on every
+ * frame, and it needs no registry instance: the live chat panel has none.
+ *
+ * Pure module: no I/O, no registry construction, no UI imports.
+ */
+
+import { ToolNames } from "../core/tool-names.js";
+
+export type ToolFoldDefault = "expanded" | "folded";
+
+export interface ToolPresentationPolicy {
+	/** How a fresh block for this call renders before the operator touches it. */
+	foldDefault: ToolFoldDefault;
+	/**
+	 * Keep the mutation diff under the folded row. A folded `edit` that hides
+	 * what it changed tells the operator nothing they could act on; the diff is
+	 * the row's whole point and stays visible, bounded, until the body is opened.
+	 */
+	showDiffWhenFolded: boolean;
+	/**
+	 * Carry the last non-empty output line on a failed folded row. Bash pioneered
+	 * this so a failed command stays diagnosable without opening its body; every
+	 * tool that fails with text gets the same courtesy.
+	 */
+	failureExcerpt: boolean;
+}
+
+const FOLDED: ToolPresentationPolicy = { foldDefault: "folded", showDiffWhenFolded: false, failureExcerpt: true };
+const FOLDED_WITH_DIFF: ToolPresentationPolicy = {
+	foldDefault: "folded",
+	showDiffWhenFolded: true,
+	failureExcerpt: true,
+};
+
+/**
+ * Per-tool presentation declarations. Every builtin folds by default: a
+ * routine turn of six reads used to open six bodies, and the one-line row
+ * already carries the call, its outcome facts, size, and settlement. Mutations
+ * keep their diff under the folded row. Everything unlisted, including dynamic
+ * tools, folds the same way.
+ */
+export const TOOL_PRESENTATION: Readonly<Record<string, ToolPresentationPolicy>> = {
+	[ToolNames.Read]: FOLDED,
+	[ToolNames.Grep]: FOLDED,
+	[ToolNames.Find]: FOLDED,
+	[ToolNames.Ls]: FOLDED,
+	[ToolNames.CodeNav]: FOLDED,
+	[ToolNames.Context]: FOLDED,
+	[ToolNames.CredentialPresent]: FOLDED,
+	[ToolNames.Write]: FOLDED_WITH_DIFF,
+	[ToolNames.Edit]: FOLDED_WITH_DIFF,
+	[ToolNames.Bash]: FOLDED,
+	[ToolNames.Git]: FOLDED,
+	[ToolNames.Verify]: FOLDED,
+	[ToolNames.Dispatch]: FOLDED,
+	[ToolNames.Monitor]: FOLDED,
+	[ToolNames.Steer]: FOLDED,
+	[ToolNames.Tasks]: FOLDED,
+	[ToolNames.Ledger]: FOLDED,
+	[ToolNames.WebFetch]: FOLDED,
+	[ToolNames.AskUser]: FOLDED,
+	[ToolNames.Artifact]: FOLDED,
+};
+
+function readStringField(args: unknown, key: string): string | null {
+	if (typeof args !== "object" || args === null || Array.isArray(args)) return null;
+	const value = (args as Record<string, unknown>)[key];
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * Compact resource-read classification. Reads of skill/handbook/agent
+ * instruction files and docs pages collapse to one labeled line and never
+ * auto-expand; their bodies are reference material, not task output.
+ */
+export function classifyResourceRead(toolName: string, args: unknown): string | null {
+	if (toolName !== ToolNames.Read) return null;
+	const path = readStringField(args, "path");
+	if (path === null) return null;
+	const normalized = path.replace(/\\/g, "/");
+	const base = normalized.split("/").pop() ?? "";
+	if (base === "SKILL.md") return "skill";
+	if (base === "CLIO-CODER.md") return "handbook";
+	if (base === "AGENTS.md") return "agents";
+	if (/(^|\/)docs\//.test(normalized)) return "docs";
+	return null;
+}
+
+/**
+ * Resolve the presentation policy for one call. Argument-sensitive rules win
+ * over the per-tool declaration because a resource read is a property of the
+ * path, not of the `read` tool.
+ */
+export function toolPresentationPolicy(toolName: string, args: unknown): ToolPresentationPolicy {
+	if (classifyResourceRead(toolName, args) !== null) return FOLDED;
+	return TOOL_PRESENTATION[toolName] ?? FOLDED;
+}

package/src/tools/registry.ts

@@ -26,7 +26,9 @@ 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 { shapeToolResult } from "./result-shaping.js";
+import type { ToolPresentationPolicy } from "./presentation.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
@@ -55,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;
 }
 
@@ -67,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;
 	/**
@@ -76,6 +82,11 @@ export interface ToolMetadata {
 	 * need none; the schema description covers them.
 	 */
 	promptHint?: string;
+	/**
+	 * How transcript surfaces present this tool's block under `/output default`.
+	 * Optional: tools that declare nothing fold like every other tool.
+	 */
+	presentation?: ToolPresentationPolicy;
 }
 
 export interface ToolSpec {
@@ -108,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
@@ -130,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
@@ -139,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;
@@ -378,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
@@ -396,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,
 				};
 			}
@@ -851,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);
@@ -1155,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[] {