@namzu/sdk 62.6.0 → 62.7.0

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'
 

package/src/types/common/index.ts

@@ -12,6 +12,22 @@ export interface TokenUsage {
 	cachedTokens: number
 	cacheWriteTokens: number
 
+	/**
+	 * The whole prompt this call processed, cache reads and cache writes
+	 * included: the size of the context the model was given.
+	 *
+	 * Drivers disagree on what `promptTokens` counts. Some include cached
+	 * tokens, others report only the uncached remainder,
+	 * which on a warm cache is a handful of tokens against a context of tens
+	 * of thousands. Context size, the compaction trigger and the context meter
+	 * need the whole prompt, so a driver that excludes cache from
+	 * `promptTokens` reports it here. Absent means `promptTokens` already is
+	 * the whole prompt; read it through {@link promptSizeOf}.
+	 *
+	 * A per-call fact like {@link TokenUsage.cacheTtlMs}: never summed.
+	 */
+	fullPromptTokens?: number
+
 	/**
 	 * Output tokens the model spent on internal reasoning.
 	 *
@@ -88,6 +104,11 @@ export interface CacheMiss {
 	missedTokens?: number
 }
 
+/** The whole prompt one call processed: {@link TokenUsage.fullPromptTokens} when the driver reports it, else `promptTokens`. */
+export function promptSizeOf(usage: TokenUsage): number {
+	return usage.fullPromptTokens ?? usage.promptTokens
+}
+
 export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage): TokenUsage {
 	return {
 		promptTokens: current.promptTokens + addition.promptTokens,
@@ -105,7 +126,7 @@ export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage):
 		...(current.webSearchRequests !== undefined || addition.webSearchRequests !== undefined
 			? { webSearchRequests: (current.webSearchRequests ?? 0) + (addition.webSearchRequests ?? 0) }
 			: {}),
-		// `cacheTtlMs`, `cacheWriteTtlTokens`, `speed`, `serviceTier`,
+		// `fullPromptTokens`, `cacheTtlMs`, `cacheWriteTtlTokens`, `speed`, `serviceTier`,
 		// `inferenceGeo` and `cacheMiss` are per-call facts and are deliberately
 		// not carried into a sum.
 	}
@@ -139,6 +160,9 @@ export function mergeTokenUsage(current: TokenUsage, next: TokenUsage): TokenUsa
 		totalTokens: Math.max(current.totalTokens, next.totalTokens, promptTokens + completionTokens),
 		cachedTokens: Math.max(current.cachedTokens, next.cachedTokens),
 		cacheWriteTokens: Math.max(current.cacheWriteTokens, next.cacheWriteTokens),
+		...(current.fullPromptTokens !== undefined || next.fullPromptTokens !== undefined
+			? { fullPromptTokens: Math.max(current.fullPromptTokens ?? 0, next.fullPromptTokens ?? 0) }
+			: {}),
 		...(current.reasoningTokens !== undefined || next.reasoningTokens !== undefined
 			? { reasoningTokens: Math.max(current.reasoningTokens ?? 0, next.reasoningTokens ?? 0) }
 			: {}),

package/src/types/hitl/index.ts

@@ -1,6 +1,7 @@
 import type { CostInfo, TokenUsage } from '../common/index.js'
 import type { CheckpointId, PlanId, SessionId, TurnId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
+import type { ShellDialect } from '../tool/index.js'
 
 export type { CheckpointId }
 
@@ -179,6 +180,32 @@ export interface ResumeContext {
 	readonly transcript: () => readonly Message[]
 	/** The turn's cancellation signal, when it has one. */
 	readonly signal?: AbortSignal
+	/**
+	 * The script files a shell line launches that the agent wrote, or that came
+	 * into being during the session, read now. Absent when the host keeps no
+	 * file ledger. `callId` names the call under review, so a change to a file
+	 * between this read and the run can be noticed when it runs.
+	 */
+	readonly launchedScripts?: (
+		callId: string,
+		line: string,
+		dialect: ShellDialect,
+	) => Promise<readonly LaunchedScript[]>
+}
+
+/** A script file a reviewed shell line launches, as read for its reviewer. */
+export interface LaunchedScript {
+	readonly path: string
+	/** `authored`: written through the write or edit tools. `unknown`: it appeared during the session some other way. */
+	readonly origin: 'authored' | 'unknown'
+	/** `ok`: shown as read. `changed`: no longer what the agent wrote. `unreadable`: the file could not be read. */
+	readonly state: 'ok' | 'changed' | 'unreadable'
+	/** One plain sentence saying what the reviewer is looking at. */
+	readonly note: string
+	/** The text shown: the whole file, or its head and tail with the cut marked. */
+	readonly content?: string
+	/** Characters of the file left out of `content`. */
+	readonly cut?: number
 }
 
 /**

package/src/types/session/config.ts

@@ -106,6 +106,26 @@ export interface TurnConfig {
 	 * Off when absent, so an embedding host sees no change.
 	 */
 	completionAudit?: boolean
+	/**
+	 * How many times in a row `turn_end` / `subagent_stop` hooks may refuse to
+	 * let the turn end (answer `skip`) before the turn stops honouring them. At
+	 * the limit the turn ends, one notice naming the hook is recorded, and the
+	 * remaining refusals are ignored. A tool call between refusals resets the
+	 * count. Off when absent or 0, so an embedding host sees no change; a
+	 * positive integer sets the limit.
+	 */
+	maxHookRefusals?: number
+	/**
+	 * The turn's outcome record: what changed, what was run to check it, and
+	 * whether the last word of each check was said about the workspace as the
+	 * turn left it (`Turn.outcome`).
+	 *
+	 * The record is kept whether or not this is set, from the kernel's own write
+	 * tools alone. A host that names `detectChanges` gets the workspace itself
+	 * compared at the start, after each check and at the end, so a change made
+	 * by a shell command is seen. It never blocks or prolongs a turn.
+	 */
+	outcome?: import('./outcome.js').TurnOutcomeConfig
 	/** Provider-hosted search for this turn. Explicit opt-in; no local network permission. */
 	webSearch?: import('../provider/index.js').ChatCompletionParams['webSearch']
 	/** Cumulative parent-and-descendant tokens; 0 is unlimited with usage accounting. */

package/src/types/session/events.ts

@@ -24,7 +24,7 @@ import type { FencingToken } from './durable.js'
 import type { Lineage } from './lineage.js'
 import type { MessageStopReason, StopReason } from './stop-reason.js'
 import type { SubSessionKind } from './sub-session.js'
-import type { Origin, TurnBudgetBinding, TurnConfigSnapshot, TurnSettlement } from './turn.js'
+import type { LiveTurnSettlement, Origin, TurnBudgetBinding, TurnConfigSnapshot } from './turn.js'
 
 /**
  * Live events of a session: the stream a host listens to while a turn runs.
@@ -809,7 +809,7 @@ type CoreSessionEvent =
 			 * value where an honest gap belongs.
 			 */
 			cancelCause?: CancelCause
-			settlement: TurnSettlement
+			settlement: LiveTurnSettlement
 	  }
 	/**
 	 * The turn failed. Terminal, like `turn_completed`.
@@ -853,7 +853,7 @@ type CoreSessionEvent =
 			 * it sends the reader somewhere specific and wrong.
 			 */
 			explanation?: { id: string; message: string; hint: string }
-			settlement: TurnSettlement
+			settlement: LiveTurnSettlement
 	  }
 	// Additive 2026-07 (provider capability negotiation): emitted once per
 	// turn when the request asks for something the provider DRIVER declared

package/src/types/session/index.ts

@@ -42,6 +42,7 @@ export type {
 } from './sub-session.js'
 
 export * from './turn.js'
+export * from './outcome.js'
 export * from './config.js'
 export * from './events.js'
 export * from './records.js'

package/src/types/session/outcome.ts

@@ -0,0 +1,139 @@
+import { z } from 'zod'
+
+/**
+ * How a turn came out, from the kernel's own record of its tool calls.
+ *
+ * `checked` says a recognised check passed on the workspace as the turn left
+ * it. It does not say the check covers the change.
+ */
+export type TurnOutcomeVerdict =
+	/** Nothing in the workspace differs from the start of the turn. */
+	| 'unchanged'
+	/** Changed; at least one check passed on the final state and none is left failing. */
+	| 'checked'
+	/** Changed; checks passed, but the workspace changed again after the last pass. */
+	| 'stale'
+	/** Some check's latest run did not pass. Changed or not. */
+	| 'failing'
+	/** Changed; checks ran but none established a pass (status hidden, background, timed out, or unknown freshness). */
+	| 'inconclusive'
+	/** Changed; no check ran. */
+	| 'unchecked'
+	/**
+	 * Whether anything changed cannot be told: no write tool ran, but a command
+	 * that may have changed files did, and no workspace detector answered.
+	 */
+	| 'unknown'
+
+/** What one check established. */
+export type TurnOutcomeCheckResult =
+	/** Exit status 0, and the status is the check's own. */
+	| 'passed'
+	/** Non-zero exit, refused, or errored. */
+	| 'failed'
+	/** The command line lets something else decide the exit status: a pipe, `;`, `||`, a trailing `&`. */
+	| 'masked'
+	/** Handed to a background job, continued, timed out, or its status was never seen. */
+	| 'unsettled'
+
+export interface TurnOutcomeCheck {
+	/** As run, clipped. */
+	readonly command: string
+	/** The loop step the latest run of this command finished in. */
+	readonly step: number
+	readonly result: TurnOutcomeCheckResult
+	readonly exitCode?: number
+	/**
+	 * True when the workspace is the same now as when this check finished. False
+	 * when it is known to have changed since. Absent when that cannot be told.
+	 */
+	readonly fresh?: boolean
+}
+
+export interface TurnOutcome {
+	readonly verdict: TurnOutcomeVerdict
+	/**
+	 * How the workspace was observed. `calls`: only the kernel's own write tools
+	 * were seen, so a change made by a shell command or another tool is invisible
+	 * and `unchanged` means only that no write tool ran. `workspace`: the host
+	 * supplied a change detector and the start, each check and the end were
+	 * compared with it.
+	 */
+	readonly basis: 'calls' | 'workspace'
+	readonly changes: {
+		/** Distinct paths the turn's write tools changed, or the number of write calls when some had no path. */
+		readonly total: number
+		/** The first of them, bounded. */
+		readonly paths: readonly string[]
+		/** The workspace moved and no write tool call explains it. */
+		readonly outsideKnownTools: boolean
+	}
+	/** In order of first run; the latest run of each distinct command; bounded. */
+	readonly checks: readonly TurnOutcomeCheck[]
+	/** How many distinct checks ran, when `checks` was cut. */
+	readonly checksTotal?: number
+}
+
+/** Host hooks for the turn's outcome record. */
+export interface TurnOutcomeConfig {
+	/**
+	 * A fingerprint of the workspace, or `null` when it cannot be told.
+	 * `fingerprintWorkspace` is the kernel's own. `null` is never a match.
+	 * Called before the first call of the turn that could change the workspace,
+	 * after each check, and once when the turn ends; never in a turn whose calls
+	 * are all provably read-only.
+	 */
+	readonly detectChanges?: () => Promise<string | null>
+	/** Names a command that checks work, beyond the ones the kernel recognises. */
+	readonly isCheck?: (command: string) => boolean
+	/** Deadline per detector call. A detector that is late is `null`. Default 3000. */
+	readonly detectTimeoutMs?: number
+}
+
+/** Bounds on a recorded outcome. */
+export const OUTCOME_MAX_PATHS = 50
+export const OUTCOME_MAX_CHECKS = 20
+export const OUTCOME_MAX_COMMAND_CHARS = 300
+export const OUTCOME_MAX_PATH_CHARS = 300
+export const OUTCOME_DEFAULT_DETECT_TIMEOUT_MS = 3000
+
+const verdict = z.enum([
+	'unchanged',
+	'checked',
+	'stale',
+	'failing',
+	'inconclusive',
+	'unchecked',
+	'unknown',
+])
+const count = z.number().int().nonnegative().safe()
+
+/** The shape a recorded outcome must have to be written to, or read back from, the session log. */
+export const TurnOutcomeSchema: z.ZodType<TurnOutcome, unknown> = z
+	.object({
+		verdict,
+		basis: z.enum(['calls', 'workspace']),
+		changes: z
+			.object({
+				total: count,
+				// One more than the bound: a clipped path ends in an ellipsis.
+				paths: z.array(z.string().max(OUTCOME_MAX_PATH_CHARS + 1)).max(OUTCOME_MAX_PATHS),
+				outsideKnownTools: z.boolean(),
+			})
+			.strict(),
+		checks: z
+			.array(
+				z
+					.object({
+						command: z.string().max(OUTCOME_MAX_COMMAND_CHARS + 1),
+						step: count,
+						result: z.enum(['passed', 'failed', 'masked', 'unsettled']),
+						exitCode: z.number().int().safe().optional(),
+						fresh: z.boolean().optional(),
+					})
+					.strict(),
+			)
+			.max(OUTCOME_MAX_CHECKS),
+		checksTotal: count.optional(),
+	})
+	.strict()

package/src/types/session/prepare-step.ts

@@ -285,6 +285,8 @@ export interface RecalledMemory {
 	 * Absent when no selector ran; the words of the request chose it.
 	 */
 	readonly reason?: string
+	/** Set when the host's check found the record may no longer hold, e.g. `may be out of date: a file it names is gone`. */
+	readonly caution?: string
 }
 
 /**