@namzu/sdk 62.6.0 → 62.7.0

package/src/tools/builtins/edit.ts

@@ -22,8 +22,91 @@ import {
 import { withFileMutationLock } from './file-mutation-lock.js'
 import { jsonStringEscapes } from './json-string-hint.js'
 import { lineDiff } from './line-diff.js'
+import { notebookRefusal } from './notebook-guard.js'
 import { staleBeforeReview } from './stale-before-review.js'
 
+type RawEditInput = {
+	path: string
+	old_string?: string
+	oldStr?: string
+	new_string?: string
+	newStr?: string
+	insertLine?: number | string
+	replace_all?: boolean
+	edits?: { old_string: string; new_string: string; replace_all?: boolean }[]
+}
+
+const ONE_SHAPE_EACH =
+	'Single edit: {"path":"file.md","old_string":"exact unique text","new_string":"replacement text"}\nSeveral edits: {"path":"file.md","edits":[{"old_string":"a","new_string":"b"},{"old_string":"c","new_string":"d"}]}'
+
+const hasTopLevelEdit = (value: RawEditInput): boolean =>
+	value.old_string !== undefined ||
+	value.oldStr !== undefined ||
+	value.new_string !== undefined ||
+	value.newStr !== undefined ||
+	value.insertLine !== undefined
+
+/**
+ * A top-level edit that is exactly the one entry of a one-entry batch: the same
+ * call said twice, not two intentions. Anything else (a different text, a
+ * longer list, an insertion) is a real conflict and stays refused.
+ */
+function restatesTheBatch(value: RawEditInput): boolean {
+	const entries = value.edits
+	if (entries === undefined || entries.length !== 1 || value.insertLine !== undefined) return false
+	const [entry] = entries
+	return (
+		entry !== undefined &&
+		(value.old_string ?? value.oldStr) === entry.old_string &&
+		(value.new_string ?? value.newStr) === entry.new_string &&
+		(value.replace_all ?? false) === (entry.replace_all ?? false)
+	)
+}
+
+/**
+ * Which of the two shapes this call is, and what to say when it is neither.
+ *
+ * An empty `edits` beside a top-level edit, and a one-entry `edits` that restates
+ * the top-level edit, are the single edit: the intent is not in doubt and nothing
+ * is dropped. A batch beside a DIFFERENT top-level edit stays refused, because
+ * any precedence would silently drop an edit somebody believes was made.
+ */
+function checkEditShape(value: RawEditInput): string | undefined {
+	const batch = value.edits !== undefined && value.edits.length > 0
+	const top = hasTopLevelEdit(value)
+	if (value.edits !== undefined && !batch && !top) {
+		return `\`edits\` is an empty list, so there is nothing to change. Send exactly one of these, and leave out the field you are not using:\n${ONE_SHAPE_EACH}`
+	}
+	if (batch && top && !restatesTheBatch(value)) {
+		return `This call has both an \`edits\` list and a different top-level edit, and only one can be applied. Send exactly one of these, and leave out the field you are not using:\n${ONE_SHAPE_EACH}`
+	}
+	if (batch) return undefined
+	if (typeof value.new_string !== 'string' && typeof value.newStr !== 'string') {
+		return 'Either new_string or newStr is required.'
+	}
+	if (
+		value.insertLine === undefined &&
+		typeof value.old_string !== 'string' &&
+		typeof value.oldStr !== 'string'
+	) {
+		return 'Either old_string/oldStr or insertLine is required.'
+	}
+	return undefined
+}
+
+/**
+ * The input every later stage sees: one shape, with the redundant half gone. The
+ * review card, the classifier, the dry run and the apply step all read this, so
+ * none of them meets `edits: []` or a restated edit.
+ */
+function canonicalEditInput(value: RawEditInput): RawEditInput {
+	if (value.edits === undefined) return value
+	const { edits, ...rest } = value
+	if (edits.length === 0) return rest
+	const { old_string, oldStr, new_string, newStr, insertLine, ...kept } = rest
+	return { ...kept, edits }
+}
+
 /**
  * Two schemas, on purpose.
  *
@@ -106,48 +189,23 @@ const inputSchema = z
 					})
 					.strict(),
 			)
-			.min(1)
+			// No `.min(1)`: a model that fills every optional field of a flat object
+			// sends `edits: []` next to a single top-level edit, and that is the
+			// single edit, not an error. An empty list with nothing beside it is
+			// refused by `checkEditShape` below, in a sentence that says what to send.
 			.optional()
 			.describe(
-				'Several replacements in one file, applied in order and committed together. Nothing is written unless every one applies.',
+				'Several replacements in one file, applied in order and committed together. Nothing is written unless every one applies. Leave out when sending a single old_string/new_string.',
 			),
 	})
 	.strict()
-	.refine(
-		(value) =>
-			value.edits !== undefined ||
-			typeof value.new_string === 'string' ||
-			typeof value.newStr === 'string',
-		{ message: 'Either new_string or newStr is required.' },
-	)
-	.refine(
-		(value) =>
-			value.edits !== undefined ||
-			value.insertLine !== undefined ||
-			typeof value.old_string === 'string' ||
-			typeof value.oldStr === 'string',
-		{ message: 'Either old_string/oldStr or insertLine is required.' },
-	)
-	// Refused rather than resolved. A call carrying both an `edits` list and a
-	// top-level replacement is two different intentions in one object, and any
-	// precedence this code picked would be a guess about which the model meant
-	// — silently dropping the other. There is no reading of that which is safe:
-	// the dropped half is an edit somebody believes was made.
-	.refine(
-		(value) =>
-			value.edits === undefined ||
-			(value.old_string === undefined &&
-				value.oldStr === undefined &&
-				value.new_string === undefined &&
-				value.newStr === undefined &&
-				value.insertLine === undefined),
-		{
-			message:
-				'Use either `edits` or a single top-level edit, not both. Move the top-level old_string/new_string into the edits list.',
-		},
-	)
+	.superRefine((value, ctx) => {
+		const problem = checkEditShape(value)
+		if (problem) ctx.addIssue({ code: 'custom', message: problem })
+	})
+	.transform(canonicalEditInput)
 
-export type EditInput = z.infer<typeof inputSchema>
+export type EditInput = z.output<typeof inputSchema>
 
 /**
  * What an `edit` call WOULD produce for a file body, without touching any file.
@@ -184,7 +242,10 @@ export function dryRunEdit(
 		}
 	}
 	const result = applyEdit(content, normalized.operations)
-	return result.success ? { success: true, content: result.content } : result
+	if (!result.success) return result
+	const notebook = notebookRefusal(parsed.data.path, result.content, content)
+	if (notebook) return { success: false, error: notebook }
+	return { success: true, content: result.content }
 }
 
 /**
@@ -205,7 +266,7 @@ const modelInputSchema: Record<string, unknown> = {
 		old_string: {
 			type: 'string',
 			description:
-				'Exact unique text from the file, without read-tool line-number prefixes. Must not be empty.',
+				'For a single change: exact unique text from the file, without read-tool line-number prefixes. Must not be empty. Do not send together with edits.',
 		},
 		new_string: {
 			type: 'string',
@@ -282,7 +343,7 @@ const modelInputSchema: Record<string, unknown> = {
 				additionalProperties: false,
 			},
 			description:
-				'Several replacements in one file, applied in order and committed together. Nothing is written unless every one applies. Use this instead of several edit calls when the changes only make sense together.',
+				'For SEVERAL changes to one file: a non-empty list, applied in order and committed together. Nothing is written unless every one applies. Leave this field out entirely when you send old_string/new_string; never send an empty list.',
 		},
 	},
 	// `old_string` is deliberately NOT required, and this is the fix.
@@ -437,7 +498,7 @@ function refusedEdit(result: EditApplyFailure, path: string) {
 export const EditTool = defineTool({
 	name: 'edit',
 	description:
-		'Makes targeted edits to a file using exact string find-and-replace or line insertion. To change an existing file, use `edit`: `write` overwrites the whole body and discards earlier work on partial failure, while `edit` keeps the rest of the file byte-for-byte intact and is recoverable: if a single edit fails (old_string/oldStr ambiguous, broader restructuring needed), follow up with another `edit` instead of re-emitting the entire file via `write`. The old_string/oldStr must be unique in the file unless replace_all is true. For insertions, pass insertLine plus new_string/newStr; use insertLine: "end" to extend a file at the end. Keep new_string/newStr under 12000 characters, because a longer payload can be cut off mid-call and fail; use repeated bounded edits for long sections. Preserves file formatting and indentation. To make several changes to one file that only make sense together, send them as `edits`: a list of {old_string, new_string} applied in order and committed as one write — if any of them does not apply, nothing is written and the reply names which one, so the file is never left half-changed.',
+		'Makes targeted edits to a file using exact string find-and-replace or line insertion. To change an existing file, use `edit`: `write` overwrites the whole body and discards earlier work on partial failure, while `edit` keeps the rest of the file byte-for-byte intact and is recoverable: if a single edit fails (old_string/oldStr ambiguous, broader restructuring needed), follow up with another `edit` instead of re-emitting the entire file via `write`. The old_string/oldStr must be unique in the file unless replace_all is true. For insertions, pass insertLine plus new_string/newStr; use insertLine: "end" to extend a file at the end. Keep new_string/newStr under 12000 characters, because a longer payload can be cut off mid-call and fail; use repeated bounded edits for long sections. Preserves file formatting and indentation. To make several changes to one file that only make sense together, send them as `edits` (and then no top-level old_string/new_string; for a single change leave `edits` out): a list of {old_string, new_string} applied in order and committed as one write — if any of them does not apply, nothing is written and the reply names which one, so the file is never left half-changed. An edit that would leave a `.ipynb` file as invalid notebook JSON is refused and the file is unchanged.',
 	inputSchema,
 	modelInputSchema,
 	enforceModelInput: true,
@@ -458,7 +519,7 @@ export const EditTool = defineTool({
 	refuseBeforeReview: (input: EditInput, context) => staleBeforeReview(context, input.path, 'edit'),
 	// The classifier judges which file changes and in what way, in a line.
 	classifierInput: (input: EditInput) => {
-		if (input.edits !== undefined) {
+		if (input.edits !== undefined && input.edits.length > 0) {
 			const shown = input.edits.slice(0, 5).map((e) => describeChange(e.old_string, e.new_string))
 			const more =
 				input.edits.length > shown.length ? `; ${input.edits.length - shown.length} more` : ''
@@ -570,6 +631,8 @@ export const EditTool = defineTool({
 				if (!admitted.success) return admitted
 				const result = admitted.result
 				if (!result.success) return refusedEdit(result, parsed.data.path)
+				const notebook = notebookRefusal(parsed.data.path, result.content, content)
+				if (notebook) return { success: false as const, output: '', error: notebook }
 
 				await context.sandbox.writeFile(parsed.data.path, result.content)
 				recordEditedContent(context, parsed.data.path, result.content)
@@ -593,6 +656,8 @@ export const EditTool = defineTool({
 			if (!admitted.success) return admitted
 			const result = admitted.result
 			if (!result.success) return refusedEdit(result, hostPath)
+			const notebook = notebookRefusal(hostPath, result.content, content)
+			if (notebook) return { success: false as const, output: '', error: notebook }
 
 			// Temp file, fsync, rename — a reader sees the old body or the new
 			// one, never a half-written one. A plain `writeFile` that fails

package/src/tools/builtins/glob.ts

@@ -68,7 +68,7 @@ function relativePattern(pattern: string, root: string, sandboxed: boolean): str
 export const GlobTool = defineTool({
 	name: 'glob',
 	description:
-		'Finds regular files by glob pattern in a bounded search. "*" searches one directory; use "**" explicitly for recursive discovery. Skips files that .gitignore and .ignore rules exclude unless include_ignored is set, and files the read rules of the session deny. Returns at most 500 paths and says when a result is limited or a search stopped early. Does not follow symlinks.',
+		'Finds regular files by glob pattern in a bounded search. "*" searches one directory; use "**" explicitly for recursive discovery. Skips files that .gitignore and .ignore rules exclude unless include_ignored is set, and files the read rules of the session deny. Returns at most 500 paths and says when a result is limited or a search stopped early. Does not follow symlinks. To search inside files, use grep.',
 	inputSchema,
 	category: 'filesystem',
 	// Declared so a path outside the turn's roots can be reviewed before the

package/src/tools/builtins/grep.ts

@@ -211,7 +211,7 @@ function isBinaryContent(buffer: Buffer): boolean {
 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

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/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 }
+										: {}),
 								},
 							}
 						: {}),

package/src/tools/coordinator/outcome-record.ts

@@ -0,0 +1,93 @@
+import type { TurnOutcome, TurnOutcomeCheck } from '../../types/session/outcome.js'
+import { KERNEL_RECORD_PREFIX } from '../untrusted-envelope.js'
+
+/**
+ * The kernel's own sentence about what a delegated run did, for the parent
+ * that delegated it.
+ *
+ * It states the record, not the child's account of itself, and it sits outside
+ * the marked block that holds the child's words: the parent reads it as a fact
+ * of the kernel's, the way it reads the task id. What it can say is exactly
+ * what the record can say. `checked` means a recognised check passed and the
+ * workspace did not change after it; it does not mean the check covers the
+ * change.
+ *
+ * A run that changed nothing and failed no check gets no line.
+ *
+ * The command is the child's own text, so it is shown as plain data: one line
+ * of printable ASCII with no quotes or backticks, cut short. A command that
+ * does not survive that is named as "a command" instead.
+ */
+export function describeOutcomeRecord(outcome: TurnOutcome): string | undefined {
+	const body = describe(outcome)
+	return body === undefined ? undefined : `${KERNEL_RECORD_PREFIX}${body}`
+}
+
+const SHOWN_COMMAND_CHARS = 60
+
+/** A command as data inside backticks, or `undefined` when it cannot be shown without being rewritten. */
+export function showCommand(command: string): string | undefined {
+	const trimmed = command.trim()
+	if (trimmed === '' || trimmed.length > SHOWN_COMMAND_CHARS) return undefined
+	// Printable ASCII, and none of the characters that open a quotation or a
+	// substitution in whatever reads this next.
+	if (!/^[\x20-\x7e]+$/.test(trimmed) || /[`'"$\\#]/.test(trimmed)) return undefined
+	return `\`${trimmed}\``
+}
+
+function named(check: TurnOutcomeCheck): string {
+	return showCommand(check.command) ?? 'a command'
+}
+
+function changedPhrase(outcome: TurnOutcome): string | undefined {
+	const { total, outsideKnownTools } = outcome.changes
+	if (total > 0) return total === 1 ? '1 file changed' : `${total} files changed`
+	if (outsideKnownTools) return 'files changed, by something other than the edit tools'
+	return undefined
+}
+
+function describe(outcome: TurnOutcome): string | undefined {
+	const changed = changedPhrase(outcome)
+	const failed = outcome.checks.filter((check) => check.result === 'failed')
+	const lead = changed === undefined ? '' : `${changed}; `
+
+	switch (outcome.verdict) {
+		case 'unchanged':
+			// Nothing to say, and a line on every delegation that only read would
+			// be noise the parent learns to skip. The record is still in `data`.
+			return undefined
+		case 'unknown':
+			return 'a command ran that may have changed files, and nothing here could tell whether it did.'
+		case 'unchecked':
+			return `${lead}nothing was run to check ${total(outcome) === 1 ? 'it' : 'them'}.`
+		case 'failing': {
+			const first = failed[0]
+			if (first === undefined) return undefined
+			const more = failed.length > 1 ? ` (and ${failed.length - 1} more)` : ''
+			return `${lead}${named(first)} failed${more}.`
+		}
+		case 'checked': {
+			const passed = [...outcome.checks].reverse().find((c) => c.result === 'passed' && c.fresh)
+			return `${lead}${passed ? named(passed) : 'a check'} passed and nothing changed after it.`
+		}
+		case 'stale': {
+			const passed = [...outcome.checks].reverse().find((c) => c.result === 'passed')
+			return `${lead}${passed ? named(passed) : 'a check'} passed, then files changed again.`
+		}
+		case 'inconclusive': {
+			const masked = outcome.checks.find((c) => c.result === 'masked')
+			if (masked) {
+				const how = /(?<!\|)\|(?!\|)/.test(masked.command) ? 'the pipe' : 'the command line'
+				return `${lead}${named(masked)} ran, but ${how} hides whether it passed.`
+			}
+			const unsettled = outcome.checks.find((c) => c.result === 'unsettled')
+			if (unsettled) return `${lead}${named(unsettled)} ran, but its result was not seen.`
+			const passed = outcome.checks.find((c) => c.result === 'passed')
+			return `${lead}${passed ? named(passed) : 'a check'} passed, but it cannot be told whether files changed after it.`
+		}
+	}
+}
+
+function total(outcome: TurnOutcome): number {
+	return outcome.changes.total
+}

package/src/tools/defineTool.ts

@@ -41,6 +41,8 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	executionBarrier?: boolean
 	/** The tool bounds its own output; see {@link ToolDefinition.selfLimitingOutput}. */
 	selfLimitingOutput?: boolean
+	/** A tighter per-result cap; see {@link ToolDefinition.maxOutputChars}. */
+	maxOutputChars?: number
 	tier?: string
 	/**
 	 * How this tool's call and result should be shown; see
@@ -163,6 +165,7 @@ export function defineTool<S extends z.ZodType>(
 		...(options.selfLimitingOutput !== undefined
 			? { selfLimitingOutput: options.selfLimitingOutput }
 			: {}),
+		...(options.maxOutputChars !== undefined ? { maxOutputChars: options.maxOutputChars } : {}),
 		category: options.category,
 		permissions: options.permissions,
 		isReadOnly: