@iowarp/clio-coder 0.4.4 → 0.4.5

package/src/tools/result-shaping.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { mkdirSync, readdirSync, rmdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
+import { INSTRUCTION_SHAPED_WARNING } from "../core/untrusted-content.js";
 import { clioStateDir } from "../core/xdg.js";
 import type { ToolInvokeOptions, ToolResult, ToolResultDetails, ToolSpec } from "./registry.js";
 import {
@@ -24,7 +25,10 @@ const RESULT_OFFLOAD_MAX_BYTES = 10 * 1024 * 1024;
 const TAIL_NOTICE_RESERVE_BYTES = 512;
 export const TOOL_OFFLOAD_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
 
-type ToolResultShapeContext = Pick<ToolInvokeOptions, "sessionId" | "toolCallId" | "toolResultMaxBytes">;
+type ToolResultShapeContext = Pick<
+	ToolInvokeOptions,
+	"sessionId" | "toolCallId" | "toolResultMaxBytes" | "supportsImages"
+>;
 
 function mergeDetails(details: ToolResultDetails | undefined, resultSize: Record<string, unknown>): ToolResultDetails {
 	return { ...(details ?? {}), resultSize };
@@ -419,7 +423,7 @@ function withOffloadMetadata(
  * Apply legacy shaping or one declared canonical disposition. Registry calls
  * this once, after middleware annotations have produced the terminal result.
  */
-export function shapeToolResult(
+function shapeTextToolResultBody(
 	spec: ToolSpec,
 	result: ToolResult,
 	context?: ToolResultShapeContext,
@@ -519,3 +523,107 @@ export function shapeToolResult(
 		modelContext: projection.text,
 	};
 }
+
+/** Keep the harness warning visible even when the chosen projection omits the source body. */
+function shapeTextToolResult(
+	spec: ToolSpec,
+	result: ToolResult,
+	context?: ToolResultShapeContext,
+	requestedDisposition?: ToolResultDisposition,
+): ToolResult {
+	const shaped = shapeTextToolResultBody(spec, result, context, requestedDisposition);
+	const warning = `[middleware:warn] ${INSTRUCTION_SHAPED_WARNING}`;
+	if (!resultText(result).includes(warning)) return shaped;
+	const hardMaxBytes = maxBytesFor(spec, context);
+	const disposition = normalizeToolResultDisposition(spec, hardMaxBytes, requestedDisposition);
+	const preserve = (text: string, cap: number, tail: boolean): string => {
+		if (text.startsWith(warning) && byteLength(text) <= cap) return text;
+		const prefix = `${warning}\n\n`;
+		const remainder = text.split(warning).join("").trimStart();
+		const allowance = Math.max(0, cap - byteLength(prefix));
+		if (allowance === 0) return truncateUtf8(warning, cap, "");
+		const body = tail
+			? truncateTail(remainder, { maxBytes: allowance, maxLines: Number.MAX_SAFE_INTEGER }).content
+			: truncateUtf8(remainder, allowance, "");
+		return prefix + body;
+	};
+	const output = preserve(
+		resultText(shaped),
+		Math.min(hardMaxBytes, disposition?.presentation.maxBytes ?? hardMaxBytes),
+		disposition?.presentation.overflow === "tail",
+	);
+	const modelContext =
+		shaped.modelContext === undefined
+			? undefined
+			: preserve(
+					shaped.modelContext,
+					Math.min(hardMaxBytes, disposition?.context.maxBytes ?? hardMaxBytes),
+					disposition?.context.mode === "bounded" && disposition.context.excerpt === "tail",
+				);
+	const previous = existingDisposition(shaped.details);
+	const details = { ...shaped.details };
+	if (previous !== null)
+		details.resultDisposition = {
+			...previous,
+			presentation: { ...previous.presentation, content: output },
+			displayedBytes: byteLength(output),
+			contextBytes: byteLength(modelContext ?? output),
+			presentationTruncated: previous.presentationTruncated || byteLength(resultText(shaped)) > byteLength(output),
+			contextTruncated:
+				previous.contextTruncated || byteLength(shaped.modelContext ?? "") > byteLength(modelContext ?? ""),
+		};
+	const size = detailsRecord(shaped.details, "resultSize");
+	if (size !== null) details.resultSize = { ...size, shownBytes: byteLength(output) };
+	return {
+		...shaped,
+		...(shaped.kind === "ok" ? { output } : { message: output }),
+		...(modelContext === undefined ? {} : { modelContext }),
+		details,
+	};
+}
+
+/** Image bytes share the same payload cap as text, including after annotation. */
+export function shapeToolResult(
+	spec: ToolSpec,
+	result: ToolResult,
+	context?: ToolResultShapeContext,
+	requestedDisposition?: ToolResultDisposition,
+): ToolResult {
+	if (result.kind !== "ok" || !result.images?.length)
+		return shapeTextToolResult(spec, result, context, requestedDisposition);
+	const hardMaxBytes = maxBytesFor(spec, context);
+	const disposition = normalizeToolResultDisposition(spec, hardMaxBytes, requestedDisposition);
+	const maxBytes = Math.min(hardMaxBytes, disposition?.context.maxBytes ?? hardMaxBytes);
+	const images: NonNullable<typeof result.images> = [];
+	let imageBytes = 0;
+	for (const image of result.images) {
+		const bytes = byteLength(image.data);
+		if (
+			context?.supportsImages === true &&
+			disposition?.context.mode !== "metadata-only" &&
+			bytes + imageBytes < maxBytes - 512
+		) {
+			images.push(image);
+			imageBytes += bytes;
+		}
+	}
+	const omitted = result.images.length - images.length;
+	const notice =
+		omitted > 0 ? `[${omitted} image(s) omitted: model capability, context policy, or tool result byte cap.]\n` : "";
+	const remaining = Math.max(1, maxBytes - imageBytes);
+	const shaped = shapeTextToolResult(
+		spec,
+		{ ...result, output: notice + result.output, images },
+		{ ...context, toolResultMaxBytes: remaining },
+		requestedDisposition,
+	);
+	if (shaped.kind !== "ok") return shaped;
+	// Legacy truncation notices may extend beyond their text allowance; the image
+	// envelope has a strict combined cap, so bound the final projections too.
+	return {
+		...shaped,
+		images,
+		output: truncateUtf8(shaped.output, remaining, ""),
+		...(shaped.modelContext === undefined ? {} : { modelContext: truncateUtf8(shaped.modelContext, remaining, "") }),
+	};
+}

package/src/tools/tasks.ts

@@ -47,7 +47,8 @@ function waitingTrailer(tasks: ReadonlyArray<UserTask>): string[] {
 		.filter((task) => task.status === "open" || task.status === "handed")
 		.map(
 			(task) =>
-				`operator tasks waiting: ${task.id} ${JSON.stringify(task.title)} — pick up with action="pick" id="${task.id}"`,
+				`operator tasks waiting: ${task.id} ${JSON.stringify(task.title)} — durable status=${task.status}; ` +
+				`not completed; pick only if this is the intended operator task, with action="pick" id="${task.id}" before work`,
 		);
 }
 
@@ -60,13 +61,30 @@ function renderTaskBoardText(board: TaskBoardSnapshot, userTasks: ReadonlyArray<
 		if (task.status === "blocked" && task.reason) line += ` — blocked: ${task.reason}`;
 		if (task.status === "cancelled" && task.reason) line += ` — dropped: ${task.reason}`;
 		lines.push(line);
-		const outputs = userTasks.find((item) => item.id === task.userTaskId)?.acceptance?.expectedOutputs;
+		const operatorTask = userTasks.find((item) => item.id === task.userTaskId);
+		if (task.userTaskId) {
+			lines.push(
+				`  operator task ${task.userTaskId}: durable status=${operatorTask?.status ?? "unavailable"}; ` +
+					`session=${operatorTask?.handedSessionId ?? "unlinked"}; board task=${operatorTask?.boardTaskId ?? "unlinked"}`,
+			);
+		}
+		const outputs = operatorTask?.acceptance?.expectedOutputs;
 		if (outputs?.length) lines.push(`  expected outputs: ${outputs.join(", ")}`);
-		for (const item of task.requiredValidationEvidence ?? [])
-			lines.push(`  acceptance: ${item.command} (${item.status}; ${item.notes})`);
+		for (const item of task.requiredValidationEvidence ?? []) {
+			if (item.status === "required") {
+				lines.push(
+					`  acceptance requirement: ${item.command} (${item.notes}; declaration only; execution status is in verification receipts)`,
+				);
+			} else {
+				lines.push(`  acceptance: ${item.command} (${item.status}; ${item.notes})`);
+			}
+		}
 	}
 	if (counts.open > 0 && counts.active === 0) {
-		lines.push(`next: start a task with action="start" before working it`);
+		lines.push(
+			`next: start only an authorized task with action="start" before working it; ` +
+				`block proposed implementation with a note naming the pending operator decision, or drop it, and wait`,
+		);
 	}
 	lines.push(...waitingTrailer(userTasks));
 	return lines.join("\n");
@@ -145,7 +163,12 @@ export function createTasksTool(deps: TasksToolDeps): ToolSpec {
 			"pick moves one operator task uN onto the board; start marks one task active (the current focus); " +
 			"done completes a task (started or still pending) and requires note as the " +
 			"evidence the work actually finished; block parks it with a required reason; drop cancels it; list shows the board. " +
-			"Work that did not happen is blocked or dropped, never done.",
+			"For an operator handoff, pick the intended uN before work and use its returned linked tN; CLI hand alone does not pick it. " +
+			"Never pick unrelated inbox tasks. Before claiming operator completion, list and confirm the linked board row is completed " +
+			"and the durable operator status is done with the same session/board link; report those IDs and actual states. " +
+			"Work that did not happen is blocked or dropped, never done. A self-created plan is not operator authorization. " +
+			"For proposal-only work, block deferred implementation with note naming the pending operator decision, or drop it; " +
+			"wait for an explicit operator go-ahead before start or implementation. A skill-install choice does not grant that go-ahead.",
 		parameters: Type.Object({
 			action: StringEnum(TASKS_ACTIONS, { description: "Board action." }),
 			title: Type.Optional(Type.String({ description: "Board title (plan)." })),
@@ -192,7 +215,10 @@ export function createTasksTool(deps: TasksToolDeps): ToolSpec {
 			if (typedAction === "list") {
 				const board = deps.board.snapshot();
 				if (!board) {
-					const output = ['no task board yet; declare one with action="plan"', ...waitingTrailer(userTasks)].join("\n");
+					const output = [
+						'no task board yet; for an operator handoff, pick the intended uN before work; otherwise declare one with action="plan"',
+						...waitingTrailer(userTasks),
+					].join("\n");
 					return {
 						kind: "ok",
 						output,

package/src/tools/verify/frontend.ts

@@ -3,10 +3,12 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { Script } from "node:vm";
+import { prepareBoundedImage } from "../../core/file-references.js";
 import { combineSafeOutput, runCommandVector } from "../../core/safe-exec.js";
+import type { ImageContent } from "../../engine/types.js";
 import { escapeRegExp } from "../ignore-policy.js";
 import { resolveReadPath } from "../path-utils.js";
-import type { ToolResult, ToolResultDetails } from "../registry.js";
+import type { ToolInvokeOptions, ToolResult, ToolResultDetails } from "../registry.js";
 import { maxOutputArg, timeoutArg } from "../safe-exec.js";
 import { truncateUtf8 } from "../truncate-utf8.js";
 import { BROWSER_MODES } from "./surface.js";
@@ -25,6 +27,9 @@ interface FrontendCheck {
 }
 
 interface ValidationOptions {
+	supportsImages?: boolean;
+	imageMaxBytes?: number;
+	images?: ImageContent[];
 	timeoutMs: number;
 	maxOutputBytes: number;
 	signal?: AbortSignal;
@@ -84,7 +89,7 @@ const JAVASCRIPT_TYPES = new Set([
  */
 export async function runFrontendCheck(
 	args: Record<string, unknown>,
-	options?: { signal?: AbortSignal },
+	options?: ToolInvokeOptions,
 ): Promise<ToolResult> {
 	const pathArg = typeof args.path === "string" ? args.path.trim() : "";
 	if (pathArg.length === 0) return { kind: "error", message: "verify: check=frontend requires a path argument" };
@@ -106,6 +111,9 @@ export async function runFrontendCheck(
 	const validateOptions: ValidationOptions = {
 		timeoutMs: timeoutArg(args),
 		maxOutputBytes: maxOutputArg(args),
+		supportsImages: options?.supportsImages === true,
+		imageMaxBytes: Math.min(maxOutputArg(args), options?.toolResultMaxBytes ?? 50_000) - 4096,
+		images: [],
 	};
 	if (options?.signal !== undefined) validateOptions.signal = options.signal;
 
@@ -131,7 +139,7 @@ export async function runFrontendCheck(
 			details,
 		};
 	}
-	return { kind: "ok", output, details };
+	return { kind: "ok", output, details, ...(validateOptions.images?.length ? { images: validateOptions.images } : {}) };
 }
 
 async function validateArtifact(
@@ -550,38 +558,67 @@ async function validateBrowserLoad(
 		});
 		return;
 	}
-	const result = await runCommandVector(
-		browser,
-		[
-			"--headless=new",
-			"--disable-gpu",
-			"--no-sandbox",
-			"--disable-dev-shm-usage",
-			"--dump-dom",
-			pathToFileURL(artifactPath).href,
-		],
-		{
-			timeoutMs: options.timeoutMs,
-			maxOutputBytes: options.maxOutputBytes,
-			...(options.signal !== undefined ? { signal: options.signal } : {}),
-		},
-	);
-	if (result.exitCode === 0 && !result.timedOut && !result.aborted && !result.outputCapped) {
+	// A DOM dump duplicates the complete artifact on stdout. Large, otherwise
+	// valid pages then trip the diagnostic output cap. A private screenshot
+	// proves that the browser rendered without charging page bytes to that cap.
+	// Vision-capable routes retain bounded pixels before the scratch cleanup.
+	const dir = mkdtempSync(path.join(tmpdir(), "clio-coder-browser-check-"));
+	const screenshot = path.join(dir, "loaded.png");
+	try {
+		const result = await runCommandVector(
+			browser,
+			[
+				"--headless=new",
+				"--disable-gpu",
+				"--no-sandbox",
+				"--disable-dev-shm-usage",
+				`--user-data-dir=${path.join(dir, "profile")}`,
+				`--screenshot=${screenshot}`,
+				pathToFileURL(artifactPath).href,
+			],
+			{
+				timeoutMs: options.timeoutMs,
+				maxOutputBytes: options.maxOutputBytes,
+				...(options.signal !== undefined ? { signal: options.signal } : {}),
+			},
+		);
+		let failure: string;
+		if (result.aborted) failure = "headless browser aborted";
+		else if (result.timedOut) failure = `headless browser timed out after ${options.timeoutMs}ms`;
+		else if (result.outputCapped) failure = `headless browser output exceeded ${options.maxOutputBytes} bytes`;
+		else if (result.exitCode !== 0) {
+			failure = `headless browser exited with ${result.exitCode ?? result.signal ?? "unknown"}`;
+		} else if (!existsSync(screenshot) || !statSync(screenshot).isFile() || statSync(screenshot).size === 0) {
+			failure = "headless browser exited without a rendered screenshot";
+		} else {
+			if (options.supportsImages) {
+				const image = await prepareBoundedImage(readFileSync(screenshot), options.imageMaxBytes ?? 0);
+				if (image) options.images?.push(image);
+				else
+					checks.push({
+						name: "browser image",
+						status: "warn",
+						message: "Screenshot omitted: could not encode within the tool result byte cap.",
+					});
+			}
+			checks.push({
+				name: "browser load",
+				status: "pass",
+				message: `loaded and rendered with ${path.basename(browser)}`,
+				path: artifactPath,
+			});
+			return;
+		}
+		const output = truncateUtf8(combineSafeOutput(result).trim(), 800, " [truncated]");
 		checks.push({
 			name: "browser load",
-			status: "pass",
-			message: `loaded with ${path.basename(browser)}`,
+			status: "fail",
+			message: `${failure}${output ? `: ${output}` : ""}`,
 			path: artifactPath,
 		});
-		return;
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
 	}
-	const output = truncateUtf8(combineSafeOutput(result).trim(), 800, " [truncated]");
-	checks.push({
-		name: "browser load",
-		status: "fail",
-		message: `headless browser exited with ${result.exitCode ?? result.signal ?? "unknown"}${output ? `: ${output}` : ""}`,
-		path: artifactPath,
-	});
 }
 
 function parseAttributes(source: string): Record<string, string> {

package/src/tools/verify/numeric.ts

@@ -156,7 +156,12 @@ export function parseNumericPayload(text: string, label: string): NumericPayload
 function deviation(actual: number, expected: number, index?: number): NumericDeviation {
 	const finite = Number.isFinite(actual) && Number.isFinite(expected);
 	const absolute = finite ? Math.abs(actual - expected) : Number.POSITIVE_INFINITY;
-	const relative = !finite ? null : expected === 0 ? (absolute === 0 ? 0 : null) : absolute / Math.abs(expected);
+	let relative = !finite ? null : expected === 0 ? (absolute === 0 ? 0 : null) : absolute / Math.abs(expected);
+	if (finite && !Number.isFinite(absolute)) {
+		// Finite subtraction overflows only across signs, where division first
+		// is safe. Keep subtraction first for nearby values to preserve precision.
+		relative = Math.abs(actual / expected - 1);
+	}
 	return {
 		...(index !== undefined ? { index } : {}),
 		actual,

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)) {