@iowarp/clio-coder 0.4.3 → 0.4.5

package/src/tools/monitor.ts

@@ -17,7 +17,7 @@ import {
 	type RunReceipt,
 	type RunReceiptVerification,
 } from "../domains/dispatch/types.js";
-import { summarizeTrustStatus } from "../domains/evidence/trust-projection.js";
+import { summarizeTrustStatus, trustStateWord } from "../domains/evidence/trust-projection.js";
 import {
 	adaptRunReceiptTrustStatus,
 	type CanonicalTrustStatus,
@@ -100,13 +100,19 @@ function listRuns(deps: MonitorToolDeps, options: ToolInvokeOptions | undefined)
 
 function runStatus(deps: MonitorToolDeps, runId: string): ToolResult {
 	const requestedRun = deps.dispatch.getRun(runId);
-	const rootRunId = requestedRun?.lineage?.rootRunId ?? runId;
-	const assignment = deps.dispatch.assignments?.getStored(rootRunId) ?? null;
+	const assignment = deps.dispatch.assignments?.getStored(runId) ?? null;
+	const rootRunId = assignment?.assignmentId ?? requestedRun?.lineage?.rootRunId ?? runId;
 	const resolvedRunId = assignment?.terminalRunId ?? runId;
 	const run = deps.dispatch.getRun(resolvedRunId) ?? requestedRun;
 	if (!run && !assignment) return { kind: "error", message: `monitor: unknown run or assignment '${runId}'` };
 	if (!run) return { kind: "error", message: `monitor: assignment '${runId}' has no available attempt` };
-	const live = deps.dispatch.snapshot().running.find((entry) => entry.lineage.rootRunId === rootRunId) ?? null;
+	const live =
+		deps.dispatch
+			.snapshot()
+			.running.find(
+				(entry) =>
+					(deps.dispatch.assignments?.getStored(entry.runId)?.assignmentId ?? entry.lineage.rootRunId) === rootRunId,
+			) ?? null;
 	const reroutes =
 		run.reroutes !== undefined && run.reroutes.length > 0
 			? ` reroutes=${run.reroutes.map((hop) => `${hop.fromNode}>${hop.toNode}`).join(",")}`
@@ -142,11 +148,18 @@ function runStatus(deps: MonitorToolDeps, runId: string): ToolResult {
 			`live: phase=${live.outcomePhase} heartbeat=${live.heartbeat} elapsed=${Math.round(live.elapsedMs / 1000)}s tokens=${live.tokens.total}`,
 		);
 	}
+	const trust = isTerminalRunEnvelope(run) ? summarizeTrustStatus(durableRunEvidence(run).trustStatus) : null;
+	if (trust)
+		lines.push(
+			`quality: ${trustStateWord("validationGrounding", trust.axes.validationGrounding)}`,
+			`trust: ${trust.text}`,
+		);
 	return {
 		kind: "ok",
 		output: lines.join("\n"),
 		details: {
 			mode: "status",
+			...(trust ? { trust } : {}),
 			...(assignment
 				? {
 						assignmentId: assignment.assignmentId,
@@ -289,8 +302,7 @@ function receiptToolLines(receipt: RunReceipt): string[] {
  */
 function runTools(deps: MonitorToolDeps, runId: string): ToolResult {
 	const requestedRun = deps.dispatch.getRun(runId);
-	const rootRunId = requestedRun?.lineage?.rootRunId ?? runId;
-	const assignment = deps.dispatch.assignments?.getStored(rootRunId) ?? null;
+	const assignment = deps.dispatch.assignments?.getStored(runId) ?? null;
 	const resolvedRunId = assignment?.terminalRunId ?? runId;
 	const run = deps.dispatch.getRun(resolvedRunId) ?? requestedRun ?? null;
 	if (run === null && assignment === null) return { kind: "error", message: `monitor: unknown run '${runId}'` };
@@ -504,8 +516,8 @@ async function runWait(
 	const startedAt = performance.now();
 	let run = deps.dispatch.getRun(runId);
 	if (!run) return { kind: "error", message: `monitor: unknown run '${runId}'` };
-	const rootRunId = run.lineage?.rootRunId ?? runId;
-	let assignment = deps.dispatch.assignments?.getStored(rootRunId) ?? null;
+	let assignment = deps.dispatch.assignments?.getStored(runId) ?? null;
+	const rootRunId = assignment?.assignmentId ?? runId;
 	while (assignment?.status === "running" || (assignment === null && !isTerminalRunEnvelope(run))) {
 		if (signal?.aborted) return { kind: "error", message: "monitor: wait aborted" };
 		const elapsed = Math.round(performance.now() - startedAt);
@@ -587,7 +599,11 @@ function collectRunLine(row: CollectedRunRow): string[] {
 	lines.push(`  ${workerTextLabel(row.evidence.trustStatus)}`);
 	const output = row.evidence.output;
 	if (output) {
-		const capped = truncateUtf8(output.text, COLLECT_TEXT_BYTES, "...");
+		const capped = truncateUtf8(
+			output.text,
+			COLLECT_TEXT_BYTES,
+			`\n[preview clipped at ${COLLECT_TEXT_BYTES} bytes; the complete sealed text is output.text in ${row.run?.receiptPath ?? "the receipt"}]`,
+		);
 		const qualifier = output.state === "partial" ? " (partial; the run did not complete this message)" : "";
 		const truncatedNote = output.truncated ? ` (stored output truncated; full text was ${output.bytes} bytes)` : "";
 		lines.push(`  agent output${qualifier}${truncatedNote}:`, ...capped.split("\n").map((line) => `  ${line}`));
@@ -606,11 +622,10 @@ function collectRunLine(row: CollectedRunRow): string[] {
 
 function resolveCollectRow(deps: MonitorToolDeps, originalRunId: string, agentId: string): CollectRow {
 	const original = deps.dispatch.getRun(originalRunId);
-	const rootRunId = original?.lineage?.rootRunId ?? originalRunId;
 	// The durable assignment record is written asynchronously at admission, so a
 	// collect issued in that window sees none yet and reads the attempt directly.
 	// terminalRunId is null while the assignment is still running.
-	const assignment = deps.dispatch.assignments?.getStored(rootRunId) ?? null;
+	const assignment = deps.dispatch.assignments?.getStored(originalRunId) ?? null;
 	const runId = assignment?.terminalRunId ?? originalRunId;
 	const run = deps.dispatch.getRun(runId) ?? original;
 	return {

package/src/tools/network-policy.ts

@@ -1,29 +1,16 @@
 /**
- * Per-process switch for the RETRIEVE plane, the only builtin plane that
- * leaves the machine.
- *
- * There is no per-run tool allowlist on the main-agent path: a headless
- * `clio-coder run` gets whatever `registerAllTools` registered, and the registry
- * answers an unregistered name with a `not_visible` verdict. So the existing
- * lever for "this run has no network" is registration itself, the same lever
- * that already keeps `ask_user` out of headless and worker registries. This
- * module carries the switch that lever reads.
- *
- * The channel is an environment variable because the process that needs the
- * policy is a child: the skill-eval harness spawns `clio-coder run` for each arm,
- * and any worker those runs dispatch is a grandchild. Env inherits down the
- * whole tree, so one setting at spawn time covers every registry built below
- * it (`src/tools/bootstrap.ts`, `src/engine/worker-tools.ts`) without a flag
- * threaded through four call layers.
- *
- * What this does not cover: a runtime that executes its own tool surface
- * outside Clio's mediation (an external CLI subprocess) never consults this
- * registry, so its network access is its own to answer for.
+ * Process-wide registration switch for the RETRIEVE tool plane (web_fetch).
+ * This removes retrieval tools from main and worker registries. It does not
+ * restrict bash, hooks, external CLIs, or provider traffic. Hermetic execution
+ * requires an OS network sandbox supplied by the operator or eval harness.
+ * The environment setting propagates to child registries without per-run wiring.
  */
+export const NO_NETWORK_TOOLS_ENV = "CLIO_CODER_DISABLE_RETRIEVE_TOOLS";
 
-/** Set to "1" to strip network tools from every registry built in this process. */
-export const NO_NETWORK_TOOLS_ENV = "CLIO_CODER_NO_NETWORK_TOOLS";
-
+/** Legacy spelling remains accepted for existing harnesses; neither is a sandbox. */
 export function networkToolsDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
-	return env[NO_NETWORK_TOOLS_ENV] === "1";
+	return env[NO_NETWORK_TOOLS_ENV] === "1" || env.CLIO_CODER_NO_NETWORK_TOOLS === "1";
 }
+
+/** Operator process opt-in; never accepted from model arguments or project settings. */
+export const WEB_FETCH_ALLOW_PRIVATE_NETWORK_ENV = "CLIO_CODER_WEB_FETCH_ALLOW_PRIVATE_NETWORK";

package/src/tools/observation.ts

@@ -1,4 +1,6 @@
 import { GUARDRAIL_DEFAULTS, resolveGuardrail } from "../core/guardrails.js";
+import { createSafetyPolicyEngine } from "../domains/safety/policy-engine.js";
+import type { ImageContent } from "../engine/types.js";
 import type { ToolInvokeOptions, ToolResult } from "./registry.js";
 import { offloadPointer, writeToolOffload } from "./result-shaping.js";
 import { formatSize } from "./truncate.js";
@@ -337,6 +339,8 @@ export function observationBudgetExhausted(input: {
 }
 
 export interface ObservationInput {
+	images?: ImageContent[];
+	withheldPaths?: number;
 	tool: string;
 	unit: ObservationUnit;
 	format?: ObservationFormat;
@@ -446,7 +450,10 @@ export function finalizeObservation(input: ObservationInput): ToolResult {
 		}
 	}
 
-	const shownBytes = byteLength(output);
+	if ((input.withheldPaths ?? 0) > 0 && format === "text")
+		output += `\n\n[${input.withheldPaths} protected paths withheld by zero-access policy]`;
+	const shownBytes =
+		byteLength(output) + (input.images ?? []).reduce((bytes, image) => bytes + byteLength(image.data), 0);
 	recordSpentBytes(input.reservation, shownBytes);
 	const budget = budgetDetails(input.reservation);
 	const observation: Observation = {
@@ -466,5 +473,35 @@ export function finalizeObservation(input: ObservationInput): ToolResult {
 		...(offloadPath !== null ? { offloadPath } : {}),
 		...(budget !== null ? { budget } : {}),
 	};
-	return { kind: "ok", output, details: { ...(input.details ?? {}), observation } };
+	return {
+		kind: "ok",
+		output,
+		...(input.images?.length ? { images: input.images } : {}),
+		details: { ...(input.details ?? {}), observation },
+	};
+}
+
+/** Producers pass structured paths before rendering or offloading any content. */
+export function createObservationPathFilter(
+	cwd = process.cwd(),
+	allowsPath?: (path: string) => boolean,
+): {
+	allows(path: string): boolean;
+	readonly withheldPaths: number;
+} {
+	const policy = allowsPath ? undefined : createSafetyPolicyEngine({ cwd });
+	const allows =
+		allowsPath ??
+		((path: string) => policy?.evaluate({ tool: "read", args: { path } }).reasonCode !== "path-policy:zeroAccessPaths");
+	const withheld = new Set<string>();
+	return {
+		allows(path) {
+			if (allows(path)) return true;
+			withheld.add(path);
+			return false;
+		},
+		get withheldPaths() {
+			return withheld.size;
+		},
+	};
 }

package/src/tools/policy.ts

@@ -21,6 +21,7 @@ interface PlaneExpectation {
 
 /** One row per registered tool: plane, action class, and concurrency rule. */
 export const TOOL_PLANES: Readonly<Record<BuiltinToolName, PlaneExpectation>> = {
+	[ToolNames.Evidence]: { plane: "observe", actionClass: "read", executionMode: "sequential" },
 	[ToolNames.Read]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.Grep]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.Find]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
@@ -53,6 +54,14 @@ export const TOOL_PLANES: Readonly<Record<BuiltinToolName, PlaneExpectation>> =
 	// panes. It mutates no workspace, so it stays read class; sequential because
 	// two pane operations in one batch would race the same pane registry.
 	[ToolNames.Panes]: { plane: "orchestrate", actionClass: "read", executionMode: "sequential" },
+	// limitation records a typed receipt in the session ledger and nothing
+	// else: no filesystem, no shell. Read class so it never trips a safety
+	// gate; parallel because the call is pure and idempotent.
+	[ToolNames.Limitation]: { plane: "orchestrate", actionClass: "read", executionMode: "parallel" },
+	// decide appends one decision-board entry to the session ledger and
+	// nothing else. Read class so it never trips a safety gate; sequential so
+	// two decisions in one batch never race the supersede lookup.
+	[ToolNames.Decide]: { plane: "orchestrate", actionClass: "read", executionMode: "sequential" },
 	[ToolNames.WebFetch]: { plane: "retrieve", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.AskUser]: { plane: "interact", actionClass: "read", executionMode: "sequential" },
 	[ToolNames.Artifact]: { plane: "artifact", actionClass: "write", executionMode: "sequential" },

package/src/tools/presentation.ts

@@ -50,6 +50,7 @@ const FOLDED_WITH_DIFF: ToolPresentationPolicy = {
  * tools, folds the same way.
  */
 export const TOOL_PRESENTATION: Readonly<Record<string, ToolPresentationPolicy>> = {
+	[ToolNames.Evidence]: FOLDED,
 	[ToolNames.Read]: FOLDED,
 	[ToolNames.Grep]: FOLDED,
 	[ToolNames.Find]: FOLDED,
@@ -68,6 +69,8 @@ export const TOOL_PRESENTATION: Readonly<Record<string, ToolPresentationPolicy>>
 	[ToolNames.Tasks]: FOLDED,
 	[ToolNames.Ledger]: FOLDED,
 	[ToolNames.Panes]: FOLDED,
+	[ToolNames.Limitation]: FOLDED,
+	[ToolNames.Decide]: FOLDED,
 	[ToolNames.WebFetch]: FOLDED,
 	[ToolNames.AskUser]: FOLDED,
 	[ToolNames.Artifact]: FOLDED,

package/src/tools/read.ts

@@ -1,8 +1,15 @@
 import { readFileSync, statSync } from "node:fs";
 import { Type } from "typebox";
+import { detectSupportedImageMimeType, prepareBoundedImage } from "../core/file-references.js";
 import { GUARDRAIL_DEFAULTS, resolveGuardrail } from "../core/guardrails.js";
 import { ToolNames } from "../core/tool-names.js";
-import { finalizeObservation, observationBudgetExhausted, reserveObservation } from "./observation.js";
+import {
+	commitObservationReservation,
+	finalizeObservation,
+	observationBudgetExhausted,
+	releaseObservation,
+	reserveObservation,
+} from "./observation.js";
 import { resolveReadPath } from "./path-utils.js";
 import type { ToolResult, ToolSpec } from "./registry.js";
 import { isSessionOffloadPath } from "./result-shaping.js";
@@ -28,13 +35,35 @@ export function readMaxBytes(): number {
 	return Math.max(MIN_READ_CAP_BYTES, resolveGuardrail("readMaxBytes"));
 }
 
+// Number only an already bounded slice, retaining its explicit physical line
+// count: a truncated slice ending in a blank line can look like a terminator.
+function numberSourceLines(content: string, firstLine: number, lineCount: number): string {
+	return content
+		.split("\n")
+		.map((line, index) => (index < lineCount ? `${firstLine + index} | ${line}` : line))
+		.join("\n");
+}
+
+function numberedPrefixBytes(totalLines: number): number {
+	let bytes = totalLines * 3; // " | " after each decimal source line number.
+	for (let first = 1, digits = 1; first <= totalLines; first *= 10, digits++) {
+		bytes += (Math.min(totalLines + 1, first * 10) - first) * digits;
+	}
+	return bytes;
+}
+
 export const readTool: ToolSpec = {
 	name: ToolNames.Read,
-	description: `Read a UTF-8 text file. Output is capped at ${DEFAULT_MAX_LINES} lines or ${
+	description: `Read a UTF-8 text file or a PNG, JPEG, GIF, or WebP image when the routed model supports vision. Output is capped at ${DEFAULT_MAX_LINES} lines or ${
 		DEFAULT_READ_MAX_BYTES / 1024
-	}KB per call; truncated results say how to continue with offset/limit. Pass tail=N to read the last N lines (jump to EOF) instead of paging from the top.`,
+	}KB per call; truncated results say how to continue with offset/limit. Pass tail=N to read the last N lines (jump to EOF) instead of paging from the top. Set line_numbers=true for citations: each source line is prefixed with its physical 1-based line number and " | "; these labels are not file content.`,
 	parameters: Type.Object({
 		path: Type.String({ description: "File path (relative or absolute)." }),
+		line_numbers: Type.Optional(
+			Type.Boolean({
+				description: "Display physical source line numbers for citations. Default false preserves plain text.",
+			}),
+		),
 		offset: Type.Optional(Type.Number({ description: "1-indexed start line." })),
 		limit: Type.Optional(Type.Number({ description: "Max lines to read." })),
 		tail: Type.Optional(
@@ -47,6 +76,7 @@ export const readTool: ToolSpec = {
 		const pathArg = typeof args.path === "string" ? args.path : null;
 		if (!pathArg) return { kind: "error", message: "read: missing path argument" };
 		const filePath = resolveReadPath(pathArg);
+		const numbered = args.line_numbers === true;
 		const offset = typeof args.offset === "number" && args.offset > 0 ? Math.floor(args.offset) : 1;
 		const limit = typeof args.limit === "number" && args.limit > 0 ? Math.floor(args.limit) : null;
 		const tail = typeof args.tail === "number" && args.tail > 0 ? Math.floor(args.tail) : null;
@@ -76,13 +106,44 @@ export const readTool: ToolSpec = {
 					hint: "Use offset/limit in a follow-up turn or grep/find for a narrower section.",
 				});
 			}
-			const content = readFileSync(filePath, "utf8");
+			const bytes = readFileSync(filePath);
+			if (detectSupportedImageMimeType(bytes) !== null) {
+				if (options?.supportsImages !== true)
+					return {
+						kind: "error",
+						message:
+							"IMAGE_INPUT_UNSUPPORTED: the routed model does not support image input. Choose a vision-capable model to inspect this file.",
+					};
+				const output = `Image: ${pathArg}`;
+				commitObservationReservation(reservation);
+				const image = await prepareBoundedImage(
+					bytes,
+					Math.min(reservation.callCapBytes, options.toolResultMaxBytes ?? readMaxBytes()) - Buffer.byteLength(output) - 512,
+				);
+				if (image === null)
+					return {
+						kind: "error",
+						message: "IMAGE_RESULT_TOO_LARGE: image could not be encoded within the tool result byte cap.",
+					};
+				return finalizeObservation({
+					tool: ToolNames.Read,
+					unit: "results",
+					output,
+					images: [image],
+					shownCount: 1,
+					totalCount: 1,
+					truncated: false,
+					reservation,
+					...(options ? { options } : {}),
+				});
+			}
+			const content = bytes.toString("utf8");
 			// Slice from the raw split (keeps the trailing newline on selections that
 			// reach EOF); count lines honestly (a trailing "\n" is a terminator, not
 			// a phantom extra line) so continuation notices never over-report by one.
 			const allLines = content.split("\n");
 			const totalLines = splitLinesForCounting(content).length;
-			const totalBytes = Buffer.byteLength(content, "utf8");
+			const totalBytes = Buffer.byteLength(content, "utf8") + (numbered ? numberedPrefixBytes(totalLines) : 0);
 			const startIndex = Math.min(offset - 1, totalLines);
 			if (tail === null && offset > 1 && startIndex >= totalLines) {
 				// The anchor matters for weak models: a bare "beyond end of file"
@@ -104,10 +165,26 @@ export const readTool: ToolSpec = {
 				// the end (reusing truncateTail) so the very tail always survives.
 				const startLine = Math.max(0, totalLines - tail);
 				const tailContent = allLines.slice(startLine).join("\n");
-				const truncation = truncateTail(tailContent, { maxBytes: cap, maxLines: tail });
+				const sourceTruncation = truncateTail(tailContent, { maxBytes: cap, maxLines: tail });
+				let truncation = sourceTruncation;
+				if (numbered) {
+					const numberedContent = numberSourceLines(
+						sourceTruncation.content,
+						totalLines - sourceTruncation.outputLines + 1,
+						sourceTruncation.outputLines,
+					);
+					truncation = truncateTail(numberedContent, { maxBytes: cap, maxLines: tail });
+					if (sourceTruncation.lastLinePartial || truncation.lastLinePartial) {
+						// Never return a tail fragment with a lost or fabricated complete
+						// line label. Keep the suffix within the cap and mark it partial.
+						const label = `${totalLines} | [partial line suffix] `;
+						const suffix = truncateTail(allLines[totalLines - 1] ?? "", { maxBytes: cap - Buffer.byteLength(label) });
+						truncation = { ...truncation, content: label + suffix.content, outputLines: 0, truncated: true };
+					}
+				}
 				const shownLines = truncation.outputLines;
 				const firstShown = Math.max(1, totalLines - shownLines + 1);
-				const truncated = startLine > 0 || truncation.truncated;
+				const truncated = startLine > 0 || sourceTruncation.truncated || truncation.truncated;
 				return finalizeObservation({
 					tool: ToolNames.Read,
 					unit: "lines",
@@ -116,19 +193,37 @@ export const readTool: ToolSpec = {
 					totalCount: totalLines,
 					totalBytes,
 					truncated,
-					...(truncated ? { next: `offset=${Math.max(1, firstShown - shownLines)} limit=${shownLines}` } : {}),
+					...(truncated && shownLines > 0
+						? {
+								next: `offset=${Math.max(1, firstShown - shownLines)} limit=${shownLines}${numbered ? " line_numbers=true" : ""}`,
+							}
+						: {}),
 					reservation,
 					...(options ? { options } : {}),
 				});
 			}
 
+			const endIndex = limit !== null ? Math.min(startIndex + limit, totalLines) : totalLines;
+			// Preserve the last selected source line's terminator when it exists.
+			// Joining a limited slice alone turns ["x", ""] into "x\n", which
+			// truncateHead counts as one line; [""] even becomes an empty file.
+			// The raw split's final entry tells us whether that newline is real,
+			// without inventing a line at EOF or changing shared text counting.
 			const selected =
-				limit !== null ? allLines.slice(startIndex, startIndex + limit).join("\n") : allLines.slice(startIndex).join("\n");
-			const truncation: TruncationResult = truncateHead(selected, { maxBytes: cap });
+				allLines.slice(startIndex, endIndex).join("\n") + (endIndex > startIndex && endIndex < allLines.length ? "\n" : "");
+			const sourceTruncation = truncateHead(selected, { maxBytes: cap });
+			const truncation: TruncationResult =
+				numbered && !sourceTruncation.firstLineExceedsLimit
+					? truncateHead(numberSourceLines(sourceTruncation.content, startIndex + 1, sourceTruncation.outputLines), {
+							maxBytes: cap,
+						})
+					: sourceTruncation;
 			if (truncation.firstLineExceedsLimit) {
-				const firstLineSize = formatSize(Buffer.byteLength(allLines[startIndex] ?? "", "utf8"));
-				const linePrefix = truncateUtf8(allLines[startIndex] ?? "", cap, "\n[line truncated]");
-				const output = `${linePrefix}\n\n[Line ${startIndex + 1} is ${firstLineSize}, exceeding the ${formatSize(cap)} read limit. Showing the UTF-8 prefix only. Use grep with a narrower literal/regex or edit with exact surrounding text; use shell access only when byte-level inspection is required.]`;
+				const label = numbered ? `${startIndex + 1} | ` : "";
+				const firstLineSize = formatSize(Buffer.byteLength(label + (allLines[startIndex] ?? ""), "utf8"));
+				const linePrefix =
+					label + truncateUtf8(allLines[startIndex] ?? "", cap - Buffer.byteLength(label), "\n[line truncated]");
+				const output = `${linePrefix}\n\n[${numbered ? "Numbered line" : "Line"} ${startIndex + 1} is ${firstLineSize}, exceeding the ${formatSize(cap)} read limit. Showing the UTF-8 prefix only. Use grep with a narrower literal/regex or edit with exact surrounding text; use shell access only when byte-level inspection is required.]`;
 				return finalizeObservation({
 					tool: ToolNames.Read,
 					unit: "lines",
@@ -144,7 +239,7 @@ export const readTool: ToolSpec = {
 			}
 			const endDisplay = startIndex + truncation.outputLines;
 			const moreAfter = endDisplay < totalLines;
-			const truncated = truncation.truncated || (limit !== null && moreAfter);
+			const truncated = sourceTruncation.truncated || truncation.truncated || (limit !== null && moreAfter);
 			return finalizeObservation({
 				tool: ToolNames.Read,
 				unit: "lines",
@@ -153,7 +248,7 @@ export const readTool: ToolSpec = {
 				totalCount: totalLines,
 				totalBytes,
 				truncated,
-				...(truncated && moreAfter ? { next: `offset=${endDisplay + 1}` } : {}),
+				...(truncated && moreAfter ? { next: `offset=${endDisplay + 1}${numbered ? " line_numbers=true" : ""}` } : {}),
 				reservation,
 				...(options ? { options } : {}),
 			});
@@ -167,6 +262,8 @@ export const readTool: ToolSpec = {
 				};
 			}
 			return { kind: "error", message: `read: ${msg}` };
+		} finally {
+			releaseObservation(reservation);
 		}
 	},
 };

package/src/tools/registry.ts

@@ -9,9 +9,10 @@ import {
 	type SkillToolSurfaceViolation,
 } from "../core/skill-activation.js";
 import { type ToolName, ToolNames } from "../core/tool-names.js";
+import { containsInstructionMarkers, INSTRUCTION_SHAPED_WARNING } from "../core/untrusted-content.js";
 import type { MiddlewareContract } from "../domains/middleware/contract.js";
 import type { MiddlewareEffect, MiddlewareHookInput, MiddlewareMetadataValue } from "../domains/middleware/types.js";
-import type { ActionClass, ClassifierCall } from "../domains/safety/action-classifier.js";
+import { type ActionClass, type ClassifierCall, webFetchIsOutward } from "../domains/safety/action-classifier.js";
 import { approvalAxisId } from "../domains/safety/approval-axis.js";
 import {
 	type AutonomyExposure,
@@ -26,6 +27,7 @@ import type { SafetyContract, SafetyDecision } from "../domains/safety/contract.
 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 type { ImageContent } from "../engine/types.js";
 import { askUserExposure } from "./ask-user.js";
 import { type DispatchPlanView, describeDispatchPlan } from "./dispatch-plan.js";
 import type { ToolPresentationPolicy } from "./presentation.js";
@@ -171,6 +173,8 @@ export type ToolResult =
 	| {
 			kind: "ok";
 			output: string;
+			/** Bounded visual evidence accompanying the mandatory text result. */
+			images?: ImageContent[];
 			details?: ToolResultDetails;
 			/** Internal registry projection consumed only by the agent-tool adapter. */
 			modelContext?: string;
@@ -214,6 +218,12 @@ export interface RegistryDeps {
 }
 
 export interface ToolInvokeOptions {
+	/** Registry-owned filter bound to the active compiled safety policy. */
+	allowsObservationPath?: (path: string) => boolean;
+	/** Trusted submitting host identity for nested dispatch; never model arguments. */
+	hostRun?: import("../domains/dispatch/contract.js").DispatchPreparationOptions["hostRun"];
+	/** Trusted resolved model capability; never read from tool arguments. */
+	supportsImages?: boolean;
 	signal?: AbortSignal;
 	runId?: string;
 	sessionId?: string;
@@ -464,7 +474,12 @@ export function createRegistry(deps: RegistryDeps): ToolRegistry {
 			try {
 				const preparedArgs = prepareToolArgs(spec, call.args ?? {});
 				resultDisposition = resolveToolResultDisposition(spec, preparedArgs);
-				const result = await spec.run(preparedArgs, options);
+				const { allowsObservationPath: _callerPathFilter, ...callerOptions } = options ?? {};
+				const allowsObservationPath = deps.safety.policy?.allowsObservationPath;
+				const result = await spec.run(preparedArgs, {
+					...callerOptions,
+					...(allowsObservationPath ? { allowsObservationPath } : {}),
+				});
 				const digest = toolResultDigestFor(spec, result, resultDisposition, options);
 				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result, digest);
 				const finalResult = shapeToolResult(spec, applyToolResultEffects(result, afterEffects), options, resultDisposition);
@@ -583,10 +598,13 @@ export function createRegistry(deps: RegistryDeps): ToolRegistry {
 				? (spec.describeDispatchPlan?.(call.args ?? {}) ?? describeDispatchPlan(call.args))
 				: null;
 		const planScale = dispatchPlan?.planScale === true;
-		// The exposure tier rides on the args of the gate that raised it, so the
-		// workflow author, not the classifier, decides what counts as outward.
-		// ask_user is the only tool that declares one today.
-		const exposure = call.tool === ToolNames.AskUser ? askUserExposure(call.args) : DEFAULT_AUTONOMY_EXPOSURE;
+		// Gates declare their tier; write-shaped HTTP requests send data outward.
+		const exposure =
+			call.tool === ToolNames.AskUser
+				? askUserExposure(call.args)
+				: call.tool === ToolNames.WebFetch && webFetchIsOutward(call.args)
+					? "outward"
+					: DEFAULT_AUTONOMY_EXPOSURE;
 		const disposition = mapAutonomy(level, actionClass, {
 			executeRecognized: decision.policy?.execRecognition !== "unrecognized",
 			...(planScale ? { dispatchPlanScale: true } : {}),
@@ -1030,10 +1048,8 @@ const HEADLESS_GUIDANCE_MAX_CHARS = 240;
  * model that hits an unrecognized-bash rail retries the same shape until the run
  * ends. An unrecognized execution decision carries the working form in its
  * reasons, and those reasons reach the audit record and the interactive approval
- * overlay but not the model. The first reason states the axis the denial already
- * implies, so only the reasons after it are candidates, and only the first of
- * those, bounded: this is a nudge toward the recognized spelling, not a dump of
- * the policy's reason list.
+ * overlay but not the model. Preserve one bounded recovery hint separately
+ * from the actual policy cause carried by the terminal denial below.
  */
 function headlessDenialGuidance(decision: SafetyDecision, reason: string): string | null {
 	// Interactive denials are left exactly as they were: the operator saw the
@@ -1059,9 +1075,9 @@ function headlessDenialGuidance(decision: SafetyDecision, reason: string): strin
  * it with the standing pivot instruction.
  *
  * A headless answer is the exception: nobody will ever approve it, so the detail
- * carries one line of recovery guidance after the denial sentence. The sentence
- * stays the detail's prefix, which the skill-eval permission-wall recognizer
- * depends on.
+ * carries the policy cause and rule, a terminal settlement statement, and any
+ * recovery guidance. The denial sentence stays the detail's prefix, which the
+ * skill-eval permission-wall recognizer depends on.
  */
 function parkAnsweredBlockedVerdict(
 	decision: SafetyDecision,
@@ -1069,12 +1085,25 @@ function parkAnsweredBlockedVerdict(
 	reason: string,
 ): Extract<RegistryVerdict, { kind: "blocked" }> {
 	const guidance = headlessDenialGuidance(decision, reason);
+	const detail = [reason];
+	if (reason.startsWith(HEADLESS_PERMISSION_DENIED_MARKER)) {
+		if (decision.policy?.ruleId) detail.push(`rule: ${decision.policy.ruleId}`);
+		const cause =
+			decision.policy?.kind === "ask"
+				? decision.policy.reasons[0]
+				: decision.kind === "allow"
+					? undefined
+					: decision.rejection.short;
+		if (cause) detail.push(cause);
+		detail.push("This call was denied; no approval is pending.");
+		if (guidance !== null) detail.push(guidance);
+	}
 	const blocked: SafetyDecision = {
 		kind: "block",
 		classification: decision.classification,
 		rejection: {
 			short: `${tool} blocked: ${decision.classification.actionClass} was not approved`,
-			detail: guidance === null ? reason : `${reason}\n${guidance}`,
+			detail: detail.join("\n"),
 			hints: [],
 		},
 		...(decision.policy !== undefined ? { policy: decision.policy } : {}),
@@ -1099,7 +1128,7 @@ function skillSurfaceBlockedVerdict(
 	const reason =
 		violation.disallowedBy.length > 0
 			? `${tool} is disallowed by the active skill(s) ${violation.disallowedBy.join(", ")} (disallowed-tools). ${lifetime} Work within the skill workflow; if it genuinely needs this step, use ask_user when available or state the blocker in your reply.`
-			: `${tool} is outside the tool surface declared by the active skill(s) ${violation.skills.join(", ")}. Tools are narrowed to: ${(violation.mergedAllowedTools ?? []).join(", ")} (plus context and ask_user). ${lifetime} Work within the skill workflow; if it genuinely needs this step, use ask_user when available or state the blocker in your reply.`;
+			: `${tool} is outside the tool surface declared by the active skill(s) ${violation.skills.join(", ")}. Tools are narrowed to: ${(violation.mergedAllowedTools ?? []).join(", ")} (plus context and ask_user). The limitation receipt is also available unless explicitly disallowed. ${lifetime} Work within the skill workflow; if it genuinely needs this step, use ask_user when available or state the blocker in your reply.`;
 	const blocked: SafetyDecision = {
 		kind: "block",
 		classification: decision.classification,
@@ -1206,6 +1235,10 @@ function buildToolHookInput(
 	}
 	if (call.tool !== spec.name) metadata.requestedToolName = call.tool;
 	if (result !== undefined) {
+		if (hook === "after_tool" && ["web_fetch", "read", "bash", "dispatch", "monitor"].includes(spec.name))
+			metadata.untrustedInstructionMarkers = containsInstructionMarkers(
+				result.kind === "ok" ? result.output : result.kind === "error" ? result.message : "",
+			);
 		metadata.resultKind = result.kind;
 		if (result.kind === "error") metadata.errorMessage = result.message;
 		if (result.kind === "ok" && result.terminate === true) metadata.terminate = true;
@@ -1259,14 +1292,18 @@ function firstBlockToolEffect(
 function applyToolResultEffects(result: ToolResult, effects: ReadonlyArray<MiddlewareEffect>): ToolResult {
 	const annotations = annotationMessages(effects);
 	if (annotations.length === 0) return result;
-	const suffix = `\n\n${annotations.join("\n")}`;
+	const warning = `[middleware:warn] ${INSTRUCTION_SHAPED_WARNING}`;
+	const prefix = annotations.includes(warning) ? `${warning}\n\n` : "";
+	const remaining = annotations.filter((annotation) => annotation !== warning);
+	const suffix = remaining.length > 0 ? `\n\n${remaining.join("\n")}` : "";
 	if (result.kind === "ok") {
-		const annotated: ToolResult = { kind: "ok", output: `${result.output}${suffix}` };
+		const annotated: ToolResult = { kind: "ok", output: `${prefix}${result.output}${suffix}` };
 		if (result.details !== undefined) annotated.details = result.details;
 		if (result.terminate === true) annotated.terminate = true;
+		if (result.images !== undefined) annotated.images = result.images;
 		return annotated;
 	}
-	const annotated: ToolResult = { kind: "error", message: `${result.message}${suffix}` };
+	const annotated: ToolResult = { kind: "error", message: `${prefix}${result.message}${suffix}` };
 	if (result.details !== undefined) annotated.details = result.details;
 	return annotated;
 }