@iowarp/clio-coder 0.4.4 → 0.4.6

package/src/tools/find.ts

@@ -8,6 +8,7 @@ import { resolveFdBinary } from "./executables.js";
 import { compileGlobRegex, fallbackIgnoredDirs, fdIgnoreArgs, normalizeGlobInput } from "./ignore-policy.js";
 import {
 	commitObservationReservation,
+	createObservationPathFilter,
 	finalizeObservation,
 	OBSERVE_SELF_CAPS,
 	type ObservationReservation,
@@ -148,6 +149,7 @@ function orderByMtime(paths: string[], searchPath: string, limit: number, candid
 }
 
 function renderFindResult(input: {
+	withheldPaths: number;
 	ordered: OrderedPaths;
 	collected: number;
 	collectLimit: number;
@@ -160,11 +162,13 @@ function renderFindResult(input: {
 	if (ordered.paths.length === 0) {
 		return finalizeObservation({
 			tool: ToolNames.Find,
+			withheldPaths: input.withheldPaths,
 			unit: "paths",
-			output: "No files found matching pattern",
+			output: "No visible files found matching pattern",
 			shownCount: 0,
-			totalCount: 0,
-			truncated: false,
+			totalCount: collected >= collectLimit ? null : 0,
+			truncated: collected >= collectLimit,
+			...(collected >= collectLimit ? { next: `limit=${limit * 2}` } : {}),
 			reservation,
 			...(options ? { options } : {}),
 		});
@@ -191,6 +195,7 @@ function renderFindResult(input: {
 	}
 	return finalizeObservation({
 		tool: ToolNames.Find,
+		withheldPaths: input.withheldPaths,
 		unit: "paths",
 		output: truncation.content,
 		// Offload only when the byte cap cut collected paths; a bare result
@@ -269,13 +274,17 @@ export const findTool: ToolSpec = {
 				}
 			}
 
+			const collectedCount = collectedPaths.length;
+			const pathFilter = createObservationPathFilter(process.cwd(), options?.allowsObservationPath);
+			collectedPaths = collectedPaths.filter((entry) => pathFilter.allows(join(searchPath, entry)));
 			const ordered: OrderedPaths =
 				order === "mtime"
 					? orderByMtime(collectedPaths, searchPath, limit, collectLimit)
 					: { paths: collectedPaths.slice(0, limit), candidateCapHit: false, candidateCap: null };
 			return renderFindResult({
+				withheldPaths: pathFilter.withheldPaths,
 				ordered,
-				collected: collectedPaths.length,
+				collected: collectedCount,
 				collectLimit,
 				limit,
 				order,

package/src/tools/grep.ts

@@ -7,6 +7,7 @@ import { resolveRgBinary } from "./executables.js";
 import { compileGlobRegex, fallbackIgnoredDirs, normalizeGlobInput, rgIgnoreArgs } from "./ignore-policy.js";
 import {
 	commitObservationReservation,
+	createObservationPathFilter,
 	finalizeObservation,
 	OBSERVE_SELF_CAPS,
 	type ObservationReservation,
@@ -67,6 +68,7 @@ interface RenderedLine {
 }
 
 interface GrepRenderInput {
+	withheldPaths: number;
 	mode: GrepMode;
 	lines: RenderedLine[];
 	matchCount: number;
@@ -90,6 +92,7 @@ function renderGrepResult(input: GrepRenderInput): ToolResult {
 	if (lines.length === 0) {
 		return finalizeObservation({
 			tool: ToolNames.Grep,
+			withheldPaths: input.withheldPaths,
 			unit: MODE_UNITS[mode],
 			output: NO_MATCH_OUTPUT,
 			shownCount: 0,
@@ -120,6 +123,7 @@ function renderGrepResult(input: GrepRenderInput): ToolResult {
 	}
 	return finalizeObservation({
 		tool: ToolNames.Grep,
+		withheldPaths: input.withheldPaths,
 		unit: MODE_UNITS[mode],
 		output,
 		// Offload only when the byte cap cut collected content; a bare match
@@ -139,6 +143,7 @@ function sanitizeMatchText(text: string): string {
 }
 
 interface RgSearchInput {
+	pathFilter: ReturnType<typeof createObservationPathFilter>;
 	rgPath: string;
 	mode: GrepMode;
 	pattern: string;
@@ -195,6 +200,7 @@ async function runRipgrep(input: RgSearchInput): Promise<ToolResult> {
 		const lineNumber = data?.line_number;
 		const lineText = (data?.lines as { text?: unknown } | undefined)?.text;
 		if (typeof filePath !== "string" || typeof lineNumber !== "number" || typeof lineText !== "string") return;
+		if (!input.pathFilter.allows(filePath)) return;
 		const { text, wasTruncated } = truncateLine(sanitizeMatchText(lineText));
 		if (wasTruncated) linesTruncated = true;
 		const isMatch = type === "match";
@@ -214,6 +220,8 @@ async function runRipgrep(input: RgSearchInput): Promise<ToolResult> {
 	const onListLine = (line: string, stop: () => void): void => {
 		const trimmed = line.replace(/\r$/, "");
 		if (trimmed.length === 0) return;
+		const filePath = input.mode === "count" ? trimmed.slice(0, trimmed.lastIndexOf(":")) : trimmed;
+		if (!input.pathFilter.allows(filePath)) return;
 		let text: string;
 		if (input.mode === "count") {
 			const sep = trimmed.lastIndexOf(":");
@@ -245,6 +253,7 @@ async function runRipgrep(input: RgSearchInput): Promise<ToolResult> {
 		return { kind: "error", message: `grep: ${result.stderr.trim() || `ripgrep exited with code ${result.exitCode}`}` };
 	}
 	return renderGrepResult({
+		withheldPaths: input.pathFilter.withheldPaths,
 		mode: input.mode,
 		lines: rendered,
 		matchCount,
@@ -279,6 +288,7 @@ function looksBinary(buffer: Buffer): boolean {
 }
 
 interface FallbackSearchInput {
+	pathFilter: ReturnType<typeof createObservationPathFilter>;
 	mode: GrepMode;
 	pattern: string;
 	searchPath: string;
@@ -328,7 +338,7 @@ function fallbackGrep(input: FallbackSearchInput): ToolResult {
 	};
 
 	const searchFile = (filePath: string): void => {
-		if (limitHit) return;
+		if (limitHit || !input.pathFilter.allows(filePath)) return;
 		let buffer: Buffer;
 		try {
 			const stat = statSync(filePath);
@@ -403,6 +413,7 @@ function fallbackGrep(input: FallbackSearchInput): ToolResult {
 	else searchFile(input.searchPath);
 	if (signal?.aborted) return { kind: "error", message: "grep: operation aborted" };
 	return renderGrepResult({
+		withheldPaths: input.pathFilter.withheldPaths,
 		mode: input.mode,
 		lines: rendered,
 		matchCount,
@@ -463,6 +474,7 @@ export const grepTool: ToolSpec = {
 			});
 		}
 		const shared = {
+			pathFilter: createObservationPathFilter(process.cwd(), options?.allowsObservationPath),
 			mode,
 			pattern,
 			searchPath,

package/src/tools/ls.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { Type } from "typebox";
 import { ToolNames } from "../core/tool-names.js";
 import {
+	createObservationPathFilter,
 	finalizeObservation,
 	OBSERVE_SELF_CAPS,
 	observationBudgetExhausted,
@@ -53,7 +54,10 @@ export const lsTool: ToolSpec = {
 		}
 
 		try {
-			const entries = readdirSync(root).sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+			const pathFilter = createObservationPathFilter(process.cwd(), options?.allowsObservationPath);
+			const entries = readdirSync(root)
+				.filter((entry) => pathFilter.allows(path.join(root, entry)))
+				.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
 			const outputEntries: string[] = [];
 			let entryLimitReached = false;
 			for (const entry of entries) {
@@ -72,6 +76,7 @@ export const lsTool: ToolSpec = {
 			if (outputEntries.length === 0) {
 				return finalizeObservation({
 					tool: ToolNames.Ls,
+					withheldPaths: pathFilter.withheldPaths,
 					unit: "entries",
 					output: "(empty directory)",
 					shownCount: 0,
@@ -90,6 +95,7 @@ export const lsTool: ToolSpec = {
 			const truncated = entryLimitReached || truncation.truncated;
 			return finalizeObservation({
 				tool: ToolNames.Ls,
+				withheldPaths: pathFilter.withheldPaths,
 				unit: "entries",
 				output: truncation.content,
 				// Offload only when the byte cap cut collected entries; a bare

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

@@ -1,6 +1,6 @@
 /**
  * Typed tool presentation policy. Answers, per tool, what the transcript's
- * balanced (`/output default`) view needs to know: does the block open folded
+ * Standard view needs to know: does the block open folded
  * or expanded, does the folded row keep a mutation diff visible, and does a
  * failed folded row carry an output excerpt.
  *

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);
 		}
 	},
 };