@namzu/sdk 62.6.1 → 62.7.0

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:

package/src/tools/file-read-tracker.ts

@@ -4,9 +4,48 @@ import { fingerprintContent } from './builtins/content-fingerprint.js'
 /** A body larger than this is not kept; the file's change is still seen by fingerprint. */
 const MAX_BODY_CHARS = 512 * 1024
 const MAX_BODIES = 128
+const MAX_AUTHORED = 1024
 
-/** Host-owned observation ledger. Share only across turns of the same conversation and filesystem. */
-export function createFileReadTracker(): FileReadTracker {
+/**
+ * What a family of agents (a parent and every descendant) wrote through the
+ * write and edit tools: path to the fingerprint of the content last put there,
+ * and when the ledger began. Shared by the whole family, because the approval
+ * classifier asks "did one of us write this script?". It carries no read
+ * state, so sharing it can never stand in for one agent's read of a file.
+ */
+export interface AuthoredLedger {
+	readonly startedAt: number
+	record(key: string, content: string): void
+	fingerprint(key: string): string | undefined
+}
+
+export function createAuthoredLedger(): AuthoredLedger {
+	const authored = new Map<string, string>()
+	return {
+		startedAt: Date.now(),
+		record(key, content) {
+			authored.delete(key)
+			authored.set(key, fingerprintContent(content))
+			while (authored.size > MAX_AUTHORED) {
+				const oldest = authored.keys().next().value
+				if (oldest === undefined) break
+				authored.delete(oldest)
+			}
+		},
+		fingerprint: (key) => authored.get(key),
+	}
+}
+
+/**
+ * Host-owned observation ledger. Share only across turns of the same
+ * conversation and filesystem, never between agents: what a ledger holds is
+ * what ITS reader has read, and the stale-write refusal compares the disk to
+ * that. A child gets `tracker.forChild()`: its own reader record, the family's
+ * authored ledger.
+ */
+export function createFileReadTracker(options?: {
+	readonly authored?: AuthoredLedger
+}): FileReadTracker {
 	const paths = new Set<string>()
 	const fingerprints = new Map<string, string>()
 	const writes = new Map<string, string>()
@@ -36,6 +75,11 @@ export function createFileReadTracker(): FileReadTracker {
 	// than the cap keeps no body (its change is still detectable by
 	// fingerprint), and the oldest bodies go first.
 	const bodies = new Map<string, string>()
+	// What the agent family wrote, by fingerprint. Not a body: a classifier
+	// reads the file as it is, and uses this only to say whether it is still
+	// what an agent wrote. Shared with children; everything else here is not.
+	const authored = options?.authored ?? createAuthoredLedger()
+	const keepAuthored = (key: string, content: string): void => authored.record(key, content)
 	function keepBody(key: string, content: string | undefined): void {
 		bodies.delete(key)
 		if (content === undefined || content.length > MAX_BODY_CHARS) return
@@ -63,6 +107,7 @@ export function createFileReadTracker(): FileReadTracker {
 		// A write supplies the whole body; any other observation without a
 		// witness may be a window of the file, which proves nothing about the rest.
 		keepBody(key, fullWriteCallId ? content : undefined)
+		if (content !== undefined && fullWriteCallId) keepAuthored(key, content)
 		if (next !== undefined && fullWriteCallId) {
 			writes.set(key, fullWriteCallId)
 			// A full body arrived whole in one call, so the chain is empty
@@ -76,6 +121,9 @@ export function createFileReadTracker(): FileReadTracker {
 	const MAX_WINDOWS_PER_FILE = 6
 	const MAX_WINDOWED_FILES = 512
 	return {
+		startedAt: authored.startedAt,
+		authoredFingerprint: (key) => authored.fingerprint(key),
+		forChild: () => createFileReadTracker({ authored }),
 		recordReadWindow(key, window, entry) {
 			let forFile = windows.get(key)
 			if (forFile) windows.delete(key)
@@ -127,6 +175,7 @@ export function createFileReadTracker(): FileReadTracker {
 			reads.delete(key)
 			fingerprints.set(key, fingerprintContent(content))
 			keepBody(key, content)
+			keepAuthored(key, content)
 			if (!chained) {
 				writes.delete(key)
 				chains.delete(key)

package/src/tools/untrusted-envelope.ts

@@ -205,6 +205,28 @@ export function wrapUntrusted(
 	].join('\n')
 }
 
+/**
+ * The opening words of the one line the kernel writes beside a delegated
+ * agent's answer, outside its block, to say what the run did according to its
+ * own record (`describeOutcomeRecord`).
+ */
+export const KERNEL_RECORD_PREFIX = 'Record of this run: '
+
+/**
+ * `text` without a kernel record line that follows its last block.
+ *
+ * A reader of the block must still find it when the kernel has said one more
+ * thing after it. The line is the kernel's: everything a child produced is
+ * inside the block, where this module has already made its delimiter
+ * impossible to forge, so a line out here asks the reader to trust nothing
+ * that it did not already trust.
+ */
+function withoutKernelRecord(trimmed: string): string {
+	const at = trimmed.lastIndexOf(`\n\n${KERNEL_RECORD_PREFIX}`)
+	if (at < 0 || trimmed.indexOf('\n', at + 2) >= 0) return trimmed
+	return trimmed.slice(0, at)
+}
+
 /**
  * The body of a single wrapped block, when `text` is one.
  *
@@ -246,7 +268,7 @@ export function wrapUntrusted(
  * it, which is the one failure this function must not have.
  */
 export function untrustedEnvelopeBody(text: string): string | undefined {
-	const trimmed = text.trim()
+	const trimmed = withoutKernelRecord(text.trim())
 	const opening = OPENING_TAG_PATTERN.exec(trimmed)
 	if (!opening) return undefined
 	const nonce = opening[1]

package/src/toolsets/manager.ts

@@ -35,6 +35,7 @@ import { type Logger, resolveLogger } from '../utils/logger.js'
 import { ToolsetConflictError } from './combine.js'
 import type { ToolSourceRef, Toolset, ToolsetAvailability } from './types.js'
 import { toToolSourceRef, toolsetIsReady } from './types.js'
+import { type ValidationIssueLike, describeValidationIssues } from './validation-issues.js'
 
 export type { ToolExecutionResult }
 
@@ -984,16 +985,9 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 	private validationFailure(
 		tool: ToolDefinition,
 		rawInput: unknown,
-		error: {
-			readonly issues: readonly {
-				readonly path: readonly PropertyKey[]
-				readonly message: string
-			}[]
-		},
+		error: { readonly issues: readonly ValidationIssueLike[] },
 	): ToolExecutionResult {
-		const errorMessage = error.issues
-			.map((issue) => `${issue.path.join('.')}: ${issue.message}`)
-			.join('; ')
+		const errorMessage = describeValidationIssues(error.issues)
 		const isEmptyInput =
 			rawInput === null ||
 			rawInput === undefined ||
@@ -1006,7 +1000,9 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 			: ''
 		const enrichedMessage = isEmptyInput
 			? `Tool "${tool.name}" was called with no arguments. ${requiredHint}${recoveryHint} Retry the call with the required parameters populated.`
-			: `Validation failed for "${tool.name}": ${errorMessage}. ${requiredHint}${recoveryHint}`
+			: `Validation failed for "${tool.name}": ${errorMessage}${
+					errorMessage.includes('\n') ? '\n' : '. '
+				}${requiredHint}${recoveryHint}`
 		this.log.error('Tool input validation failed', {
 			'namzu.tool.name': tool.name,
 			'namzu.registry.errors': errorMessage,

package/src/toolsets/validation-issues.ts

@@ -0,0 +1,97 @@
+/**
+ * Tool-input validation issues as sentences a model can act on.
+ *
+ * A zod message is written for a developer reading a stack trace:
+ * `edits: Too small: expected array to have >=1 items` names neither what to
+ * send nor why. A small model that reads it tends to repeat the same call. Each
+ * kind of issue a flat tool schema commonly produces is rewritten here to name
+ * the field and the fix; anything not recognised keeps its own message, so
+ * nothing is lost by this being a short list.
+ */
+
+export interface ValidationIssueLike {
+	readonly path: readonly PropertyKey[]
+	readonly message: string
+	readonly code?: string
+	readonly origin?: string
+	readonly minimum?: number | bigint
+	readonly maximum?: number | bigint
+	readonly expected?: string
+	readonly keys?: readonly string[]
+	readonly values?: readonly unknown[]
+}
+
+/** `edits.0.old_string` as `edits[0].old_string`, the way a model wrote it. */
+export function renderIssuePath(path: readonly PropertyKey[]): string {
+	let out = ''
+	for (const part of path) {
+		if (typeof part === 'number') out += `[${part}]`
+		else out += out === '' ? String(part) : `.${String(part)}`
+	}
+	return out
+}
+
+function plural(n: number | bigint, noun: string): string {
+	return `${n} ${noun}${n === 1 || n === 1n ? '' : 's'}`
+}
+
+function received(message: string): string | undefined {
+	return /received (\w+)$/.exec(message)?.[1]
+}
+
+/** One issue as one sentence, without a trailing period. */
+export function describeValidationIssue(issue: ValidationIssueLike): string {
+	const field = renderIssuePath(issue.path)
+	const name = field === '' ? 'The input' : `"${field}"`
+	const min = issue.minimum
+	switch (issue.code) {
+		case 'too_small':
+			if (issue.origin === 'string' && min !== undefined && Number(min) <= 1) {
+				return `${name} must not be empty; send the text itself`
+			}
+			if (issue.origin === 'string' && min !== undefined) {
+				return `${name} is too short; it needs at least ${plural(min, 'character')}`
+			}
+			if (issue.origin === 'array' && min !== undefined) {
+				return `${name} is a list with too few entries; it needs at least ${plural(min, 'entry').replace('entrys', 'entries')}, or leave the field out`
+			}
+			if (min !== undefined) return `${name} is too small; the smallest accepted is ${min}`
+			break
+		case 'too_big':
+			if (issue.maximum !== undefined) {
+				return `${name} is too large; the largest accepted is ${issue.maximum}`
+			}
+			break
+		case 'invalid_type': {
+			const got = received(issue.message)
+			if (issue.expected !== undefined && got === 'undefined') {
+				return `${name} is missing; send it as ${withArticle(issue.expected)}`
+			}
+			if (issue.expected !== undefined && got !== undefined) {
+				return `${name} must be ${withArticle(issue.expected)}, not ${got === 'null' ? 'null' : `a ${got}`}`
+			}
+			break
+		}
+		case 'unrecognized_keys':
+			if (issue.keys !== undefined && issue.keys.length > 0) {
+				const list = issue.keys.map((key) => `"${key}"`).join(', ')
+				return `${field === '' ? '' : `${name} has `}${issue.keys.length === 1 ? 'a field' : 'fields'} this tool does not take: ${list}. Remove ${issue.keys.length === 1 ? 'it' : 'them'}`
+			}
+			break
+		case 'invalid_value':
+			if (issue.values !== undefined && issue.values.length > 0) {
+				return `${name} must be one of ${issue.values.map((v) => JSON.stringify(v)).join(', ')}`
+			}
+			break
+	}
+	const message = issue.message.replace(/\.+$/, '')
+	return field === '' ? message : `${field}: ${message}`
+}
+
+function withArticle(type: string): string {
+	return /^[aeiou]/.test(type) ? `an ${type}` : `a ${type}`
+}
+
+export function describeValidationIssues(issues: readonly ValidationIssueLike[]): string {
+	return issues.map(describeValidationIssue).join('; ')
+}

package/src/turn/memory-recall.ts

@@ -28,6 +28,19 @@ export interface MemoryRecallOptions {
 	 * aged memory names before relying on it. Default one day.
 	 */
 	readonly ageNoticeAfterMs?: number
+	/**
+	 * Asked once for each record about to be shown (at most `maxMemories` a
+	 * request), with its id and metadata, never its body. A returned string is
+	 * added to the record's line as `caution` and to the event's entry, so the
+	 * model reads that the record may no longer hold; the record is still
+	 * shown. A host uses it to check what a record names (a file, say) against
+	 * the project as it is now. It runs inside the recall deadline, so it must
+	 * be cheap; a throw, or a deadline passing, means no caution.
+	 */
+	readonly caution?: (record: {
+		readonly id: string
+		readonly metadata?: Readonly<Record<string, unknown>>
+	}) => string | undefined | Promise<string | undefined>
 	/** Clock for ages; defaults to `Date.now`. */
 	readonly now?: () => number
 	/**
@@ -593,6 +606,19 @@ export function createMemoryRecallStep(options: MemoryRecallOptions): PrepareSte
 					)
 				)
 					continue
+				let caution: string | undefined
+				if (options.caution) {
+					try {
+						caution = await options.caution({
+							id: entry.id,
+							...(full.metadata ? { metadata: full.metadata } : {}),
+						})
+					} catch {
+						// A check that failed says nothing about the record.
+					}
+					if (expired) break
+					if (caution !== undefined) caution = clipped(caution, 200)
+				}
 				const aged = now() - entry.updatedAt > ageNoticeAfterMs
 				// The first aged record pays for the notice it brings with it, so
 				// a block of fresh records spends nothing on it.
@@ -614,6 +640,7 @@ export function createMemoryRecallStep(options: MemoryRecallOptions): PrepareSte
 						),
 						updatedAt: entry.updatedAt,
 						...(aged ? { age: describeMemoryAge(entry.updatedAt, now()) } : {}),
+						...(caution ? { caution } : {}),
 						sourceTurn:
 							typeof full.metadata?.turnId === 'string'
 								? clipped(full.metadata.turnId, 80)
@@ -632,6 +659,7 @@ export function createMemoryRecallStep(options: MemoryRecallOptions): PrepareSte
 						title: entry.title,
 						origin: memoryOrigin(full.metadata),
 						updatedAt: entry.updatedAt,
+						...(caution ? { caution } : {}),
 						// Without a selector the words chose it and there is nothing to add;
 						// with one, say so when it did not.
 						...(reasons.has(entry.id) || options.select

package/src/types/agent/base.ts

@@ -160,6 +160,20 @@ export interface BaseAgentConfig {
 	 */
 	toolResultGuardrails?: readonly import('../guardrail/index.js').ToolResultGuardrailSpec[]
 
+	/**
+	 * This agent's own file observation ledger.
+	 *
+	 * A delegated child is a fresh turn with its own executor. It starts with
+	 * its own read record (`FileReadTracker.forChild`), so a write by its
+	 * parent or a sibling still makes what it read stale, but it shares the
+	 * delegating turn's record of what the agents wrote: a script its parent
+	 * wrote, run by the child, is the session's own, so the auto-mode
+	 * classifier reads it. Stamped by `AgentManager` from
+	 * `configOverrides.fileReadTracker`, which the delegation tools fill from
+	 * the turn's own `ToolContext`.
+	 */
+	fileReadTracker?: import('../tool/index.js').FileReadTracker
+
 	/**
 	 * Tools this turn may NOT use, subtracted from whatever it would
 	 * otherwise have.
@@ -232,6 +246,10 @@ export interface BaseAgentConfig {
 	reasoning?: import('../session/config.js').TurnConfig['reasoning']
 	/** Ask once for a check of edits before a turn ends; see {@link import('../session/config.js').TurnConfig.completionAudit}. */
 	completionAudit?: boolean
+	/** Consecutive end-of-turn hook refusals honoured; see {@link import('../session/config.js').TurnConfig.maxHookRefusals}. */
+	maxHookRefusals?: number
+	/** The outcome record's hooks; see {@link import('../session/config.js').TurnConfig.outcome}. */
+	outcome?: import('../session/config.js').TurnConfig['outcome']
 
 	/**
 	 * Deduplicate a retried invocation instead of running it twice.
@@ -411,6 +429,8 @@ export interface BaseAgentResult {
 	durationMs: number
 	messages: Message[]
 	result?: string
+	/** What the turn changed and what checked it; see {@link import('../session/turn.js').Turn.outcome}. */
+	outcome?: import('../session/outcome.js').TurnOutcome
 	/**
 	 * The schema-validated answer, when the turn was configured to produce one.
 	 *

package/src/types/agent/query.ts

@@ -67,6 +67,8 @@ export interface QueryAgentConfig extends BaseAgentConfig {
 	sandboxTeardownTimeoutMs?: number
 	/** See {@link QueryParams.outsideRootAccess}. Default `'refuse'`. */
 	outsideRootAccess?: 'refuse' | 'review'
+	/** See {@link QueryParams.outsideRootRefusal}. */
+	outsideRootRefusal?: string
 	/** See {@link QueryParams.sandboxEscape}. Default `'refuse'`. */
 	sandboxEscape?: 'refuse' | 'review'