@iowarp/clio-coder 0.4.3 → 0.4.5

package/src/tools/verify/scripts.ts

@@ -1,17 +1,30 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { resolveSafeCwd } from "../../core/safe-exec.js";
+import { resolveSafeCwd, runCommandVector, type SafeCommandResult } from "../../core/safe-exec.js";
 import { declaredVerificationScripts, VERIFICATION_SCRIPT_FAMILY_HINT } from "../../core/verification-scripts.js";
 import type { ToolResult } from "../registry.js";
 import { runVectorTool } from "../safe-exec.js";
 import {
 	type DeclaredCheck,
 	type DeclaredCheckSource,
+	type DeclaredNumericCompare,
+	type DeclaredPerfBudget,
 	loadProjectVerifierCatalog,
 	PROJECT_VERIFIER_CATALOG_RELATIVE_PATH,
 	packageDeclaredCheck,
 	resolveProjectVerifierExecutionCwd,
 } from "./catalog.js";
+import { compareNumeric, type NumericCompareReport, parseNumericPayload, renderNumericReport } from "./numeric.js";
+import {
+	evaluatePerfBudget,
+	type PerfBaseline,
+	type PerfBudgetReport,
+	parsePerfBaseline,
+	renderPerfBaseline,
+} from "./perf.js";
+
+/** The structured verdict a numeric-compare or perf-budget check records beside the command facts. */
+export type DeclaredCheckReport = NumericCompareReport | PerfBudgetReport;
 
 /**
  * Package scripts and the project catalog meet here as one canonical check
@@ -197,6 +210,7 @@ function withDeclaredEvidence(result: ToolResult, check: DeclaredCheck): ToolRes
 			...result.details,
 			action: "verify",
 			check: check.id,
+			kind: check.kind,
 			source: { ...check.source },
 			description: check.description,
 			declaredCommand: [...check.command],
@@ -207,15 +221,228 @@ function withDeclaredEvidence(result: ToolResult, check: DeclaredCheck): ToolRes
 	};
 }
 
+/**
+ * The JSON object a numeric-compare command printed. The whole text is tried
+ * first; when the command also wrote diagnostics around it, the span from the
+ * first `{` to the last `}` is tried once more, so a preamble line does not
+ * turn a correct payload into a parse failure.
+ */
+export function extractNumericPayloadText(output: string): string {
+	const trimmed = output.trim();
+	try {
+		JSON.parse(trimmed);
+		return trimmed;
+	} catch {
+		const start = trimmed.indexOf("{");
+		const end = trimmed.lastIndexOf("}");
+		return start >= 0 && end > start ? trimmed.slice(start, end + 1) : trimmed;
+	}
+}
+
+/** Read a repository-relative check file inside the workspace root, as text. */
+function readCheckFile(workspaceRoot: string, relative: string, label: string): string | Error {
+	let resolved: string;
+	try {
+		resolved = resolveSafeCwd(relative, workspaceRoot);
+	} catch (error) {
+		return new Error(`${label} ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!existsSync(resolved)) return new Error(`${label} '${relative}' does not exist`);
+	try {
+		return readFileSync(resolved, "utf8");
+	} catch (error) {
+		return new Error(`${label} '${relative}' cannot be read (${error instanceof Error ? error.message : String(error)})`);
+	}
+}
+
+/** Judge a numeric-compare command's stdout against reference text already read from disk. Pure. */
+export function judgeNumericTexts(
+	stdout: string,
+	referenceText: string,
+	tolerance: DeclaredNumericCompare["tolerance"],
+	referenceLabel: string,
+): NumericCompareReport | Error {
+	const reference = parseNumericPayload(referenceText, referenceLabel);
+	if (reference instanceof Error) return reference;
+	const actual = parseNumericPayload(extractNumericPayloadText(stdout), "command output");
+	if (actual instanceof Error) return actual;
+	return compareNumeric(actual, reference, tolerance);
+}
+
+/** Judge a numeric-compare command's stdout against the declared reference under the workspace root. */
+function judgeNumericCompare(
+	stdout: string,
+	numeric: DeclaredNumericCompare,
+	workspaceRoot: string,
+): NumericCompareReport | Error {
+	const referenceText = readCheckFile(workspaceRoot, numeric.reference, "reference");
+	if (referenceText instanceof Error) return referenceText;
+	return judgeNumericTexts(stdout, referenceText, numeric.tolerance, `reference '${numeric.reference}'`);
+}
+
+/** Judge a measured wall time against a budget, or against baseline text already read from disk. Pure. */
+export function judgePerfTexts(
+	measuredMs: number,
+	perf: DeclaredPerfBudget,
+	baselineText: string | undefined,
+	baselineLabel: string,
+): PerfBudgetReport | Error {
+	let baseline: PerfBaseline | undefined;
+	if (perf.baseline !== undefined) {
+		if (baselineText === undefined) {
+			return new Error(`${baselineLabel} is missing; record it with \`clio-coder verifiers baseline <id>\``);
+		}
+		const parsed = parsePerfBaseline(baselineText, baselineLabel);
+		if (parsed instanceof Error) return parsed;
+		baseline = parsed;
+	}
+	return evaluatePerfBudget(measuredMs, {
+		...(perf.budget !== undefined ? { budget: perf.budget } : {}),
+		...(baseline !== undefined ? { baseline } : {}),
+		...(perf.tolerance?.relative !== undefined ? { relative: perf.tolerance.relative } : {}),
+	});
+}
+
+/** Judge a measured wall time against the declared budget or the recorded baseline under the workspace root. */
+function judgePerfBudget(
+	measuredMs: number,
+	perf: DeclaredPerfBudget,
+	workspaceRoot: string,
+): PerfBudgetReport | Error {
+	let baselineText: string | undefined;
+	if (perf.baseline !== undefined) {
+		const text = readCheckFile(workspaceRoot, perf.baseline, "baseline");
+		if (text instanceof Error) {
+			return new Error(`${text.message}; record it with \`clio-coder verifiers baseline <id>\``);
+		}
+		baselineText = text;
+	}
+	return judgePerfTexts(measuredMs, perf, baselineText, `baseline '${perf.baseline ?? ""}'`);
+}
+
+function commandFacts(result: SafeCommandResult): Record<string, unknown> {
+	return {
+		command: [result.file, ...result.args].join(" "),
+		argv: [result.file, ...result.args],
+		cwd: result.cwd,
+		exitCode: result.exitCode,
+		durationMs: result.durationMs,
+		aborted: result.aborted,
+		timedOut: result.timedOut,
+		outputCapped: result.outputCapped,
+	};
+}
+
+/**
+ * Run a numeric-compare or perf-budget check: the command through the same
+ * safe-exec spine as a command check, then the pure judgement. A command that
+ * exits non-zero, times out, or is aborted fails before any comparison, so a
+ * crashed validator never reads as a tolerance verdict.
+ */
+async function runJudgedCheck(
+	check: DeclaredCheck,
+	file: string,
+	vector: ReadonlyArray<string>,
+	cwd: string,
+	options?: { signal?: AbortSignal },
+): Promise<ToolResult> {
+	let result: SafeCommandResult;
+	try {
+		result = await runCommandVector(file, vector, {
+			cwd,
+			timeoutMs: check.timeoutMs,
+			...(options?.signal !== undefined ? { signal: options.signal } : {}),
+		});
+	} catch (error) {
+		return { kind: "error", message: `verify: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	const facts = commandFacts(result);
+	const tail = `${result.stdout}${result.stderr}`.trim().slice(-2_000);
+	if (result.aborted) return { kind: "error", message: "verify: aborted", details: facts };
+	if (result.timedOut) return { kind: "error", message: `verify: timed out after ${check.timeoutMs}ms`, details: facts };
+	if (result.exitCode !== 0) {
+		return {
+			kind: "error",
+			message: `verify: ${check.kind} command exited with code ${result.exitCode ?? "?"} before judgement: ${tail}`,
+			details: facts,
+		};
+	}
+	const report =
+		check.kind === "numeric-compare" && check.numeric !== undefined
+			? judgeNumericCompare(result.stdout, check.numeric, process.cwd())
+			: check.kind === "perf-budget" && check.perf !== undefined
+				? judgePerfBudget(result.durationMs, check.perf, process.cwd())
+				: new Error(`declared check '${check.id}' has kind ${check.kind} without its parameters`);
+	if (report instanceof Error) return { kind: "error", message: `verify: ${report.message}`, details: facts };
+	const rendered = report.kind === "numeric-compare" ? renderNumericReport(report) : report.summary;
+	const details = { ...facts, report };
+	if (!report.passed) return { kind: "error", message: `verify: ${rendered}`, details };
+	return { kind: "ok", output: `${rendered}\n`, details };
+}
+
 export async function runProjectCheck(check: DeclaredCheck, options?: { signal?: AbortSignal }): Promise<ToolResult> {
 	const [file, ...vector] = check.command;
 	if (file === undefined) return { kind: "error", message: `verify: declared check '${check.id}' has empty argv` };
 	const cwd = resolveProjectVerifierExecutionCwd(check.cwd, process.cwd());
 	if (cwd instanceof Error) return { kind: "error", message: `verify: ${cwd.message}` };
+	if (check.kind !== "command") {
+		return withDeclaredEvidence(await runJudgedCheck(check, file, vector, cwd, options), check);
+	}
 	const result = await runVectorTool("verify", file, vector, { cwd, timeout_ms: check.timeoutMs }, options);
 	return withDeclaredEvidence(result, check);
 }
 
+/**
+ * Run a perf-budget check once and write its wall time as the baseline the
+ * check's `baseline` path names. The command must exit cleanly; a failed run
+ * records nothing, so a baseline never encodes a broken command's timing.
+ */
+export async function recordPerfBaseline(
+	check: DeclaredCheck,
+	options?: { signal?: AbortSignal; now?: () => Date },
+): Promise<{ ok: true; path: string; wallTimeMs: number } | { ok: false; message: string }> {
+	if (check.kind !== "perf-budget" || check.perf?.baseline === undefined) {
+		return { ok: false, message: `check '${check.id}' is not a perf-budget check with a baseline path` };
+	}
+	const [file, ...vector] = check.command;
+	if (file === undefined) return { ok: false, message: `declared check '${check.id}' has empty argv` };
+	const cwd = resolveProjectVerifierExecutionCwd(check.cwd, process.cwd());
+	if (cwd instanceof Error) return { ok: false, message: cwd.message };
+	let result: SafeCommandResult;
+	try {
+		result = await runCommandVector(file, vector, {
+			cwd,
+			timeoutMs: check.timeoutMs,
+			...(options?.signal !== undefined ? { signal: options.signal } : {}),
+		});
+	} catch (error) {
+		return { ok: false, message: error instanceof Error ? error.message : String(error) };
+	}
+	if (result.aborted || result.timedOut || result.exitCode !== 0) {
+		return {
+			ok: false,
+			message: `command ${result.timedOut ? "timed out" : result.aborted ? "was aborted" : `exited with code ${result.exitCode ?? "?"}`}; no baseline recorded`,
+		};
+	}
+	let target: string;
+	try {
+		target = resolveSafeCwd(check.perf.baseline, process.cwd());
+	} catch (error) {
+		return { ok: false, message: `baseline ${error instanceof Error ? error.message : String(error)}` };
+	}
+	const recordedAt = (options?.now?.() ?? new Date()).toISOString();
+	try {
+		mkdirSync(path.dirname(target), { recursive: true });
+		writeFileSync(target, renderPerfBaseline({ wallTimeMs: result.durationMs, check: check.id, recordedAt }), "utf8");
+	} catch (error) {
+		return {
+			ok: false,
+			message: `cannot write baseline '${check.perf.baseline}' (${error instanceof Error ? error.message : String(error)})`,
+		};
+	}
+	return { ok: true, path: check.perf.baseline, wallTimeMs: result.durationMs };
+}
+
 export async function runScriptCheck(
 	check: string,
 	args: Record<string, unknown>,

package/src/tools/web-fetch-network.ts

@@ -0,0 +1,179 @@
+import { lookup } from "node:dns/promises";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { BlockList, isIP } from "node:net";
+import { Readable } from "node:stream";
+import { createBrotliDecompress, createGunzip, createInflate } from "node:zlib";
+import { WEB_FETCH_ALLOW_PRIVATE_NETWORK_ENV } from "./network-policy.js";
+
+const blocked = new BlockList();
+for (const [address, prefix] of [
+	["0.0.0.0", 8],
+	["10.0.0.0", 8],
+	["100.64.0.0", 10],
+	["127.0.0.0", 8],
+	["169.254.0.0", 16],
+	["172.16.0.0", 12],
+	["192.168.0.0", 16],
+	["192.0.0.0", 24],
+	["192.0.2.0", 24],
+	["198.18.0.0", 15],
+	["198.51.100.0", 24],
+	["203.0.113.0", 24],
+	["224.0.0.0", 4],
+	["240.0.0.0", 4],
+] as const)
+	blocked.addSubnet(address, prefix, "ipv4");
+// Permit only global unicast IPv6. Block transition mechanisms that can embed
+// an IPv4 destination and local/documentation allocations within that range.
+for (const [address, prefix] of [
+	["2001::", 32],
+	["2001:db8::", 32],
+	["2002::", 16],
+] as const)
+	blocked.addSubnet(address, prefix, "ipv6");
+const globalV6 = new BlockList();
+globalV6.addSubnet("2000::", 3, "ipv6");
+export function isPublicWebAddress(address: string): boolean {
+	const family = isIP(address);
+	if (family === 4) return !blocked.check(address, "ipv4");
+	return family === 6 && globalV6.check(address, "ipv6") && !blocked.check(address, "ipv6");
+}
+
+export class WebFetchNetworkError extends Error {
+	constructor(message: string) {
+		super(`WEB_FETCH_PRIVATE_NETWORK: ${message}`);
+		this.name = "WebFetchNetworkError";
+	}
+}
+
+interface Address {
+	address: string;
+	family: number;
+}
+export interface WebFetchNetworkDependencies {
+	resolve?: (hostname: string) => Promise<Address[]>;
+	request?: (url: URL, init: RequestInit, address: Address) => Promise<Response>;
+	allowPrivateNetwork?: boolean;
+}
+
+/** Pin the checked address in the socket lookup while retaining the URL host
+ * for Host, TLS SNI and certificate verification. No second DNS resolution,
+ * proxy, pooled socket, or automatic redirect can bypass admission. */
+async function requestPinnedWebUrl(url: URL, init: RequestInit, address: Address): Promise<Response> {
+	return new Promise((resolve, reject) => {
+		const headers = new Headers(init.headers);
+		headers.delete("host");
+		const request = (url.protocol === "https:" ? httpsRequest : httpRequest)(
+			url,
+			{
+				method: init.method ?? "GET",
+				headers: Object.fromEntries(headers),
+				agent: false,
+				...(init.signal ? { signal: init.signal } : {}),
+				lookup: (_hostname, options, callback) => {
+					if (options.all) callback(null, [address]);
+					else callback(null, address.address, address.family);
+				},
+			},
+			(response) => {
+				const responseHeaders = new Headers();
+				for (const [key, value] of Object.entries(response.headers)) {
+					if (value !== undefined) responseHeaders.set(key, Array.isArray(value) ? value.join(", ") : value);
+				}
+				const status = response.statusCode ?? 500;
+				let stream: Readable = response;
+				const encoding = responseHeaders.get("content-encoding");
+				const decoder =
+					encoding === "gzip"
+						? createGunzip()
+						: encoding === "br"
+							? createBrotliDecompress()
+							: encoding === "deflate"
+								? createInflate()
+								: null;
+				if (decoder) {
+					response.on("error", (error) => decoder.destroy(error));
+					decoder.on("close", () => response.destroy());
+					stream = response.pipe(decoder);
+					responseHeaders.delete("content-encoding");
+					responseHeaders.delete("content-length");
+				}
+				const noBody = init.method === "HEAD" || [204, 205, 304].includes(status);
+				if (noBody) response.resume();
+				const result = new Response(noBody ? null : (Readable.toWeb(stream) as ReadableStream<Uint8Array>), {
+					status,
+					statusText: response.statusMessage ?? "",
+					headers: responseHeaders,
+				});
+				Object.defineProperty(result, "url", { value: url.toString() });
+				resolve(result);
+			},
+		);
+		request.on("error", reject);
+		request.end(typeof init.body === "string" ? init.body : undefined);
+	});
+}
+
+/** DNS lookup itself is not cancellable; stop awaiting it on turn cancellation. */
+async function abortableLookup(
+	pending: Promise<Address[]>,
+	signal: AbortSignal | null | undefined,
+): Promise<Address[]> {
+	if (!signal) return pending;
+	signal.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		const onAbort = (): void => reject(signal.reason);
+		signal.addEventListener("abort", onAbort, { once: true });
+		pending.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+	});
+}
+
+/** Every hop, including helper URLs, resolves and validates before connecting. */
+export async function fetchWebUrl(
+	input: string | URL,
+	initial: RequestInit = {},
+	dependencies: WebFetchNetworkDependencies = {},
+): Promise<Response> {
+	let url = new URL(input);
+	const init = { ...initial, headers: new Headers(initial.headers) };
+	const allowPrivate = dependencies.allowPrivateNetwork ?? process.env[WEB_FETCH_ALLOW_PRIVATE_NETWORK_ENV] === "1";
+	for (let hop = 0; hop <= 10; hop++) {
+		init.signal?.throwIfAborted();
+		if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+			throw new Error("web_fetch: unsupported URL scheme or embedded credentials");
+		const hostname = url.hostname.replace(/^\[|\]$/g, "");
+		const addresses = isIP(hostname)
+			? [{ address: hostname, family: isIP(hostname) }]
+			: await abortableLookup((dependencies.resolve ?? ((host) => lookup(host, { all: true })))(hostname), init.signal);
+		init.signal?.throwIfAborted();
+		const address = addresses[0];
+		if (address === undefined) throw new Error("web_fetch: DNS returned no addresses");
+		if (!allowPrivate && addresses.some((address) => !isPublicWebAddress(address.address)))
+			throw new WebFetchNetworkError(
+				`destination ${url.hostname} is not public; operator opt-in ${WEB_FETCH_ALLOW_PRIVATE_NETWORK_ENV}=1 is required`,
+			);
+		const response = await (dependencies.request ?? requestPinnedWebUrl)(url, init, address);
+		const location = response.headers.get("location");
+		if (![301, 302, 303, 307, 308].includes(response.status) || location === null) return response;
+		await response.body?.cancel();
+		if (hop === 10) throw new Error("web_fetch: too many redirects");
+		const next = new URL(location, url);
+		if (next.origin !== url.origin) {
+			// Custom headers can carry credentials too. A cross-origin redirect gets
+			// no caller headers; the target still receives the ordinary Host header.
+			init.headers = new Headers();
+		}
+		if (
+			(response.status === 303 && init.method !== "HEAD") ||
+			([301, 302].includes(response.status) && init.method === "POST")
+		) {
+			init.method = "GET";
+			delete init.body;
+			init.headers.delete("content-type");
+			init.headers.delete("content-length");
+		}
+		url = next;
+	}
+	throw new Error("web_fetch: too many redirects");
+}

package/src/tools/web-fetch-surface.ts

@@ -4,7 +4,8 @@ import type { ToolSurface } from "./lazy-tool.js";
 
 export const webFetchToolSurface = {
 	name: ToolNames.WebFetch,
-	description: "Fetch an http(s) URL; HTML is cleaned and converted to Markdown. Non-2xx responses are errors.",
+	description:
+		"Fetch an http(s) URL; HTML is cleaned and converted to Markdown. Non-2xx responses are errors. Non-GET/HEAD methods or any body require outward-action approval; private networks require operator opt-in.",
 	parameters: Type.Object({
 		url: Type.String({ description: "Fully-qualified http(s) URL." }),
 		method: Type.Optional(Type.String({ description: "HTTP method (default GET)." })),

package/src/tools/web-fetch.ts

@@ -1,5 +1,7 @@
+import { UNTRUSTED_CONTENT_BANNER } from "../core/untrusted-content.js";
 import type { ToolResult, ToolSpec } from "./registry.js";
 import { truncateUtf8 } from "./truncate-utf8.js";
+import { fetchWebUrl } from "./web-fetch-network.js";
 import { webFetchToolSurface } from "./web-fetch-surface.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -374,7 +376,7 @@ async function fetchArxivPaperSummary(
 	maxBytes: number,
 ): Promise<ToolResult | null> {
 	const metadataUrl = `https://export.arxiv.org/api/query?id_list=${encodeURIComponent(paperId)}`;
-	const response = await fetch(metadataUrl, init);
+	const response = await fetchWebUrl(metadataUrl, init);
 	if (response.status < 200 || response.status >= 300) return null;
 	const read = await readResponseText(response, Math.min(120_000, maxBytes));
 	const entry = /<entry\b[^>]*>([\s\S]*?)<\/entry>/i.exec(read.text)?.[1];
@@ -384,7 +386,7 @@ async function fetchArxivPaperSummary(
 	let alphaxivRead: ReadResult | null = null;
 	const alphaUrl = `https://alphaxiv.org/overview/${encodeURIComponent(paperId)}.md`;
 	try {
-		const alpha = await fetch(alphaUrl, init);
+		const alpha = await fetchWebUrl(alphaUrl, init);
 		if (alpha.status >= 200 && alpha.status < 300) {
 			alphaxivRead = await readResponseText(alpha, Math.min(80_000, Math.max(0, maxBytes - read.bytesRead)));
 			if (alphaxivRead.text.trim().length > 0) paper.alphaxivOverview = alphaxivRead.text.trim();
@@ -416,7 +418,7 @@ async function fetchArxivPaperSummary(
 	const bytesRead = read.bytesRead + (alphaxivRead?.bytesRead ?? 0);
 	return {
 		kind: "ok",
-		output: truncate(lines.join("\n"), maxBytes),
+		output: truncate(`${UNTRUSTED_CONTENT_BANNER}\n${lines.join("\n")}`, maxBytes),
 		details: {
 			url: `https://arxiv.org/abs/${paper.id}`,
 			status: 200,
@@ -437,7 +439,7 @@ async function fetchArxivApiSummary(
 	init: Parameters<typeof fetch>[1],
 	maxBytes: number,
 ): Promise<ToolResult | null> {
-	const response = await fetch(url, init);
+	const response = await fetchWebUrl(url, init);
 	if (response.status < 200 || response.status >= 300) return null;
 	const read = await readResponseText(response, Math.min(240_000, maxBytes));
 	const entries = Array.from(read.text.matchAll(/<entry\b[^>]*>([\s\S]*?)<\/entry>/gi))
@@ -469,7 +471,7 @@ async function fetchArxivApiSummary(
 	}
 	return {
 		kind: "ok",
-		output: truncate(lines.join("\n"), maxBytes),
+		output: truncate(`${UNTRUSTED_CONTENT_BANNER}\n${lines.join("\n")}`, maxBytes),
 		details: {
 			url: url.toString(),
 			status: 200,
@@ -553,7 +555,7 @@ async function fetchRepoTreeSummary(
 	init: Parameters<typeof fetch>[1],
 	maxBytes: number,
 ): Promise<ToolResult | null> {
-	const apiResponse = await fetch(target.apiUrl, init);
+	const apiResponse = await fetchWebUrl(target.apiUrl, init);
 	if (apiResponse.status < 200 || apiResponse.status >= 300) return null;
 	const apiRead = await readResponseText(apiResponse, Math.min(200_000, maxBytes));
 	let entries: unknown[];
@@ -581,7 +583,7 @@ async function fetchRepoTreeSummary(
 	for (const file of files) {
 		if (remaining <= 2000) break;
 		const rawUrl = `${target.rawBaseUrl}/${file}`;
-		const rawResponse = await fetch(rawUrl, init);
+		const rawResponse = await fetchWebUrl(rawUrl, init);
 		if (rawResponse.status < 200 || rawResponse.status >= 300) continue;
 		const rawRead = await readResponseText(rawResponse, Math.min(80_000, remaining));
 		sections.push("", `--- ${file} ---`, rawRead.text.trim());
@@ -589,7 +591,7 @@ async function fetchRepoTreeSummary(
 	}
 	return {
 		kind: "ok",
-		output: truncate(sections.join("\n"), maxBytes),
+		output: truncate(`${UNTRUSTED_CONTENT_BANNER}\n${sections.join("\n")}`, maxBytes),
 		details: {
 			url: target.apiUrl,
 			status: 200,
@@ -621,7 +623,7 @@ function formatOutput(args: {
 	if (args.extracted.description) lines.push(`Description: ${args.extracted.description}`);
 	if (args.extracted.canonical) lines.push(`Canonical: ${args.extracted.canonical}`);
 	lines.push("", "Content:", args.extracted.content || "[empty]");
-	return truncate(lines.join("\n"), args.maxBytes);
+	return truncate(`${UNTRUSTED_CONTENT_BANNER}\n${lines.join("\n")}`, args.maxBytes);
 }
 
 export const webFetchTool: ToolSpec = {
@@ -683,10 +685,10 @@ export const webFetchTool: ToolSpec = {
 				method,
 				headers,
 				signal: controller.signal,
-				redirect: "follow",
+				redirect: "manual",
 			};
 			if (body !== undefined) init.body = body;
-			if (method === "GET" && body === undefined && format !== "raw") {
+			if (method === "GET" && body === undefined && format !== "raw" && Object.keys(userHeaders).length === 0) {
 				if (arxivApiUrl(parsed)) {
 					const arxivApiSummary = await fetchArxivApiSummary(parsed, init, maxBytes);
 					if (arxivApiSummary) return arxivApiSummary;
@@ -702,7 +704,7 @@ export const webFetchTool: ToolSpec = {
 					if (repoSummary) return repoSummary;
 				}
 			}
-			const response = await fetch(parsed, init);
+			const response = await fetchWebUrl(parsed, init);
 			const contentType = headerValue(response, "content-type");
 			const readLimit =
 				response.status >= 200 && response.status < 300 ? maxBytes : Math.min(ERROR_PREVIEW_BYTES, maxBytes);
@@ -711,7 +713,7 @@ export const webFetchTool: ToolSpec = {
 				const preview = extractWebFetchContent(read.text, contentType, response.url || parsed.toString(), "auto").content;
 				return {
 					kind: "error",
-					message: `web_fetch: HTTP ${response.status}: ${response.statusText}${preview ? `\nPreview:\n${truncate(preview, ERROR_PREVIEW_BYTES)}` : ""}`,
+					message: `web_fetch: HTTP ${response.status}: ${response.statusText}${preview ? `\n${UNTRUSTED_CONTENT_BANNER}\nPreview:\n${truncate(preview, ERROR_PREVIEW_BYTES)}` : ""}`,
 				};
 			}
 			if (isProbablyBinary(contentType, read.text)) {

package/src/tools/worker-evidence.ts

@@ -1,4 +1,5 @@
 import { mentionsWorkerToolCallCap } from "../core/guardrails.js";
+import { RESULT_SUMMARY_MAX_BYTES_CEILING, resultContractAuthorship } from "../domains/agents/result-contract.js";
 import {
 	formatBudgetPolicy,
 	formatBudgetReasons,
@@ -158,6 +159,7 @@ export function receiptEvidenceLabels(
 	return [
 		...canonical,
 		`receipt_integrity=verified/v${receipt.integrity.version}/${receipt.integrity.algorithm}`,
+		...documenterDeliveryLabels(receipt),
 		`evidence_verification=${verification.state}/${verification.basis}`,
 		`host_verification=${receipt.hostVerification?.status ?? "not_requested"}`,
 		...(responseModelIdObservation ? [responseModelIdObservation] : []),
@@ -170,6 +172,31 @@ export function receiptEvidenceLabels(
 	];
 }
 
+/** Delivery guidance uses only an authenticated, terminal mutation report. */
+function documenterDeliveryLabels(receipt: RunReceipt): string[] {
+	if (
+		receipt.agentId !== "documenter" ||
+		!receipt.quality.resultContract?.sourceId.startsWith("agent-result-contract:mutation-report:")
+	)
+		return [];
+	const output = receipt.output;
+	// Read at the ceiling: the receipt already sealed conformance under the
+	// run's own allowance, which this reader does not know; any conforming
+	// summary is within the ceiling, and a reader that re-applied the default
+	// would report a delivered 20 KB summary as absent.
+	const summary =
+		output?.state === "final"
+			? resultContractAuthorship(
+					{ kind: "mutation-report", maxSummaryBytes: RESULT_SUMMARY_MAX_BYTES_CEILING },
+					output.text,
+				).summary
+			: null;
+	return [
+		`terminal Documenter result: ${summary === null ? "no inline summary is available" : "the inline deliverable or limitation is in output.text JSON field summary"}. Execution success and contract conformance alone do not prove the requested explanation was delivered.`,
+		"Read the summary or the task-authorized artifact once and check it against the requested deliverable. If it is absent, incomplete, or states a limitation, report the specific limitation and the run ID; do not repeatedly read this unchanged terminal receipt or poll it for new output. Keep any separately authorized recovery and its outcome distinct from the original run.",
+	];
+}
+
 /**
  * The compact projection first, then the canonical axis line, both from the
  * shared projection so the dispatch and monitor text can never spell a state