@oh-my-pi/pi-coding-agent 17.2.4 → 17.2.5

package/src/tools/grep.ts

@@ -22,6 +22,7 @@ import type { InternalResource, ResolveContext } from "../internal-urls/types";
 import type { Theme } from "../modes/theme/theme";
 import grepDescription from "../prompts/tools/grep.md" with { type: "text" };
 import { DEFAULT_MAX_COLUMN, type TruncationResult, truncateHead, truncateLine } from "../session/streaming-output";
+import { isScoutSpawnable } from "../task/spawn-policy";
 import {
 	Ellipsis,
 	fileHyperlink,
@@ -909,7 +910,17 @@ export class GrepTool implements AgentTool<typeof searchSchema, GrepToolDetails>
 	readonly label = "Grep";
 	readonly loadMode = "discoverable";
 	readonly summary = "Grep file contents using ripgrep (fast regex search)";
-	readonly description: string;
+	get description(): string {
+		const displayMode = resolveFileDisplayMode(this.session);
+		return prompt.render(grepDescription, {
+			IS_HL_MODE: displayMode.hashLines,
+			IS_LINE_NUMBER_MODE: !displayMode.hashLines && displayMode.lineNumbers,
+			scoutAvailable: isScoutSpawnable(
+				this.session.settings.get("task.disabledAgents") as string[] | undefined,
+				this.session.getSessionSpawns?.() ?? "*",
+			),
+		});
+	}
 	readonly parameters = searchSchema;
 	readonly strict = true;
 
@@ -924,11 +935,6 @@ export class GrepTool implements AgentTool<typeof searchSchema, GrepToolDetails>
 		this.#contextOverride = context !== undefined ? Math.max(0, Math.floor(context)) : undefined;
 		const total = options?.totalMatchLimit;
 		this.#totalMatchLimit = total !== undefined ? Math.max(1, Math.floor(total)) : undefined;
-		const displayMode = resolveFileDisplayMode(session);
-		this.description = prompt.render(grepDescription, {
-			IS_HL_MODE: displayMode.hashLines,
-			IS_LINE_NUMBER_MODE: !displayMode.hashLines && displayMode.lineNumbers,
-		});
 	}
 
 	async execute(

package/src/tools/inspect-image.ts

@@ -12,9 +12,15 @@ import { prompt } from "@oh-my-pi/pi-utils";
 import { type } from "arktype";
 import { extractTextContent } from "../commit/utils";
 
-import { expandRoleAlias, getModelMatchPreferences, resolveModelFromString } from "../config/model-resolver";
+import {
+	expandRoleAlias,
+	extractExplicitThinkingSelector,
+	getModelMatchPreferences,
+	resolveModelFromString,
+} from "../config/model-resolver";
 import inspectImageDescription from "../prompts/tools/inspect-image.md" with { type: "text" };
 import inspectImageSystemPromptTemplate from "../prompts/tools/inspect-image-system.md" with { type: "text" };
+import { concreteThinkingLevel, resolveThinkingLevelForModel, toReasoningEffort } from "../thinking";
 import {
 	ImageInputTooLargeError,
 	type LoadedImageInput,
@@ -163,11 +169,17 @@ export class InspectImageTool implements AgentTool<typeof inspectImageSchema, In
 		};
 
 		const activeModelPattern = this.session.getActiveModelString?.() ?? this.session.getModelString?.();
-		const model =
-			resolvePattern("@vision") ??
-			resolvePattern("@default") ??
-			resolvePattern(activeModelPattern) ??
-			availableModels[0];
+		let model: Model<Api> | undefined;
+		let selectedPattern: string | undefined;
+		for (const pattern of ["@vision", "@default", activeModelPattern]) {
+			const resolved = resolvePattern(pattern);
+			if (resolved) {
+				model = resolved;
+				selectedPattern = pattern;
+				break;
+			}
+		}
+		model ??= availableModels[0];
 		if (!model) {
 			throw new ToolError("Unable to resolve a model for inspect_image.");
 		}
@@ -233,6 +245,19 @@ export class InspectImageTool implements AgentTool<typeof inspectImageSchema, In
 			return `inspect_image request timed out after ${seconds}s. Increase inspect_image.timeoutMs (currently ${timeoutMs}ms; 0 disables) or check the vision model provider.`;
 		};
 
+		// Honor the thinking effort configured on the resolved model role
+		// (e.g. `modelRoles.vision: <model>:high`). Without it the oneshot sent a
+		// suppressed/zero thinking budget, which thinking-only models (Gemini 3.x)
+		// reject with HTTP 400 ("Budget 0 is invalid. This model only works in
+		// thinking mode.").
+		const configuredThinking = concreteThinkingLevel(
+			extractExplicitThinkingSelector(selectedPattern, this.session.settings, {
+				isLiteralModelId: (provider, id) =>
+					availableModels.some(candidate => candidate.provider === provider && candidate.id === id),
+			}),
+		);
+		const reasoning = toReasoningEffort(resolveThinkingLevelForModel(model, configuredThinking));
+
 		let response: AssistantMessage;
 		try {
 			response = await instrumentedCompleteSimple(
@@ -253,6 +278,7 @@ export class InspectImageTool implements AgentTool<typeof inspectImageSchema, In
 				{
 					apiKey: modelRegistry.resolver(model, this.session.getSessionId?.() ?? undefined),
 					signal: effectiveSignal,
+					reasoning,
 				},
 				{ telemetry, oneshotKind: "inspect_image", completeImpl: this.completeImageRequest },
 			);

package/src/tools/render-utils.ts

@@ -61,6 +61,8 @@ export const PREVIEW_LIMITS = {
 	OUTPUT_COLLAPSED: 3,
 	/** Output preview lines in expanded view */
 	OUTPUT_EXPANDED: 10,
+	/** Computer script lines shown in collapsed view */
+	COMPUTER_CODE_COLLAPSED: 10,
 	/** Max hunks shown when collapsed (edit tool) */
 	DIFF_COLLAPSED_HUNKS: 8,
 	/** Max diff lines shown when collapsed (edit tool) */

package/src/tools/{browser/run-cancellation.ts → run-scope.ts}

@@ -1,10 +1,10 @@
-import { untilAborted } from "@oh-my-pi/pi-utils";
-import { ToolError, throwIfAborted } from "../tool-errors";
+import { untilAborted } from "@oh-my-pi/pi-utils/abortable";
+import { ToolError, throwIfAborted } from "./tool-errors";
 
 /**
  * Marks a run-scoped promise as observed without changing its behavior for awaited callers.
  *
- * Browser run teardown aborts can reject promises created for evaluated code after user code
+ * Run teardown aborts can reject promises created for evaluated code after user code
  * has stopped observing them (for example fire-and-forget `wait()`/facade calls). In 16.3.0
  * those zero-consumer rejections reached the process-level `unhandledRejection` handler and
  * killed every subagent sharing the process (issues #4499/#4672). Attaching a no-op rejection
@@ -33,8 +33,8 @@ export interface WaitPredicateOptions {
 /**
  * Effective `wait(predicate)` deadline for a given cell budget. Always strictly below
  * the cell budget so the named `wait(predicate) timed out` error wins the race against
- * the opaque whole-cell "Browser code execution timed out". `0`/`Infinity` ("disable")
- * map to the largest bounded deadline; negative/NaN garbage falls back to the default.
+ * the opaque whole-cell execution timeout. `0`/`Infinity` ("disable") map to the largest
+ * bounded deadline; negative/NaN garbage falls back to the default.
  */
 export function resolvePredicateTimeout(cellTimeoutMs: number, explicit?: number): number {
 	const budgetBound = Math.max(1, cellTimeoutMs - CELL_BUDGET_SLACK_MS);
@@ -44,15 +44,15 @@ export function resolvePredicateTimeout(cellTimeoutMs: number, explicit?: number
 }
 
 /**
- * Run-scoped `wait()` helper for evaluated browser code, honoring the owning run's
- * cancellation signal.
+ * Run-scoped `wait()` helper for evaluated code (browser and computer workers), honoring
+ * the owning run's cancellation signal.
  *
  * - `wait(ms)` sleeps for `ms` milliseconds.
  * - `wait(fn, { timeout?, interval? })` polls `fn` (sync or async) until it returns a
  *   truthy value and resolves with that value; throws a named `ToolError` on timeout
  *   instead of stalling into the whole-cell deadline. Predicate errors propagate.
  */
-export function waitForBrowserRun(
+export function waitForRun(
 	msOrPredicate: number | (() => unknown),
 	signal: AbortSignal,
 	opts?: WaitPredicateOptions,
@@ -86,8 +86,8 @@ export function waitForBrowserRun(
 	return markHandled(promise);
 }
 
-/** Binds a long-lived browser facade to one evaluated run's abort signal. */
-export function bindBrowserRunFacade<T extends object>(target: T, signal: AbortSignal): T {
+/** Binds a long-lived scope facade (page/tab/desktop objects) to one evaluated run's abort signal. */
+export function bindRunFacade<T extends object>(target: T, signal: AbortSignal): T {
 	const cache = new Map<PropertyKey, unknown>();
 	return new Proxy(target, {
 		get(current, prop) {
@@ -121,7 +121,7 @@ export function bindBrowserRunFacade<T extends object>(target: T, signal: AbortS
 				// brand-check internal slots that a Proxy cannot forward, and reading a
 				// signal needs no abort gating anyway.
 				if (value instanceof AbortSignal) return value;
-				const wrapped = bindBrowserRunFacade(value, signal);
+				const wrapped = bindRunFacade(value, signal);
 				cache.set(prop, wrapped);
 				return wrapped;
 			}

package/src/tools/tool-timeouts.ts

@@ -11,6 +11,7 @@ export const TOOL_TIMEOUTS = {
 	bash: { default: 300, min: 1, max: 3600 },
 	eval: { default: 30, min: 1, max: 3600 },
 	browser: { default: 30, min: 1, max: 300 },
+	computer: { default: 120, min: 1, max: 300 },
 	ssh: { default: 60, min: 1, max: 3600 },
 	fetch: { default: 20, min: 1, max: 45 },
 	lsp: { default: 20, min: 5, max: 300 },

package/src/tools/xdev.ts

@@ -36,6 +36,7 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { XD_URL_PREFIX } from "../internal-urls/xd-protocol";
 import type { Theme } from "../modes/theme/theme";
 import { truncateHeadBytes } from "../session/streaming-output";
+import { resolveToolTier, type ToolTier } from "./approval";
 import { renderDefaultToolExecution } from "./default-renderer";
 import type { Tool } from "./index";
 import { replaceTabs } from "./render-utils";
@@ -88,6 +89,13 @@ export interface XdevDispatch {
 	mode: "help" | "execute";
 	/** Validated inner args, kept for renderer delegation on result rebuilds. */
 	args?: Record<string, unknown>;
+	/**
+	 * Approval tier of the wrapped tool for {@link args} (`read` = no workspace
+	 * mutation). Absent for `help` dispatches and calls whose tier could not be
+	 * resolved. Consumed by the prewalk coordinator to skip read-only device
+	 * calls when deciding the model hand-off (issue #7312).
+	 */
+	tier?: ToolTier;
 	/** Details object returned by the wrapped tool, when executed. */
 	inner?: unknown;
 }
@@ -415,7 +423,18 @@ export async function dispatchXdevTool(
 		}
 
 		const validated = parseDeviceArgs(canonical as AiTool, content, toolCallId, () => renderDocs(canonical));
-		xdev = { ...xdev, args: validated };
+		// Record the wrapped tool's approval tier so the prewalk coordinator can
+		// tell a read-only device call (e.g. `lsp` navigation) from a real
+		// workspace mutation without re-decoding the payload. Best-effort: a
+		// throwing approval leaves the tier absent (prewalk then declines to
+		// switch), unlike the write gate which fails closed to `exec`.
+		let tier: ToolTier | undefined;
+		try {
+			tier = resolveToolTier(canonical, validated);
+		} catch {
+			tier = undefined;
+		}
+		xdev = { ...xdev, args: validated, tier };
 		const innerOnUpdate: AgentToolUpdateCallback | undefined = onUpdate
 			? partial =>
 					onUpdate({
@@ -425,7 +444,15 @@ export async function dispatchXdevTool(
 					})
 			: undefined;
 		const executable = state.decorateExecution?.(canonical) ?? canonical;
-		const result = await executable.execute(toolCallId, validated as never, signal, innerOnUpdate, context);
+		const executionContext = context
+			? {
+					...context,
+					xdevTierResolved: (effectiveTier: ToolTier) => {
+						xdev = { ...xdev, tier: effectiveTier };
+					},
+				}
+			: undefined;
+		const result = await executable.execute(toolCallId, validated as never, signal, innerOnUpdate, executionContext);
 		return { result, xdev: { ...xdev, inner: result.details } };
 	} catch (error) {
 		if (

package/src/utils/clipboard.ts

@@ -1,8 +1,14 @@
-import type { ClipboardImage } from "@oh-my-pi/pi-natives";
-import * as native from "@oh-my-pi/pi-natives";
-import { logger } from "@oh-my-pi/pi-utils";
+import {
+	type ClipboardImage,
+	copyToClipboard as nativeCopyToClipboard,
+	readImageFromClipboard as nativeReadImageFromClipboard,
+} from "@oh-my-pi/pi-natives/clipboard";
+import * as logger from "@oh-my-pi/pi-utils/logger";
+import { SUPPORTED_IMAGE_MIME_TYPES } from "@oh-my-pi/pi-utils/mime";
 import MAC_FILE_URL_SCRIPT from "./mac-file-urls.applescript" with { type: "text" };
 
+type SpawnCaptureOptions = { input?: string; timeoutMs?: number };
+
 /**
  * Run a subprocess and capture its stdout without blocking the event loop.
  *
@@ -10,15 +16,20 @@ import MAC_FILE_URL_SCRIPT from "./mac-file-urls.applescript" with { type: "text
  * path all shell out to CLI clipboard tools. The synchronous `execSync` API
  * parks the render loop until the child exits or the timeout fires, so a hung
  * clipboard daemon freezes the TUI for the full 2000ms budget (#4235). This
- * helper mirrors the previous semantics — read stdout as UTF-8, throw on
- * non-zero exit or timeout, forward optional stdin — but yields to the event
- * loop while the child runs.
+ * helper mirrors the previous semantics — capture stdout, throw on non-zero
+ * exit or timeout, forward optional stdin — but yields to the event loop while
+ * the child runs.
  *
  * @throws Error when the child fails to spawn, is killed by the timeout, or
- *   exits with a non-zero status. Callers rely on this to fall through to the
- *   outer catch and return an empty string / empty list.
+ *   exits with a non-zero status. Callers rely on this to use platform
+ *   fallbacks or report an empty clipboard.
  */
-async function spawnCapture(cmd: string[], options: { input?: string; timeoutMs?: number } = {}): Promise<string> {
+async function spawnCapture(cmd: string[], options: SpawnCaptureOptions & { encoding: "bytes" }): Promise<Uint8Array>;
+async function spawnCapture(cmd: string[], options?: SpawnCaptureOptions): Promise<string>;
+async function spawnCapture(
+	cmd: string[],
+	options: SpawnCaptureOptions & { encoding?: "bytes" } = {},
+): Promise<string | Uint8Array> {
 	const timeoutMs = options.timeoutMs ?? 2000;
 	const proc = Bun.spawn(cmd, {
 		stdout: "pipe",
@@ -31,7 +42,9 @@ async function spawnCapture(cmd: string[], options: { input?: string; timeoutMs?
 		proc.kill();
 	}, timeoutMs);
 	try {
-		const stdout = await new Response(proc.stdout).text();
+		const response = new Response(proc.stdout);
+		const stdout =
+			options.encoding === "bytes" ? new Uint8Array(await response.arrayBuffer()) : await response.text();
 		await proc.exited;
 		if (timedOut) {
 			throw new Error(`${cmd[0]} timed out after ${timeoutMs}ms`);
@@ -125,7 +138,7 @@ export async function copyToClipboard(text: string): Promise<void> {
 			}
 		}
 
-		await native.copyToClipboard(text);
+		await nativeCopyToClipboard(text);
 	} catch {
 		// Ignore — clipboard copy is best-effort
 	}
@@ -255,7 +268,7 @@ async function readTextViaPowerShell(): Promise<string | null> {
  * because terminal clipboard paths can leave image payloads invisible to the
  * native bridge.
  *
- * @returns PNG payload or null when no image is available.
+ * @returns A supported image payload or null when no image is available.
  */
 export async function readImageFromClipboard(): Promise<ClipboardImage | null> {
 	if (process.env.TERMUX_VERSION) {
@@ -272,7 +285,7 @@ export async function readImageFromClipboard(): Promise<ClipboardImage | null> {
 
 	if (process.platform === "win32") {
 		try {
-			const image = await native.readImageFromClipboard();
+			const image = await nativeReadImageFromClipboard();
 			if (image) return image;
 		} catch (err) {
 			logger.warn("clipboard: native Windows image read failed", { error: String(err) });
@@ -280,11 +293,24 @@ export async function readImageFromClipboard(): Promise<ClipboardImage | null> {
 		return await readImageViaPowerShell();
 	}
 
+	if (process.platform === "linux" && process.env.WAYLAND_DISPLAY) {
+		try {
+			const offeredMimeTypes = new Set((await spawnCapture(["wl-paste", "--list-types"])).split(/\r?\n/));
+			for (const mimeType of SUPPORTED_IMAGE_MIME_TYPES) {
+				if (!offeredMimeTypes.has(mimeType)) continue;
+				const data = await spawnCapture(["wl-paste", "--type", mimeType], { encoding: "bytes" });
+				if (data.byteLength > 0) return { data, mimeType };
+			}
+		} catch {
+			// Fall through when wl-clipboard is absent or no advertised image payload can be read.
+		}
+	}
+
 	if (!hasDisplay()) {
 		return null;
 	}
 
-	return (await native.readImageFromClipboard()) ?? null;
+	return (await nativeReadImageFromClipboard()) ?? null;
 }
 
 /**

package/src/utils/command-args.ts

@@ -39,38 +39,36 @@ export function parseCommandArgs(argsString: string): string[] {
  * containing patterns like $1, $@, or $ARGUMENTS are NOT recursively substituted.
  */
 export function substituteArgs(content: string, args: string[]): string {
-	let result = content;
-
-	// Replace $1, $2, etc. with positional args FIRST (before wildcards)
-	// This prevents wildcard replacement values containing $<digit> patterns from being re-substituted
-	result = result.replace(/\$(\d+)/g, (_, num) => {
-		const index = parseInt(num, 10) - 1;
-		return args[index] ?? "";
-	});
-
-	result = result.replace(/\$@\[(\d+)(?::(\d*)?)?\]/g, (_, startRaw: string, lengthRaw?: string) => {
-		const start = Number.parseInt(startRaw, 10);
-		if (!Number.isFinite(start) || start < 1) return "";
-		const startIndex = start - 1;
-		if (startIndex >= args.length) return "";
+	const allArgs = args.join(" ");
 
-		if (lengthRaw === undefined || lengthRaw === "") {
-			return args.slice(startIndex).join(" ");
-		}
+	return content.replace(
+		/\$@\[(\d+)(?::(\d*)?)?\]|\$ARGUMENTS|\$@|\$(\d+)/g,
+		(match, startRaw?: string, lengthRaw?: string, positionalNum?: string) => {
+			if (positionalNum !== undefined) {
+				const index = Number.parseInt(positionalNum, 10) - 1;
+				return args[index] ?? "";
+			}
 
-		const length = Number.parseInt(lengthRaw, 10);
-		if (!Number.isFinite(length) || length <= 0) return "";
-		return args.slice(startIndex, startIndex + length).join(" ");
-	});
+			if (startRaw !== undefined) {
+				const start = Number.parseInt(startRaw, 10);
+				if (!Number.isFinite(start) || start < 1) return "";
+				const startIndex = start - 1;
+				if (startIndex >= args.length) return "";
 
-	// Pre-compute all args joined (optimization)
-	const allArgs = args.join(" ");
+				if (lengthRaw === undefined || lengthRaw === "") {
+					return args.slice(startIndex).join(" ");
+				}
 
-	// Replace $ARGUMENTS with all args joined (new syntax, aligns with Claude, Codex, OpenCode)
-	result = result.replaceAll("$ARGUMENTS", allArgs);
+				const length = Number.parseInt(lengthRaw, 10);
+				if (!Number.isFinite(length) || length <= 0) return "";
+				return args.slice(startIndex, startIndex + length).join(" ");
+			}
 
-	// Replace $@ with all args joined (existing syntax)
-	result = result.replaceAll("$@", allArgs);
+			if (match === "$ARGUMENTS" || match === "$@") {
+				return allArgs;
+			}
 
-	return result;
+			return match;
+		},
+	);
 }

package/src/utils/tool-choice.ts

@@ -12,19 +12,6 @@ export function buildNamedToolChoice(toolName: string, model?: Model<Api>): Tool
 		return { type: "tool", name: toolName };
 	}
 
-	if (toolName === "computer" && model.supportsComputerUse === true) {
-		if (
-			model.api === "openai-codex-responses" ||
-			model.api === "openai-responses" ||
-			model.api === "azure-openai-responses"
-		) {
-			return { type: "computer" };
-		}
-		return undefined;
-	}
-	// Models without native computer support receive the tool as a regular
-	// function tool, so the generic named-function forcing below applies.
-
 	if (
 		model.api === "openai-codex-responses" ||
 		model.api === "openai-responses" ||

package/src/web/kagi.ts

@@ -156,6 +156,7 @@ export interface KagiSearchOptions {
 	recency?: "day" | "week" | "month" | "year";
 	sessionId?: string;
 	signal?: AbortSignal;
+	timeoutMs?: number;
 	fetch?: FetchImpl;
 }
 
@@ -253,7 +254,7 @@ export async function searchWithKagi(
 					Accept: "application/json",
 				},
 				body,
-				signal: withHardTimeout(options.signal),
+				signal: withHardTimeout(options.signal, options.timeoutMs),
 			});
 
 			if (!res.ok) {

package/src/web/search/index.ts

@@ -29,8 +29,13 @@ import {
 } from "./provider";
 import { applyQueryConstraints, parseSearchQuery } from "./query";
 import { renderSearchCall, renderSearchResult, type SearchRenderDetails } from "./render";
-import type { SearchProviderId, SearchResponse } from "./types";
-import { SearchProviderError } from "./types";
+import {
+	DEFAULT_WEB_SEARCH_TIMEOUT_SECONDS,
+	MAX_WEB_SEARCH_TIMEOUT_SECONDS,
+	SearchProviderError,
+	type SearchProviderId,
+	type SearchResponse,
+} from "./types";
 
 /** Web search tool parameters schema */
 export const webSearchSchema = type({
@@ -164,6 +169,16 @@ async function executeSearch(
 		geminiModel = undefined;
 	}
 
+	let timeoutMs = DEFAULT_WEB_SEARCH_TIMEOUT_SECONDS * 1_000;
+	try {
+		const configuredSeconds = settings.get("providers.webSearchTimeoutSeconds");
+		if (Number.isFinite(configuredSeconds) && configuredSeconds > 0) {
+			timeoutMs = Math.ceil(Math.min(configuredSeconds, MAX_WEB_SEARCH_TIMEOUT_SECONDS) * 1_000);
+		}
+	} catch {
+		// Preserve the default for one-shot callers that do not initialize Settings.
+	}
+
 	const failures: Array<{ provider: Pick<SearchProvider, "id" | "label">; error: unknown }> = [];
 	let availableProviderCount = 0;
 	let lastProvider: Pick<SearchProvider, "id" | "label"> | undefined;
@@ -196,6 +211,7 @@ async function executeSearch(
 				numSearchResults: params.num_search_results,
 				temperature: params.temperature,
 				signal,
+				timeoutMs,
 				authStorage,
 				modelRegistry,
 				sessionId,

package/src/web/search/providers/anthropic.ts

@@ -98,6 +98,7 @@ export interface AnthropicSearchParams {
 	max_tokens?: number;
 	temperature?: number;
 	signal?: AbortSignal;
+	timeoutMs?: number;
 	fetch?: FetchImpl;
 }
 
@@ -153,6 +154,7 @@ async function callSearch(
 	temperature?: number,
 	signal?: AbortSignal,
 	fetchImpl: FetchImpl = fetch,
+	timeoutMs?: number,
 ): Promise<AnthropicApiResponse> {
 	const url = buildAnthropicUrl(auth);
 	const headers = buildAnthropicSearchHeaders(auth);
@@ -193,7 +195,7 @@ async function callSearch(
 		method: "POST",
 		headers,
 		body: JSON.stringify(body),
-		signal: withHardTimeout(signal),
+		signal: withHardTimeout(signal, timeoutMs),
 	});
 
 	if (!response.ok) {
@@ -369,6 +371,7 @@ export async function searchAnthropic(
 				params.temperature,
 				params.signal,
 				params.fetch,
+				params.timeoutMs,
 			);
 		},
 		{

package/src/web/search/providers/base.ts

@@ -47,6 +47,8 @@ export interface SearchParams {
 	recency?: "day" | "week" | "month" | "year";
 	systemPrompt: string;
 	signal?: AbortSignal;
+	/** Hard timeout for this provider's search transport, in milliseconds. */
+	timeoutMs?: number;
 	fetch?: FetchImpl;
 	maxOutputTokens?: number;
 	numSearchResults?: number;

package/src/web/search/providers/brave.ts

@@ -52,6 +52,7 @@ export interface BraveSearchParams {
 	recency?: "day" | "week" | "month" | "year";
 	parsedQuery?: StructuredQuery;
 	signal?: AbortSignal;
+	timeoutMs?: number;
 	fetch?: FetchImpl;
 }
 
@@ -113,7 +114,7 @@ async function callBraveSearch(
 			Accept: "application/json",
 			"X-Subscription-Token": apiKey,
 		},
-		signal: withHardTimeout(params.signal),
+		signal: withHardTimeout(params.signal, params.timeoutMs),
 	});
 
 	if (!response.ok) {
@@ -173,6 +174,7 @@ export class BraveProvider extends SearchProvider {
 			recency: params.recency,
 			parsedQuery: params.parsedQuery,
 			signal: params.signal,
+			timeoutMs: params.timeoutMs,
 			fetch: params.fetch,
 		});
 	}

package/src/web/search/providers/browser-page.ts

@@ -26,6 +26,7 @@ interface BrowserFallbackOptions {
 export interface BrowserFetchOptions {
 	fetch?: FetchImpl;
 	signal: AbortSignal;
+	timeoutMs?: number;
 	randomizeHeaders?: boolean;
 	referer?: string;
 	init?: Omit<RequestInit, "headers" | "signal">;
@@ -50,6 +51,7 @@ async function browseHtmlPage(
 	url: string,
 	options: BrowserFallbackOptions,
 	signal: AbortSignal,
+	timeoutMs = SEARCH_HARD_TIMEOUT_MS,
 ): Promise<LoadedHtmlPage> {
 	const { homeUrl, ready } = options;
 	const attempts = Math.max(1, options.attempts ?? 1);
@@ -76,14 +78,14 @@ async function browseHtmlPage(
 		await applyStealthPatches(handle.browser, activePage, handle.stealth);
 		if (homeUrl) {
 			await untilAborted(signal, () =>
-				activePage.goto(homeUrl, { waitUntil: "domcontentloaded", timeout: SEARCH_HARD_TIMEOUT_MS }),
+				activePage.goto(homeUrl, { waitUntil: "domcontentloaded", timeout: timeoutMs }),
 			);
 		}
 		for (let attempt = 0; attempt < attempts; attempt++) {
 			if (attempt > 0 && options.retryDelayMs) await Bun.sleep(options.retryDelayMs);
 
 			const response = await untilAborted(signal, () =>
-				activePage.goto(url, { waitUntil: "domcontentloaded", timeout: SEARCH_HARD_TIMEOUT_MS }),
+				activePage.goto(url, { waitUntil: "domcontentloaded", timeout: timeoutMs }),
 			);
 			if (options.afterNavigation) await options.afterNavigation(activePage, signal);
 			if (ready) {
@@ -113,11 +115,11 @@ export async function browserFetch(url: string, options: BrowserFetchOptions): P
 		page = await fetchHtmlPage(url, options, fetchImpl);
 	} catch (error) {
 		if (options.fetch || !options.browser) throw error;
-		return browseHtmlPage(url, options.browser, options.signal);
+		return browseHtmlPage(url, options.browser, options.signal, options.timeoutMs);
 	}
 
 	if (!options.browser || options.fetch) return page;
 	const isSuccessful = page.status >= 200 && page.status < 300;
 	if (isSuccessful && !options.browser.shouldFallback(page)) return page;
-	return browseHtmlPage(url, options.browser, options.signal);
+	return browseHtmlPage(url, options.browser, options.signal, options.timeoutMs);
 }

package/src/web/search/providers/codex.ts

@@ -145,6 +145,7 @@ function shouldRetryWithNextDefaultModel(error: unknown): boolean {
 
 export interface CodexSearchParams {
 	signal?: AbortSignal;
+	timeoutMs?: number;
 	fetch?: FetchImpl;
 	query: string;
 	system_prompt?: string;
@@ -442,6 +443,7 @@ async function callCodexSearch(
 	query: string,
 	options: {
 		signal?: AbortSignal;
+		timeoutMs?: number;
 		systemPrompt?: string;
 		searchContextSize?: "low" | "medium" | "high";
 		model: CodexModelCandidate;
@@ -496,7 +498,7 @@ async function callCodexSearch(
 		method: "POST",
 		headers,
 		body: JSON.stringify(body),
-		signal: withHardTimeout(options.signal),
+		signal: withHardTimeout(options.signal, options.timeoutMs),
 	});
 
 	if (!response.ok) {
@@ -645,6 +647,7 @@ async function runCodexSearchCandidates(options: {
 		try {
 			return await callCodexSearch(options.auth, options.query, {
 				signal: options.params.signal,
+				timeoutMs: options.params.timeoutMs,
 				systemPrompt: options.params.systemPrompt,
 				searchContextSize: "high",
 				model: candidate,