@gajae-code/coding-agent 0.16.1 → 0.16.4

package/src/tools/bash.ts

@@ -1107,7 +1107,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			manager.failNow(jobId, jobGeneration, "Bash job owner was torn down.");
 		});
 		void completion.promise.finally(unregisterOwnerCleanup);
-		registerOwnedIfLineaged(manager, options.toolCallId, jobId, this.session.getSessionId?.() ?? undefined);
+		registerOwnedIfLineaged(
+			manager,
+			options.toolCallId,
+			jobId,
+			this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined,
+		);
 
 		return {
 			jobId,
@@ -1132,27 +1137,29 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 	 * running (review thread P1).
 	 */
 	#resolveOwnedJobManager(): AsyncJobManager | undefined {
-		const endpointId = this.session.getSessionId?.() ?? undefined;
+		const endpointId = this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined;
 		if (this.session.getAsyncJobManager) return this.session.getAsyncJobManager();
 		return AsyncJobManager.forEndpoint(endpointId) ?? AsyncJobManager.instance();
 	}
 
 	/**
 	 * Whether a queued user steer may fold the running foreground wait. Mirrors
-	 * the loop's own steer admission: `busyPromptMode=queue` never admits a
-	 * steer into the busy run, and `toolInterruptPolicy=finish_tools` explicitly
-	 * lets the tool finish, so neither may fold. The
-	 * auto-background setting is deliberately not consulted: like the chord,
-	 * a steer fold is a user action.
+	 * the loop's steer admission: `busyPromptMode=queue` never admits a steer
+	 * into the busy run, so it never folds. `toolInterruptPolicy` is
+	 * deliberately NOT a gate: `finish_tools` means "do not kill the batch to
+	 * deliver a steer", and a fold kills nothing. It is the one way to deliver
+	 * the steer now AND let the command finish, so it applies under both
+	 * policies; the policy only decides what the loop does with sibling tools
+	 * after the fold returns. The auto-background setting is likewise not
+	 * consulted: like the chord, a steer fold is a user action.
 	 *
-	 * Fails closed: a session that cannot prove its tool interrupt policy or
-	 * report newly admitted steering is not steer-foldable.
+	 * Fails closed: a session that cannot report newly admitted steering or
+	 * accept a fold request is not steer-foldable.
 	 */
 	#steerFoldEnabled(): boolean {
-		const { waitForUserSteering, getToolInterruptPolicy, requestForegroundBashBackground } = this.session;
-		if (!waitForUserSteering || !getToolInterruptPolicy || !requestForegroundBashBackground) return false;
-		if (this.session.settings.get("busyPromptMode") !== "steer") return false;
-		return getToolInterruptPolicy() === "abort_tools";
+		const { waitForUserSteering, requestForegroundBashBackground } = this.session;
+		if (!waitForUserSteering || !requestForegroundBashBackground) return false;
+		return this.session.settings.get("busyPromptMode") === "steer";
 	}
 
 	/**
@@ -1161,8 +1168,8 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 	 * when the wait starts, or one that arrives inside the grace window, never
 	 * folds: the command finishes normally and that steer is consumed at the
 	 * ordinary tool boundary. The watcher keeps observing so a later qualifying
-	 * steer still folds, and re-checks the gates at that moment so a
-	 * `busyPromptMode`/`toolInterruptPolicy` change during the command is honored.
+	 * steer still folds, and re-checks the gate at that moment so a
+	 * `busyPromptMode` change during the command is honored.
 	 * Returns a stop function; call it when the wait settles. No-op when steer
 	 * folding is gated off at start.
 	 */
@@ -1679,7 +1686,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		// Monitor jobs are exact owned background work of the turn that started
 		// them: register the five-tuple so scope:"owned" terminal abort stops the
 		// monitor too (review thread P2).
-		registerOwnedIfLineaged(manager, opts.toolCallId, jobId, this.session.getSessionId?.() ?? undefined);
+		registerOwnedIfLineaged(
+			manager,
+			opts.toolCallId,
+			jobId,
+			this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined,
+		);
 		currentJobId = jobId;
 		return { jobId, label, commandCwd: prepared.commandCwd };
 	}
@@ -1881,19 +1893,31 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			}
 			if (waitResult.kind === "completed") {
 				ownedManager.acknowledgeDeliveries([job.jobId]);
-				unregisterForegroundOwnedBash(ownedManager, job.jobId, this.session.getSessionId?.() ?? "local");
+				unregisterForegroundOwnedBash(
+					ownedManager,
+					job.jobId,
+					this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? "local",
+				);
 				return waitResult.result;
 			}
 			if (waitResult.kind === "failed") {
 				ownedManager.acknowledgeDeliveries([job.jobId]);
-				unregisterForegroundOwnedBash(ownedManager, job.jobId, this.session.getSessionId?.() ?? "local");
+				unregisterForegroundOwnedBash(
+					ownedManager,
+					job.jobId,
+					this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? "local",
+				);
 				throw waitResult.error;
 			}
 			if (waitResult.kind === "aborted") {
 				ownedManager.cancel(job.jobId);
 				const terminal = await job.completion;
 				ownedManager.acknowledgeDeliveries([job.jobId]);
-				unregisterForegroundOwnedBash(ownedManager, job.jobId, this.session.getSessionId?.() ?? "local");
+				unregisterForegroundOwnedBash(
+					ownedManager,
+					job.jobId,
+					this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? "local",
+				);
 				if (terminal.kind === "failed") {
 					throw new ToolAbortError(
 						formatManagedAbortFailure(terminal.error, terminal.result, job.getLatestText()),
@@ -2355,7 +2379,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			// already ran above, so exactly ONE remote handle exists and is retained
 			// across the fold.
 			const bridgeManager = ownedManager;
-			const bridgeEndpointId = this.session.getSessionId?.() ?? "local";
+			const bridgeEndpointId = this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? "local";
 			const bridgeLabel = command.length > 120 ? `${command.slice(0, 117)}...` : command;
 			const bridgeCompletion = Promise.withResolvers<ManagedBashJobCompletion>();
 			let bridgeForegroundSettled = false;
@@ -2619,7 +2643,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 							throw error;
 						}
 						const ptyGeneration = ptyManager.getJob(ptyJobId)?.generation ?? ptyJobId;
-						registerOwnedIfLineaged(ptyManager, toolCallId, ptyJobId, this.session.getSessionId?.() ?? undefined);
+						registerOwnedIfLineaged(
+							ptyManager,
+							toolCallId,
+							ptyJobId,
+							this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined,
+						);
 						const unregisterPtyOwnerCleanup = ptyManager.registerOwnerCleanup(ptyOwnerId, () => {
 							killPtyOnce();
 							ptyManager.failNow(ptyJobId, ptyGeneration, ownerTeardownText());

package/src/tools/cron.ts

@@ -592,7 +592,7 @@ export class CronTool implements AgentTool<typeof cronSchema, CronToolDetails> {
 	}
 
 	#resolveOwnedJobManager(): AsyncJobManager | undefined {
-		const endpointId = this.session.getSessionId?.() ?? undefined;
+		const endpointId = this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined;
 		return (
 			this.session.getAsyncJobManager?.() ?? AsyncJobManager.forEndpoint(endpointId) ?? AsyncJobManager.instance()
 		);

package/src/tools/fetch.ts

@@ -1167,13 +1167,36 @@ interface ReadUrlCacheEntry {
 	wrappedPreambleChars?: number;
 }
 
+// Entries hold whole-page outputs and image payloads, so this map must stay
+// bounded in long-lived hosts (TUI, SDK broker). Each fetch caches one entry
+// under up to two keys (requested + final URL). FIFO eviction is sufficient:
+// a miss simply refetches, so correctness never depends on a hit.
+export const READ_URL_CACHE_MAX_KEYS = 64;
+
 const readUrlCache = new Map<string, ReadUrlCacheEntry>();
 
 function getReadUrlCacheKey(session: ToolSession, requestedUrl: string, raw: boolean): string {
-	const scope = session.getSessionFile() ?? session.cwd;
+	const sessionFile = session.getSessionFile();
+	const sessionId = session.getSessionId?.();
+	const scope = sessionFile ? `file:${sessionFile}` : sessionId ? `session:${sessionId}` : `cwd:${session.cwd}`;
 	return `${scope}::${raw ? "raw" : "rendered"}::${normalizeUrl(requestedUrl)}`;
 }
 
+/** Test-only seam for deterministic module-global cache assertions. */
+export const readUrlCacheTestHooks = {
+	get size(): number {
+		return readUrlCache.size;
+	},
+	get retainedOutputChars(): number {
+		let total = 0;
+		for (const entry of new Set(readUrlCache.values())) total += entry.output.length;
+		return total;
+	},
+	reset(): void {
+		readUrlCache.clear();
+	},
+};
+
 async function readArtifactOutput(session: ToolSession, artifactId: string): Promise<string | null> {
 	const artifactsDir = session.getArtifactsDir?.();
 	if (!artifactsDir) return null;
@@ -1224,6 +1247,11 @@ async function ensureReadUrlCacheArtifact(session: ToolSession, entry: ReadUrlCa
 function cacheReadUrlEntry(session: ToolSession, requestedUrl: string, raw: boolean, entry: ReadUrlCacheEntry): void {
 	readUrlCache.set(getReadUrlCacheKey(session, requestedUrl, raw), entry);
 	readUrlCache.set(getReadUrlCacheKey(session, entry.details.finalUrl, raw), entry);
+	while (readUrlCache.size > READ_URL_CACHE_MAX_KEYS) {
+		const oldest = readUrlCache.keys().next().value;
+		if (oldest === undefined) break;
+		readUrlCache.delete(oldest);
+	}
 }
 
 async function buildReadUrlCacheEntry(

package/src/tools/index.ts

@@ -242,8 +242,6 @@ export interface ToolSession {
 	hasForegroundBashBackgroundRequestHandler?: () => boolean;
 	/** Request that a foreground wait fold into a background job, if supported. `reason` names the trigger; `adapter` targets a specific wait instead of the newest registration. */
 	requestForegroundBashBackground?: (reason?: FoldReason, adapter?: FoldAdapter) => Promise<boolean>;
-	/** Current tool interrupt policy; `finish_tools` lets the running tool finish, so a steer must not fold it. */
-	getToolInterruptPolicy?: () => "abort_tools" | "finish_tools";
 
 	/** Get the session-owned or inherited async job manager. */
 	getAsyncJobManager?: () => AsyncJobManager | undefined;
@@ -251,6 +249,14 @@ export interface ToolSession {
 	waitForUserSteering?: (signal: AbortSignal) => Promise<void>;
 	/** Get session ID */
 	getSessionId?: () => string | null;
+	/**
+	 * Opaque async-job ownership/lookup endpoint key. This is not a workflow or
+	 * path identity: workflow/session consumers must use getSessionId(). Only
+	 * AsyncJobManager ownership and endpoint-first lookup may use this accessor
+	 * (subagent-inherited managers are registered under the parent's endpoint;
+	 * review thread P1).
+	 */
+	getAsyncEndpointId?: () => string | null;
 	/** Get credential-selection session identity. */
 	getCredentialSessionId?: () => string | null;
 	/** Scope-held MCP facade for mcp:// resolution. */

package/src/tools/job.ts

@@ -105,7 +105,9 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 	): Promise<AgentToolResult<JobToolDetails>> {
 		const manager =
 			this.session.getAsyncJobManager?.() ??
-			AsyncJobManager.forEndpoint(this.session.getSessionId?.() ?? undefined) ??
+			AsyncJobManager.forEndpoint(
+				this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined,
+			) ??
 			AsyncJobManager.instance();
 		if (!manager) {
 			return {
@@ -396,7 +398,11 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 			const generation = manager.getJob?.(job.id)?.generation;
 			if (!generation) continue;
 			// The endpoint disambiguates concurrent sessions' same job ids (review P1).
-			const registration = lookupOwnedRegistration(job.id, generation, this.session.getSessionId?.() ?? "local");
+			const registration = lookupOwnedRegistration(
+				job.id,
+				generation,
+				this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? "local",
+			);
 			if (registration) unregisterOwnedRegistration(registration);
 		}
 

package/src/tools/monitor.ts

@@ -119,7 +119,9 @@ export class MonitorTool implements AgentTool<typeof monitorSchema, MonitorToolD
 		// different concurrent top-level session (review thread P1).
 		const manager =
 			this.session.getAsyncJobManager?.() ??
-			AsyncJobManager.forEndpoint(this.session.getSessionId?.() ?? undefined) ??
+			AsyncJobManager.forEndpoint(
+				this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined,
+			) ??
 			AsyncJobManager.instance();
 		if (!manager) {
 			throw new ToolError("Async execution is disabled; the monitor tool is unavailable in this session.");
@@ -197,7 +199,11 @@ export class MonitorTool implements AgentTool<typeof monitorSchema, MonitorToolD
 			// endpoint-less fallback scan could attach a foreign session's
 			// registration (review thread P2).
 			const registration = generation
-				? lookupOwnedRegistration(jobId, generation, this.session.getSessionId?.() ?? "local")
+				? lookupOwnedRegistration(
+						jobId,
+						generation,
+						this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? "local",
+					)
 				: undefined;
 			const ownedCompletion = registration
 				? {

package/src/tools/path-utils.ts

@@ -696,6 +696,8 @@ export interface ToolScopeOptions {
 	surfaceExactFilePaths?: boolean;
 	/** Extra hint appended to "Path not found" when stat fails and the user supplied multiple paths. */
 	multipathStatHint?: string;
+	/** Cancels internal-URL resolution and prevents further scope work. */
+	signal?: AbortSignal;
 }
 
 export interface ToolScopeResolution {
@@ -719,6 +721,7 @@ export interface ToolScopeResolution {
  */
 export async function resolveToolSearchScope(opts: ToolScopeOptions): Promise<ToolScopeResolution> {
 	const { rawPaths: inputs, cwd, internalUrlAction, getArtifactsDir, getAuthorizedArtifactsDirs } = opts;
+	opts.signal?.throwIfAborted();
 	const rawPaths = inputs.map(normalizePathLikeInput);
 	if (rawPaths.some(rawPath => rawPath.length === 0)) {
 		throw new ToolError("`paths` must contain non-empty paths or globs");
@@ -727,6 +730,7 @@ export async function resolveToolSearchScope(opts: ToolScopeOptions): Promise<To
 	const resolvedPathInputs: string[] = [];
 	const immutableSourcePaths = new Set<string>();
 	for (const rawPath of rawPaths) {
+		opts.signal?.throwIfAborted();
 		if (!internalRouter.canHandle(rawPath)) {
 			resolvedPathInputs.push(rawPath);
 			continue;
@@ -739,7 +743,9 @@ export async function resolveToolSearchScope(opts: ToolScopeOptions): Promise<To
 			getArtifactsDir,
 			getAuthorizedArtifactsDirs,
 			mcpManager: opts.mcpManager,
+			signal: opts.signal,
 		});
+		opts.signal?.throwIfAborted();
 		if (!resource.sourcePath) {
 			throw new ToolError(`Cannot ${internalUrlAction} internal URL without a backing file: ${rawPath}`);
 		}
@@ -753,6 +759,7 @@ export async function resolveToolSearchScope(opts: ToolScopeOptions): Promise<To
 	let effectivePaths = resolvedPathInputs;
 	if (resolvedPathInputs.length > 1) {
 		const partition = await partitionExistingPaths(resolvedPathInputs, cwd, parseSearchPath);
+		opts.signal?.throwIfAborted();
 		if (partition.valid.length === 0) {
 			throw new ToolError(`Path not found: ${partition.missing.join(", ")}`);
 		}

package/src/tools/search.ts

@@ -5,7 +5,7 @@ import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallb
 import type { GrepMatch, GrepResult, grep as grepFn } from "@gajae-code/natives";
 import type { Component } from "@gajae-code/tui";
 import { Text } from "@gajae-code/tui";
-import { prompt, untilAborted } from "@gajae-code/utils";
+import { prompt } from "@gajae-code/utils";
 import * as z from "zod/v4";
 import { getFileReadCache } from "../edit/file-read-cache";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
@@ -35,7 +35,7 @@ import {
 	PREVIEW_LIMITS,
 	splitGroupsByBlankLine,
 } from "./render-utils";
-import { ToolError } from "./tool-errors";
+import { ToolAbortError, ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
 
 let searchNativesLoad:
@@ -71,6 +71,7 @@ const searchSchema = z
 			.number()
 			.optional()
 			.describe("files to skip before collecting results — use to paginate when the prior call hit the file limit"),
+		timeout: z.number().min(0.5).max(60).default(5).describe("timeout in seconds (0.5–60)").optional(),
 	})
 	.strict();
 
@@ -90,6 +91,9 @@ export const SINGLE_FILE_MATCHES = 200;
  * (DEFAULT_FILE_LIMIT files × MULTI_FILE_PER_FILE_MATCHES matches) plus
  * pagination headroom so the caller can see total file count. */
 const INTERNAL_TOTAL_CAP = 2000;
+const DEFAULT_SEARCH_TIMEOUT_MS = 5000;
+const MIN_SEARCH_TIMEOUT_MS = 500;
+const MAX_SEARCH_TIMEOUT_MS = 60_000;
 
 /**
  * Detect a `,` that is not inside a `{…}` brace expansion. Used to catch
@@ -130,6 +134,7 @@ function containsTopLevelComma(entry: string): boolean {
 async function resolveArchiveSearchPaths(
 	paths: string[],
 	cwd: string,
+	signal?: AbortSignal,
 ): Promise<{
 	resolvedPaths: string[];
 	displayMap: Map<string, string>;
@@ -143,64 +148,71 @@ async function resolveArchiveSearchPaths(
 	const unreadable: string[] = [];
 	let tempDir: string | undefined;
 	const archiveCache = new Map<string, ArchiveReader>();
+	const cleanup = async () => {
+		const directory = tempDir;
+		tempDir = undefined;
+		if (directory) await rm(directory, { recursive: true, force: true }).catch(() => {});
+	};
 
-	for (let idx = 0; idx < paths.length; idx++) {
-		const entry = paths[idx];
-		const candidates = parseArchivePathCandidates(entry);
-		// Longest archive prefix first; we want the one whose member portion is non-empty.
-		const member = candidates.find(c => c.subPath !== "" && c.archivePath !== entry);
-		if (!member) continue;
+	try {
+		for (let idx = 0; idx < paths.length; idx++) {
+			signal?.throwIfAborted();
+			const entry = paths[idx];
+			const candidates = parseArchivePathCandidates(entry);
+			// Longest archive prefix first; we want the one whose member portion is non-empty.
+			const member = candidates.find(c => c.subPath !== "" && c.archivePath !== entry);
+			if (!member) continue;
+
+			const archiveAbs = resolveReadPath(member.archivePath, cwd);
+			let archive = archiveCache.get(archiveAbs);
+			if (!archive) {
+				try {
+					archive = await openArchive(archiveAbs);
+				} catch (err) {
+					unreadable.push(`${entry} (cannot open archive: ${(err as Error).message})`);
+					continue;
+				}
+				archiveCache.set(archiveAbs, archive);
+			}
 
-		const archiveAbs = resolveReadPath(member.archivePath, cwd);
-		let archive = archiveCache.get(archiveAbs);
-		if (!archive) {
+			let extracted: ExtractedArchiveFile;
 			try {
-				archive = await openArchive(archiveAbs);
+				extracted = await archive.readFile(member.subPath);
 			} catch (err) {
-				unreadable.push(`${entry} (cannot open archive: ${(err as Error).message})`);
+				unreadable.push(`${entry} (${(err as Error).message})`);
+				continue;
+			}
+			signal?.throwIfAborted();
+			// UTF-8 only — binary members would just produce noise through ripgrep.
+			if (extracted.bytes.some(byte => byte === 0)) {
+				unreadable.push(`${entry} (binary archive entry)`);
+				continue;
+			}
+			let text: string;
+			try {
+				text = new TextDecoder("utf-8", { fatal: true }).decode(extracted.bytes);
+			} catch {
+				unreadable.push(`${entry} (non-UTF-8 archive entry)`);
 				continue;
 			}
-			archiveCache.set(archiveAbs, archive);
-		}
-
-		let extracted: ExtractedArchiveFile;
-		try {
-			extracted = await archive.readFile(member.subPath);
-		} catch (err) {
-			unreadable.push(`${entry} (${(err as Error).message})`);
-			continue;
-		}
-		// UTF-8 only — binary members would just produce noise through ripgrep.
-		if (extracted.bytes.some(byte => byte === 0)) {
-			unreadable.push(`${entry} (binary archive entry)`);
-			continue;
-		}
-		let text: string;
-		try {
-			text = new TextDecoder("utf-8", { fatal: true }).decode(extracted.bytes);
-		} catch {
-			unreadable.push(`${entry} (non-UTF-8 archive entry)`);
-			continue;
-		}
 
-		if (!tempDir) {
-			tempDir = await mkdtemp(path.join(tmpdir(), "gjc-search-archive-"));
+			if (!tempDir) {
+				tempDir = await mkdtemp(path.join(tmpdir(), "gjc-search-archive-"));
+			}
+			// Per-entry filename keeps the scratch path unique even when two selectors
+			// resolve to members with the same basename.
+			const safeBase = path.basename(member.subPath).replace(/[^\w.-]+/g, "_") || "entry";
+			const tempPath = path.join(tempDir, `${idx}-${safeBase}`);
+			await writeFile(tempPath, text);
+			resolvedPaths[idx] = tempPath;
+			displayMap.set(tempPath, entry);
+			displaySet.add(entry);
 		}
-		// Per-entry filename keeps the scratch path unique even when two selectors
-		// resolve to members with the same basename.
-		const safeBase = path.basename(member.subPath).replace(/[^\w.-]+/g, "_") || "entry";
-		const tempPath = path.join(tempDir, `${idx}-${safeBase}`);
-		await writeFile(tempPath, text);
-		resolvedPaths[idx] = tempPath;
-		displayMap.set(tempPath, entry);
-		displaySet.add(entry);
+	} catch (error) {
+		await cleanup();
+		throw error;
 	}
 
-	const cleanup = async () => {
-		if (tempDir) {
-			await rm(tempDir, { recursive: true, force: true }).catch(() => {});
-		}
-	};
 	return { resolvedPaths, displayMap, displaySet, unreadable, cleanup };
 }
 
@@ -235,6 +247,8 @@ export interface SearchToolOptions {
 	context?: number;
 	/** Per-call total match cap used by Cursor's native Pi grep frame. */
 	totalMatchLimit?: number;
+	/** Test or remote override for the native grep implementation. */
+	grep?: typeof grepFn;
 }
 
 type SearchParams = z.infer<typeof searchSchema>;
@@ -266,12 +280,23 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 		_onUpdate?: AgentToolUpdateCallback<SearchToolDetails>,
 		_toolContext?: AgentToolContext,
 	): Promise<AgentToolResult<SearchToolDetails>> {
-		const { pattern, i, gitignore, skip } = params;
+		const { pattern, i, gitignore, skip, timeout } = params;
 		// Recurring real-world failure mode: models omit `paths` for repo-wide
 		// searches. Default to the working directory instead of failing the call.
 		const paths = params.paths ?? ["."];
+		const requestedTimeoutMs = timeout != null ? Math.round(timeout * 1000) : DEFAULT_SEARCH_TIMEOUT_MS;
+		const timeoutMs = Math.min(MAX_SEARCH_TIMEOUT_MS, Math.max(MIN_SEARCH_TIMEOUT_MS, requestedTimeoutMs));
+		const deadlineAt = Date.now() + timeoutMs;
+		const timeoutSignal = AbortSignal.timeout(timeoutMs);
+		const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+		const throwIfSearchCancelled = (): void => {
+			signal?.throwIfAborted();
+			if (Date.now() >= deadlineAt) throw new Error("Aborted: Timeout");
+			combinedSignal.throwIfAborted();
+		};
 
-		return untilAborted(signal, async () => {
+		try {
+			throwIfSearchCancelled();
 			const normalizedPattern = pattern.trim();
 			if (!normalizedPattern) {
 				throw new ToolError("Pattern must not be empty");
@@ -292,8 +317,10 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 				displaySet: archiveDisplaySet,
 				unreadable: archiveUnreadable,
 				cleanup: cleanupArchiveScratch,
-			} = await resolveArchiveSearchPaths(paths, this.session.cwd);
+			} = await resolveArchiveSearchPaths(paths, this.session.cwd, combinedSignal);
+			let completedResult: AgentToolResult<SearchToolDetails> | undefined;
 			try {
+				throwIfSearchCancelled();
 				if (archiveUnreadable.length > 0 && resolvedPaths.length === archiveUnreadable.length) {
 					// All inputs were archive selectors we couldn't materialize; surface the
 					// reason instead of a downstream "path not found" from the scope resolver.
@@ -324,7 +351,9 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 					trackImmutableSources: true,
 					surfaceExactFilePaths: true,
 					multipathStatHint: " (`paths` entries must each exist relative to cwd)",
+					signal: combinedSignal,
 				});
+				throwIfSearchCancelled();
 				const { searchPath, isDirectory, multiTargets, exactFilePaths, missingPaths, immutableSourcePaths } = scope;
 				// When the only input was an archive selector, surface that selector instead
 				// of the temp scratch path the resolver substituted in.
@@ -345,7 +374,8 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 				const baseDisplayMode = resolveFileDisplayMode(this.session);
 				const immutableDisplayMode = resolveFileDisplayMode(this.session, { immutable: true });
 
-				const { GrepOutputMode, grep } = await searchNatives();
+				const { GrepOutputMode, grep: nativeGrep } = await searchNatives();
+				const grep = this.options.grep ?? nativeGrep;
 				const effectiveOutputMode = GrepOutputMode.Content;
 				// Multi-scope = more than one file may match. We fetch up to
 				// INTERNAL_TOTAL_CAP matches from native grep, then in JS group by
@@ -363,7 +393,10 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 						let totalMatches = 0;
 						let filesSearched = 0;
 						const targets = exactFilePaths
-							? exactFilePaths.map(filePath => ({ basePath: filePath, glob: undefined as string | undefined }))
+							? exactFilePaths.map(filePath => ({
+									basePath: filePath,
+									glob: undefined as string | undefined,
+								}))
 							: (multiTargets ?? []);
 						for (const target of targets) {
 							const targetResult = await grep(
@@ -381,9 +414,12 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 									contextAfter: normalizedContextAfter,
 									maxColumns: DEFAULT_MAX_COLUMN,
 									mode: effectiveOutputMode,
+									signal: combinedSignal,
+									timeoutMs,
 								},
 								undefined,
 							);
+							throwIfSearchCancelled();
 							limitReached = limitReached || Boolean(targetResult.limitReached);
 							totalMatches += targetResult.totalMatches;
 							filesSearched += targetResult.filesSearched;
@@ -416,9 +452,12 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 								contextAfter: normalizedContextAfter,
 								maxColumns: DEFAULT_MAX_COLUMN,
 								mode: effectiveOutputMode,
+								signal: combinedSignal,
+								timeoutMs,
 							},
 							undefined,
 						);
+						throwIfSearchCancelled();
 					}
 				} catch (err) {
 					if (err instanceof Error && err.message.startsWith("regex parse error")) {
@@ -518,7 +557,10 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 						missingPaths: missingPaths.length > 0 ? missingPaths : undefined,
 					};
 					const text = warningNote ? `No matches found\n${warningNote}` : "No matches found";
-					return toolResult(details).text(text).done();
+					const noMatchResult = toolResult(details).text(text).done();
+					await cleanupArchiveScratch();
+					throwIfSearchCancelled();
+					return noMatchResult;
 				}
 				const outputLines: string[] = [];
 				let linesTruncated = false;
@@ -644,11 +686,25 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 				if (truncation.truncated) {
 					resultBuilder.truncation(truncation, { direction: "head" });
 				}
-				return resultBuilder.done();
+				throwIfSearchCancelled();
+				completedResult = resultBuilder.done();
 			} finally {
 				await cleanupArchiveScratch();
 			}
-		});
+			throwIfSearchCancelled();
+			if (!completedResult) throw new Error("Search result assembly did not complete");
+			return completedResult;
+		} catch (error) {
+			const nativeTimedOut = error instanceof Error && error.message === "Aborted: Timeout";
+			if ((timeoutSignal.aborted || nativeTimedOut) && !signal?.aborted) {
+				const seconds = timeoutMs % 1000 === 0 ? `${timeoutMs / 1000}` : (timeoutMs / 1000).toFixed(1);
+				throw new ToolError(`Search timed out after ${seconds}s; increase timeout or narrow paths/pattern`);
+			}
+			if (combinedSignal.aborted || (error instanceof Error && error.name === "AbortError")) {
+				throw new ToolAbortError();
+			}
+			throw error;
+		}
 	}
 }
 
@@ -662,6 +718,7 @@ interface SearchRenderArgs {
 	i?: boolean;
 	gitignore?: boolean;
 	skip?: number;
+	timeout?: number;
 }
 
 const COLLAPSED_TEXT_LIMIT = PREVIEW_LIMITS.COLLAPSED_LINES * 2;
@@ -674,6 +731,7 @@ export const searchToolRenderer = {
 		if (args.i) meta.push("case:insensitive");
 		if (args.gitignore === false) meta.push("gitignore:false");
 		if (args.skip !== undefined && args.skip > 0) meta.push(`skip:${args.skip}`);
+		if (args.timeout !== undefined && args.timeout !== 5) meta.push(`timeout:${args.timeout}s`);
 
 		const text = renderStatusLine(
 			{ icon: "pending", title: "Search", description: args.pattern || "?", meta },