@iowarp/clio-coder 0.3.2 → 0.3.4

package/src/tools/agent-tools.ts

@@ -28,6 +28,7 @@ import { validateEngineToolArguments } from "../engine/ai.js";
 import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "../engine/types.js";
 import { applyToolProfile, type ToolProfileName } from "./profiles.js";
 import type { ToolInvokeOptions, ToolRegistry, ToolResult, ToolSpec } from "./registry.js";
+import { isDispositionedToolResultError, toolResultContextText } from "./result-disposition.js";
 
 /**
  * Lightweight per-call observability hook. Default no-op so unused
@@ -99,10 +100,10 @@ type WorkerToolOkDetails = { kind: "ok" } & Record<string, unknown>;
 function projectToolResult(result: ToolResult): WorkerAgentToolResult {
 	const details = { ...(result.details ?? {}), kind: result.kind } as { kind: "ok" } | { kind: "error" };
 	if (result.kind === "error") {
-		return { content: [{ type: "text", text: result.message }], details };
+		return { content: [{ type: "text", text: toolResultContextText(result) }], details };
 	}
 	return {
-		content: [{ type: "text", text: result.output }],
+		content: [{ type: "text", text: toolResultContextText(result) }],
 		details,
 		...(result.terminate === true ? { terminate: true } : {}),
 	};
@@ -119,6 +120,8 @@ interface RunValidatedToolCallInput {
 	signal?: AbortSignal;
 	telemetry?: ToolTelemetry;
 	invokeOptions?: Partial<ToolInvokeOptions>;
+	/** Agent loops can preserve canonical failure envelopes and classify them after execution. */
+	returnDispositionedErrors?: boolean;
 }
 
 async function runValidatedToolCall(input: RunValidatedToolCallInput): Promise<WorkerAgentToolResult> {
@@ -183,13 +186,16 @@ async function runValidatedToolCall(input: RunValidatedToolCallInput): Promise<W
 			reason: verdict.result.message,
 			decision: verdict.decision,
 		});
-		throw new Error(verdict.result.message);
+		if (input.returnDispositionedErrors === true && isDispositionedToolResultError(verdict.result)) {
+			return projectToolResult(verdict.result);
+		}
+		throw new Error(toolResultContextText(verdict.result));
 	}
 	const toolDetails = isRecord(verdict.result.details) ? verdict.result.details : {};
 	const skillActivation =
 		spec.name === ToolNames.Context ? skillActivationFromToolDetails(toolDetails, input.invokeOptions?.turnId) : null;
 	const result: AgentToolResult<WorkerToolOkDetails> = {
-		content: [{ type: "text", text: verdict.result.output }],
+		content: [{ type: "text", text: toolResultContextText(verdict.result) }],
 		details: { ...toolDetails, kind: "ok" },
 	};
 	if (verdict.result.terminate === true) {
@@ -291,6 +297,7 @@ function toAgentTool(
 				spec,
 				args: params as Record<string, unknown>,
 				registry,
+				returnDispositionedErrors: true,
 			};
 			if (signal) callInput.signal = signal;
 			if (telemetry) callInput.telemetry = telemetry;

package/src/tools/bash.ts

@@ -3,87 +3,124 @@ import { BASH_HARD_CAP_BYTES, combineBashOutput, runBashCommand } from "../core/
 import { resolveSafeCwd } from "../core/safe-exec.js";
 import { ToolNames } from "../core/tool-names.js";
 import { expandPath } from "./path-utils.js";
-import type { ToolInvokeOptions, ToolResult, ToolResultDetails, ToolSpec } from "./registry.js";
-import { writeToolOffload } from "./result-shaping.js";
-import { DEFAULT_MAX_LINES, formatSize, truncateTail } from "./truncate.js";
+import { toolPresentationPolicy } from "./presentation.js";
+import type { ToolResult, ToolResultDetails, ToolSpec } from "./registry.js";
+import {
+	deterministicDiagnosticSummary,
+	type NormalizedToolResultDisposition,
+	type ToolResultContextDisposition,
+	type ToolResultDisposition,
+} from "./result-disposition.js";
+import { DEFAULT_MAX_LINES, truncateTail } from "./truncate.js";
+import { byteLength } from "./truncate-utf8.js";
 
-// What the model sees inline. The tail is where the failing assertion, compiler
-// error, and exit summary live, so we keep the LAST lines/bytes. The full
-// output is spilled to an offload file before truncating, so nothing is lost.
+// The registry's bounded model projection and operator presentation share this
+// cap. Both are tail-biased for Bash because diagnostics usually land last.
 const BASH_DISPLAY_MAX_BYTES = 16 * 1024;
-// Slack reserved so the continuation notice appended after truncation still
-// fits under the registry's per-tool bash budget without a second (head-first)
-// re-truncation cutting the tail we just preserved.
-const BASH_TAIL_NOTE_RESERVE = 512;
+export type BashOutputPolicy = "full" | "bounded" | "summary" | "metadata-only";
 
-interface ShapedBashOutput {
-	text: string;
-	details?: ToolResultDetails;
+const BASH_OUTPUT_POLICIES = new Set<BashOutputPolicy>(["full", "bounded", "summary", "metadata-only"]);
+
+function bashContextDisposition(policy: BashOutputPolicy): ToolResultContextDisposition & { maxBytes: number } {
+	if (policy === "full") {
+		return { mode: "full", maxBytes: BASH_DISPLAY_MAX_BYTES, downgradeExcerpt: "tail" };
+	}
+	if (policy === "summary") {
+		return {
+			mode: "summary",
+			maxBytes: BASH_DISPLAY_MAX_BYTES,
+			strategy: "diagnostic",
+			redact: true,
+		};
+	}
+	if (policy === "metadata-only") return { mode: "metadata-only", maxBytes: BASH_DISPLAY_MAX_BYTES };
+	return { mode: "bounded", maxBytes: BASH_DISPLAY_MAX_BYTES, excerpt: "tail" };
+}
+
+/** Canonical default attached by the builtin catalog and reused by direct registries. */
+export const BASH_DEFAULT_RESULT_DISPOSITION: ToolResultDisposition = {
+	presentation: {
+		...toolPresentationPolicy(ToolNames.Bash, undefined),
+		maxBytes: BASH_DISPLAY_MAX_BYTES,
+		overflow: "tail",
+	},
+	context: bashContextDisposition("bounded"),
+};
+
+/** Pure, idempotent normalization used by registry admission and direct calls. */
+export function normalizeBashArguments(args: Record<string, unknown>): Record<string, unknown> {
+	return args.output_policy === undefined ? { ...args, output_policy: "bounded" } : args;
+}
+
+function bashOutputPolicy(args: Record<string, unknown>): BashOutputPolicy | null {
+	const value = args.output_policy;
+	return typeof value === "string" && BASH_OUTPUT_POLICIES.has(value as BashOutputPolicy)
+		? (value as BashOutputPolicy)
+		: null;
+}
+
+function resolveBashResultDisposition(
+	args: Record<string, unknown>,
+	declared: ToolResultDisposition | undefined = BASH_DEFAULT_RESULT_DISPOSITION,
+): ToolResultDisposition {
+	const policy = bashOutputPolicy(args) ?? "bounded";
+	const base = declared ?? BASH_DEFAULT_RESULT_DISPOSITION;
+	return { presentation: base.presentation, context: bashContextDisposition(policy) };
+}
+
+function normalizedBashDisposition(policy: BashOutputPolicy): NormalizedToolResultDisposition {
+	return {
+		presentation: { ...BASH_DEFAULT_RESULT_DISPOSITION.presentation, maxBytes: BASH_DISPLAY_MAX_BYTES },
+		context: bashContextDisposition(policy),
+	};
 }
 
 /** Bound a cumulative live snapshot without writing an offload file per tick. */
-function shapeBashProgress(rawOutput: string): ToolResult {
-	const truncation = truncateTail(rawOutput, {
-		maxLines: DEFAULT_MAX_LINES,
-		maxBytes: BASH_DISPLAY_MAX_BYTES - BASH_TAIL_NOTE_RESERVE,
-	});
-	const bytes = Buffer.byteLength(rawOutput, "utf8");
+function shapeBashProgress(rawOutput: string, outputBytes: number, policy: BashOutputPolicy): ToolResult {
+	const disposition = normalizedBashDisposition(policy);
+	let output: string;
+	if (policy === "metadata-only") {
+		output = `bash: running; captured ${outputBytes} bytes; stdout/stderr omitted by metadata-only policy`;
+	} else if (policy === "summary") {
+		output = deterministicDiagnosticSummary(rawOutput, BASH_DISPLAY_MAX_BYTES, true).text;
+	} else {
+		output = truncateTail(rawOutput, {
+			maxLines: DEFAULT_MAX_LINES,
+			maxBytes: disposition.context.maxBytes,
+		}).content;
+	}
 	return {
 		kind: "ok",
-		output: truncation.content,
+		output,
 		details: {
 			resultSize: {
-				bytes,
-				shownBytes: truncation.outputBytes,
+				bytes: outputBytes,
+				shownBytes: byteLength(output),
 				maxBytes: BASH_DISPLAY_MAX_BYTES,
-				truncated: truncation.truncated,
-				policy: "tail",
+				truncated: byteLength(rawOutput) > byteLength(output),
+				policy,
 			},
 		},
 	};
 }
 
-// Tail-truncate the combined output for display, spilling the full output to a
-// scratch file first when it overflows the display cap. Setting
-// `details.resultSize.offloadPath` tells the registry result-shaper to leave
-// this already-shaped (tail-biased) output alone instead of re-truncating it
-// head-first.
-function shapeBashOutput(
+function bashResultDetails(
+	result: Awaited<ReturnType<typeof runBashCommand>>,
 	rawOutput: string,
-	context: Pick<ToolInvokeOptions, "sessionId" | "toolCallId"> | undefined,
-): ShapedBashOutput {
-	const truncation = truncateTail(rawOutput, {
-		maxLines: DEFAULT_MAX_LINES,
-		maxBytes: BASH_DISPLAY_MAX_BYTES - BASH_TAIL_NOTE_RESERVE,
-	});
-	if (!truncation.truncated) return { text: rawOutput };
-
-	const totalBytes = Buffer.byteLength(rawOutput, "utf8");
-	const offloadPath = writeToolOffload(rawOutput, context, BASH_HARD_CAP_BYTES);
-	const startLine = truncation.totalLines - truncation.outputLines + 1;
-	const scope = truncation.lastLinePartial
-		? `last ${formatSize(truncation.outputBytes)} of line ${truncation.totalLines} (line is large)`
-		: `lines ${startLine}-${truncation.totalLines} of ${truncation.totalLines}`;
-	const location = offloadPath !== null ? ` Full output saved to ${offloadPath}; read it with offset/limit.` : "";
-	const note = `[Output tail-truncated: showing ${scope} (${formatSize(BASH_DISPLAY_MAX_BYTES)} display limit).${location}]`;
-	const details: ToolResultDetails = {
-		resultSize: {
-			bytes: totalBytes,
-			shownBytes: truncation.outputBytes,
-			maxBytes: BASH_DISPLAY_MAX_BYTES,
-			truncated: true,
-			policy: "tail",
-			followUpHint: "Read the full-output offload file with offset/limit, or re-run a narrower command.",
-			...(offloadPath !== null ? { offloadPath } : {}),
-		},
+	outcome: "success" | "nonzero" | "timeout" | "abort" | "output-cap",
+): ToolResultDetails {
+	return {
+		outcome,
+		exitCode: result.exitCode,
+		signal: result.signal,
+		timedOut: result.timedOut,
+		aborted: result.aborted,
+		outputCapped: result.outputCapped,
+		outputBytes: result.outputBytes,
+		retainedBytes: byteLength(rawOutput),
+		stdoutBytes: byteLength(result.stdout),
+		stderrBytes: byteLength(result.stderr),
 	};
-	return { text: `${truncation.content}\n\n${note}`, details };
-}
-
-function withDetails(base: ToolResult, details: ToolResultDetails | undefined): ToolResult {
-	if (details === undefined) return base;
-	if (base.kind === "ok") return { ...base, details };
-	return { ...base, details };
 }
 
 // A bash command whose first word is a plain file/dir observer has a
@@ -120,7 +157,7 @@ function observeToolsNudge(command: string, sessionId: string | undefined): stri
 export const bashTool: ToolSpec = {
 	name: ToolNames.Bash,
 	description:
-		"Execute a bash command and return stdout and stderr. Runs inside the session workspace. Default timeout 300000 ms.",
+		"Execute a bash command inside the session workspace. output_policy controls model context: bounded keeps the diagnostic tail and is the default; summary keeps deterministic redacted diagnostics; metadata-only keeps facts and retrieval; full is admitted only within the result budget.",
 	parameters: Type.Object({
 		command: Type.String({ description: "Bash command to execute." }),
 		cwd: Type.Optional(
@@ -130,13 +167,30 @@ export const bashTool: ToolSpec = {
 			}),
 		),
 		timeout_ms: Type.Optional(Type.Number({ description: "Timeout in milliseconds." })),
+		output_policy: Type.Optional(
+			Type.Union([Type.Literal("full"), Type.Literal("bounded"), Type.Literal("summary"), Type.Literal("metadata-only")], {
+				description:
+					"Model-context disposition. Omit for bounded tail output. Use summary for noisy runs, metadata-only when only status and retrieval matter, and full only for known-small output.",
+			}),
+		),
 	}),
 	baseActionClass: "execute",
 	executionMode: "sequential",
+	prepareArguments: normalizeBashArguments,
+	resolveResultDisposition: resolveBashResultDisposition,
 	async run(args, options): Promise<ToolResult> {
+		args = normalizeBashArguments(args);
 		if (typeof args.command !== "string" || args.command.length === 0) {
 			return { kind: "error", message: "bash: missing command argument" };
 		}
+		const outputPolicy = bashOutputPolicy(args);
+		if (outputPolicy === null) {
+			return {
+				kind: "error",
+				message: "bash: output_policy must be one of full, bounded, summary, or metadata-only (omit it for bounded)",
+				details: { outcome: "invalid-arguments", exitCode: null },
+			};
+		}
 		const cwdArg = typeof args.cwd === "string" && args.cwd.length > 0 ? args.cwd : undefined;
 		// Pin the child's cwd inside the session workspace in the tool itself.
 		// The safety net blocks escaping cwd arguments at admission; this is the
@@ -161,41 +215,49 @@ export const bashTool: ToolSpec = {
 			};
 			if (options?.onUpdate !== undefined) {
 				runOptions.onUpdate = (progress) => {
-					options.onUpdate?.(shapeBashProgress(combineBashOutput(progress)));
+					options.onUpdate?.(shapeBashProgress(combineBashOutput(progress), progress.outputBytes, outputPolicy));
 				};
 			}
 			const result = await runBashCommand(args.command, runOptions);
 			const { error, aborted, timedOut, outputCapped } = result;
+			const rawOutput = combineBashOutput(result);
+			const output = rawOutput.trim();
 			if (aborted) {
-				return { kind: "error", message: "bash: command aborted" };
+				const status = "bash: command aborted";
+				return {
+					kind: "error",
+					message: output.length > 0 ? `${output}\n\n${status}` : status,
+					details: bashResultDetails(result, rawOutput, "abort"),
+				};
 			}
-			const shaped = shapeBashOutput(combineBashOutput(result), options);
-			const output = shaped.text.trim();
 			if (timedOut) {
 				const status = `bash: command timed out after ${timeout}ms`;
-				return withDetails(
-					{ kind: "error", message: output.length > 0 ? `${output}\n\n${status}` : status },
-					shaped.details,
-				);
+				return {
+					kind: "error",
+					message: output.length > 0 ? `${output}\n\n${status}` : status,
+					details: bashResultDetails(result, rawOutput, "timeout"),
+				};
 			}
 			if (outputCapped) {
 				const status = `bash: command output exceeded ${BASH_HARD_CAP_BYTES} bytes and was stopped`;
-				return withDetails(
-					{ kind: "error", message: output.length > 0 ? `${output}\n\n${status}` : status },
-					shaped.details,
-				);
+				return {
+					kind: "error",
+					message: output.length > 0 ? `${output}\n\n${status}` : status,
+					details: bashResultDetails(result, rawOutput, "output-cap"),
+				};
 			}
 			if (error) {
 				const code = typeof error.code === "number" ? error.code : (error as { code?: string }).code;
 				const status = `bash: command failed (exit ${code ?? "?"})`;
 				const message = output.length > 0 ? `${output}\n\n${status}` : `${status}: ${error.message}`;
-				return withDetails({ kind: "error", message }, shaped.details);
+				return { kind: "error", message, details: bashResultDetails(result, rawOutput, "nonzero") };
 			}
-			const body = shaped.text.length > 0 ? shaped.text : "(no output)";
-			return withDetails(
-				{ kind: "ok", output: `${body}${observeToolsNudge(args.command, options?.sessionId)}` },
-				shaped.details,
-			);
+			const body = rawOutput.length > 0 ? rawOutput : "(no output)";
+			return {
+				kind: "ok",
+				output: `${body}${observeToolsNudge(args.command, options?.sessionId)}`,
+				details: bashResultDetails(result, rawOutput, "success"),
+			};
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			return { kind: "error", message: `bash: ${msg}` };

package/src/tools/builtin-tool-catalog.ts

@@ -1,5 +1,8 @@
+import { BASH_HARD_CAP_BYTES } from "../core/bash-exec.js";
 import { type ToolName, ToolNames } from "../core/tool-names.js";
+import { BASH_DEFAULT_RESULT_DISPOSITION } from "./bash.js";
 import { OBSERVATION_POLICY_SLACK_BYTES, OBSERVE_SELF_CAPS } from "./observation.js";
+import { toolPresentationPolicy } from "./presentation.js";
 import { readMaxBytes } from "./read.js";
 import type { ToolMetadata, ToolSourceInfo, ToolSpec } from "./registry.js";
 
@@ -92,7 +95,7 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		),
 		costLatency: "local_fast",
 		promptHint:
-			'Call context with scope="skills" to list installed and marketplace skills; when one matches the task, or the operator names a skill or asks how one works, suggest the operator run /skill <name> (a marketplace skill is offered for install) and never load it uninvited. When the user message carries a skill request, first load that skill via context (scope="skills", name=<skill>) before doing anything else.',
+			'Call context with scope="skills" to list installed and marketplace skills; when one matches the task, or the operator names a skill or asks how one works, suggest the operator run /skill <name> (a marketplace skill is offered for install) and never load it uninvited. When the user message carries a skill request, first load that skill via context (scope="skills", name=<skill>) before doing anything else. When an [evicted ...] marker names content you need, recall it with context(scope="recall", ref=...); re-read the file only when the marker says it changed.',
 	},
 	[ToolNames.CredentialPresent]: {
 		objective: "Check whether a credential key is present without returning its value.",
@@ -120,15 +123,19 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		resultSizePolicy: exactMutationPolicy,
 		costLatency: "local_fast",
 	},
-	// EXECUTE: the safe-exec spine (bash offloads its own overflow).
+	// EXECUTE: the safe-exec spine (canonical shaping offloads Bash overflow).
 	[ToolNames.Bash]: {
 		objective: "Execute an explicit shell command when narrower tools are insufficient.",
 		uiLabel: "Shell",
 		retrySafety: "unknown",
-		resultSizePolicy: summaryPolicy(
-			"Use a narrower command or a dedicated verification/read/search tool to inspect omitted output.",
-		),
+		resultSizePolicy: {
+			...summaryPolicy("Use a narrower command or a dedicated verification/read/search tool to inspect omitted output."),
+			offloadMaxBytes: BASH_HARD_CAP_BYTES,
+		},
+		resultDisposition: BASH_DEFAULT_RESULT_DISPOSITION,
 		costLatency: "local_slow",
+		promptHint:
+			"Bash output_policy defaults to bounded diagnostic tail. Use summary for noisy commands, metadata-only when only outcome and retrieval matter, and full only when output is known to fit the bounded result budget.",
 	},
 	[ToolNames.Git]: {
 		objective: "Read-only git inspection: status, diff, or log.",
@@ -255,9 +262,14 @@ export function toolPromptHintsForNames(names: ReadonlyArray<ToolName>): Readonl
 	return hints;
 }
 
+// Every builtin carries its transcript presentation on its metadata, resolved
+// from the one declaration table in presentation.ts, so the registry and the
+// live panel (which has no registry) answer the fold question identically.
 function withBuiltinMetadata<T extends ToolSpec>(spec: T): T {
 	const metadata = TOOL_METADATA[spec.name];
-	return metadata ? withMetadata(spec, metadata) : spec;
+	return metadata
+		? withMetadata(spec, { ...metadata, presentation: toolPresentationPolicy(spec.name, undefined) })
+		: spec;
 }
 
 export function builtin<T extends ToolSpec>(spec: T, sourceInfo: ToolSourceInfo): T {

package/src/tools/context/index.ts

@@ -1,7 +1,15 @@
 import { type Dirent, readdirSync } from "node:fs";
 import path from "node:path";
+import type { ContextRecalledPayload } from "../../core/bus-events.js";
 import { SKILL_SUGGESTION_ANCHOR } from "../../core/skill-activation.js";
 import { ToolNames } from "../../core/tool-names.js";
+import { foldWorkingSet } from "../../domains/context/working-set/fold.js";
+import {
+	buildRecallFields,
+	recallErrorMessage,
+	recallParentTurnId,
+	resolveRecall,
+} from "../../domains/context/working-set/recall.js";
 import {
 	checkSkillDrift,
 	discoverMarketplaceSkills,
@@ -11,6 +19,8 @@ import {
 	modelVisibleSkills,
 	type Skill,
 } from "../../domains/resources/index.js";
+import type { SessionEntryInput } from "../../domains/session/contract.js";
+import type { SessionEntry } from "../../domains/session/entries.js";
 import type { WorkspaceSnapshot } from "../../domains/session/workspace/index.js";
 import {
 	finalizeObservation,
@@ -30,7 +40,8 @@ import { contextToolSurface } from "./surface.js";
  * workspace snapshot, scope=docs retrieves cited sections from Clio's bundled
  * documentation, scope=skills lists available skills or loads a requested
  * skill body (the skill-activation and pending-request contracts are
- * unchanged from the absorbed read_skill tool).
+ * unchanged from the absorbed read_skill tool), scope=recall readmits an
+ * evicted tool-result body by ref and records the `contextRecall` entry.
  */
 
 const DEFAULT_TREE_ENTRIES = 50;
@@ -42,6 +53,17 @@ export interface ContextWorkspaceDeps {
 	saveSnapshot(snapshot: WorkspaceSnapshot): void;
 }
 
+/** Ledger access for scope=recall: read the full ledger, fold it at the live leaf, append the recall record. */
+export interface ContextSessionDeps {
+	hasSession(): boolean;
+	readEntries(): ReadonlyArray<SessionEntry>;
+	/** The live append point (`/tree` pin or tree leaf); undefined lets the fold infer it. */
+	activeLeafTurnId(): string | undefined;
+	appendEntry(entry: SessionEntryInput): SessionEntry;
+	/** Called after the recall entry is recorded; the orchestrator publishes it as BusChannels.ContextRecalled. */
+	onRecalled?: (payload: ContextRecalledPayload) => void;
+}
+
 export interface ContextToolDeps {
 	getCwd?: () => string;
 	getSkillLoaderOptions?: () => Pick<
@@ -50,6 +72,8 @@ export interface ContextToolDeps {
 	>;
 	/** Absent in worker registries without a session; scope=workspace errors cleanly. */
 	workspace?: ContextWorkspaceDeps;
+	/** Absent in worker registries without a session; scope=recall errors cleanly. */
+	session?: ContextSessionDeps;
 	/**
 	 * Whether scope=skills may list marketplace entries beside installed
 	 * skills. Worker registries set false: a worker can neither install a
@@ -482,13 +506,90 @@ function runSkillsScope(
 	});
 }
 
+/**
+ * scope=recall: the body goes back through the observation envelope like any
+ * OBSERVE result, so the per-turn pool and the self cap still apply; an
+ * oversize body is offloaded by the envelope and the notice carries the
+ * pointer. A body whose original result was itself offloaded already ends in
+ * that tool's own `full: <path>` pointer, which is what the model gets back;
+ * the file is never inlined. The `contextRecall` entry is appended before the
+ * result returns; it is the churn record, not an un-eviction, so the marker
+ * and the prefix cache stay where they are.
+ */
+function runRecallScope(
+	deps: ContextToolDeps,
+	args: Record<string, unknown>,
+	reservation: ObservationReservation,
+	options: ToolInvokeOptions | undefined,
+): ToolResult {
+	const session = deps.session;
+	if (!session?.hasSession()) {
+		return { kind: "error", message: "context: recall scope requires a bound session; none is active here" };
+	}
+	const ref = typeof args.ref === "string" ? args.ref.trim() : "";
+	if (ref.length === 0) {
+		return {
+			kind: "error",
+			message: "context: recall scope requires ref=<turnId>, the ref named in the [evicted ...] marker",
+		};
+	}
+	const entries = session.readEntries();
+	const leaf = session.activeLeafTurnId();
+	const view = foldWorkingSet(entries, leaf);
+	const resolved = resolveRecall(entries, view, ref, leaf);
+	if (!resolved.ok) return { kind: "error", message: `context: ${recallErrorMessage(resolved.error, entries, view)}` };
+	const { result } = resolved;
+	const fields = buildRecallFields(result, {
+		trigger: "tool",
+		...(options?.toolCallId ? { toolCallId: options.toolCallId } : {}),
+	});
+	// The recall record parents onto the live leaf so the fold sees it on
+	// this branch and only this branch.
+	const parentTurnId = recallParentTurnId(entries, leaf);
+	let recorded: SessionEntry;
+	try {
+		recorded = session.appendEntry({ ...fields, parentTurnId });
+	} catch (err) {
+		return {
+			kind: "error",
+			message: `context: recall of ${result.ref.entry} could not be recorded: ${err instanceof Error ? err.message : String(err)}`,
+		};
+	}
+	session.onRecalled?.({ ref: result.ref.entry, trigger: "tool", tokensReadmitted: result.tokens, at: Date.now() });
+	const evictedState = view.evicted.get(result.ref.entry);
+	const truncation = truncateHead(result.body, {
+		maxBytes: reservation.callCapBytes,
+		maxLines: Number.MAX_SAFE_INTEGER,
+	});
+	return finalizeObservation({
+		tool: ToolNames.Context,
+		unit: "results",
+		output: truncation.content,
+		...(truncation.truncated ? { fullOutput: result.body } : {}),
+		shownCount: 1,
+		totalCount: 1,
+		truncated: truncation.truncated,
+		details: {
+			recall: {
+				ref: result.ref.entry,
+				tokensReadmitted: result.tokens,
+				recallTurnId: recorded.turnId,
+				...(evictedState ? { reason: evictedState.reason, evictedAtTurnId: evictedState.evictedAtTurnId } : {}),
+				...(result.offloadPath !== undefined ? { offloadPath: result.offloadPath } : {}),
+			},
+		},
+		reservation,
+		...(options ? { options } : {}),
+	});
+}
+
 export function createContextTool(deps: ContextToolDeps = {}): ToolSpec {
 	return {
 		...contextToolSurface,
 		async run(args, options): Promise<ToolResult> {
 			const scope = typeof args.scope === "string" ? args.scope : "";
-			if (scope !== "workspace" && scope !== "docs" && scope !== "skills") {
-				return { kind: "error", message: `context: scope must be workspace, docs, or skills; got '${scope}'` };
+			if (scope !== "workspace" && scope !== "docs" && scope !== "skills" && scope !== "recall") {
+				return { kind: "error", message: `context: scope must be workspace, docs, skills, or recall; got '${scope}'` };
 			}
 			const selfCap =
 				scope === "docs"
@@ -508,6 +609,7 @@ export function createContextTool(deps: ContextToolDeps = {}): ToolSpec {
 			}
 			if (scope === "workspace") return runWorkspaceScope(deps, reservation, options);
 			if (scope === "docs") return runDocsScope(args, reservation, options);
+			if (scope === "recall") return runRecallScope(deps, args, reservation, options);
 			return runSkillsScope(deps, args, reservation, options);
 		},
 	};

package/src/tools/context/surface.ts

@@ -6,12 +6,13 @@ import type { ToolSurface } from "../lazy-tool.js";
 export const contextToolSurface = {
 	name: ToolNames.Context,
 	description:
-		"Environment context: scope=workspace returns the git/project snapshot, scope=docs searches Clio's bundled documentation (omit query to list the corpus), scope=skills lists installed and marketplace skills or loads an installed one by name. For repository code and the repo's generated wiki use code_nav (mode=wiki).",
+		"Environment context: scope=workspace returns the git/project snapshot, scope=docs searches Clio's bundled documentation (omit query to list the corpus), scope=skills lists installed and marketplace skills or loads an installed one by name, scope=recall returns the exact body of an evicted tool result by ref (the turnId named in an [evicted ...] marker). For repository code and the repo's generated wiki use code_nav (mode=wiki).",
 	parameters: Type.Object({
-		scope: StringEnum(["workspace", "docs", "skills"], { description: "Context source." }),
+		scope: StringEnum(["workspace", "docs", "skills", "recall"], { description: "Context source." }),
 		query: Type.Optional(Type.String({ description: "scope=docs: question or terms; omit to list the corpus." })),
 		name: Type.Optional(Type.String({ description: "scope=skills: skill name to load; omit to list." })),
 		limit: Type.Optional(Type.Number({ description: "scope=docs: max sections (default 5, max 12)." })),
+		ref: Type.Optional(Type.String({ description: "scope=recall: ref of the evicted item, as named in its marker." })),
 		include_tree: Type.Optional(Type.Boolean({ description: "scope=skills: list files under the skill base_dir." })),
 	}),
 	baseActionClass: "read",

package/src/tools/core-bootstrap.ts

@@ -1,5 +1,7 @@
+import type { ContextRecalledPayload } from "../core/bus-events.js";
 import type { LoadSkillsInput } from "../domains/resources/index.js";
 import type { SessionContract } from "../domains/session/contract.js";
+import type { SessionEntry } from "../domains/session/entries.js";
 import { createTaskBoardStore, type TaskBoardStore } from "../domains/session/task-board.js";
 import type { UserTasksStore } from "../domains/user-tasks/store.js";
 import type { AgentLedgerPort } from "../worker/protocol.js";
@@ -28,6 +30,10 @@ import { writeTool } from "./write.js";
 
 export interface CoreToolBootstrapDeps {
 	session?: SessionContract;
+	/** Full ledger of the current session; context(scope=recall) folds it. Absent in worker registries. */
+	readSessionEntries?: () => ReadonlyArray<SessionEntry>;
+	/** Publishes a successful context(scope=recall) on the bus; absent where no bus is wired. */
+	onContextRecalled?: (payload: ContextRecalledPayload) => void;
 	askUser?: AskUserHandler;
 	taskBoard?: TaskBoardStore;
 	userTasks?: UserTasksStore;
@@ -108,6 +114,7 @@ export function registerCoreTools(registry: ToolRegistry, deps: CoreToolBootstra
 		...builtin(credentialPresentTool, { path: "src/tools/credential-present.ts", scope: "core" }),
 	});
 	const session = deps.session;
+	const readSessionEntries = deps.readSessionEntries;
 	registry.register({
 		...builtin(
 			lazyTool(contextToolSurface, async () => {
@@ -116,6 +123,20 @@ export function registerCoreTools(registry: ToolRegistry, deps: CoreToolBootstra
 				const { probeWorkspace } = await import("../domains/session/workspace/index.js");
 				return createContextTool({
 					...skillToolDeps,
+					...(readSessionEntries
+						? {
+								session: {
+									hasSession: () => session.current() !== null,
+									readEntries: readSessionEntries,
+									activeLeafTurnId: () => {
+										const meta = session.current();
+										return meta ? (session.tree(meta.id).leafId ?? undefined) : undefined;
+									},
+									appendEntry: (entry) => session.appendEntry(entry),
+									...(deps.onContextRecalled ? { onRecalled: deps.onContextRecalled } : {}),
+								},
+							}
+						: {}),
 					workspace: {
 						hasSession: () => session.current() !== null,
 						getSnapshot: () => session.current()?.workspace ?? null,