@gajae-code/coding-agent 0.11.10 → 0.12.0

package/src/task/types.ts

@@ -1,6 +1,6 @@
 import type { ThinkingLevel } from "@gajae-code/agent-core";
 import type { Usage } from "@gajae-code/ai";
-import { $pickenv } from "@gajae-code/utils";
+import { $env } from "@gajae-code/utils";
 import * as z from "zod/v4";
 import { isValidTaskId, TASK_ID_DESCRIPTION } from "./id";
 import type { TaskResultReceipt } from "./receipt";
@@ -14,23 +14,28 @@ export type AgentSource = "bundled" | "user" | "project";
 export type ForkContextPolicy = "forbidden" | "allowed";
 export type ForkContextMode = "none" | "receipt" | "last-turn" | "bounded" | "full";
 
-const parseNumber = (value: string | undefined, defaultValue: number): number => {
-	if (value) {
-		try {
-			const number = Number.parseInt(value, 10);
-			if (!Number.isNaN(number) && number > 0) {
-				return number;
-			}
-		} catch {}
+const parsePositiveIntegerEnvironment = (keys: string[], defaultValue: number): number => {
+	for (const key of keys) {
+		const value = $env[key];
+		if (!value || value.trim().length === 0) continue;
+		if (!/^\d+$/.test(value)) return defaultValue;
+		const number = Number(value);
+		return Number.isSafeInteger(number) && number > 0 ? number : defaultValue;
 	}
 	return defaultValue;
 };
 
 /** Maximum output bytes per agent */
-export const MAX_OUTPUT_BYTES = parseNumber($pickenv("GJC_TASK_MAX_OUTPUT_BYTES", "PI_TASK_MAX_OUTPUT_BYTES"), 500_000);
+export const MAX_OUTPUT_BYTES = parsePositiveIntegerEnvironment(
+	["GJC_TASK_MAX_OUTPUT_BYTES", "PI_TASK_MAX_OUTPUT_BYTES"],
+	500_000,
+);
 
 /** Maximum output lines per agent */
-export const MAX_OUTPUT_LINES = parseNumber($pickenv("GJC_TASK_MAX_OUTPUT_LINES", "PI_TASK_MAX_OUTPUT_LINES"), 5000);
+export const MAX_OUTPUT_LINES = parsePositiveIntegerEnvironment(
+	["GJC_TASK_MAX_OUTPUT_LINES", "PI_TASK_MAX_OUTPUT_LINES"],
+	5000,
+);
 
 /** EventBus channel for raw subagent events */
 export const TASK_SUBAGENT_EVENT_CHANNEL = "task:subagent:event";
@@ -92,6 +97,12 @@ const createTaskItemSchema = (_contextEnabled: boolean) =>
 		id: z.string().max(48).refine(isValidTaskId, TASK_ID_DESCRIPTION).describe("filesystem-safe task identifier"),
 		description: z.string().describe("ui label, not seen by subagent"),
 		assignment: z.string().describe(assignmentDescription),
+		executionMode: z
+			.enum(["default", "ultragoal-red-team"])
+			.optional()
+			.describe(
+				"typed executor mode: default keeps ordinary executor behavior; ultragoal-red-team injects the Ultragoal QA/red-team prompt fragment. Prefer this over free-form assignment text (#2698).",
+			),
 		inheritContext: z
 			.enum(["none", "receipt", "last-turn", "bounded", "full"])
 			.optional()

package/src/task/ultragoal-redteam-activation.ts

@@ -0,0 +1,75 @@
+/**
+ * Decide whether an executor assignment should inject the ultragoal red-team
+ * prompt fragment.
+ *
+ * Preference order (parse, don't re-validate later):
+ * 1. Explicit typed `executionMode` on the task / ExecutorOptions — authoritative.
+ * 2. Assignment text heuristics — only explicit Ultragoal QA/red-team phrasing.
+ *
+ * Bare mentions of `executorQa` (docs, quality-gate field names, negative
+ * instructions) must not flip the mode (#2698 / #2456).
+ *
+ * Mirrors `executor.md`:
+ * "activates only when the assignment explicitly labels Executor as Ultragoal
+ * completion QA/red-team or asks for `executorQa` red-team evidence."
+ */
+
+export const EXECUTOR_EXECUTION_MODES = ["default", "ultragoal-red-team"] as const;
+export type ExecutorExecutionMode = (typeof EXECUTOR_EXECUTION_MODES)[number];
+
+const ULTRAGOAL_COMPLETION_QA = /\bultragoal\s+completion\s+(?:qa|red[-\s]?team)\b/i;
+
+/** `executorQa` within a short window of red-team / matrix / evidence framing. */
+const EXECUTOR_QA_EVIDENCE =
+	/\bexecutorQa\b[\s\S]{0,120}\b(?:red[-\s]?team|matrix|evidence)\b|\b(?:red[-\s]?team|matrix|evidence)\b[\s\S]{0,120}\bexecutorQa\b/i;
+
+/** Common Ultragoal skill spawn phrasing: "executor QA/red-team lane". */
+const EXECUTOR_QA_LANE = /\bexecutor\b[\s\S]{0,48}\b(?:qa|red[-\s]?team)\s+lane\b/i;
+
+export function isExecutorExecutionMode(value: unknown): value is ExecutorExecutionMode {
+	return value === "default" || value === "ultragoal-red-team";
+}
+
+/**
+ * Parse a caller-supplied mode. Unknown values fail closed to `undefined`
+ * so the assignment heuristic (or default off) still applies — never invent on.
+ */
+export function parseExecutorExecutionMode(value: unknown): ExecutorExecutionMode | undefined {
+	if (typeof value !== "string") return undefined;
+	const normalized = value.trim().toLowerCase().replaceAll("_", "-");
+	if (normalized === "default" || normalized === "ordinary" || normalized === "implement") {
+		return "default";
+	}
+	if (
+		normalized === "ultragoal-red-team" ||
+		normalized === "ultragoal-redteam" ||
+		normalized === "red-team" ||
+		normalized === "redteam" ||
+		normalized === "executor-qa"
+	) {
+		return "ultragoal-red-team";
+	}
+	return undefined;
+}
+
+export function assignmentRequestsUltragoalRedTeam(assignment: string | undefined): boolean {
+	const text = assignment?.trim() ?? "";
+	if (text.length === 0) return false;
+	return ULTRAGOAL_COMPLETION_QA.test(text) || EXECUTOR_QA_EVIDENCE.test(text) || EXECUTOR_QA_LANE.test(text);
+}
+
+export interface ResolveUltragoalRedTeamArgs {
+	readonly executionMode?: unknown;
+	readonly assignment?: string;
+}
+
+/**
+ * Final activation decision for the executor prompt fragment.
+ * Typed mode wins; assignment text is a compatibility fallback only.
+ */
+export function resolveUltragoalRedTeamActivation(args: ResolveUltragoalRedTeamArgs): boolean {
+	const mode = parseExecutorExecutionMode(args.executionMode);
+	if (mode === "ultragoal-red-team") return true;
+	if (mode === "default") return false;
+	return assignmentRequestsUltragoalRedTeam(args.assignment);
+}

package/src/tools/ask.ts

@@ -351,15 +351,23 @@ function parseEncodedContainer(value: unknown): unknown {
 function isRoundZeroRecoveryCandidate(value: unknown): boolean {
 	const root = parseEncodedContainer(value);
 	if (typeof root !== "object" || root === null || !Object.hasOwn(root, "questions")) return false;
-	const questionsValue = parseEncodedContainer((root as Record<string, unknown>).questions);
+	const rawQuestions = (root as Record<string, unknown>).questions;
+	const questionsValue = parseEncodedContainer(rawQuestions);
 	if (!Array.isArray(questionsValue)) return questionsValue === null;
+	const rootEncoded = typeof value === "string" || typeof rawQuestions === "string";
 	return questionsValue.some(rawQuestion => {
 		const question = parseEncodedContainer(rawQuestion);
 		if (typeof question !== "object" || question === null || !Object.hasOwn(question, "deepInterview")) return false;
-		const deepInterview = parseEncodedContainer((question as Record<string, unknown>).deepInterview);
+		const rawDeepInterview = (question as Record<string, unknown>).deepInterview;
+		const deepInterview = parseEncodedContainer(rawDeepInterview);
 		if (typeof deepInterview !== "object" || deepInterview === null) return false;
 		const metadata = deepInterview as Record<string, unknown>;
-		return Object.hasOwn(metadata, "intent_contract") || Object.hasOwn(metadata, "intent_review");
+		const hasContract = Object.hasOwn(metadata, "intent_contract");
+		const hasReview = Object.hasOwn(metadata, "intent_review");
+		// A JSON-string container is terminal only for the retired contract+review
+		// pair; canonical single-sided asks stay eligible for generic JSON coercion.
+		const encoded = rootEncoded || typeof rawQuestion === "string" || typeof rawDeepInterview === "string";
+		return encoded ? hasContract && hasReview : hasContract || hasReview;
 	});
 }
 
@@ -1252,6 +1260,14 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 			receipt: AskRemoteReceipt;
 			settlement?: AskSettlement;
 		};
+		const ignoreRemoteAnswerFailure = (error: unknown): Promise<never> => {
+			if (!(error instanceof Error && error.name === "AbortError")) {
+				logger.warn("Ask remote answer source failed", {
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+			return new Promise<never>(() => {});
+		};
 		const settleActiveRemote = async (settlement: AskSettlement): Promise<void> => {
 			const receipt = activeRemoteReceipt;
 			activeRemoteReceipt = undefined;
@@ -1304,60 +1320,62 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 								remoteController.signal,
 							)
 						: source.awaitAnswer(prompt, options, remoteController.signal)
-				).then((answer): RemoteRaceResult | Promise<RemoteRaceResult> => {
-					if (answer === undefined) return new Promise<never>(() => {});
-					const receipt = typeof answer === "string" ? legacyAskReceipt(answer) : answer;
-					if (generation !== remoteGeneration) {
-						return receipt
-							.settle({ kind: "resolve_without_commit", reason: "aborted" })
-							.then(() => new Promise<never>(() => {}));
-					}
-					const remoteValue = receipt.interaction.kind === "value" ? receipt.interaction.value : undefined;
-					const value = remoteValue ?? REMOTE_NAVIGATION_FORWARD;
-					const selectedValue =
-						remoteValue === undefined
-							? value
-							: (options.find(
-									option =>
-										option === remoteValue ||
-										option === `${theme.checkbox.checked} ${remoteValue}` ||
-										option === `${theme.checkbox.unchecked} ${remoteValue}`,
-								) ?? value);
-					const normalizedRemoteValue = remoteValue?.startsWith(`${theme.checkbox.checked} `)
-						? remoteValue.slice(`${theme.checkbox.checked} `.length)
-						: remoteValue?.startsWith(`${theme.checkbox.unchecked} `)
-							? remoteValue.slice(`${theme.checkbox.unchecked} `.length)
-							: remoteValue;
-					const semanticRemoteValue = normalizedRemoteValue?.replace(/^\s*\d+[.)]\s+/, "");
-					const transitionReason =
-						semanticRemoteValue === OTHER_OPTION
-							? "other_transition"
-							: semanticRemoteValue === ASK_CLARIFICATION_OPTION
-								? "clarification_transition"
-								: undefined;
-					if (transitionReason) {
-						return {
-							winner: "remote" as const,
-							value: selectedValue,
-							receipt,
-							settlement: { kind: "resolve_without_commit", reason: transitionReason },
-						};
-					}
-					if (
-						remoteValue !== undefined &&
-						activeRemoteRequest?.interaction === "selector" &&
-						activeRemoteRequest.controls.length > 0 &&
-						activeRemoteRequest.options.includes(remoteValue)
-					) {
-						return {
-							winner: "remote" as const,
-							value: selectedValue,
-							receipt,
-							settlement: { kind: "resolve_without_commit", reason: "toggle" },
-						};
-					}
-					return { winner: "remote" as const, value: selectedValue, receipt };
-				});
+				)
+					.then((answer): RemoteRaceResult | Promise<RemoteRaceResult> => {
+						if (answer === undefined) return new Promise<never>(() => {});
+						const receipt = typeof answer === "string" ? legacyAskReceipt(answer) : answer;
+						if (generation !== remoteGeneration) {
+							return receipt
+								.settle({ kind: "resolve_without_commit", reason: "aborted" })
+								.then(() => new Promise<never>(() => {}));
+						}
+						const remoteValue = receipt.interaction.kind === "value" ? receipt.interaction.value : undefined;
+						const value = remoteValue ?? REMOTE_NAVIGATION_FORWARD;
+						const selectedValue =
+							remoteValue === undefined
+								? value
+								: (options.find(
+										option =>
+											option === remoteValue ||
+											option === `${theme.checkbox.checked} ${remoteValue}` ||
+											option === `${theme.checkbox.unchecked} ${remoteValue}`,
+									) ?? value);
+						const normalizedRemoteValue = remoteValue?.startsWith(`${theme.checkbox.checked} `)
+							? remoteValue.slice(`${theme.checkbox.checked} `.length)
+							: remoteValue?.startsWith(`${theme.checkbox.unchecked} `)
+								? remoteValue.slice(`${theme.checkbox.unchecked} `.length)
+								: remoteValue;
+						const semanticRemoteValue = normalizedRemoteValue?.replace(/^\s*\d+[.)]\s+/, "");
+						const transitionReason =
+							semanticRemoteValue === OTHER_OPTION
+								? "other_transition"
+								: semanticRemoteValue === ASK_CLARIFICATION_OPTION
+									? "clarification_transition"
+									: undefined;
+						if (transitionReason) {
+							return {
+								winner: "remote" as const,
+								value: selectedValue,
+								receipt,
+								settlement: { kind: "resolve_without_commit", reason: transitionReason },
+							};
+						}
+						if (
+							remoteValue !== undefined &&
+							activeRemoteRequest?.interaction === "selector" &&
+							activeRemoteRequest.controls.length > 0 &&
+							activeRemoteRequest.options.includes(remoteValue)
+						) {
+							return {
+								winner: "remote" as const,
+								value: selectedValue,
+								receipt,
+								settlement: { kind: "resolve_without_commit", reason: "toggle" },
+							};
+						}
+						return { winner: "remote" as const, value: selectedValue, receipt };
+					})
+					.catch(ignoreRemoteAnswerFailure);
 
 				const local = extensionUi
 					.select(prompt, options, { ...dialogOptions, signal: localController.signal })
@@ -1419,18 +1437,20 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 								remoteController.signal,
 							)
 						: source.awaitAnswer(title, [], remoteController.signal)
-				).then((answer): RemoteRaceResult | Promise<RemoteRaceResult> => {
-					if (answer === undefined) return new Promise<never>(() => {});
-					const receipt = typeof answer === "string" ? legacyAskReceipt(answer) : answer;
-					if (generation !== remoteGeneration) {
-						return receipt
-							.settle({ kind: "resolve_without_commit", reason: "aborted" })
-							.then(() => new Promise<never>(() => {}));
-					}
-					const value =
-						receipt.interaction.kind === "control" ? REMOTE_NAVIGATION_FORWARD : receipt.interaction.value;
-					return { winner: "remote" as const, value, receipt };
-				});
+				)
+					.then((answer): RemoteRaceResult | Promise<RemoteRaceResult> => {
+						if (answer === undefined) return new Promise<never>(() => {});
+						const receipt = typeof answer === "string" ? legacyAskReceipt(answer) : answer;
+						if (generation !== remoteGeneration) {
+							return receipt
+								.settle({ kind: "resolve_without_commit", reason: "aborted" })
+								.then(() => new Promise<never>(() => {}));
+						}
+						const value =
+							receipt.interaction.kind === "control" ? REMOTE_NAVIGATION_FORWARD : receipt.interaction.value;
+						return { winner: "remote" as const, value, receipt };
+					})
+					.catch(ignoreRemoteAnswerFailure);
 				const local = extensionUi
 					.editor(title, prefill, { ...(dialogOptions ?? {}), signal: localController.signal }, editorOptions)
 					.then(answer => {

package/src/tools/browser/launch.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { getPuppeteerDir } from "@gajae-code/utils/dirs";
+import { $credentialEnv } from "@gajae-code/utils/env";
 import * as logger from "@gajae-code/utils/logger";
 import { $which } from "@gajae-code/utils/which";
 import * as browsers from "@puppeteer/browsers";
@@ -80,6 +81,42 @@ export async function loadPuppeteerInWorker(safeDir: string): Promise<typeof Pup
 	}
 }
 
+/**
+ * Browser launch overrides resolved from trusted environment sources only.
+ *
+ * These choose the browser binary and route/verify its traffic, so whatever can
+ * set them controls what runs and who sees the session. `$env` merges the
+ * caller's `cwd/.env` into `process.env`, so reading them directly would let
+ * repository content pick the executable, point every request at an attacker's
+ * proxy, or disable certificate validation. Resolve them the same way provider
+ * credentials are: launching shell plus GJC/user-owned `.env` files, never the
+ * project `.env`.
+ */
+function trustedBrowserEnv(name: string): string | undefined {
+	return $credentialEnv(name);
+}
+
+/** Boolean-like trusted browser env knob (`true`/`1`/`yes`/`on`). */
+function browserLaunchFlagEnabled(name: string): boolean {
+	const value = trustedBrowserEnv(name)?.toLowerCase();
+	return value === "true" || value === "1" || value === "yes" || value === "on";
+}
+
+/** Test seam: the browser launch overrides as resolved from trusted env. */
+export function resolveBrowserEnvOverridesForTest(): {
+	executablePath: string | undefined;
+	proxy: string | undefined;
+	proxyBypassLoopback: boolean;
+	ignoreCertErrors: boolean;
+} {
+	return {
+		executablePath: trustedBrowserEnv("PUPPETEER_EXECUTABLE_PATH"),
+		proxy: trustedBrowserEnv("PUPPETEER_PROXY"),
+		proxyBypassLoopback: browserLaunchFlagEnabled("PUPPETEER_PROXY_BYPASS_LOOPBACK"),
+		ignoreCertErrors: browserLaunchFlagEnabled("PUPPETEER_PROXY_IGNORE_CERT_ERRORS"),
+	};
+}
+
 /**
  * Lazily download Chromium on first browser launch via @puppeteer/browsers.
  * Skipped when a system Chromium (NixOS) or PUPPETEER_EXECUTABLE_PATH is set.
@@ -89,7 +126,7 @@ let chromiumExecutablePromise: Promise<string | undefined> | undefined;
 async function ensureChromiumExecutable(): Promise<string | undefined> {
 	const sysChrome = resolveSystemChromium();
 	if (sysChrome) return sysChrome;
-	const envPath = process.env.PUPPETEER_EXECUTABLE_PATH;
+	const envPath = trustedBrowserEnv("PUPPETEER_EXECUTABLE_PATH");
 	if (envPath) return envPath;
 	if (chromiumExecutablePromise) return chromiumExecutablePromise;
 
@@ -272,13 +309,12 @@ export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promis
 		// Isolated copy only (caller guarantees). Never point this at a live profile.
 		launchArgs.push(`--user-data-dir=${opts.profileWarmupDir}`);
 	}
-	const proxy = process.env.PUPPETEER_PROXY;
+	const proxy = trustedBrowserEnv("PUPPETEER_PROXY");
 	if (proxy) {
 		launchArgs.push(`--proxy-server=${proxy}`);
 		// Chrome (since v72) bypasses proxies for localhost by default. When PUPPETEER_PROXY_BYPASS_LOOPBACK
 		// is true, add <-loopback> so traffic to localhost reaches the proxy (e.g. for mitmdump/auth capture).
-		const bypassLoopback = process.env.PUPPETEER_PROXY_BYPASS_LOOPBACK?.toLowerCase();
-		if (bypassLoopback === "true" || bypassLoopback === "1" || bypassLoopback === "yes" || bypassLoopback === "on") {
+		if (browserLaunchFlagEnabled("PUPPETEER_PROXY_BYPASS_LOOPBACK")) {
 			launchArgs.push("--proxy-bypass-list=<-loopback>");
 		}
 	}
@@ -287,8 +323,7 @@ export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promis
 	if (opts.geo?.locale) {
 		launchArgs.push(`--lang=${opts.geo.locale}`);
 	}
-	const ignoreCert = process.env.PUPPETEER_PROXY_IGNORE_CERT_ERRORS?.toLowerCase();
-	if (ignoreCert === "true" || ignoreCert === "1" || ignoreCert === "yes" || ignoreCert === "on") {
+	if (browserLaunchFlagEnabled("PUPPETEER_PROXY_IGNORE_CERT_ERRORS")) {
 		launchArgs.push("--ignore-certificate-errors");
 	}
 	const launchEnv = opts.geo?.timezone ? { ...process.env, TZ: opts.geo.timezone } : undefined;

package/src/tools/fetch.ts

@@ -10,7 +10,7 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { type Theme, theme } from "../modes/theme/theme";
 import type { ToolSession } from "../sdk";
 import type { AgentStorage } from "../session/agent-storage";
-import { DEFAULT_MAX_BYTES, truncateHead } from "../session/streaming-output";
+import { DEFAULT_MAX_BYTES, type TruncationDirection, truncateContent } from "../session/streaming-output";
 import { renderStatusLine } from "../tui";
 import { CachedOutputBlock } from "../tui/output-block";
 import { formatDimensionNote, resizeImage } from "../utils/image-resize";
@@ -1146,7 +1146,12 @@ interface ReadUrlCacheEntry {
 	artifactId?: string;
 	details: ReadUrlToolDetails;
 	image?: FetchImagePayload;
+	/** Complete URL output, including its preamble and body. */
 	output: string;
+	/** UTF-16 code-unit offset of the preamble in `output`. */
+	preambleChars: number;
+	/** Offset of the preamble after `wrapUntrustedContent(output)` is persisted. */
+	wrappedPreambleChars?: number;
 }
 
 const readUrlCache = new Map<string, ReadUrlCacheEntry>();
@@ -1178,7 +1183,13 @@ async function materializeReadUrlCacheEntry(
 	if (entry.artifactId) {
 		const artifactOutput = await readArtifactOutput(session, entry.artifactId);
 		if (artifactOutput !== null) {
-			return { ...entry, output: artifactOutput };
+			// Artifacts retain their trust-boundary wrapper. Keep the raw preamble
+			// coordinate alongside the escaped coordinate for live/rehydrated parity.
+			return {
+				...entry,
+				output: artifactOutput,
+				...(entry.wrappedPreambleChars !== undefined ? { wrappedPreambleChars: entry.wrappedPreambleChars } : {}),
+			};
 		}
 	}
 	return null;
@@ -1218,8 +1229,8 @@ async function buildReadUrlCacheEntry(
 
 	const storage = session.settings.getStorage();
 	const result = await renderUrl(url, effectiveTimeout, raw, session.settings, signal, storage);
-	const output = buildUrlReadOutput(result, result.content);
-	const artifactId = options?.ensureArtifact ? await persistReadUrlArtifact(session, output) : undefined;
+	const built = buildUrlReadOutput(result, result.content);
+	const artifactId = options?.ensureArtifact ? await persistReadUrlArtifact(session, built.output) : undefined;
 
 	return {
 		artifactId,
@@ -1233,7 +1244,9 @@ async function buildReadUrlCacheEntry(
 			notes: result.notes,
 		},
 		image: result.image,
-		output,
+		output: built.output,
+		preambleChars: built.preambleChars,
+		wrappedPreambleChars: built.wrappedPreambleChars,
 	};
 }
 
@@ -1263,60 +1276,138 @@ export async function loadReadUrlCacheEntry(
 
 const UNTRUSTED_CONTENT_OPEN = "<untrusted-content>";
 const UNTRUSTED_CONTENT_CLOSE = "</untrusted-content>";
+export const WRAP_PREFIX_CHARS = `${UNTRUSTED_CONTENT_OPEN}\n`.length;
+const WRAP_SUFFIX = `\n${UNTRUSTED_CONTENT_CLOSE}`;
+
+export function escapeUntrustedContent(content: string): string {
+	return content.replace(/<\/untrusted-content>/gi, "&lt;/untrusted-content>");
+}
 
 export function wrapUntrustedContent(content: string): string {
-	return `${UNTRUSTED_CONTENT_OPEN}\n${content.replace(/<\/untrusted-content>/gi, "&lt;/untrusted-content>")}\n${UNTRUSTED_CONTENT_CLOSE}`;
+	return `${UNTRUSTED_CONTENT_OPEN}\n${escapeUntrustedContent(content)}${WRAP_SUFFIX}`;
+}
+
+function isWrappedReadUrlOutput(output: string): boolean {
+	return output.startsWith(`${UNTRUSTED_CONTENT_OPEN}\n`) && output.endsWith(WRAP_SUFFIX);
+}
+
+/**
+ * Remove only the outer URL-output wrapper before line pagination. The content
+ * remains escaped exactly as persisted; it is deliberately never unescaped.
+ */
+export function prepareReadUrlSelectorInput(
+	output: string,
+	preambleChars: number,
+	wrappedPreambleChars?: number,
+): { text: string; preambleChars: number } {
+	if (!isWrappedReadUrlOutput(output)) return { text: output, preambleChars };
+	const bodyEnd = output.length - WRAP_SUFFIX.length;
+	return {
+		text: output.slice(WRAP_PREFIX_CHARS, Math.max(WRAP_PREFIX_CHARS, bodyEnd)),
+		preambleChars: Math.max(0, (wrappedPreambleChars ?? preambleChars) - WRAP_PREFIX_CHARS),
+	};
+}
+interface BuiltUrlReadOutput {
+	output: string;
+	preambleChars: number;
+	wrappedPreambleChars: number;
 }
 
-function buildUrlReadOutput(result: FetchRenderResult, content: string): string {
-	let output = "";
-	output += `URL: ${result.finalUrl}\n`;
-	output += `Content-Type: ${result.contentType}\n`;
-	output += `Method: ${result.method}\n`;
+function buildReadUrlPreamble(
+	result: Pick<FetchRenderResult, "finalUrl" | "contentType" | "method" | "notes">,
+): string {
+	let preamble = "";
+	preamble += `URL: ${result.finalUrl}\n`;
+	preamble += `Content-Type: ${result.contentType}\n`;
+	preamble += `Method: ${result.method}\n`;
 	if (result.notes.length > 0) {
-		output += `Notes: ${result.notes.join("; ")}\n`;
+		preamble += `Notes: ${result.notes.join("; ")}\n`;
 	}
-	output += `\n---\n\n`;
-	output += content;
-	return output;
+	preamble += "\n---\n\n";
+	return preamble;
+}
+
+function buildUrlReadOutput(result: FetchRenderResult, content: string): BuiltUrlReadOutput {
+	const preamble = buildReadUrlPreamble(result);
+	const preambleChars = preamble.length;
+	const output = `${preamble}${content}`;
+	return {
+		output,
+		preambleChars,
+		wrappedPreambleChars: WRAP_PREFIX_CHARS + escapeUntrustedContent(preamble).length,
+	};
 }
 
 export async function executeReadUrl(
 	session: ToolSession,
 	params: { path: string; raw?: boolean },
 	signal?: AbortSignal,
+	direction: TruncationDirection = "head",
 ): Promise<AgentToolResult<ReadUrlToolDetails>> {
 	let cacheEntry = await loadReadUrlCacheEntry(session, params, signal, { preferCached: true });
-	const truncation = truncateHead(cacheEntry.output, {
+	// `head` intentionally retains the historical whole-output accounting so the
+	// existing URL golden remains byte-identical. Non-head directions account for
+	// and truncate only the body; preamble bytes/chars are never part of that cap.
+	const effectiveDirection =
+		direction !== "head" && cacheEntry.wrappedPreambleChars === undefined ? "head" : direction;
+	const isWrappedOutput = isWrappedReadUrlOutput(cacheEntry.output);
+	const preambleChars = isWrappedOutput
+		? (cacheEntry.wrappedPreambleChars ??
+			WRAP_PREFIX_CHARS + escapeUntrustedContent(buildReadUrlPreamble(cacheEntry.details)).length)
+		: cacheEntry.preambleChars;
+	const wrappedPrefix = isWrappedOutput ? WRAP_PREFIX_CHARS : 0;
+	const wrappedSuffix = isWrappedOutput ? `\n${UNTRUSTED_CONTENT_CLOSE}` : "";
+	const bodyEnd = cacheEntry.output.length - wrappedSuffix.length;
+	const unwrappedOutput = isWrappedOutput
+		? cacheEntry.output.slice(wrappedPrefix, Math.max(wrappedPrefix, bodyEnd))
+		: cacheEntry.output;
+	const truncationInput =
+		effectiveDirection === "head"
+			? unwrappedOutput
+			: cacheEntry.output.slice(preambleChars, Math.max(preambleChars, bodyEnd));
+	const truncation = truncateContent(truncationInput, {
 		maxBytes: DEFAULT_MAX_BYTES,
 		maxLines: FETCH_DEFAULT_MAX_LINES,
+		direction: effectiveDirection,
 	});
 	const needsArtifact = truncation.truncated;
 	if (needsArtifact && !cacheEntry.artifactId) {
 		cacheEntry = await ensureReadUrlCacheArtifact(session, cacheEntry);
 		cacheReadUrlEntry(session, params.path, params.raw ?? false, cacheEntry);
 	}
-	const output = needsArtifact ? truncation.content : cacheEntry.output;
+	const output =
+		effectiveDirection !== "head"
+			? needsArtifact
+				? `${cacheEntry.output.slice(0, preambleChars)}${truncation.content}${wrappedSuffix}`
+				: cacheEntry.output
+			: truncation.content;
 	const details: ReadUrlToolDetails = {
 		...cacheEntry.details,
 		truncated: Boolean(cacheEntry.details.truncated || needsArtifact),
 	};
 
-	const contentBlocks: Array<TextContent | ImageContent> = [{ type: "text", text: wrapUntrustedContent(output) }];
+	const contentBlocks: Array<TextContent | ImageContent> = [
+		{ type: "text", text: isWrappedOutput && effectiveDirection !== "head" ? output : wrapUntrustedContent(output) },
+	];
 	if (cacheEntry.image) {
 		contentBlocks.push({ type: "image", data: cacheEntry.image.data, mimeType: cacheEntry.image.mimeType });
 	}
 
 	const resultBuilder = toolResult(details).content(contentBlocks).sourceUrl(details.finalUrl);
 	if (needsArtifact) {
-		resultBuilder.truncation(truncation, { direction: "head", artifactId: cacheEntry.artifactId });
+		resultBuilder.truncation(truncation, {
+			direction: effectiveDirection === "both" ? "middle" : effectiveDirection === "last" ? "tail" : "head",
+			artifactId: cacheEntry.artifactId,
+			...(effectiveDirection !== "head" ? { maxBytes: DEFAULT_MAX_BYTES } : {}),
+		});
 	} else if (cacheEntry.details.truncated) {
-		const outputLines = cacheEntry.output.split("\n").length;
-		const outputBytes = Buffer.byteLength(cacheEntry.output, "utf-8");
+		const reportedText = effectiveDirection === "head" ? cacheEntry.output : truncationInput;
+		const outputLines = reportedText.split("\n").length;
+		const outputBytes = Buffer.byteLength(reportedText, "utf-8");
 		const totalBytes = Math.max(outputBytes + 1, MAX_OUTPUT_CHARS + 1);
 		const totalLines = outputLines + 1;
-		resultBuilder.truncationFromText(cacheEntry.output, {
-			direction: "tail",
+		resultBuilder.truncationFromText(reportedText, {
+			direction: effectiveDirection === "both" ? "middle" : effectiveDirection === "last" ? "tail" : "head",
 			totalLines,
 			totalBytes,
 			maxBytes: MAX_OUTPUT_CHARS,