@namzu/sdk 62.6.1 → 62.8.0

package/src/tools/builtins/grep.ts

@@ -1,5 +1,5 @@
 import { stat } from 'node:fs/promises'
-import { isAbsolute, join, relative, sep } from 'node:path'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import { z } from 'zod'
 import { walkFilesLocally } from '../../sandbox/file-walk.js'
 import type { SandboxWalkFilesOptions, SandboxWalkSummary } from '../../types/sandbox/index.js'
@@ -7,6 +7,7 @@ import type { ToolContext } from '../../types/tool/index.js'
 import { subscribeToAbort } from '../../utils/abort.js'
 import { defineTool } from '../defineTool.js'
 import {
+	canonicalize,
 	resolveWithin,
 	resolveWithinAny,
 	resolveWithinAnyReal,
@@ -14,7 +15,13 @@ import {
 	toolRoots,
 } from '../paths.js'
 import { relativePosix, resolveWithinPosix } from '../posix-path.js'
-import { readBoundedChunks, readBoundedFile } from './bounded-file-read.js'
+import {
+	CAN_REFUSE_LINKS,
+	REFUSE_LINK_FLAG,
+	readBoundedChunks,
+	readBoundedFile,
+	readBoundedFileSync,
+} from './bounded-file-read.js'
 import {
 	MAX_FILES_SEARCHED,
 	SEARCH_BUDGET_MS,
@@ -24,6 +31,7 @@ import {
 	isReadDenied,
 	openSearchBudget,
 	plural,
+	readAhead,
 	stoppedNotice,
 } from './search-support.js'
 
@@ -49,6 +57,125 @@ async function readWithSignal(read: () => Promise<Buffer>, signal?: AbortSignal)
 	}
 }
 
+/** Longest the local read loop holds the event loop before it yields. */
+const READ_SLICE_MS = 8
+
+/**
+ * Largest file the local reader reads synchronously, by the size on the open
+ * handle. One synchronous read of a file is one uninterrupted block, which on a
+ * slow mount can last tens of milliseconds; a larger file is read through the
+ * asynchronous bounded read instead, which lets the event loop run between
+ * chunks.
+ */
+export const LOCAL_SYNC_READ_MAX_BYTES = 64 * 1024
+
+/**
+ * Reads files of a local search root. Each directory is resolved to its real
+ * path once and checked against the real root once; a file is then one open
+ * (links refused at the last component), fstat, read and close, all
+ * synchronous, with a yield to the event loop every few milliseconds. That is
+ * the same containment decision as resolving every file, because the walk
+ * lists only regular files in real directories and the open refuses a file
+ * that has become a link. Not used for a sandbox, nor where the platform cannot
+ * refuse links.
+ */
+function createLocalReader(root: string, signal: AbortSignal | undefined) {
+	const scratch = Buffer.allocUnsafe(64 * 1024)
+	const rootRealPromise = canonicalize(resolve(root))
+	const directories = new Map<string, Promise<string>>()
+	let sliceStart = performance.now()
+	const realDirectory = (directory: string): Promise<string> => {
+		let known = directories.get(directory)
+		if (!known) {
+			known = canonicalize(directory)
+			directories.set(directory, known)
+		}
+		return known
+	}
+	let rootReal: string | undefined
+	return {
+		async read(
+			filePath: string,
+		): Promise<{ buffer: Buffer | 'too-large' | 'gone'; contained: string }> {
+			if (performance.now() - sliceStart > READ_SLICE_MS) {
+				await new Promise<void>((done) => setImmediate(done))
+				sliceStart = performance.now()
+			}
+			signal?.throwIfAborted()
+			const directory = dirname(filePath)
+			const real = await realDirectory(directory)
+			rootReal ??= await rootRealPromise
+			const contained =
+				real === directory ? filePath : join(real, filePath.slice(directory.length + 1))
+			if (!(contained.startsWith(rootReal + sep) || contained === rootReal)) {
+				const rel = relative(rootReal, contained)
+				if (rel.startsWith('..') || isAbsolute(rel)) {
+					throw new Error('Path escapes the working directory through a link.')
+				}
+			}
+			signal?.throwIfAborted()
+			try {
+				const read = readBoundedFileSync(
+					contained,
+					MAX_FILE_SIZE,
+					scratch,
+					LOCAL_SYNC_READ_MAX_BYTES,
+				)
+				if (read !== 'large') return { buffer: read, contained }
+				// The handle that measured the file is closed; the asynchronous read opens it
+				// again with the same flags (links refused) and repeats every check.
+				const large = await readBoundedFile(
+					contained,
+					MAX_FILE_SIZE,
+					signal,
+					undefined,
+					REFUSE_LINK_FLAG,
+				)
+				sliceStart = performance.now()
+				return { buffer: large, contained }
+			} catch (error) {
+				// Gone since the walk listed it: absent, as a walk that ran later would find it.
+				const code = (error as NodeJS.ErrnoException).code
+				if (code === 'ENOENT' || code === 'ENOTDIR') return { buffer: 'gone', contained }
+				throw error
+			}
+		},
+	}
+}
+
+/** A walked path that is already inside `root` in normal form, or null when it needs the full check. */
+const PLAIN_TAIL = /(^|\/)\.{1,2}(\/|$)|\/\/|\/$/
+
+/**
+ * The fast form of what `resolveWithin` and the display path compute for the
+ * walk's own entries on a POSIX host: a path the walk built under `root` is
+ * already normal, so it is returned as it is and its display name is a
+ * prefix plus the tail. Anything else, and every other platform, takes the
+ * full computation.
+ */
+function createWalkedPaths(root: string, lexicalRoot: string, workingDirectory: string) {
+	if (sep !== '/') return undefined
+	const prefix = root === '/' ? '/' : `${root}/`
+	const rootRel = relative(workingDirectory, lexicalRoot)
+	const display = rootRel.startsWith('..') || isAbsolute(rootRel) ? undefined : rootRel
+	return {
+		within(path: string): string {
+			if (path.startsWith(prefix) && path.length > prefix.length) {
+				if (!PLAIN_TAIL.test(path.slice(prefix.length))) return path
+			}
+			return resolveWithin(root, path)
+		},
+		displayName(path: string): string | undefined {
+			if (display === undefined || !path.startsWith(prefix) || path.length === prefix.length) {
+				return undefined
+			}
+			const tail = path.slice(prefix.length)
+			if (PLAIN_TAIL.test(tail)) return undefined
+			return display === '' ? tail : `${display}/${tail}`
+		},
+	}
+}
+
 function relativeInclude(include: string, root: string, sandboxed: boolean): string {
 	let pattern = sandboxed ? include : include.split(sep).join('/')
 	if (pattern.split('/').includes('..'))
@@ -201,17 +328,13 @@ const MAX_FILE_SIZE = 5 * 1024 * 1024 // 5 MB — skip binaries/large files
 const BINARY_CHECK_BYTES = 512
 
 function isBinaryContent(buffer: Buffer): boolean {
-	const check = buffer.subarray(0, BINARY_CHECK_BYTES)
-	for (const byte of check) {
-		if (byte === 0) return true
-	}
-	return false
+	return buffer.subarray(0, BINARY_CHECK_BYTES).includes(0)
 }
 
 export const GrepTool = defineTool({
 	name: 'grep',
 	description:
-		'Searches file contents using a regular expression. By default returns the paths of matching files, newest first; output_mode "content" returns matching lines with file paths, line numbers and optional context lines, and "count" returns the number of matching lines per file. Set multiline for a pattern that spans lines and type (js, py, rust, ...) to search one kind of file. In content mode, before_context and after_context override symmetric context_lines; only_matching returns matched substrings without context. Results are paged: head_limit (default 250, 0 for none) and offset. A line over 500 characters is replaced by a notice. Searches hidden files unless include_hidden is false. Skips files that .gitignore and .ignore rules exclude unless include_ignored is set, and files the read rules of the session deny. Says when a result is limited or a search stopped early. Skips binary files, files over 5 MB, and symlinks. Choose the narrowest relevant directory.',
+		'Searches file contents using a regular expression. By default returns the paths of matching files, newest first; output_mode "content" returns matching lines with file paths, line numbers and optional context lines, and "count" returns the number of matching lines per file. Set multiline for a pattern that spans lines and type (js, py, rust, ...) to search one kind of file. In content mode, before_context and after_context override symmetric context_lines; only_matching returns matched substrings without context. Results are paged: head_limit (default 250, 0 for none) and offset. A line over 500 characters is replaced by a notice. Searches hidden files unless include_hidden is false. Skips files that .gitignore and .ignore rules exclude unless include_ignored is set, and files the read rules of the session deny. Says when a result is limited or a search stopped early. Skips binary files, files over 5 MB, and symlinks. Choose the narrowest relevant directory. To find files by name, use glob.',
 	inputSchema,
 	category: 'analysis',
 	// Declared so a path outside the turn's roots can be reviewed before the
@@ -291,7 +414,11 @@ export const GrepTool = defineTool({
 				walkEnd = value
 			},
 		}
-		const entries = walkSandbox ? walkSandbox(root, options) : walkFilesLocally(root, options)
+		// A local walk is read ahead so its directory reads overlap with matching; a
+		// sandbox's walk is left as the adapter produces it.
+		const entries = walkSandbox
+			? walkSandbox(root, options)
+			: readAhead(walkFilesLocally(root, { ...options, withoutSizes: CAN_REFUSE_LINKS }))
 
 		// `execute` is reachable without the schema's defaults.
 		const mode = input.output_mode ?? 'files_with_matches'
@@ -321,12 +448,16 @@ export const GrepTool = defineTool({
 		const filesToCollect =
 			headLimit > 0 ? offset + Math.max(headLimit * 4, 1000) : Number.POSITIVE_INFINITY
 		let enough = false
+		const walked = sandbox
+			? undefined
+			: createWalkedPaths(root, lexicalRoot, context.workingDirectory)
+		const localReader = !sandbox && CAN_REFUSE_LINKS ? createLocalReader(root, signal) : undefined
 		try {
 			for await (const entry of entries) {
 				signal?.throwIfAborted()
 				const filePath = sandbox
 					? resolveWithinPosix(root, entry.path)
-					: resolveWithin(root, entry.path)
+					: (walked?.within(entry.path) ?? resolveWithin(root, entry.path))
 				if (filesSearched >= MAX_FILES_SEARCHED) {
 					fileLimit = true
 					break
@@ -339,21 +470,34 @@ export const GrepTool = defineTool({
 				let content: string
 				let contained: string | undefined
 				try {
-					const buffer = await readWithSignal(
-						() =>
-							sandbox
-								? readBoundedChunks(
-										(offset, length) =>
-											sandbox.readFile(filePath, { offset, length, signal: signal }),
-										MAX_FILE_SIZE,
-										signal,
-									)
-								: resolveWithinReal(root, filePath).then((path) => {
-										contained = path
-										return readBoundedFile(path, MAX_FILE_SIZE, signal)
-									}),
-						signal,
-					)
+					let buffer: Buffer
+					if (localReader) {
+						const read = await localReader.read(filePath)
+						contained = read.contained
+						// Over the cap by the size on the open handle: skipped, not unreadable.
+						if (read.buffer === 'too-large') continue
+						// Gone since the walk listed it: as if the walk had not listed it.
+						if (read.buffer === 'gone') {
+							filesSearched--
+							continue
+						}
+						buffer = read.buffer
+					} else
+						buffer = await readWithSignal(
+							() =>
+								sandbox
+									? readBoundedChunks(
+											(offset, length) =>
+												sandbox.readFile(filePath, { offset, length, signal: signal }),
+											MAX_FILE_SIZE,
+											signal,
+										)
+									: resolveWithinReal(root, filePath).then((path) => {
+											contained = path
+											return readBoundedFile(path, MAX_FILE_SIZE, signal)
+										}),
+							signal,
+						)
 					signal?.throwIfAborted()
 					if (buffer.length > MAX_FILE_SIZE || isBinaryContent(buffer)) continue
 					content = buffer.toString('utf-8')
@@ -367,7 +511,8 @@ export const GrepTool = defineTool({
 				let fileMatches = 0
 				const relPath = sandbox
 					? relativePosix(sandbox.rootDir, filePath)
-					: hostDisplayPath(context.workingDirectory, join(lexicalRoot, relative(root, filePath)))
+					: (walked?.displayName(filePath) ??
+						hostDisplayPath(context.workingDirectory, join(lexicalRoot, relative(root, filePath))))
 
 				if (mode === 'content' && input.only_matching) {
 					for (const fragment of matchingFragments(content, regex, multiline)) {
@@ -580,7 +725,8 @@ function lineHits(
 ): [number, number][] {
 	const hits: [number, number][] = []
 	for (let i = 0; i < lines.length; i++) {
-		context.abortSignal?.throwIfAborted()
+		// A cancellation is seen within a few hundred lines; per line it cost more than the match.
+		if ((i & 255) === 0) context.abortSignal?.throwIfAborted()
 		regex.lastIndex = 0
 		if (regex.test(lines[i] ?? '')) hits.push([i, i])
 	}

package/src/tools/builtins/notebook-guard.ts

@@ -0,0 +1,76 @@
+/**
+ * A notebook is JSON with a fixed shape. `edit` and `write` treat every file
+ * as text, so a model can leave an `.ipynb` that no notebook program opens.
+ * This check runs on the body about to be written, never on the file on disk,
+ * so a refusal leaves the file untouched.
+ */
+
+const CELL_TYPES = new Set(['code', 'markdown', 'raw'])
+
+export function isNotebookPath(path: string): boolean {
+	return path.toLowerCase().endsWith('.ipynb')
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function shapeProblem(parsed: unknown): string | undefined {
+	if (!isRecord(parsed)) return 'the top level must be a JSON object'
+	if (typeof parsed.nbformat !== 'number') return 'it needs a numeric "nbformat"'
+	if (!isRecord(parsed.metadata)) return 'it needs a "metadata" object'
+	// Formats before 4 keep their cells inside "worksheets" and name a code cell's text "input".
+	// Those files are valid and still open, so only the envelope is checked for them.
+	if (parsed.nbformat < 4) {
+		return Array.isArray(parsed.worksheets) ? undefined : 'it needs a "worksheets" list'
+	}
+	if (!Array.isArray(parsed.cells)) return 'it needs a "cells" list'
+	for (const [index, cell] of parsed.cells.entries()) {
+		if (!isRecord(cell)) return `cell ${index} must be an object`
+		if (typeof cell.cell_type !== 'string' || !CELL_TYPES.has(cell.cell_type)) {
+			return `cell ${index} needs a "cell_type" of code, markdown or raw`
+		}
+		const source = cell.source
+		const sourceOk =
+			typeof source === 'string' ||
+			(Array.isArray(source) && source.every((line) => typeof line === 'string'))
+		if (!sourceOk) return `cell ${index} needs a "source" that is a string or a list of strings`
+	}
+	return undefined
+}
+
+/** Why a notebook body would not open, or `undefined` when it would. */
+function bodyProblem(content: string): string | undefined {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(content)
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error)
+		return `it is not valid JSON (${reason})`
+	}
+	return shapeProblem(parsed)
+}
+
+/**
+ * Returns a plain refusal for a notebook body that would no longer open, or
+ * `undefined` when the body is fine or the path is not a notebook.
+ *
+ * `before` is the file's current body, when the caller has it. A notebook that
+ * was already broken cannot be mended one string at a time, because every
+ * partial repair still leaves a file that does not open; without saying so the
+ * refusal would tell the model to keep a structure the file never had, and it
+ * would try the same edit again.
+ */
+export function notebookRefusal(
+	path: string,
+	content: string,
+	before?: string,
+): string | undefined {
+	if (!isNotebookPath(path)) return undefined
+	const problem = bodyProblem(content)
+	if (problem === undefined) return undefined
+	if (before !== undefined && bodyProblem(before) !== undefined) {
+		return `Not written: ${path} is a notebook that already does not open, and after this change it still would not because ${problem}. Repair it in one change that leaves a whole valid notebook, or replace the file with a write of the corrected notebook. The file is unchanged.`
+	}
+	return `Not written: ${path} is a notebook, and after this change it would no longer open because ${problem}. Change only text inside a cell and keep the notebook's structure (its cells, nbformat and metadata, with the surrounding quotes, commas and brackets), then try again. The file is unchanged.`
+}

package/src/tools/builtins/read-render.ts

@@ -80,8 +80,12 @@ export function renderNumberedRead(content: string, input: ReadWindowRequest): R
 	}
 	const selected = lines.slice(start, Math.min(end, lineCount))
 	const numbered = selected.map((line, i) => `${start + i + 1}\t${line}`).join('\n')
+	// Only a cut the cap imposed is the model's to be warned about: a window it
+	// asked for is what it got.
+	const asked = (input.readRange?.length ?? 0) >= 2 || Boolean(input.limit)
+	const capCut = !asked
 	return {
-		output: numbered + partialViewNotice(start, selected.length, lineCount),
+		output: numbered + partialViewNotice(start, selected.length, lineCount, capCut),
 		totalLines: lineCount,
 		returnedLines: selected.length,
 		partial: selected.length < lineCount,
@@ -97,9 +101,15 @@ export function renderNumberedRead(content: string, input: ReadWindowRequest): R
  * most expensive silent failure a read tool can have. The notice names the
  * exact next call rather than describing it.
  */
-function partialViewNotice(start: number, returned: number, total: number): string {
+function partialViewNotice(
+	start: number,
+	returned: number,
+	total: number,
+	capCut: boolean,
+): string {
 	if (returned >= total) return ''
 	const shownTo = start + returned
+	if (!capCut) return `\n\n[Lines ${start + 1}-${shownTo} of ${total}, as asked.]`
 	return [
 		'',
 		'',

package/src/tools/builtins/search-support.ts

@@ -105,3 +105,65 @@ export function isReadDenied(
 	if (relative === '..' || relative.startsWith('../') || posix.isAbsolute(relative)) return true
 	return context.readDenied(joinPath(context.workingDirectory, relative))
 }
+
+/**
+ * Pulls from `source` ahead of the consumer, up to `ahead` items, so a walk's
+ * directory reads overlap with the matching of files already listed. Order is
+ * unchanged. An error from the source is thrown to the consumer after the
+ * items listed before it; when the consumer stops, the source is closed (its
+ * own cleanup runs) before this returns.
+ */
+export async function* readAhead<T>(source: AsyncIterable<T>, ahead = 256): AsyncGenerator<T> {
+	const iterator = source[Symbol.asyncIterator]()
+	const buffer: T[] = []
+	let finished = false
+	let failure: { error: unknown } | undefined
+	let stop = false
+	let wakeConsumer: (() => void) | undefined
+	let wakeProducer: (() => void) | undefined
+	const notifyConsumer = () => {
+		const wake = wakeConsumer
+		wakeConsumer = undefined
+		wake?.()
+	}
+	const producer = (async () => {
+		try {
+			while (!stop) {
+				if (buffer.length >= ahead) {
+					await new Promise<void>((resolve) => {
+						wakeProducer = resolve
+					})
+					continue
+				}
+				const next = await iterator.next()
+				if (next.done) break
+				buffer.push(next.value)
+				notifyConsumer()
+			}
+		} catch (error) {
+			failure = { error }
+		}
+		finished = true
+		notifyConsumer()
+	})()
+	try {
+		for (;;) {
+			if (buffer.length > 0) {
+				const item = buffer.shift() as T
+				wakeProducer?.()
+				yield item
+				continue
+			}
+			if (failure) throw failure.error
+			if (finished) return
+			await new Promise<void>((resolve) => {
+				wakeConsumer = resolve
+			})
+		}
+	} finally {
+		stop = true
+		wakeProducer?.()
+		await producer
+		await iterator.return?.()
+	}
+}

package/src/tools/builtins/write-file.ts

@@ -11,6 +11,7 @@ import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
 import { fileWriteResult } from './file-write-result.js'
 import { jsonStringEscapes } from './json-string-hint.js'
+import { notebookRefusal } from './notebook-guard.js'
 import { staleBeforeReview } from './stale-before-review.js'
 
 const inputSchema = z
@@ -74,7 +75,7 @@ const modelInputSchema: Record<string, unknown> = {
 export const WriteFileTool = defineTool({
 	name: 'write',
 	description:
-		'Writes a file to the local filesystem. Overwrites the existing file at the path if there is one.\n\n- If the file already exists, you must use the `read` tool on it first in this conversation, or this call will fail.\n- To modify an existing file, use `edit`: it only sends the diff and preserves the rest of the file byte-for-byte.\n- Use `write` to create a new file or to perform a deliberate full rewrite of a file you have already read.\n- Self-budget content/newStr under 12000 characters before emitting the tool call. For long content, write a smaller opening section, then use `edit` with insertLine: "end" to extend the file section by section. Chaining several `write` calls to one path loses content, because each overwrites the previous.',
+		'Writes a file to the local filesystem. Overwrites the existing file at the path if there is one.\n\n- If the file already exists, you must use the `read` tool on it first in this conversation, or this call will fail.\n- To modify an existing file, use `edit`: it only sends the diff and preserves the rest of the file byte-for-byte.\n- Use `write` to create a new file or to perform a deliberate full rewrite of a file you have already read.\n- Self-budget content/newStr under 12000 characters before emitting the tool call. For long content, write a smaller opening section, then use `edit` with insertLine: "end" to extend the file section by section. Chaining several `write` calls to one path loses content, because each overwrites the previous.\n- A `.ipynb` body must stay a valid notebook (JSON with cells, nbformat and metadata), or the write is refused.',
 	inputSchema,
 	modelInputSchema,
 	enforceModelInput: true,
@@ -154,6 +155,12 @@ export const WriteFileTool = defineTool({
 		}
 		const valid = parsed.data
 		const content = valid.content ?? valid.newStr ?? ''
+		// The sandbox has its own root, so its path is checked as typed. The
+		// host path is checked below, once containment has resolved symlinks.
+		if (context.sandbox) {
+			const notebook = notebookRefusal(valid.path, content)
+			if (notebook) return { success: false as const, output: '', error: notebook }
+		}
 		// Host-side containment, on the host branch only. The sandbox has its
 		// own root and its own resolver; canonicalizing a sandbox-relative
 		// path against the HOST filesystem asks a question about the wrong
@@ -161,6 +168,10 @@ export const WriteFileTool = defineTool({
 		const filePath = context.sandbox
 			? undefined
 			: await resolveWithinAnyReal(toolRoots(context), valid.path)
+		if (filePath !== undefined) {
+			const notebook = notebookRefusal(filePath, content)
+			if (notebook) return { success: false as const, output: '', error: notebook }
+		}
 		// The exists-check and the write are a check-then-act pair. Unlocked,
 		// two writers both see "absent", both skip the read-before-overwrite
 		// guard, and the second silently discards the first.

package/src/tools/coordinator/agent.ts

@@ -5,7 +5,8 @@ import type { CreateTaskOptions, TaskHandle, TaskScheduler } from '../../types/a
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { jsonStringEscapes } from '../builtins/json-string-hint.js'
 import { defineTool } from '../defineTool.js'
-import { wrapUntrusted } from '../untrusted-envelope.js'
+import { KERNEL_RECORD_PREFIX, wrapUntrusted } from '../untrusted-envelope.js'
+import { describeOutcomeRecord } from './outcome-record.js'
 import { failureLabel, taskSucceeded } from './outcome.js'
 
 import { DELEGATION_TIMEOUT_MS } from './index.js'
@@ -169,13 +170,16 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 					// of every delegation. Merged into ONE `configOverrides`
 					// rather than spread twice — the second spread would replace
 					// the first and drop the environment.
-					...(Object.keys(context.env ?? {}).length > 0 || context.toolResultGuardrails
+					...(Object.keys(context.env ?? {}).length > 0 ||
+					context.toolResultGuardrails ||
+					context.fileReadTracker
 						? {
 								configOverrides: {
 									...(Object.keys(context.env ?? {}).length > 0 ? { env: context.env } : {}),
 									...(context.toolResultGuardrails
 										? { toolResultGuardrails: context.toolResultGuardrails }
 										: {}),
+									...(context.fileReadTracker ? { fileReadTracker: context.fileReadTracker } : {}),
 								},
 							}
 						: {}),
@@ -222,19 +226,28 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 							? JSON.stringify(completed.result.result)
 							: ''
 
+			// The kernel's own record of the child's turn, never the child's words.
+			// Written outside the marked block below, and attributed to the record.
+			const outcome = completed.result?.outcome
+			const recordLine = outcome ? describeOutcomeRecord(outcome) : undefined
+
 			if (!succeeded) {
-				const detail =
-					completed.result?.lastError ?? resultText ?? '(subagent provided no failure detail)'
+				// The child's words are not marked on this path, so a line of them
+				// that opens like the kernel's own would read as the kernel's.
+				const detail = neutraliseKernelLines(
+					completed.result?.lastError ?? resultText ?? '(subagent provided no failure detail)',
+				)
 				return {
 					success: false,
 					output: '',
-					error: `Subagent ${agentId} ${failureLabel(completed)}: ${detail}`,
+					error: `Subagent ${agentId} ${failureLabel(completed)}: ${detail}${recordLine ? `\n${recordLine}` : ''}`,
 					data: {
 						task_id: handle.taskId,
 						subagent_type: agentId,
 						state: completed.state,
 						status: completed.result?.status,
 						lastError: completed.result?.lastError,
+						...(outcome ? { outcome } : {}),
 					},
 				}
 			}
@@ -247,20 +260,21 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 			// the result programmatically.
 			return {
 				success: true,
-				output: wrapUntrusted(
+				output: `${wrapUntrusted(
 					{
 						kind: 'agent-result',
 						attributes: { agent: agentId, task: handle.taskId },
 						provenance: `This is the output of the delegated subagent "${agentId}", not this agent's own work.`,
 					},
 					resultText || '(subagent returned no text)',
-				),
+				)}${recordLine ? `\n\n${recordLine}` : ''}`,
 				data: {
 					task_id: handle.taskId,
 					subagent_type: agentId,
 					result: resultText,
 					state: completed.state,
 					status: completed.result?.status,
+					...(outcome ? { outcome } : {}),
 				},
 			}
 		},
@@ -339,3 +353,13 @@ async function runBlockingAgentTask(
 		signal.removeEventListener('abort', onAbort)
 	}
 }
+
+/** `text` with any line that opens with the kernel record prefix quoted, so it cannot pass for the kernel's line. */
+function neutraliseKernelLines(text: string): string {
+	return text
+		.split('\n')
+		.map((line) =>
+			line.trimStart().startsWith(KERNEL_RECORD_PREFIX) ? `> ${line.trimStart()}` : line,
+		)
+		.join('\n')
+}

package/src/tools/coordinator/index.ts

@@ -679,7 +679,9 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 					// turned them off had that decision revert behind every
 					// delegation. One merged `configOverrides`, because a second
 					// spread of the key would replace this one.
-					...(Object.keys(_context.env ?? {}).length > 0 || _context.toolResultGuardrails
+					...(Object.keys(_context.env ?? {}).length > 0 ||
+					_context.toolResultGuardrails ||
+					_context.fileReadTracker
 						? {
 								configOverrides: {
 									...(_context.env && Object.keys(_context.env).length > 0
@@ -688,6 +690,9 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 									...(_context.toolResultGuardrails
 										? { toolResultGuardrails: _context.toolResultGuardrails }
 										: {}),
+									...(_context.fileReadTracker
+										? { fileReadTracker: _context.fileReadTracker }
+										: {}),
 								},
 							}
 						: {}),