@namzu/sdk 35.0.0 → 36.0.0

package/src/tools/builtins/bash.ts

@@ -1,11 +1,13 @@
-import { exec } from 'node:child_process'
-import { promisify } from 'node:util'
+import { spawn } from 'node:child_process'
+import { StringDecoder } from 'node:string_decoder'
 import { z } from 'zod'
+import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
 import { DANGEROUS_PATTERNS } from '../../constants/tools/index.js'
+import { killTree } from '../../process/kill-tree.js'
+import { subscribeToAbort } from '../../utils/abort.js'
 import { defineTool } from '../defineTool.js'
 import { scrubInheritedEnv } from '../env-scrub.js'
 
-const execAsync = promisify(exec)
 // Namzu owns its own bash timeout knob — `NAMZU_BASH_TIMEOUT_MS`.
 // The Vandal fallback (`VANDAL_NAMZU_TIMEOUT_MS`) lived here as a
 // historical bridge while Namzu was carved out of the Vandal repo,
@@ -67,25 +69,205 @@ const inputSchema = z.object({
 
 type BashInput = z.infer<typeof inputSchema>
 
+const MAX_SHELL_PROGRESS_CHARS = 160
+
+/** Keep a bounded tail even when a process never writes a newline. */
+function appendProgressTail(previous: string, chunk: string, start: number, end: number): string {
+	return (previous + chunk.slice(Math.max(start, end - MAX_SHELL_PROGRESS_CHARS), end)).slice(
+		-MAX_SHELL_PROGRESS_CHARS,
+	)
+}
+
+/** Clipping a UTF-16 string must not display half of a surrogate pair. */
+function progressLine(value: string): string {
+	let line = value.trim()
+	const first = line.charCodeAt(0)
+	if (first >= 0xdc00 && first <= 0xdfff) line = line.slice(1)
+	const last = line.charCodeAt(line.length - 1)
+	if (last >= 0xd800 && last <= 0xdbff) line = line.slice(0, -1)
+	return line
+}
+
 /**
- * The last line worth showing from one chunk of streamed output.
- *
- * A progress line is a status, not a log: the host renders one line and
- * replaces it as the next arrives, so sending a whole chunk sends a wall
- * of text into a slot that shows one line of it. A chunk usually ends
- * mid-line and usually ends with a newline, so the last NON-EMPTY line is
- * the most recent complete thing the command actually said.
- *
- * Progress is capped rather than truncated with an ellipsis: this is
- * glanced at, and a marker in a line nobody reads to the end is noise.
+ * One latest line per stream, independent of transport chunk boundaries.
+ * Reports stay synchronous: the executor owns coalescing and backpressure.
+ * This projection adds neither an output log nor a queue of pending reports.
  */
-function lastNonEmptyLine(chunk: string): string | undefined {
-	const lines = chunk.split('\n')
-	for (let i = lines.length - 1; i >= 0; i--) {
-		const line = lines[i]?.trim()
-		if (line) return line.length > 160 ? line.slice(0, 160) : line
+function shellProgress(report?: (message: string) => void) {
+	if (!report) return undefined
+	const partial = { stdout: '', stderr: '' }
+	let lastMessage = ''
+	return ({ stream, data }: { stream: 'stdout' | 'stderr'; data: string }): void => {
+		let line = partial[stream]
+		let latest = ''
+		let start = 0
+		// Scan delimiters without allocating an array for arbitrarily chatty output.
+		for (const match of data.matchAll(/[\r\n]/g)) {
+			line = appendProgressTail(line, data, start, match.index)
+			latest = progressLine(line) || latest
+			line = ''
+			start = match.index + 1
+		}
+		line = appendProgressTail(line, data, start, data.length)
+		partial[stream] = line
+		const message = progressLine(line) || latest
+		if (!message || message === lastMessage) return
+		lastMessage = message
+		try {
+			report(message)
+		} catch {
+			// A diagnostic observer cannot break the process output reader.
+		}
 	}
-	return undefined
+}
+
+/**
+ * Keep the shell's process group until inherited pipes close. Node's exec
+ * timeout/AbortSignal kills only the wrapper and closes its pipes immediately,
+ * leaving the command and its descendants running after the promise settles.
+ */
+function execHostShell(
+	command: string,
+	options: {
+		cwd: string
+		env: NodeJS.ProcessEnv
+		timeout: number
+		maxBuffer: number
+		signal?: AbortSignal
+		onOutput?: ReturnType<typeof shellProgress>
+	},
+): Promise<{ stdout: string; stderr: string }> {
+	options.signal?.throwIfAborted()
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, {
+			cwd: options.cwd,
+			env: options.env,
+			shell: true,
+			// killTree's negative PID must never target the caller's own group.
+			detached: process.platform !== 'win32',
+		})
+		const captures = {
+			stdout: {
+				chunks: [] as Buffer[],
+				bytes: 0,
+				truncated: false,
+				decoder: new StringDecoder('utf8'),
+			},
+			stderr: {
+				chunks: [] as Buffer[],
+				bytes: 0,
+				truncated: false,
+				decoder: new StringDecoder('utf8'),
+			},
+		}
+		let cause: 'caller' | 'timeout' | 'maxBuffer' | undefined
+		let failure: (Error & { code?: string | number }) | undefined
+		let escalation: ReturnType<typeof setTimeout> | undefined
+		let disposeAbort: (() => void) | undefined
+		let closed = false
+		const cancel = (origin: NonNullable<typeof cause>) => {
+			if (closed || cause !== undefined) return
+			cause = origin
+			escalation = setTimeout(() => {
+				escalation = undefined
+				killTree(child, 'SIGKILL')
+				// A descendant can deliberately start a separate session. It is
+				// outside this group, but its inherited pipes must not hold the
+				// cancelled call forever. Keep what was captured during grace.
+				child.stdin?.destroy()
+				child.stdout?.destroy()
+				child.stderr?.destroy()
+			}, SANDBOX_KILL_GRACE_MS)
+			escalation.unref?.()
+			killTree(child, 'SIGTERM')
+		}
+		const capture = (stream: 'stdout' | 'stderr', chunk: Buffer) => {
+			const state = captures[stream]
+			const kept = Math.min(chunk.length, options.maxBuffer - state.bytes)
+			if (kept > 0) {
+				state.chunks.push(Buffer.from(chunk.subarray(0, kept)))
+				state.bytes += kept
+			}
+			if (kept < chunk.length) {
+				state.truncated = true
+				if (cause === undefined) {
+					failure = Object.assign(new RangeError(`${stream} maxBuffer length exceeded`), {
+						code: 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER',
+					})
+					cancel('maxBuffer')
+				}
+			}
+			if (options.onOutput) {
+				const data = state.decoder.write(chunk)
+				if (data) options.onOutput({ stream, data })
+			}
+		}
+		const onStdout = (chunk: Buffer) => capture('stdout', chunk)
+		const onStderr = (chunk: Buffer) => capture('stderr', chunk)
+		child.stdout?.on('data', onStdout)
+		child.stderr?.on('data', onStderr)
+		child.once('error', (error: NodeJS.ErrnoException) => {
+			failure ??= error
+		})
+		child.once('close', (code, signal) => {
+			closed = true
+			disposeAbort?.()
+			clearTimeout(deadline)
+			if (escalation !== undefined) {
+				clearTimeout(escalation)
+				// Pipes closing can precede a descendant which closed its copies.
+				// Force the owned group now instead of retaining its PID in a timer.
+				killTree(child, 'SIGKILL')
+			}
+			child.stdout?.off('data', onStdout)
+			child.stderr?.off('data', onStderr)
+			for (const stream of ['stdout', 'stderr'] as const) {
+				const data = captures[stream].decoder.end()
+				if (data) options.onOutput?.({ stream, data })
+			}
+			const decodeCapture = (stream: 'stdout' | 'stderr') => {
+				const state = captures[stream]
+				const bytes = Buffer.concat(state.chunks, state.bytes)
+				// Do not flush an incomplete UTF-8 character cut by our byte cap.
+				return state.truncated ? new StringDecoder('utf8').write(bytes) : bytes.toString('utf8')
+			}
+			const stdout = decodeCapture('stdout')
+			const stderr = decodeCapture('stderr')
+			if (!failure && cause === undefined && code === 0 && signal === null) {
+				resolve({ stdout, stderr })
+				return
+			}
+			const error =
+				failure ??
+				(cause === 'caller'
+					? Object.assign(
+							new Error('The operation was aborted', { cause: options.signal?.reason }),
+							{
+								name: 'AbortError',
+								code: 'ABORT_ERR',
+							},
+						)
+					: new Error(`Command failed: ${command}\n${stderr}`))
+			reject(
+				Object.assign(error, {
+					stdout,
+					stderr,
+					stdoutTruncated: captures.stdout.truncated,
+					stderrTruncated: captures.stderr.truncated,
+					code: failure?.code ?? (cause === 'caller' ? 'ABORT_ERR' : code),
+					killed: cause !== undefined,
+					signal,
+					timedOut: cause === 'timeout',
+				}),
+			)
+		})
+		const deadline = setTimeout(() => cancel('timeout'), options.timeout)
+		deadline.unref?.()
+		if (options.signal) {
+			disposeAbort = subscribeToAbort(options.signal, () => cancel('caller'))
+			if (options.signal.aborted) cancel('caller')
+		}
+	})
 }
 
 function isDangerousCommand(command: string): boolean {
@@ -192,6 +374,7 @@ export const BashTool = defineTool({
 		// sandbox can be added later as an explicit
 		// `SandboxExecOptions.workspaceRelativeCwd` field; the bash
 		// builtin doesn't have that requirement today.
+		const onOutput = shellProgress(context.report)
 		if (context.sandbox) {
 			const result = await context.sandbox.exec('/bin/sh', ['-c', input.command], {
 				timeout: input.timeout,
@@ -206,22 +389,9 @@ export const BashTool = defineTool({
 				// durable transcript — so this is a progress signal, not a
 				// second copy of the output. `result.stdout` remains the
 				// answer the model is given.
-				onOutput: context.report
-					? ({ data }) => {
-							const line = lastNonEmptyLine(data)
-							if (line) context.report?.(line)
-						}
-					: undefined,
+				onOutput,
 			})
 
-			if (result.timedOut) {
-				return {
-					success: false,
-					output: '',
-					error: `Command timed out after ${input.timeout}ms`,
-				}
-			}
-
 			// The sandbox reports when IT clipped a stream. Dropping those
 			// flags meant the model saw a complete-looking result that had
 			// silently lost its tail — and the kernel's own convention is
@@ -235,41 +405,32 @@ export const BashTool = defineTool({
 				result.stdout ? `STDOUT:\n${result.stdout}` : '',
 				result.stderr ? `STDERR:\n${result.stderr}` : '',
 				clipped.length > 0
-					? `[${clipped.join(' and ')} was truncated by the sandbox output cap — re-run with a filter (grep/head/tail) to see the rest]`
+					? `[${clipped.join(' and ')} was truncated by the sandbox output cap. The omitted output is unavailable in this result. Use a saved artifact or a read-only observation; do not repeat a state-changing action to recover its output.]`
 					: '',
 			]
 				.filter(Boolean)
 				.join('\n\n')
 
 			return {
-				success: result.exitCode === 0,
+				success: !result.timedOut && result.exitCode === 0,
 				output: output || '(no output)',
 				data: {
 					exitCode: result.exitCode,
 					sandboxed: true,
+					timedOut: result.timedOut,
 					stdoutTruncated: result.stdoutTruncated ?? false,
 					stderrTruncated: result.stderrTruncated ?? false,
 				},
-				error: result.exitCode !== 0 ? `Command exited with code ${result.exitCode}` : undefined,
+				error: result.timedOut
+					? `Command timed out after ${input.timeout}ms. Any captured output before the deadline is above.`
+					: result.exitCode !== 0
+						? `Command exited with code ${result.exitCode}`
+						: undefined,
 			}
 		}
 
-		// Thread the run/deadline signal into the child process. Without it
-		// a Stop tore down the model stream and left the command running,
-		// and the executor's deadline could only ever DETACH from the tool
-		// rather than end the work it started.
-		// `exec` REJECTS on a non-zero exit, on its own timeout, and on a
-		// kill — and the rejection carries `stdout`, `stderr`, `code` and
-		// `killed`. Letting it propagate threw all of that away: the registry
-		// turned the throw into a structured failure, so the model was told a
-		// command failed and not one word about how.
-		//
-		// That is the common case, not an edge one. A failing test run and a
-		// failing build are the two things an agent runs bash for most, and
-		// both exit non-zero WITH the output that explains why. The sandbox
-		// branch above already reports all of it; this branch did not, so the
-		// same command told the model two different amounts depending on where
-		// it happened to run.
+		// The owned runner retains stdout/stderr on non-zero exit and timeout,
+		// so a failed command still returns the evidence explaining its failure.
 		// The inherited half is scrubbed; `context.env` is not. Inheritance is
 		// implicit — nobody decided this command should see `process.env` — while
 		// a `context.env` key is one a host wrote on purpose. See
@@ -278,14 +439,14 @@ export const BashTool = defineTool({
 		const inherited = scrubInheritedEnv()
 
 		try {
-			const { stdout, stderr } = await execAsync(input.command, {
+			const { stdout, stderr } = await execHostShell(input.command, {
 				cwd: context.workingDirectory,
 				timeout: input.timeout,
 				env: { ...inherited.env, ...context.env },
 				maxBuffer: DEFAULT_BASH_MAX_BUFFER_BYTES,
 				signal: context.abortSignal,
+				onOutput,
 			})
-
 			return {
 				success: true,
 				output: formatShellOutput(stdout, stderr) || '(no output)',
@@ -295,25 +456,34 @@ export const BashTool = defineTool({
 			const failure = err as NodeJS.ErrnoException & {
 				stdout?: string
 				stderr?: string
+				stdoutTruncated?: boolean
+				stderrTruncated?: boolean
 				code?: number | string
 				killed?: boolean
 				signal?: string
+				timedOut?: boolean
 			}
 
 			// A caller-owned Stop is the caller's, not a command failure.
 			if (context.abortSignal?.aborted) throw err
 
-			// `exec` reports its own timeout as a kill, and the distinction
-			// matters to the model: "ran out of time" is a different next move
-			// from "exited 1".
-			const timedOut = failure.killed === true && failure.signal === 'SIGTERM'
+			// A maxBuffer stop or an ordinary signal is not a deadline. The
+			// runner latches the first cancellation cause before signalling.
+			const timedOut = failure.timedOut === true
 			const exitCode = typeof failure.code === 'number' ? failure.code : undefined
+			const clipped = [
+				failure.stdoutTruncated ? 'stdout' : '',
+				failure.stderrTruncated ? 'stderr' : '',
+			].filter(Boolean)
 			// Only on the failure path. A successful command did not need to know,
 			// and appending this to every result would make the common case noisy
 			// to buy nothing. A failing one is exactly where "authentication
 			// failed" has to be distinguishable from "the variable was withheld".
 			const output = [
 				formatShellOutput(failure.stdout, failure.stderr),
+				clipped.length > 0
+					? `[${clipped.join(' and ')} ${clipped.length === 1 ? 'was' : 'were'} truncated by the host output cap. The omitted output is unavailable in this result.]`
+					: '',
 				describeWithheldEnv(inherited.dropped),
 			]
 				.filter(Boolean)
@@ -325,6 +495,8 @@ export const BashTool = defineTool({
 				data: {
 					...(exitCode !== undefined ? { exitCode } : {}),
 					timedOut,
+					stdoutTruncated: failure.stdoutTruncated ?? false,
+					stderrTruncated: failure.stderrTruncated ?? false,
 					...(failure.signal ? { signal: failure.signal } : {}),
 				},
 				error: timedOut

package/src/tools/builtins/glob.ts

@@ -1,157 +1,139 @@
-import { glob } from 'node:fs/promises'
-import { basename, dirname, relative, resolve, sep } from 'node:path'
+import { isAbsolute, join, relative, sep } from 'node:path'
 import { z } from 'zod'
-import type { Sandbox } from '../../types/sandbox/index.js'
-import type { ToolResult } from '../../types/tool/index.js'
+import { walkFilesLocally } from '../../sandbox/file-walk.js'
+import type { SandboxWalkFilesOptions } from '../../types/sandbox/index.js'
 import { defineTool } from '../defineTool.js'
-import { matchesGlob } from '../glob-match.js'
-import { resolveWithinAny, toolRoots } from '../paths.js'
-import { joinPosix, relativePosix, resolveWithinPosix } from '../posix-path.js'
+import { resolveWithin, resolveWithinAny, resolveWithinAnyReal, toolRoots } from '../paths.js'
+import { relativePosix, resolveWithinPosix } from '../posix-path.js'
 
-/**
- * Cap on results, shared by both paths so a sandboxed search and a host
- * search truncate at the same point.
- */
 const MAX_GLOB_RESULTS = 500
-
-/**
- * Enumerate inside the sandbox and match there.
- *
- * This tool read the HOST filesystem through `node:fs` and referenced
- * `context.sandbox` nowhere, so with a container backend wired in the
- * sandbox was not a read boundary at all. The paths it returned were
- * host-relative too, while `read` resolves what it is given INSIDE the
- * sandbox — so every glob-to-read handoff either failed or opened a
- * different file. Every sibling builtin already remembers this branch.
- *
- * `listFiles` returns sandbox-relative paths, which is the coordinate
- * system `read` and `grep` already speak, so a path from here can be
- * handed straight to them.
- */
-async function globInSandbox(
-	input: { pattern: string; path?: string },
-	sandbox: Sandbox,
-): Promise<ToolResult> {
-	// The sandbox's own coordinate system — see `posix-path`.
-	const root = resolveWithinPosix(sandbox.rootDir, input.path)
-	const entries = await sandbox.listFiles(root)
-
-	let pattern = input.pattern
-	if (!pattern.includes('/') && !pattern.startsWith('**/')) pattern = `**/${pattern}`
-
-	const matches: string[] = []
-	for (const entry of entries) {
-		const relPath = relativePosix(sandbox.rootDir, joinPosix(root, entry.path))
-		if (!matchesGlob(relPath, pattern)) continue
-		matches.push(`./${relPath}`)
-		if (matches.length >= MAX_GLOB_RESULTS) break
-	}
-
-	if (matches.length === 0) {
-		return {
-			success: true,
-			output: `No files found matching pattern "${input.pattern}" in ${root}`,
-			data: { count: 0, files: [], sandboxed: true },
-		}
-	}
-	return {
-		success: true,
-		output: matches.join('\n'),
-		data: { count: matches.length, files: matches, sandboxed: true },
-	}
-}
+const MAX_VISITED_ENTRIES = 20_000
 
 const inputSchema = z.object({
-	pattern: z.string().describe('Glob pattern (e.g. "**/*.ts", "src/**/*.js")'),
+	pattern: z
+		.string()
+		.min(1)
+		.max(4096)
+		.describe(
+			'File glob relative to path. "*" lists immediate files; "**/*.ts" explicitly searches subdirectories. Supports braces and character classes. Known file paths can be read directly without discovery.',
+		),
 	path: z
 		.string()
 		.optional()
-		.describe('Directory to search in. Defaults to the working directory if not specified.'),
+		.describe(
+			'Directory to search in. Defaults to the working directory. Choose the narrowest relevant directory.',
+		),
+	include_hidden: z
+		.boolean()
+		.optional()
+		.describe(
+			'Include hidden files and directories in wildcard matches. Default: false. Explicit dotfile patterns still match.',
+		),
 })
 
-function extractGlobBaseDirectory(pattern: string): {
-	baseDir: string
-	relativePattern: string
-} {
-	const globChars = /[*?[{]/
-	const match = pattern.match(globChars)
-
-	if (!match || match.index === undefined) {
-		return { baseDir: dirname(pattern), relativePattern: basename(pattern) }
+/** Keep the pattern in the selected directory's coordinate system. */
+function relativePattern(pattern: string, root: string, sandboxed: boolean): string {
+	let result = sandboxed ? pattern : pattern.split(sep).join('/')
+	if (result.split('/').includes('..')) {
+		throw new Error(
+			'Glob pattern escapes the search directory through "..". Choose a contained path and a relative pattern.',
+		)
 	}
-
-	const staticPrefix = pattern.slice(0, match.index)
-	const lastSepIndex = Math.max(staticPrefix.lastIndexOf('/'), staticPrefix.lastIndexOf(sep))
-
-	if (lastSepIndex === -1) {
-		return { baseDir: '', relativePattern: pattern }
+	if (sandboxed ? result.startsWith('/') : isAbsolute(pattern)) {
+		const contained = sandboxed ? resolveWithinPosix(root, result) : resolveWithin(root, pattern)
+		result = sandboxed
+			? relativePosix(root, contained)
+			: relative(root, contained).split(sep).join('/')
 	}
+	while (result.startsWith('./')) result = result.slice(2)
+	return result || '.'
+}
 
-	const baseDir = staticPrefix.slice(0, lastSepIndex)
-	const relativePattern = pattern.slice(lastSepIndex + 1)
-
-	return { baseDir, relativePattern }
+/** Keep unusual filenames unambiguous without changing the returned path data. */
+function displayPath(path: string): string {
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: quote filenames containing control bytes instead of creating fake result lines.
+	return /[\x00-\x1f\x7f]/.test(path) ? JSON.stringify(path) : path
 }
 
 export const GlobTool = defineTool({
 	name: 'glob',
-	description: 'Searches for files using a glob pattern. Returns matching file paths.',
+	description:
+		'Finds regular files by glob pattern in a bounded search. "*" searches one directory; use "**" explicitly for recursive discovery. Returns at most 500 paths and identifies incomplete searches. Does not follow symlinks.',
 	inputSchema,
 	category: 'filesystem',
 	permissions: ['file_read'],
 	readOnly: true,
 	destructive: false,
 	concurrencySafe: true,
+	timeoutMs: 15_000,
 
-	async execute(input, context) {
-		if (context.sandbox) {
-			return await globInSandbox(input, context.sandbox)
-		}
-
-		// Contained, not merely resolved. This was a bare `resolve`, so
-		// `path: "../../.."` reached whatever sits above the working
-		// directory — with no sandbox needed to make it work.
-		const basePath = resolveWithinAny(toolRoots(context), input.path)
-
-		let searchPath = basePath
-		let pattern = input.pattern
+	presentCall(input) {
+		return { kind: 'generic', label: `${input.pattern} in ${input.path ?? '.'}` }
+	},
 
-		const { baseDir, relativePattern } = extractGlobBaseDirectory(pattern)
-		if (baseDir) {
-			// A base directory lifted out of the PATTERN is caller-supplied
-			// too: `pattern: "../../**/*.pem"` is the same escape wearing a
-			// different argument.
-			const resolvedPatternBase = resolveWithinAny(toolRoots(context), baseDir)
-			if (resolvedPatternBase === basePath || resolvedPatternBase.startsWith(`${basePath}/`)) {
-				searchPath = resolvedPatternBase
-				pattern = relativePattern
+	async execute(input, context) {
+		context.abortSignal?.throwIfAborted()
+		const sandbox = context.sandbox
+		const lexicalRoot = sandbox
+			? resolveWithinPosix(sandbox.rootDir, input.path)
+			: resolveWithinAny(toolRoots(context), input.path)
+		const root = sandbox ? lexicalRoot : await resolveWithinAnyReal(toolRoots(context), input.path)
+		const pattern = relativePattern(input.pattern, lexicalRoot, sandbox !== undefined)
+		const walkSandbox = sandbox?.walkFiles?.bind(sandbox)
+		if (sandbox && !walkSandbox) {
+			return {
+				success: false,
+				output: '',
+				error:
+					'This sandbox does not support bounded file discovery (Sandbox.walkFiles). Update its adapter or use an available directory-listing command inside the sandbox.',
 			}
 		}
-
-		if (!pattern.includes('/') && !pattern.startsWith('**/')) {
-			pattern = `**/${pattern}`
-		}
-
-		const matches: string[] = []
-
-		for await (const entry of glob(pattern, { cwd: searchPath })) {
-			const absolutePath = resolve(searchPath, entry)
-			matches.push(`./${relative(context.workingDirectory, absolutePath)}`)
-			if (matches.length >= MAX_GLOB_RESULTS) break
+		const options: SandboxWalkFilesOptions = {
+			pattern,
+			signal: context.abortSignal,
+			maxEntries: MAX_GLOB_RESULTS + 1,
+			maxVisitedEntries: MAX_VISITED_ENTRIES,
+			includeHidden: input.include_hidden ?? false,
 		}
-
-		if (matches.length === 0) {
-			return {
-				success: true,
-				output: `No files found matching pattern "${input.pattern}" in ${searchPath}`,
-				data: { count: 0, files: [] },
+		const entries = walkSandbox ? walkSandbox(root, options) : walkFilesLocally(root, options)
+		const files: string[] = []
+		let truncated = false
+		let failure: string | undefined
+		try {
+			for await (const entry of entries) {
+				context.abortSignal?.throwIfAborted()
+				const absolute = sandbox
+					? resolveWithinPosix(root, entry.path)
+					: resolveWithin(root, entry.path)
+				if (files.length === MAX_GLOB_RESULTS) {
+					truncated = true
+					break
+				}
+				// Readers resolve relative input against the original working path,
+				// which may be a symlink. Project back through the selected alias
+				// before relativizing so added directories remain reachable.
+				const file = sandbox
+					? relativePosix(sandbox.rootDir, absolute)
+					: relative(context.workingDirectory, join(lexicalRoot, relative(root, absolute)))
+				files.push(`./${sandbox ? file : file.split(sep).join('/')}`)
 			}
+		} catch (error) {
+			if (context.abortSignal?.aborted) throw error
+			truncated = true
+			failure = error instanceof Error ? error.message : String(error)
 		}
-
+		const notice = failure
+			? `[Search incomplete: ${failure}]`
+			: truncated
+				? `[Showing the first ${MAX_GLOB_RESULTS} matching files. Narrow the directory or pattern for the remaining results.]`
+				: undefined
 		return {
-			success: true,
-			output: matches.join('\n'),
-			data: { count: matches.length, files: matches },
+			success: failure === undefined,
+			output:
+				[...files.map(displayPath), ...(notice ? [notice] : [])].join('\n') ||
+				`No files found matching pattern "${input.pattern}" in ${root}`,
+			data: { count: files.length, files, truncated, ...(sandbox ? { sandboxed: true } : {}) },
+			...(failure ? { error: failure } : {}),
 		}
 	},
 })