@iowarp/clio-coder 0.3.4 → 0.3.6

package/src/tools/agent-tools.ts

@@ -22,6 +22,7 @@ import { type SkillActivation, skillActivationFromToolDetails } from "../core/sk
 import type { ToolName } from "../core/tool-names.js";
 import { ToolNames } from "../core/tool-names.js";
 import type { ResolvedRuntimeTarget } from "../domains/providers/index.js";
+import { type CallActionDescriptor, describeCallAction } from "../domains/safety/call-target.js";
 import type { SafetyDecision } from "../domains/safety/contract.js";
 import { formatModelRejection } from "../domains/safety/rejection-feedback.js";
 import { validateEngineToolArguments } from "../engine/ai.js";
@@ -45,6 +46,12 @@ export type ToolOutcome = "ok" | "error" | "blocked";
 
 export interface ToolStartEvent {
 	tool: string;
+	/**
+	 * The engine's id for this call, when the producer has one. New producers
+	 * put the same id on start and finish so concurrent calls of one tool remain
+	 * independently attributable. Optional for direct callers and old streams.
+	 */
+	toolCallId?: string;
 	posture: "operating";
 	/**
 	 * Wall-clock anchor for the instant the call began, for a human correlating
@@ -53,6 +60,14 @@ export interface ToolStartEvent {
 	 * event is measured on that process's monotonic clock instead.
 	 */
 	startedAt: number;
+	/**
+	 * What this call is doing, as a bounded redacted descriptor composed here
+	 * where the arguments are trusted. This is the only account of a worker's
+	 * arguments that may cross the NDJSON stdout seam; the arguments themselves
+	 * never do, so an operator surface reads a verb and an object it can show,
+	 * never an argument object it would have to sanitize itself.
+	 */
+	action?: CallActionDescriptor;
 }
 
 export interface ToolFinishEvent {
@@ -130,11 +145,21 @@ async function runValidatedToolCall(input: RunValidatedToolCallInput): Promise<W
 	// spans the call, so `durationMs` survives a clock correction mid-tool.
 	const startedAt = Date.now();
 	const startedAtClock = performance.now();
-	telemetry?.onStart?.({ tool: spec.name, posture: "operating", startedAt });
-	// Stamped onto every finish event so a consumer can join this authoritative
-	// outcome to the engine's `tool_execution_end` for the same call.
+	// Stamped onto both lifecycle events so a concurrent finish resolves only
+	// the start for its own engine call. Direct callers may legitimately omit it.
 	const callId = input.invokeOptions?.toolCallId;
 	const withCallId = callId === undefined ? {} : { toolCallId: callId };
+	// The one seam that holds validated arguments and publishes telemetry, so it
+	// is where the redacted descriptor is composed. Everything downstream of here
+	// sees the descriptor and never the arguments.
+	const action = describeCallAction(spec.name, args);
+	telemetry?.onStart?.({
+		tool: spec.name,
+		...withCallId,
+		posture: "operating",
+		startedAt,
+		...(action !== null ? { action } : {}),
+	});
 	const invokeOpts: ToolInvokeOptions = {};
 	if (input.invokeOptions) Object.assign(invokeOpts, input.invokeOptions);
 	if (signal) invokeOpts.signal = signal;

package/src/tools/ask-user.ts

@@ -5,6 +5,7 @@ import { Type } from "typebox";
 import { ToolNames } from "../core/tool-names.js";
 import { clioStateDir } from "../core/xdg.js";
 import { type AutonomyExposure, DEFAULT_AUTONOMY_EXPOSURE } from "../domains/safety/autonomy.js";
+import { classifyDecisionPresentation, decisionFactsForAnswer } from "../domains/safety/decision-presentation.js";
 import { StringEnum } from "../engine/ai.js";
 import type {
 	AskUserToolPolicy,
@@ -57,6 +58,7 @@ export interface AskUserResult {
 
 export interface AskUserCall {
 	action: AskUserAction;
+	exposure?: AutonomyExposure;
 	mode?: AskUserMode;
 	questions?: AskUserQuestion[];
 	decisions?: AskUserDecision[];
@@ -284,6 +286,7 @@ export function normalizeAskUserCall(args: Record<string, unknown>): { call?: As
 	return {
 		call: {
 			action: "ask",
+			exposure: exposure.exposure ?? DEFAULT_AUTONOMY_EXPOSURE,
 			...(mode.mode ? { mode: mode.mode } : {}),
 			questions: questions.questions,
 			...(summary ? { summary } : {}),
@@ -319,6 +322,7 @@ function createStandalonePolicy(options?: ToolInvokeOptions): AskUserToolPolicy
 		updatedAt: now,
 		...(options?.sessionId ? { sessionId: options.sessionId } : {}),
 		...(options?.turnId ? { turnId: options.turnId } : {}),
+		exposure: DEFAULT_AUTONOMY_EXPOSURE,
 		rounds: [],
 		decisions: [],
 		inFlight: false,
@@ -335,6 +339,13 @@ function hydratePolicy(policy: AskUserToolPolicy, options?: ToolInvokeOptions):
 	if (options?.turnId && !policy.turnId) policy.turnId = options.turnId;
 }
 
+/** Once an interview is outward, a later local round cannot lower its replay tier. */
+function mergePolicyExposure(policy: AskUserToolPolicy, exposure: AutonomyExposure): AutonomyExposure {
+	const merged = policy.exposure === "outward" || exposure === "outward" ? "outward" : "local";
+	policy.exposure = merged;
+	return merged;
+}
+
 function transcriptQuestions(questions: ReadonlyArray<AskUserQuestion>): AskUserTranscriptQuestion[] {
 	return questions.map((question) => ({
 		question: question.question,
@@ -455,6 +466,7 @@ async function persistAskUserTranscript(
 			...(policy.endedAt ? { endedAt: policy.endedAt } : {}),
 			...(policy.sessionId ? { sessionId: policy.sessionId } : {}),
 			...(policy.turnId ? { turnId: policy.turnId } : {}),
+			exposure: policy.exposure ?? DEFAULT_AUTONOMY_EXPOSURE,
 			...(policy.summary ? { summary: policy.summary } : {}),
 			decisions: policy.decisions,
 			rounds: policy.rounds,
@@ -478,6 +490,7 @@ function compactInterview(
 		rounds: policy.rounds.length,
 		max_rounds: policy.maxCalls,
 		transcript_path: policy.transcriptPath ?? null,
+		exposure: policy.exposure ?? DEFAULT_AUTONOMY_EXPOSURE,
 		latest_answers: latestAnswers,
 		decisions: policy.decisions,
 		...(policy.summary ? { summary: policy.summary } : {}),
@@ -591,6 +604,7 @@ export function createAskUserTool(deps: AskUserToolDeps = {}): ToolSpec {
 				return completeInterview(policy, "complete", options, call.summary, call.decisions ?? []);
 			}
 			const questions = call.questions ?? [];
+			const exposure = mergePolicyExposure(policy, call.exposure ?? DEFAULT_AUTONOMY_EXPOSURE);
 			if (call.max_rounds !== undefined) {
 				const nextLimit = policy.callCount === 0 ? call.max_rounds : Math.max(policy.maxCalls, call.max_rounds);
 				policy.maxCalls = Math.max(nextLimit, policy.callCount + 1);
@@ -632,7 +646,13 @@ export function createAskUserTool(deps: AskUserToolDeps = {}): ToolSpec {
 			if (call.summary) policy.summary = call.summary;
 			const handler = deps.askUser ?? defaultAskUserHandler;
 			try {
-				const result = normalizeAskUserResult(questions, await handler(questions, options));
+				const result = normalizeAskUserResult(
+					questions,
+					await handler(questions, {
+						...options,
+						decisionPresentation: classifyDecisionPresentation(decisionFactsForAnswer(exposure)),
+					}),
+				);
 				const answeredAt = new Date().toISOString();
 				policy.callCount += 1;
 				policy.askedQuestionKeys.add(key);

package/src/tools/context/index.ts

@@ -168,7 +168,7 @@ function policyIsRecipeBound(policy: { requests: ReadonlyArray<{ source: string
 // load it (only the operator activates), so its move is suggest-and-wait.
 const NO_PENDING_SKILL_DENIAL =
 	"context: no pending skill request is active this turn; only the operator can activate a skill, so do not retry this load. " +
-	`If a listed skill matches the task, open your reply with the line \`${SKILL_SUGGESTION_ANCHOR}\` and wait for the operator to run it; otherwise continue without skills.`;
+	`If a listed skill matches the task, open your reply with the line \`${SKILL_SUGGESTION_ANCHOR}\` and continue the task without it; only the operator can run it. Otherwise continue without skills.`;
 
 function pendingSkillPolicyError(name: string, options: ToolInvokeOptions | undefined): string | null {
 	const policy = options?.pendingSkillPolicy;
@@ -287,7 +287,7 @@ function renderSkillsList(
 	// template where they skip conditional prose in the header.
 	lines.push(
 		"",
-		`If one skill above matches the current task, begin your reply with the line \`${SKILL_SUGGESTION_ANCHOR}\` (a comma-separated sequence, in order, when several compose) and wait for the operator to run it. If none match, do not mention skills.`,
+		`If one skill above matches the current task, begin your reply with the line \`${SKILL_SUGGESTION_ANCHOR}\` (a comma-separated sequence, in order, when several compose), then continue the task in the same turn without it; only the operator can run it. If none match, do not mention skills.`,
 	);
 	return lines.join("\n");
 }

package/src/tools/dispatch-arguments.ts

@@ -2,6 +2,7 @@
 
 import type { AgentAutomationAuthority } from "../domains/agents/spec.js";
 import { type AgentTaskType, classifyAgentTask } from "../domains/dispatch/agent-candidates.js";
+import { cloneDispatchBudgetRequest } from "../domains/dispatch/budget-envelope.js";
 import type { DispatchRequest } from "../domains/dispatch/contract.js";
 import { type AgentRoleFactsResolver, requestExecutionRole } from "../domains/dispatch/execution-role.js";
 import { parseRoutingIntent } from "../domains/dispatch/routing-intent.js";
@@ -171,6 +172,13 @@ function dispatchRequestFromArgs(
 		}
 		request.thinkingLevel = thinkingLevel as JobThinkingLevel;
 	}
+	if (args.budget !== undefined) {
+		try {
+			request.budget = cloneDispatchBudgetRequest(args.budget);
+		} catch (error) {
+			return { ok: false, message: error instanceof Error ? error.message : String(error) };
+		}
+	}
 	return { ok: true, request };
 }
 

package/src/tools/dispatch-event-text.ts

@@ -1,6 +1,25 @@
+import { responseModelIdObservationFromRecord } from "../core/response-model-id.js";
 import { durableAssistantTextFromEvent } from "../domains/dispatch/event-pump.js";
+import type { RunReceipt } from "../domains/dispatch/types.js";
 
 /** Return the durable final assistant text carried by a worker event. */
 export function assistantTextFromEvent(event: unknown): string {
 	return durableAssistantTextFromEvent(event).trim();
 }
+
+/** Human projection of the response model-id observations carried by a receipt. */
+export function receiptResponseModelIdObservationLabel(receipt: Pick<RunReceipt, "upstreamResponses">): string | null {
+	const responses = receipt.upstreamResponses ?? [];
+	if (responses.length === 0) return null;
+	const labels = responses.map((response) => {
+		const observation = responseModelIdObservationFromRecord(
+			response as unknown as Record<string, unknown>,
+			"legacy-difference-only",
+		);
+		if (observation.state === "reported") return `reported:${observation.reportedModelId}`;
+		if (observation.state === "not-reported") return "not-reported";
+		if (observation.state === "not-observed") return "not-observed";
+		return `legacy-difference-only:${observation.differingModelId ?? "none"}`;
+	});
+	return `response_model_id_observation=${labels.join(",")}`;
+}

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,6 +2,12 @@ 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 } from "../domains/dispatch/receipt-integrity.js";
@@ -117,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}`,
@@ -143,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,
 		},

package/src/tools/registry.ts

@@ -22,13 +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 type { ToolResultDisposition } from "./result-disposition.js";
-import { DEFAULT_TOOL_RESULT_MAX_BYTES, 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
@@ -200,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 };
 	/**
@@ -259,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[];
@@ -421,13 +426,15 @@ export function createRegistry(deps: RegistryDeps): ToolRegistry {
 				const preparedArgs = prepareToolArgs(spec, call.args ?? {});
 				resultDisposition = resolveToolResultDisposition(spec, preparedArgs);
 				const result = await spec.run(preparedArgs, options);
-				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result);
+				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: ToolResult = { kind: "error", message };
-				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result);
+				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, resultDisposition),
@@ -446,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);
@@ -1135,6 +1143,7 @@ function buildToolHookInput(
 	posture: string,
 	options: ToolInvokeOptions | undefined,
 	result: ToolResult | undefined,
+	resultDigest: ToolResultDigest | undefined,
 ): MiddlewareHookInput {
 	const metadata: Record<string, MiddlewareMetadataValue> = {
 		posture,
@@ -1171,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;

package/src/tools/result-disposition.ts

@@ -52,6 +52,23 @@ export interface ToolResultSummaryProvenance {
 	redactions?: number;
 }
 
+export const TOOL_RESULT_DIGEST_MAX_BYTES = 240;
+
+export interface ToolResultDigestProvenance {
+	producer: "code";
+	source: "canonical-result-disposition" | "legacy-fallback";
+	algorithm: "redacted-context-digest-v1" | "redacted-legacy-digest-v1";
+	contextMode?: AppliedToolResultContextMode;
+	summaryAlgorithm?: ToolResultSummaryProvenance["algorithm"];
+	redactions?: number;
+}
+
+/** A bounded diagnostic that is safe to pass to task memory. */
+export interface ToolResultDigest {
+	text: string;
+	provenance: ToolResultDigestProvenance;
+}
+
 export interface ToolResultDispositionMetadata {
 	version: 1;
 	applications: 1;
@@ -223,6 +240,14 @@ function capUtf8(text: string, maxBytes: number): string {
 	return byteLength(text) <= maxBytes ? text : utf8Prefix(text, maxBytes);
 }
 
+function capDigestUtf8(text: string, maxBytes: number): string {
+	if (byteLength(text) <= maxBytes) return text;
+	const marker = "…";
+	const markerBytes = byteLength(marker);
+	if (markerBytes >= maxBytes) return utf8Prefix(text, maxBytes);
+	return `${utf8Prefix(text, maxBytes - markerBytes).trimEnd()}${marker}`;
+}
+
 /** A deterministic, UTF-8-safe excerpt whose total bytes never exceed maxBytes. */
 function boundedToolResultExcerpt(text: string, maxBytes: number, bias: ToolResultExcerptBias = "head-tail"): string {
 	if (maxBytes <= 0) return "";
@@ -504,6 +529,137 @@ export function projectToolResultContext(input: ProjectToolResultContextInput):
 	};
 }
 
+const DIGEST_FACT_KEYS = [
+	"outcome",
+	"exitCode",
+	"timedOut",
+	"aborted",
+	"outputCapped",
+	"signal",
+	"status",
+	"error",
+	"decision",
+	"next",
+] as const;
+
+function digestFactText(details: ToolResultDetails | undefined): string {
+	if (details === undefined) return "";
+	const facts: string[] = [];
+	for (const key of DIGEST_FACT_KEYS) {
+		if (details[key] !== undefined) facts.push(`${key}=${stableJson(details[key])}`);
+	}
+	return facts.join(" ");
+}
+
+function projectionBody(input: ProjectToolResultContextInput, projection: ToolResultContextProjection): string {
+	if (projection.appliedMode === "metadata-only") return "";
+	if (projection.appliedMode === "full") {
+		const trailer = fullTrailer(input);
+		return trailer.length > 0 && projection.text.endsWith(`\n\n${trailer}`)
+			? projection.text.slice(0, -(trailer.length + 2))
+			: projection.text;
+	}
+	const header = contextHeader(input, projection.appliedMode, projection.truncated, projection.summaryProvenance);
+	const prefix = `${header}\n`;
+	return projection.text.startsWith(prefix) ? projection.text.slice(prefix.length) : "";
+}
+
+function digestText(
+	status: string,
+	facts: string,
+	body: string,
+	redactions: number,
+	maxBytes: number,
+): { text: string; redactions: number } {
+	const tally = createRedactionTally();
+	const safeStatus = redactSecretsText(status, tally);
+	const safeFacts = redactSecretsText(facts, tally);
+	const statusAndFacts = [safeStatus, safeFacts].filter((value) => value.length > 0).join(" ");
+	const bodyBudget = Math.max(0, maxBytes - byteLength(statusAndFacts) - 2);
+	const selected = deterministicDiagnosticSummary(body, bodyBudget, true);
+	const candidate = [statusAndFacts, selected.text.replace(/\s+/gu, " ").trim()]
+		.filter((value) => value.length > 0)
+		.join("; ");
+	return {
+		text: capDigestUtf8(candidate, maxBytes),
+		redactions: redactions + tally.count + selected.redactions,
+	};
+}
+
+/**
+ * Reuse the applied model-context projection as task memory's diagnostic
+ * source. Metadata-only never contributes captured content, and bounded or
+ * summarized modes contribute only the body admitted by that projection.
+ */
+export function deterministicToolResultDigest(
+	input: ProjectToolResultContextInput,
+	maxBytes = TOOL_RESULT_DIGEST_MAX_BYTES,
+): ToolResultDigest {
+	const projection = projectToolResultContext(input);
+	const status = [
+		`kind=${input.kind}`,
+		`mode=${projection.appliedMode}`,
+		`truncated=${String(projection.truncated)}`,
+		...(projection.appliedMode === "metadata-only" || projection.truncated
+			? [`capturedBytes=${input.capturedBytes}`]
+			: []),
+	].join(" ");
+	const digest = digestText(
+		status,
+		digestFactText(input.details),
+		projectionBody(input, projection),
+		projection.summaryProvenance?.redactions ?? 0,
+		Math.max(1, Math.floor(maxBytes)),
+	);
+	return {
+		text: digest.text,
+		provenance: {
+			producer: "code",
+			source: "canonical-result-disposition",
+			algorithm: "redacted-context-digest-v1",
+			contextMode: projection.appliedMode,
+			...(projection.summaryProvenance === undefined ? {} : { summaryAlgorithm: projection.summaryProvenance.algorithm }),
+			...(digest.redactions > 0 ? { redactions: digest.redactions } : {}),
+		},
+	};
+}
+
+/** Deterministic compatibility path for results without a canonical disposition. */
+export function legacyToolResultDigest(
+	text: string,
+	options: { outcome: "ok" | "error"; maxBytes?: number },
+): ToolResultDigest {
+	const maxBytes = Math.max(1, Math.floor(options.maxBytes ?? TOOL_RESULT_DIGEST_MAX_BYTES));
+	const fallback = options.outcome === "error" && text.trim().length === 0 ? "an unknown tool error" : text;
+	const digest = digestText("", "", fallback, 0, maxBytes);
+	return {
+		text: digest.text,
+		provenance: {
+			producer: "code",
+			source: "legacy-fallback",
+			algorithm: "redacted-legacy-digest-v1",
+			...(digest.redactions > 0 ? { redactions: digest.redactions } : {}),
+		},
+	};
+}
+
+/** Reapply the memory boundary's redaction and byte cap to a supplied digest. */
+export function sanitizeToolResultDigest(
+	digest: ToolResultDigest,
+	maxBytes = TOOL_RESULT_DIGEST_MAX_BYTES,
+): ToolResultDigest {
+	const tally = createRedactionTally();
+	const safe = redactSecretsText(digest.text, tally).replace(/\s+/gu, " ").trim();
+	const redactions = (digest.provenance.redactions ?? 0) + tally.count;
+	return {
+		text: capDigestUtf8(safe, Math.max(1, Math.floor(maxBytes))),
+		provenance: {
+			...digest.provenance,
+			...(redactions > 0 ? { redactions } : {}),
+		},
+	};
+}
+
 /** The text inserted into the provider conversation for a registry result. */
 export function toolResultContextText(result: ToolResult): string {
 	if (result.modelContext !== undefined) return result.modelContext;

package/src/tools/result-shaping.ts

@@ -1,11 +1,14 @@
 import { createHash } from "node:crypto";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, readdirSync, rmdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { clioStateDir } from "../core/xdg.js";
 import type { ToolInvokeOptions, ToolResult, ToolResultDetails, ToolSpec } from "./registry.js";
 import {
+	deterministicToolResultDigest,
+	legacyToolResultDigest,
 	normalizeToolResultDisposition,
 	projectToolResultContext,
+	type ToolResultDigest,
 	type ToolResultDisposition,
 	type ToolResultDispositionFallback,
 	type ToolResultDispositionMetadata,
@@ -21,6 +24,7 @@ export const DEFAULT_TOOL_RESULT_MAX_BYTES = DEFAULT_MAX_BYTES + 2 * 1024;
 const RESULT_TRUNCATION_MARKER = "\n[tool result truncated]";
 const RESULT_OFFLOAD_MAX_BYTES = 10 * 1024 * 1024;
 const TAIL_NOTICE_RESERVE_BYTES = 512;
+export const TOOL_OFFLOAD_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
 
 type ToolResultShapeContext = Pick<ToolInvokeOptions, "sessionId" | "toolCallId">;
 
@@ -49,6 +53,34 @@ function offloadMaxBytesFor(spec: ToolSpec): number {
 		: RESULT_OFFLOAD_MAX_BYTES;
 }
 
+/**
+ * Build the task-memory diagnostic from the same normalized disposition that
+ * will shape model context. Legacy tools use the explicit compatibility path.
+ */
+export function toolResultDigestFor(
+	spec: ToolSpec,
+	result: ToolResult,
+	requestedDisposition?: ToolResultDisposition,
+): ToolResultDigest {
+	const text = resultText(result);
+	const disposition = normalizeToolResultDisposition(spec, maxBytesFor(spec), requestedDisposition);
+	if (disposition === null) {
+		const projected = shapeLegacyToolResult(spec, result);
+		return legacyToolResultDigest(resultText(projected), { outcome: result.kind });
+	}
+	const capturedBytes = capturedBytesFor(result, text);
+	return deterministicToolResultDigest({
+		text,
+		kind: result.kind,
+		details: result.details,
+		disposition,
+		capturedBytes,
+		displayedBytes: Math.min(capturedBytes, disposition.presentation.maxBytes),
+		offloadPath: existingOffloadPath(result.details),
+		followUpHint: followUpHint(spec),
+	});
+}
+
 function detailsRecord(details: ToolResultDetails | undefined, key: string): Record<string, unknown> | null {
 	const candidate = details?.[key];
 	return candidate !== null && typeof candidate === "object" && !Array.isArray(candidate)
@@ -91,6 +123,32 @@ function offloadBody(text: string, bytes: number, maxBytes: number): string {
 	return `${truncateUtf8(text, Math.max(0, prefixBudget), "")}${notice}`;
 }
 
+/** Remove regular offload files older than the boot retention cap. */
+export function sweepExpiredToolOffloads(now = Date.now()): number {
+	const root = join(clioStateDir(), "scratch");
+	const cutoff = now - TOOL_OFFLOAD_MAX_AGE_MS;
+	let removed = 0;
+	try {
+		for (const session of readdirSync(root, { withFileTypes: true })) {
+			if (!session.isDirectory()) continue;
+			const sessionDir = join(root, session.name);
+			for (const entry of readdirSync(sessionDir, { withFileTypes: true })) {
+				if (!entry.isFile()) continue;
+				const path = join(sessionDir, entry.name);
+				try {
+					if (statSync(path).mtimeMs >= cutoff) continue;
+					rmSync(path, { force: true });
+					removed += 1;
+				} catch {}
+			}
+			try {
+				if (readdirSync(sessionDir).length === 0) rmdirSync(sessionDir);
+			} catch {}
+		}
+	} catch {}
+	return removed;
+}
+
 /**
  * Persist the full text of a tool result to a per-session scratch file and
  * return its path (or null if the write fails). Self-shaping callers use this