@namzu/sdk 34.2.0 → 35.0.0

package/src/runtime/jobs/registry.ts

@@ -57,11 +57,25 @@ export interface BackgroundJobOutput {
 	readonly exitCode?: number
 }
 
+/** A job's process, when something other than the registry starts it. */
+export interface JobProcess {
+	readonly child: ReturnType<typeof spawn>
+	/** How to stop it, when the registry's process-group kill would not reach everything. */
+	kill?(signal: NodeJS.Signals): void
+}
+
 export interface StartJobParams {
 	readonly owner: string
 	readonly command: string
 	readonly workingDirectory: string
 	readonly env?: Readonly<Record<string, string>>
+	/**
+	 * Start the process yourself — a sandbox does, so the job runs inside
+	 * its boundary. Absent, the registry runs `/bin/sh -c command` on the
+	 * host. The process must be the leader of its own group and must not
+	 * expect stdin.
+	 */
+	readonly spawn?: () => JobProcess
 }
 
 export interface BackgroundJobRegistryConfig {
@@ -106,6 +120,8 @@ export class UnknownBackgroundJobError extends Error {
 interface JobEntry {
 	record: BackgroundJob
 	child: ReturnType<typeof spawn>
+	/** The spawner's own kill, when it gave one. */
+	killProcess?: (signal: NodeJS.Signals) => void
 	/** Retained tail. */
 	buffer: string
 	/** Bytes produced in total, including the ones the cap dropped. */
@@ -113,9 +129,46 @@ interface JobEntry {
 	exit: Promise<void>
 }
 
+/** Whether any process of the group led by `pid` is still alive. */
+function groupAlive(pid: number | undefined): boolean {
+	if (pid === undefined || process.platform === 'win32') return false
+	try {
+		process.kill(-pid, 0)
+		return true
+	} catch {
+		return false
+	}
+}
+
+const GROUP_POLL_MS = 250
+
 export class BackgroundJobRegistry {
 	private readonly jobs = new Map<string, JobEntry>()
 	private counter = 0
+	private readonly exitListeners = new Set<(job: BackgroundJob) => void>()
+
+	/**
+	 * Be told when a job ends, whoever owns it. A job outlives the call that
+	 * started it, so the one thing the model could not do was learn that it
+	 * had finished without polling; a run subscribes here and turns the exit
+	 * into a notice on its next tool result. Returns the unsubscribe.
+	 */
+	onExit(listener: (job: BackgroundJob) => void): () => void {
+		this.exitListeners.add(listener)
+		return () => {
+			this.exitListeners.delete(listener)
+		}
+	}
+
+	private announceExit(job: BackgroundJob): void {
+		for (const listener of this.exitListeners) {
+			try {
+				listener(job)
+			} catch {
+				// A listener that throws is its owner's problem, not the job's.
+			}
+		}
+	}
 
 	constructor(private readonly config: BackgroundJobRegistryConfig = {}) {}
 
@@ -151,15 +204,20 @@ export class BackgroundJobRegistry {
 		// started it, which makes the leak longer-lived, not smaller.
 		const inherited = scrubInheritedEnv()
 
-		const child = spawn('/bin/sh', ['-c', params.command], {
-			cwd: params.workingDirectory,
-			env: { ...inherited.env, ...params.env },
-			// Leader of its own process group, which is what `killTree` needs
-			// to reach the command and everything it forks rather than only the
-			// wrapping shell. See `process/kill-tree.ts`.
-			detached: process.platform !== 'win32',
-			stdio: ['ignore', 'pipe', 'pipe'],
-		})
+		const started = params.spawn
+			? params.spawn()
+			: {
+					child: spawn('/bin/sh', ['-c', params.command], {
+						cwd: params.workingDirectory,
+						env: { ...inherited.env, ...params.env },
+						// Leader of its own process group, which is what `killTree` needs
+						// to reach the command and everything it forks rather than only the
+						// wrapping shell. See `process/kill-tree.ts`.
+						detached: process.platform !== 'win32',
+						stdio: ['ignore', 'pipe', 'pipe'],
+					}),
+				}
+		const child = started.child
 		// Started, not adopted: this process stays the parent for the job's
 		// whole life. `unref` would let Node exit with the job still running,
 		// which is the orphan this registry exists to prevent.
@@ -175,10 +233,11 @@ export class BackgroundJobRegistry {
 				startedAt: Date.now(),
 			},
 			child,
+			...(started.kill ? { killProcess: started.kill.bind(started) } : {}),
 			buffer: '',
 			produced: 0,
 			exit: new Promise<void>((resolve) => {
-				child.once('close', (code, signal) => {
+				const finalize = (code: number | null, signal: NodeJS.Signals | null): void => {
 					entry.record = {
 						...entry.record,
 						// A job killed by this registry says `killed`, not
@@ -190,10 +249,33 @@ export class BackgroundJobRegistry {
 						...(signal ? { signal } : {}),
 					}
 					resolve()
+					this.announceExit(entry.record)
+				}
+				child.once('close', (code, signal) => {
+					// The job is the process GROUP, not the shell. A command that
+					// backgrounds its real work (`server &`) exits the shell at
+					// once and leaves the server as the group's survivor; calling
+					// that "exited" told the model the job was over while the
+					// port was still held, and nothing stopped the survivor at
+					// session end because the job was no longer running. So a
+					// job whose shell has ended stays running while its group is
+					// alive, and ends — with the shell's exit code — when the
+					// group is empty.
+					if (entry.record.status !== 'killed' && groupAlive(child.pid)) {
+						const poll = setInterval(() => {
+							if (groupAlive(child.pid)) return
+							clearInterval(poll)
+							finalize(code, signal)
+						}, GROUP_POLL_MS)
+						poll.unref()
+						return
+					}
+					finalize(code, signal)
 				})
 				child.once('error', () => {
 					entry.record = { ...entry.record, status: 'exited', exitedAt: Date.now() }
 					resolve()
+					this.announceExit(entry.record)
 				})
 			}),
 		}
@@ -266,8 +348,10 @@ export class BackgroundJobRegistry {
 		// tell a kill from an ordinary exit. Set it after and the race decides
 		// which of two different answers a reader gets.
 		entry.record = { ...entry.record, status: 'killed' }
-		killTree(entry.child, 'SIGTERM')
-		const grace = setTimeout(() => killTree(entry.child, 'SIGKILL'), SANDBOX_KILL_GRACE_MS)
+		const signal = (sig: NodeJS.Signals) =>
+			entry.killProcess ? entry.killProcess(sig) : killTree(entry.child, sig)
+		signal('SIGTERM')
+		const grace = setTimeout(() => signal('SIGKILL'), SANDBOX_KILL_GRACE_MS)
 		// Unreffed: a job that exits on SIGTERM must not hold the process open
 		// for the remaining grace period doing nothing.
 		grace.unref?.()
@@ -317,7 +401,16 @@ export class BackgroundJobRegistry {
 export function bindOwner(
 	registry: BackgroundJobRegistry,
 	owner: string,
-	defaults: { readonly workingDirectory?: string; readonly env?: Record<string, string> } = {},
+	defaults: {
+		readonly workingDirectory?: string
+		readonly env?: Record<string, string>
+		/** See `StartJobParams.spawn`; given the resolved command, directory and env. */
+		readonly spawn?: (params: {
+			readonly command: string
+			readonly workingDirectory: string
+			readonly env?: Record<string, string>
+		}) => JobProcess
+	} = {},
 ) {
 	const mine = (id: string): BackgroundJob => {
 		const job = registry.get(id)
@@ -325,13 +418,26 @@ export function bindOwner(
 		return job
 	}
 	return {
-		start: (params: { command: string; workingDirectory?: string }) =>
-			registry.start({
+		start: (params: { command: string; workingDirectory?: string }) => {
+			const workingDirectory = params.workingDirectory ?? defaults.workingDirectory ?? process.cwd()
+			const spawnHost = defaults.spawn
+			return registry.start({
 				owner,
 				command: params.command,
-				workingDirectory: params.workingDirectory ?? defaults.workingDirectory ?? process.cwd(),
+				workingDirectory,
 				...(defaults.env ? { env: defaults.env } : {}),
-			}),
+				...(spawnHost
+					? {
+							spawn: () =>
+								spawnHost({
+									command: params.command,
+									workingDirectory,
+									...(defaults.env ? { env: defaults.env } : {}),
+								}),
+						}
+					: {}),
+			})
+		},
 		get: (id: string) => mine(id),
 		read: (id: string, opts?: { fromOffset?: number }) => {
 			mine(id)

package/src/runtime/query/checkpoint.ts

@@ -20,7 +20,7 @@ import type { EmergencySaveData } from '../../types/run/emergency.js'
 import type { CheckpointListEntry } from '../../types/run/replay.js'
 import { ZERO_COST } from '../../utils/cost.js'
 import { buildToolResultHashes } from '../../utils/hash.js'
-import { asCheckpointId, generateCheckpointId } from '../../utils/id.js'
+import { asCheckpointId, asEmergencySaveId, generateCheckpointId } from '../../utils/id.js'
 
 /**
  * Projection from a full checkpoint payload to the public listing entry.
@@ -72,9 +72,11 @@ export function toCheckpointListEntry(cp: IterationCheckpoint): CheckpointListEn
  * See ses_005-deterministic-replay design §2 + §5.2.
  */
 export function projectEmergencyToCheckpoint(dump: EmergencySaveData): IterationCheckpoint {
-	const emergencySuffix = dump.id.replace(/^esave_/, '')
+	const emergencyId = asEmergencySaveId(dump.id)
+	// The checkpoint is another view of the same snapshot and retains its key.
+	const checkpointId = asCheckpointId(emergencyId)
 	return {
-		id: asCheckpointId(`cp_emergency_${emergencySuffix}`),
+		id: checkpointId,
 		runId: dump.runId,
 		// The dump records the run's start, so this projection carries the
 		// same stamp an ordinary checkpoint of that run would — a run whose
@@ -85,6 +87,8 @@ export function projectEmergencyToCheckpoint(dump: EmergencySaveData): Iteration
 		iteration: dump.currentIteration,
 		messages: dump.messages,
 		tokenUsage: dump.tokenUsage,
+		budgetBinding: dump.budgetBinding,
+		budgetAccountId: dump.budgetAccountId,
 		costInfo: { ...ZERO_COST, unpricedTokens: dump.tokenUsage.totalTokens },
 		guardState: {
 			iterationCount: dump.currentIteration,
@@ -264,6 +268,8 @@ export class CheckpointManager {
 			iteration,
 			messages: [...runMgr.messages],
 			tokenUsage: { ...runMgr.tokenUsage },
+			budgetBinding: runMgr.budget?.binding,
+			budgetAccountId: runMgr.budget?.accountId,
 			costInfo: { ...runMgr.costInfo },
 			guardState: {
 				iterationCount: runMgr.currentIteration,
@@ -275,6 +281,7 @@ export class CheckpointManager {
 			traceContext: this.traceSource?.(),
 		}
 
+		await runMgr.budget?.flush()
 		await this.store.writeCheckpoint(this.scope, checkpoint, this.claimFence)
 		this.lastCreatedId = checkpoint.id
 		return checkpoint

package/src/runtime/query/context.ts

@@ -2,12 +2,7 @@ import { join } from 'node:path'
 import { GENAI, NAMZU } from '../../constants/telemetry/index.js'
 import { PlanManager } from '../../manager/plan/lifecycle.js'
 import { RunPersistence } from '../../manager/run/persistence.js'
-import {
-	DefaultFilesystemMigrator,
-	type FilesystemMigrationResult,
-	type FilesystemMigrator,
-	NOOP_FILESYSTEM_MIGRATION_SINK,
-} from '../../session/migration/index.js'
+import type { TokenBudget } from '../../run/token-budget.js'
 import { DefaultPathBuilder, type PathBuilder } from '../../session/workspace/path-builder.js'
 import { ActivityStore } from '../../store/activity/memory.js'
 import { type ActivityTrackingConfig, resolveActivityTracking } from '../../types/activity/index.js'
@@ -33,20 +28,9 @@ import { type Logger, resolveLogger } from '../../utils/logger.js'
  * `pathBuilder` is optional; when absent a {@link DefaultPathBuilder} is
  * constructed against `{workingDirectory}/.namzu`.
  *
- * `filesystemMigrator` is optional, but note what `build` actually does
- * with it: nothing. Migration is not part of `build` — it runs once per
- * process via {@link RunContextFactory.ensureMigrated}, kept out of `build`
- * entirely so the static method stays synchronous for existing callers;
- * `query()` calls `ensureMigrated` itself, with its own migrator, before it
- * ever calls `build`. This field predates that split, and no code path
- * threads it to `ensureMigrated` on `build`'s behalf. Its sibling
- * `migrationSink` had the identical shape — declared, never read anywhere
- * in the workspace — and NZ-BOOT-04 removed it
- * (`docs/conventions/declared-but-undriven.md`) rather than invent a caller
- * for a field nothing needed; `filesystemMigrator` is the same defect, left
- * for a follow-up rather than folded into that change.
  */
 export interface RunContextConfig {
+	budget?: TokenBudget
 	/**
 	 * The mode this conversation was left in, when the run config names none.
 	 *
@@ -93,13 +77,6 @@ export interface RunContextConfig {
 	checkpointStore?: CheckpointStore
 	runStore?: RunStore
 
-	/**
-	 * Optional injected migrator — tests pass a stub; production code relies
-	 * on the {@link DefaultFilesystemMigrator}. See session-hierarchy.md
-	 * §13.4.1.
-	 */
-	filesystemMigrator?: FilesystemMigrator
-
 	runId?: RunId
 
 	parentRunId?: RunId
@@ -138,39 +115,7 @@ export interface RunContext {
 	trackingConfig: ActivityTrackingConfig
 }
 
-/**
- * Module-level first-call guard for the boot-time filesystem migration
- * (session-hierarchy.md §13.4.1). Keyed on the root directory so a single
- * process that spans multiple `.namzu` roots (unusual but legal) migrates
- * each one once. Subsequent calls short-circuit via the cached promise —
- * never re-reading the on-disk marker per call.
- */
-const migrationPromises = new Map<string, Promise<FilesystemMigrationResult>>()
-
 export class RunContextFactory {
-	/**
-	 * Run the boot-time filesystem migration for `rootDir` at most once per
-	 * process. Safe to `await` from any async entry point; concurrent callers
-	 * for the same root share a single migration promise (no duplicate work,
-	 * no race with the on-disk `.tmp` lock).
-	 */
-	static ensureMigrated(
-		rootDir: string,
-		migrator: FilesystemMigrator = new DefaultFilesystemMigrator(NOOP_FILESYSTEM_MIGRATION_SINK),
-	): Promise<FilesystemMigrationResult> {
-		const cached = migrationPromises.get(rootDir)
-		if (cached) return cached
-		const promise = migrator.migrate(rootDir)
-		migrationPromises.set(rootDir, promise)
-		// Crash-safety: if the migration rejects, drop the cached promise so
-		// the next caller gets a fresh attempt. Successful results stay cached
-		// (idempotency — further calls short-circuit without re-running).
-		promise.catch(() => {
-			migrationPromises.delete(rootDir)
-		})
-		return promise
-	}
-
 	/**
 	 * The run's one correlated logger, built once and handed to every
 	 * consumer that used to construct its own. Split out of `build` because
@@ -271,6 +216,7 @@ export class RunContextFactory {
 
 		const runMgr = new RunPersistence({
 			runId,
+			budget: config.budget,
 			agentId: config.agentId,
 			agentName: config.agentName,
 			runConfig: config.runConfig,

package/src/runtime/query/executor.ts

@@ -1,3 +1,4 @@
+import { join } from 'node:path'
 import type { Span } from '@opentelemetry/api'
 import type { AuthorizationGate } from '../../authorization/gate.js'
 import { extractFromToolCall, extractFromToolResult } from '../../compaction/extractor.js'
@@ -47,10 +48,11 @@ import { toErrorMessage } from '../../utils/error.js'
 import { generateToolCallId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
 import { compressShellOutput } from '../../utils/shell-compress.js'
-import { type BackgroundJobRegistry, bindOwner } from '../jobs/registry.js'
+import { type BackgroundJobRegistry, type JobProcess, bindOwner } from '../jobs/registry.js'
 import type { ToolResultObservation } from './project-instructions.js'
 import {
 	DEFAULT_MAX_TOOL_OUTPUT_CHARS,
+	type ToolOutputBudgetResult,
 	applyToolOutputBudget,
 	describeDroppedContent,
 	measureContentBytes,
@@ -290,6 +292,8 @@ export interface ToolExecutorConfig {
 	tools: ToolRegistryContract
 	runId: RunId
 	workingDirectory: string
+	/** See `ToolContext.additionalDirectories`. */
+	additionalDirectories?: readonly string[]
 	/**
 	 * Read LIVE, not frozen at run start.
 	 *
@@ -319,6 +323,13 @@ export interface ToolExecutorConfig {
 	 * that fallback is a lie rather than a lesser version.
 	 */
 	backgroundJobs?: BackgroundJobRegistry
+	/**
+	 * Which owner the run's jobs are bound to. The run id by default, which
+	 * scopes them to the run; a host that wants jobs to outlive a turn (a
+	 * dev server started in one, read in the next) binds them to its
+	 * session and stops them itself when the session ends.
+	 */
+	backgroundJobOwner?: string
 
 	/**
 	 * Where the `skill` tool reads from.
@@ -1175,6 +1186,9 @@ export class ToolExecutor {
 		const context: ToolContext = {
 			runId: this.config.runId,
 			workingDirectory: this.config.workingDirectory,
+			...(this.config.additionalDirectories?.length
+				? { additionalDirectories: this.config.additionalDirectories }
+				: {}),
 			abortSignal: this.config.abortSignal,
 			env: this.config.env,
 			log: (level, message) => this.log[level](message),
@@ -1219,12 +1233,38 @@ export class ToolExecutor {
 			// that its foreground work would use. A sandbox-aware persistent
 			// process capability needs its own execution seam; until one exists,
 			// the safe composition is to withhold this host capability entirely.
-			...(this.config.backgroundJobs && !this.config.sandbox
+			//
+			// That seam now exists: a sandbox that can `spawnDetached` starts
+			// the job inside its boundary, and the registry only keeps it. A
+			// sandbox without it still withholds the capability.
+			...(this.config.backgroundJobs &&
+			(!this.config.sandbox || this.config.sandbox.spawnDetached !== undefined)
 				? {
-						backgroundJobs: bindOwner(this.config.backgroundJobs, this.config.runId, {
-							workingDirectory: this.config.workingDirectory,
-							env: this.config.env,
-						}),
+						backgroundJobs: bindOwner(
+							this.config.backgroundJobs,
+							this.config.backgroundJobOwner ?? this.config.runId,
+							{
+								workingDirectory: this.config.workingDirectory,
+								env: this.config.env,
+								...(this.config.sandbox?.spawnDetached
+									? {
+											spawn: (job: {
+												readonly command: string
+												readonly workingDirectory: string
+												readonly env?: Record<string, string>
+											}): JobProcess =>
+												(this.config.sandbox as Sandbox).spawnDetached?.(
+													'/bin/sh',
+													['-c', job.command],
+													{
+														cwd: job.workingDirectory,
+														...(job.env ? { env: job.env } : {}),
+													},
+												) as JobProcess,
+										}
+									: {}),
+							},
+						),
 					}
 				: {}),
 			...(this.parentSpan ? { parentSpan: this.parentSpan } : {}),
@@ -1510,23 +1550,23 @@ export class ToolExecutor {
 		const postOverride = post.override
 		let output =
 			postOverride?.output ?? (result.success ? this.maybeCompress(toolName, rawOutput) : rawOutput)
-		const selectedContent = postOverride?.isError
+		let selectedContent = postOverride?.isError
 			? undefined
 			: (postOverride?.content ?? result.content)
-		const maxToolOutputChars = this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS
-
-		// If the text preview forces rich content out, say so inside the SAME
-		// budget. Appending this after truncation made the diagnostic itself a
-		// cap bypass; selecting a post-hook override after truncation was a
-		// larger bypass that could replace a bounded result with anything.
-		if (
-			maxToolOutputChars > 0 &&
-			output.length > maxToolOutputChars &&
-			selectedContent !== undefined
-		) {
-			const dropped = describeDroppedContent(selectedContent)
-			if (dropped) output = `${output}\n\n${dropped}`
+		if (postOverride && !postOverride.isError && postOverride.content === undefined) {
+			// A text redaction must reach both text channels. Only the image or
+			// document blocks survive implicitly; explicit replacement content
+			// remains the hook's complete model-visible decision.
+			if (typeof selectedContent === 'string') selectedContent = postOverride.output
+			else if (selectedContent) {
+				selectedContent = [
+					{ type: 'text', text: postOverride.output },
+					...selectedContent.filter((block) => block.type !== 'text'),
+				]
+			}
 		}
+		const maxToolOutputChars = this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS
+		const sourceOutput = output
 
 		// Compression is opportunistic and shell-only; the budget is the
 		// hard bound that applies to every final tool result, including a
@@ -1553,6 +1593,10 @@ export class ToolExecutor {
 			})
 		}
 		output = budgeted.output
+		const modelContent =
+			selectedContent === undefined
+				? undefined
+				: this.budgetContent(selectedContent, toolName, toolCall.id, { sourceOutput, budgeted })
 
 		// A failed call, or an override that says the call failed. A `replace`
 		// says the opposite, and reading it as a failure is what made redaction
@@ -1562,6 +1606,9 @@ export class ToolExecutor {
 
 		if (this.workingStateManager) {
 			extractFromToolResult(this.workingStateManager, toolName, output, effectiveIsError)
+			for (const pin of result.workingState ?? []) {
+				this.workingStateManager.pin(pin.key, pin.text, toolName)
+			}
 		}
 
 		if (result.success) {
@@ -1615,11 +1662,6 @@ export class ToolExecutor {
 			result,
 		})
 
-		const resolveContent = (): { content?: ToolResultContent } => {
-			if (budgeted.truncated || selectedContent === undefined) return {}
-			return { content: this.budgetContent(selectedContent, toolName) }
-		}
-
 		return {
 			toolCallId: toolCall.id,
 			toolName,
@@ -1629,13 +1671,12 @@ export class ToolExecutor {
 			//
 			// An ERROR override drops it: the payload is no longer the tool's,
 			// and shipping an image beside a failure message describes something
-			// the model was just told did not happen. A spilled preview drops it
-			// for the same reason.
+			// the model was just told did not happen.
 			//
 			// A REPLACE keeps it, because the common case is redacting text from
 			// a result whose image is unaffected — and a hook that needs it gone
 			// says so with `content`, which wins over both.
-			...resolveContent(),
+			...(modelContent !== undefined ? { content: modelContent } : {}),
 		}
 	}
 
@@ -2108,6 +2149,7 @@ export class ToolExecutor {
 						output: `Error: ${result.message}`,
 					}
 				case 'retry':
+				case 'annotate':
 				// There is no result to replace yet. Rejecting loudly beats
 				// silently ignoring it: a hook author who returned this here
 				// meant to redact something and would otherwise watch the secret
@@ -2368,6 +2410,7 @@ export class ToolExecutor {
 					continue
 				case 'skip':
 				case 'modify':
+				case 'annotate':
 					throw new Error(
 						`Plugin hook post_tool_use returned unsupported action '${result.action}' for tool ${toolName}`,
 					)
@@ -2493,42 +2536,69 @@ export class ToolExecutor {
 	}
 
 	/**
-	 * Bound the rich channel, or leave it alone when no cap is configured.
-	 *
-	 * Refused whole rather than trimmed: half a base64 payload is not a
-	 * smaller image, it is a corrupt one, and a driver handed it would
-	 * either fail the request or show the model noise. The text half stays
-	 * untouched, so the result still says what happened — and the
-	 * replacement names what was withheld and how big it was, which is what
-	 * lets the agent ask for a smaller region instead of retrying the same
-	 * call.
+	 * The host preview and model text may differ; each gets its own text
+	 * budget. Rich bytes are measured separately and withheld whole when
+	 * over their cap, with a notice inside the model text's same hard bound.
 	 */
 	private budgetContent(
-		content: import('../../types/message/index.js').ToolResultContent,
+		content: ToolResultContent,
 		toolName: string,
-	): import('../../types/message/index.js').ToolResultContent {
+		toolUseId: string,
+		host: { sourceOutput: string; budgeted: ToolOutputBudgetResult },
+	): ToolResultContent {
 		const cap = this.config.maxToolContentBytes ?? 0
-		if (cap <= 0) return content
-
 		const size = measureContentBytes(content)
-		if (size <= cap) return content
-
-		this.log.warn('Tool result content exceeded the rich-content budget', {
-			[NAMZU.RUN_ID]: this.config.runId,
-			[GENAI.TOOL_NAME]: toolName,
-			'namzu.runtime.content_bytes': size,
-			'namzu.runtime.cap': cap,
-		})
-
-		const described = describeDroppedContent(content)
+		const richWithheld = cap > 0 && size > cap
+		const text =
+			typeof content === 'string'
+				? content
+				: content.flatMap((block) => (block.type === 'text' ? [block.text] : [])).join('\n')
+		const notice = richWithheld
+			? `[rich content withheld: ${size} base64 chars exceeds this run's ${cap} cap] ${describeDroppedContent(content) ?? ''}`
+			: undefined
+		if (richWithheld) {
+			this.log.warn('Tool result content exceeded the rich-content budget', {
+				[NAMZU.RUN_ID]: this.config.runId,
+				[GENAI.TOOL_NAME]: toolName,
+				'namzu.runtime.content_bytes': size,
+				'namzu.runtime.cap': cap,
+			})
+		}
+		const budgeted =
+			text === host.sourceOutput && !notice
+				? host.budgeted
+				: applyToolOutputBudget({
+						toolName,
+						toolUseId,
+						output: text,
+						maxChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
+						...(notice ? { notice } : {}),
+						// A tool may return different host and model text. They must
+						// never compete for the same exclusive spill filename.
+						spillDir: this.config.toolOutputDir
+							? join(this.config.toolOutputDir, 'content')
+							: undefined,
+						onError: (message) =>
+							this.log.warn('Failed to spill oversized model tool content', {
+								[NAMZU.RUN_ID]: this.config.runId,
+								[GENAI.TOOL_NAME]: toolName,
+								'exception.message': message,
+							}),
+					})
+		if (budgeted.truncated && budgeted !== host.budgeted) {
+			this.log.warn('Model tool text exceeded the model-visible budget', {
+				[NAMZU.RUN_ID]: this.config.runId,
+				[GENAI.TOOL_NAME]: toolName,
+				'namzu.runtime.original_length': budgeted.originalLength,
+				'namzu.runtime.spill_path': budgeted.spillPath,
+			})
+		}
+		if (!budgeted.truncated && !richWithheld) return content
+		if (typeof content === 'string') return budgeted.output
 		return [
-			{
-				type: 'text',
-				text: `[rich content withheld: ${size} base64 chars exceeds this run's ${cap} cap${
-					described ? ` — ${described}` : ''
-				}]`,
-			},
-		] as import('../../types/message/index.js').ToolResultContent
+			...(budgeted.output ? [{ type: 'text' as const, text: budgeted.output }] : []),
+			...(richWithheld ? [] : content.filter((block) => block.type !== 'text')),
+		]
 	}
 
 	private maybeCompress(toolName: string, output: string): string {

package/src/runtime/query/guard.ts

@@ -110,6 +110,14 @@ export class GuardCoordinator {
 		}
 
 		const limitResult = checkLimitsDetailed(this.limitConfig, limitState)
+		if (!abortSignal.aborted && runMgr.budget && runMgr.budget.remaining <= 0) {
+			return {
+				shouldStop: true,
+				forceFinalize: false,
+				stopReason: 'token_budget',
+				isCancelled: false,
+			}
+		}
 
 		if (limitResult.type === 'hard_stop') {
 			return {