@namzu/sdk 62.6.1 → 62.8.0

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'
 

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'