@namzu/sdk 32.0.0 → 33.0.0

package/src/runtime/query/index.ts

@@ -25,6 +25,7 @@ import { EmergencySaveManager } from '../../manager/run/emergency.js'
 import type { RunPersistence } from '../../manager/run/persistence.js'
 import { resolveModelPricing } from '../../pricing/index.js'
 import { resolveProviderCapabilities } from '../../provider/capabilities.js'
+import { isCallerAbortError } from '../../provider/errors.js'
 import {
 	type ProviderChainMember,
 	type ServingMember,
@@ -77,6 +78,7 @@ import type { AgentPersona } from '../../types/persona/index.js'
 import type { LLMProvider } from '../../types/provider/index.js'
 import type { TaskRouterConfig } from '../../types/router/index.js'
 import type { ReviewAnswer } from '../../types/run/answer-review.js'
+import { cancelCauseOf } from '../../types/run/cancel-cause.js'
 import type { CheckpointStore, FencingToken } from '../../types/run/checkpoint-store.js'
 import type { RunEventCursor, RunEventReplay } from '../../types/run/event-cursor.js'
 import { resolveRunEventReplay } from '../../types/run/event-cursor.js'
@@ -1367,6 +1369,40 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	eventTranslator.wireActivityStore(ctx.activityStore, ctx.runId)
 	eventTranslator.wirePlanManager(ctx.planManager, ctx.runId)
 	eventTranslator.setGeneration(params.claimFence)
+	let interruptHooksStarted = false
+	const executeUserInterruptHooks = async (terminalError: unknown): Promise<void> => {
+		if (
+			interruptHooksStarted ||
+			!params.pluginManager ||
+			!isCallerAbortError(terminalError, ctx.abortController.signal) ||
+			params.parentRunId !== undefined ||
+			(params.depth ?? 0) !== 0 ||
+			cancelCauseOf(ctx.abortController.signal.reason) !== 'user'
+		) {
+			return
+		}
+
+		interruptHooksStarted = true
+		try {
+			// Deliberately omit the already-aborted run signal. The lifecycle
+			// manager still supplies each handler its own deadline signal, while
+			// `run_interrupt`'s observational fan-out prevents one result from
+			// suppressing the cleanup hooks that follow it.
+			await params.pluginManager.executeHooks(
+				'run_interrupt',
+				{ runId: ctx.runId, cancelCause: 'user' },
+				eventTranslator.emitEvent,
+			)
+		} catch (error) {
+			// Cancellation is the terminal authority. A hook event sink or an
+			// unexpected manager failure is reported, but cannot turn Stop into a
+			// failed run or prevent the durable cancellation verdict.
+			ctx.log.error('Run interrupt hooks did not settle cleanly', {
+				[NAMZU.RUN_ID]: ctx.runId,
+				...errorAttributes(error),
+			})
+		}
+	}
 
 	if (attachmentResolutionCancelled) {
 		// Attachment materialization happens before RunContext exists. Once it
@@ -1375,6 +1411,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		// and settle through the ordinary cancellation classifier. Prompt
 		// contributions/cache, host callbacks, tools, plugins, sandbox, guardrails,
 		// advisors, and providers are all authority-bearing work and stay out.
+		// The dedicated root interrupt notification is the sole plugin exception:
+		// it runs after cancellation under its own deadline and cannot regain model
+		// or tool authority.
 		if (params.resumeFromCheckpoint && !selectedResumeState) {
 			// The canonical resume surface hands query the checkpoint state it
 			// already selected. A raw resume query has no such snapshot; after
@@ -1460,6 +1499,8 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			const terminalError = ctx.abortController.signal.aborted
 				? ctx.abortController.signal.reason
 				: error
+			await executeUserInterruptHooks(terminalError)
+			yield* eventTranslator.drainPending()
 			yield* cancelledAssembler.handleError(terminalError, rootSpan)
 		} finally {
 			rootSpan.end()
@@ -1620,6 +1661,14 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	const questionParks = params.questionParks ?? new QuestionParkBinding()
 	const pendingAnswers = params.pendingAnswers ?? new PendingAnswers()
 
+	// One gate instance owns both model-issued calls and calls dispatched by
+	// another tool. Constructing it only inside the iteration review left the
+	// nested registry path outside the operator's policy entirely.
+	const gateConfig = params.authorizationGate
+	const verificationGate = gateConfig?.enabled
+		? new AuthorizationGate(gateConfig, ctx.log)
+		: undefined
+
 	//  is null only when the run has no disk layout (tests,
 	// in-memory hosts); the budget then degrades to middle-elision.
 	const runDirForTools = ctx.runMgr.getRunDir()
@@ -1660,6 +1709,8 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			// `read`/`grep` without a new affordance.
 			...(toolOutputDir ? { toolOutputDir } : {}),
 			...(params.repairToolCall ? { repairToolCall: params.repairToolCall } : {}),
+			...(verificationGate ? { authorizationGate: verificationGate } : {}),
+			recordAudit: (input) => ctx.runMgr.recordAudit(input),
 			// The durable pause, reachable from any tool rather than from the
 			// four kernel-owned points that used to own it. Built here from
 			// the machinery the run already holds; the recorder binds a few
@@ -1806,12 +1857,6 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		}
 	}
 
-	const gateConfig = params.authorizationGate
-
-	const verificationGate = gateConfig?.enabled
-		? new AuthorizationGate(gateConfig, ctx.log)
-		: undefined
-
 	const iterationOrchestrator = new IterationOrchestrator({
 		provider: resilientProvider,
 		servingMember: () => serving.current,
@@ -2581,6 +2626,8 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		} catch (err) {
 			// A failed run still spent its steps; report them.
 			ctx.runMgr.setSteps(iterationOrchestrator.getSteps())
+			await executeUserInterruptHooks(err)
+			yield* eventTranslator.drainPending()
 			yield* resultAssembler.handleError(err, rootSpan)
 		} finally {
 			// Release the process's termination path as soon as this run is

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -1,7 +1,8 @@
 import type { AuthorizationGate } from '../../../../authorization/index.js'
+import type { ToolCallSummary } from '../../../../types/hitl/index.js'
 import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
 import type { RunEvent } from '../../../../types/run/index.js'
-import type { ToolCallDenials } from '../../executor.js'
+import type { PreparedToolBatch, ToolCallDenials } from '../../executor.js'
 import {
 	awaitProjectInstructionCallback,
 	replaceProjectInstructionSnapshot,
@@ -64,28 +65,42 @@ export async function* runToolReview(
 		return finish('executed')
 	}
 
-	const toolCallSummaries = toolCalls.map((tc) => {
-		let input: unknown
-		try {
-			input = JSON.parse(tc.function.arguments)
-		} catch {
-			input = tc.function.arguments
-		}
-		const tool = ctx.tools.get(tc.function.name)
-		const isDestructive = tool?.isDestructive ? tool.isDestructive(input) : false
-
-		return {
-			id: tc.id,
-			name: tc.function.name,
-			input,
-			isDestructive,
-		}
-	})
+	const prepareForReview = async (): Promise<PreparedToolBatch | undefined> => {
+		const prepare = ctx.toolExecutor.prepareBatchForReview
+		return typeof prepare === 'function' ? prepare.call(ctx.toolExecutor, response) : undefined
+	}
+	let preparedBatch = await prepareForReview()
+	const summariesFor = (prepared: PreparedToolBatch | undefined): ToolCallSummary[] => {
+		const calls =
+			prepared?.reviewCalls ??
+			toolCalls.map((tc) => {
+				let input: unknown
+				try {
+					input = JSON.parse(tc.function.arguments)
+				} catch {
+					input = tc.function.arguments
+				}
+				return { id: tc.id, name: tc.function.name, input }
+			})
+		return calls.map((tc) => {
+			const tool = ctx.tools.get(tc.name)
+			const isDestructive = tool?.isDestructive ? tool.isDestructive(tc.input) : false
+
+			return {
+				id: tc.id,
+				name: tc.name,
+				input: tc.input,
+				isDestructive,
+				authorization: { decision: 'review' },
+			}
+		})
+	}
+	let toolCallSummaries = summariesFor(preparedBatch)
 
 	/** Executes the batch, answering every call, and appends the results. */
 	const settle = async (denials?: ToolCallDenials): Promise<void> => {
 		const startedAt = Date.now()
-		const batch = await ctx.toolExecutor.executeBatch(response, denials)
+		const batch = await ctx.toolExecutor.executeBatch(response, denials, undefined, preparedBatch)
 		toolMs += Date.now() - startedAt
 		executed = batch.results
 		// Recorded AFTER execution and never before it: this advises, it does
@@ -130,6 +145,12 @@ export async function* runToolReview(
 		}
 	}
 
+	if (toolCallSummaries.length === 0) {
+		await settle()
+		yield* ctx.drainPending()
+		return finish('executed')
+	}
+
 	/** Every call denied for the same reason (human rejection, gate stop). */
 	const denyAll = (reason: string): ToolCallDenials =>
 		new Map(toolCalls.map((tc) => [tc.id, reason]))
@@ -159,10 +180,16 @@ export async function* runToolReview(
 				toolDef: ctx.tools.get(tc.name),
 			}),
 		}))
+		for (const { toolCall, gateResult } of gateResults) {
+			toolCall.authorization = {
+				decision: gateResult.decision,
+				...(gateResult.reason ? { reason: gateResult.reason } : {}),
+			}
+		}
 
 		for (const gr of gateResults) {
 			if (gr.gateResult.decision === 'deny') {
-				const reason = `Blocked by the verification gate: ${gr.gateResult.reason}`
+				const reason = `Blocked by the authorization gate: ${gr.gateResult.reason}`
 				gateDenied.set(gr.toolCall.id, reason)
 				// A gate denial is a refusal — first-class in the audit trail, never
 				// an absent record (LOG-14, design §5). Written here, once per
@@ -180,7 +207,7 @@ export async function* runToolReview(
 		const allDenied = gateResults.every((gr) => gr.gateResult.decision === 'deny')
 
 		if (allAllowed) {
-			ctx.log.debug('Verification gate: all tool calls pre-approved', {
+			ctx.log.debug('Authorization gate: all tool calls pre-approved', {
 				'namzu.tool.names': gateResults.map((gr) => gr.toolCall.name),
 			})
 			await settle()
@@ -189,7 +216,7 @@ export async function* runToolReview(
 		}
 
 		if (allDenied) {
-			ctx.log.debug('Verification gate: all tool calls denied', {
+			ctx.log.debug('Authorization gate: all tool calls denied', {
 				'namzu.tool.names': gateResults.map((gr) => gr.toolCall.name),
 			})
 			await settle(gateDenied)
@@ -197,7 +224,7 @@ export async function* runToolReview(
 			return finish('rejected')
 		}
 
-		ctx.log.debug('Verification gate: mixed decisions, proceeding to review', {
+		ctx.log.debug('Authorization gate: mixed decisions, proceeding to review', {
 			'namzu.runtime.decisions': gateResults.map((gr) => ({
 				tool: gr.toolCall.name,
 				decision: gr.gateResult.decision,
@@ -267,6 +294,7 @@ export async function* runToolReview(
 
 			// Gate denials are the floor; per-call human denials add to them.
 			const denials = new Map(gateDenied)
+			const modifiedCallIds = new Set<string>()
 
 			for (const mod of reviewDecision.modifications) {
 				if (mod.action === 'modify' && mod.modifiedInput !== undefined) {
@@ -274,6 +302,7 @@ export async function* runToolReview(
 					// A modification cannot resurrect a gate-denied call.
 					if (tc && !denials.has(tc.id)) {
 						tc.function.arguments = JSON.stringify(mod.modifiedInput)
+						modifiedCallIds.add(tc.id)
 					}
 				}
 				if (mod.action === 'deny' && !denials.has(mod.toolCallId)) {
@@ -281,6 +310,41 @@ export async function* runToolReview(
 				}
 			}
 
+			// A human modification changes the raw call after the first preparation.
+			// Decode it once again, then require policy to explicitly allow the new
+			// executable value. A second nested review would be ambiguous: the human
+			// edited raw JSON, not an unseen schema transform of it.
+			if (modifiedCallIds.size > 0) {
+				const reprepare = ctx.toolExecutor.reprepareBatchForReview
+				preparedBatch =
+					preparedBatch && typeof reprepare === 'function'
+						? await reprepare.call(ctx.toolExecutor, response, preparedBatch, modifiedCallIds)
+						: await prepareForReview()
+				toolCallSummaries = summariesFor(preparedBatch)
+			}
+			if (ctx.verificationGate && modifiedCallIds.size > 0) {
+				for (const summary of toolCallSummaries) {
+					if (!modifiedCallIds.has(summary.id)) continue
+					if (denials.has(summary.id)) continue
+					const gateResult = ctx.verificationGate.evaluate({
+						toolName: summary.name,
+						toolInput: summary.input,
+						toolDef: ctx.tools.get(summary.name),
+					})
+					if (gateResult.decision === 'allow') continue
+					const reason =
+						gateResult.decision === 'deny'
+							? `Blocked by the authorization gate after the tool input was modified: ${gateResult.reason}`
+							: `Blocked by the authorization gate after the tool input was modified: the prepared value requires a new explicit approval. ${gateResult.reason}`
+					denials.set(summary.id, reason)
+					await ctx.runMgr.recordAudit({
+						what: { action: 'tool_call', tool: summary.name },
+						outcome: 'refused',
+						reason,
+					})
+				}
+			}
+
 			const everythingDenied = denials.size === toolCalls.length
 			await settle(denials)
 			yield* ctx.drainPending()

package/src/runtime/query/request-rich-content.ts

@@ -34,7 +34,7 @@ interface RichOccurrence {
 	readonly source: 'user' | 'tool'
 	readonly kind: RichKind
 	readonly bytes: number
-	readonly reason: 'budget' | 'provider-rejected'
+	readonly reason: 'budget' | 'provider-rejected' | 'invalid-image'
 }
 
 export interface RequestImageIdentity {
@@ -54,6 +54,12 @@ const rejectedUserImageMarker = (): string =>
 const rejectedToolImageMarker = (): string =>
 	'[image omitted from this model request because the provider rejected this image; call the producing tool again after correcting its image source if it is still needed.]'
 
+const invalidUserImageMarker = (): string =>
+	'[image omitted from this model request because its encoded bytes are not a complete supported raster matching the declared media type; attach a corrected image in a new message if it is still needed.]'
+
+const invalidToolImageMarker = (): string =>
+	'[image omitted from this model request because the producing tool returned encoded bytes that are not a complete supported raster matching the declared media type; call the tool again after correcting its image source if it is still needed.]'
+
 function assertInlineAttachment(
 	attachment: MessageAttachment,
 ): asserts attachment is Exclude<MessageAttachment, { readonly type: 'stored' }> {
@@ -78,10 +84,12 @@ function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[]
 					kind: attachment.type === 'document' ? 'document' : 'image',
 					bytes: attachment.data.length,
 					reason:
-						attachment.type !== 'document' &&
-						attachment.modelOmission?.reason === 'provider-rejected'
-							? 'provider-rejected'
-							: 'budget',
+						attachment.type !== 'document' && attachment.modelOmission?.reason === 'invalid-image'
+							? 'invalid-image'
+							: attachment.type !== 'document' &&
+									attachment.modelOmission?.reason === 'provider-rejected'
+								? 'provider-rejected'
+								: 'budget',
 				})
 			}
 			continue
@@ -97,9 +105,11 @@ function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[]
 				kind: block.type,
 				bytes: block.data.length,
 				reason:
-					block.type === 'image' && block.modelOmission?.reason === 'provider-rejected'
-						? 'provider-rejected'
-						: 'budget',
+					block.type === 'image' && block.modelOmission?.reason === 'invalid-image'
+						? 'invalid-image'
+						: block.type === 'image' && block.modelOmission?.reason === 'provider-rejected'
+							? 'provider-rejected'
+							: 'budget',
 			})
 		}
 	}
@@ -117,7 +127,9 @@ function appendMarkers(content: string, occurrences: readonly RichOccurrence[]):
 	const markers = occurrences.map((occurrence) =>
 		occurrence.reason === 'provider-rejected'
 			? rejectedUserImageMarker()
-			: userMarker(occurrence.kind),
+			: occurrence.reason === 'invalid-image'
+				? invalidUserImageMarker()
+				: userMarker(occurrence.kind),
 	)
 	return appendTextMarkers(content, markers)
 }
@@ -146,7 +158,9 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 	}
 
 	for (const occurrence of occurrences) {
-		if (occurrence.reason === 'provider-rejected') omit(occurrence)
+		if (occurrence.reason === 'provider-rejected' || occurrence.reason === 'invalid-image') {
+			omit(occurrence)
+		}
 	}
 
 	let total = occurrences.reduce(
@@ -189,7 +203,9 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 							text:
 								occurrence.reason === 'provider-rejected'
 									? rejectedToolImageMarker()
-									: toolMarker(occurrence.kind),
+									: occurrence.reason === 'invalid-image'
+										? invalidToolImageMarker()
+										: toolMarker(occurrence.kind),
 						}
 					: block
 			})
@@ -220,7 +236,10 @@ export function findSingleRequestImage(messages: readonly Message[]): RequestIma
 				}
 				if (attachment.type === 'document') continue
 				if (candidate === null) {
-					candidate = { data: attachment.data, mediaType: attachment.mediaType }
+					candidate = {
+						data: attachment.data,
+						mediaType: attachment.mediaType,
+					}
 				} else if (!sameImage(attachment, candidate)) {
 					return null
 				}
@@ -302,7 +321,10 @@ export function markProviderRejectedImage(
 				}
 				changed = true
 				count += 1
-				return { ...attachment, modelOmission: { reason: 'provider-rejected' as const } }
+				return {
+					...attachment,
+					modelOmission: { reason: 'provider-rejected' as const },
+				}
 			})
 			return changed ? { ...message, attachments } : message
 		}
@@ -318,7 +340,10 @@ export function markProviderRejectedImage(
 			}
 			changed = true
 			count += 1
-			return { ...block, modelOmission: { reason: 'provider-rejected' as const } }
+			return {
+				...block,
+				modelOmission: { reason: 'provider-rejected' as const },
+			}
 		})
 		return changed ? { ...message, content } : message
 	})

package/src/runtime/query/resume-pending.ts

@@ -1,8 +1,11 @@
+import { isDeepStrictEqual } from 'node:util'
+
 import type { RunPersistence } from '../../manager/run/persistence.js'
 import type {
 	CheckpointId,
 	HITLResumeDecision,
 	IterationCheckpoint,
+	ToolCallSummary,
 } from '../../types/hitl/index.js'
 import type { AssistantMessage, Message, ToolCall } from '../../types/message/index.js'
 import type { ChatCompletionResponse } from '../../types/provider/index.js'
@@ -38,6 +41,10 @@ export interface PendingResumePlan {
 	readonly response: ChatCompletionResponse
 	/** Per-call refusals derived from the decision. */
 	readonly denials: ToolCallDenials
+	/** Exact projections and gate decisions persisted with a tool review. */
+	readonly reviewedCalls?: readonly ToolCallSummary[]
+	/** Calls whose raw input the human replaced in the durable decision. */
+	readonly modifiedCallIds?: ReadonlySet<string>
 	/**
 	 * Answers to deliver to tools that parked on a question, keyed by the
 	 * asking call's id. Present only on a question resume.
@@ -117,6 +124,8 @@ export function planPendingResume(
 		assistant,
 		response: synthesizeResponse(assistant),
 		denials,
+		reviewedCalls: pending.request.toolCalls,
+		modifiedCallIds: modifiedCallIds(decision),
 	}
 }
 
@@ -246,13 +255,86 @@ export async function applyPendingResume(
 	executor: ToolExecutor,
 	prior?: PriorToolResults,
 ): Promise<void> {
+	const denials = new Map(plan.denials)
+	const reviewedById = new Map(plan.reviewedCalls?.map((call) => [call.id, call]))
+
+	// A gate denial belongs to the run, not to the process that first evaluated
+	// it. Restore it before preparation so denied calls do not even reach a
+	// pre-tool hook after restart.
+	for (const call of plan.reviewedCalls ?? []) {
+		if (call.authorization?.decision !== 'deny' || denials.has(call.id)) continue
+		denials.set(
+			call.id,
+			`Blocked by the authorization gate: ${call.authorization.reason ?? 'the persisted operator policy denied this call'}`,
+		)
+	}
+
+	const callsToPrepare = (plan.response.message.toolCalls ?? []).filter(
+		(call) => !prior?.has(call.id) && !denials.has(call.id),
+	)
+	const responseToPrepare: ChatCompletionResponse = {
+		...plan.response,
+		message: { ...plan.response.message, toolCalls: callsToPrepare },
+	}
+	const preparedBatch = await executor.prepareBatchForReview(responseToPrepare)
+
+	for (const call of preparedBatch.reviewCalls) {
+		const reviewed = reviewedById.get(call.id)
+		const wasModified = plan.modifiedCallIds?.has(call.id) === true
+		if (reviewed && !wasModified) {
+			const unchanged = reviewed.name === call.name && isDeepStrictEqual(reviewed.input, call.input)
+			if (!unchanged) {
+				const reason =
+					'The tool input changed after its durable review; the earlier approval cannot be reused.'
+				denials.set(call.id, reason)
+				await runMgr.recordAudit({
+					what: { action: 'tool_call', tool: call.name },
+					outcome: 'refused',
+					reason,
+				})
+				continue
+			}
+		}
+
+		const current = executor.evaluatePreparedAuthorization(call.name, call.input)
+		let reason: string | undefined
+		if (current?.decision === 'deny') {
+			reason = `Blocked by the authorization gate after resume: ${current.reason}`
+		} else if (current?.decision === 'review' && (wasModified || !reviewed)) {
+			reason = wasModified
+				? `Blocked by the authorization gate after resume: the modified prepared value requires a new explicit approval. ${current.reason}`
+				: `Blocked by the authorization gate after resume: this recovered call requires operator review. ${current.reason}`
+		} else if (!current && reviewed && reviewed.authorization === undefined) {
+			reason =
+				'The durable review predates bound authorization metadata; review this call again before execution.'
+		}
+
+		if (reason) {
+			denials.set(call.id, reason)
+			await runMgr.recordAudit({
+				what: { action: 'tool_call', tool: call.name },
+				outcome: 'refused',
+				reason,
+			})
+		}
+	}
+
 	runMgr.pushMessage(plan.assistant)
-	const batch = await executor.executeBatch(plan.response, plan.denials, prior)
+	const batch = await executor.executeBatch(plan.response, denials, prior, preparedBatch)
 	for (const msg of batch.messages) {
 		runMgr.pushMessage(msg)
 	}
 }
 
+function modifiedCallIds(decision: HITLResumeDecision): ReadonlySet<string> {
+	if (decision.action !== 'modify_tools') return new Set()
+	return new Set(
+		decision.modifications
+			.filter((modification) => modification.action === 'modify')
+			.map((modification) => modification.toolCallId),
+	)
+}
+
 /**
  * Results the run already produced for calls in `toolCalls`.
  *

package/src/runtime/query/tool-output-budget.ts

@@ -37,6 +37,57 @@ export const SPILL_MARKER = 'The full output was written to:'
  */
 const HEAD_SHARE = 0.75
 
+function safeHead(text: string, maxChars: number): string {
+	let end = Math.min(text.length, Math.max(0, maxChars))
+	if (end > 0) {
+		const last = text.charCodeAt(end - 1)
+		if (last >= 0xd800 && last <= 0xdbff) end--
+	}
+	return text.slice(0, end)
+}
+
+function safeTail(text: string, maxChars: number): string {
+	let start = Math.max(0, text.length - Math.max(0, maxChars))
+	if (start < text.length) {
+		const first = text.charCodeAt(start)
+		if (first >= 0xdc00 && first <= 0xdfff) start++
+	}
+	return text.slice(start)
+}
+
+/**
+ * Fit a recoverable head+tail preview inside the actual model-visible cap.
+ *
+ * The old implementation allocated the entire cap to source text and then
+ * appended its diagnostic and recovery instructions. A configured 1,000
+ * character cap therefore emitted 1,200–1,300 characters; at very small
+ * limits the explanation could be several times larger than the limit.
+ */
+function boundedPreview(
+	output: string,
+	maxChars: number,
+	toolName: string,
+	recovery: string,
+): string {
+	const detailedMiddle = [
+		'',
+		`[... characters omitted — "${toolName}" returned ${output.length.toLocaleString()} characters, over the ${maxChars.toLocaleString()}-character budget ...]`,
+		recovery,
+		'',
+	].join('\n')
+	const compactMiddle = '\n[... omitted ...]\n'
+	const middle = detailedMiddle.length < maxChars ? detailedMiddle : compactMiddle
+
+	// A host may deliberately set a tiny positive cap. At that point no
+	// truthful recovery sentence fits; the hard bound still wins.
+	if (middle.length >= maxChars) return safeHead(middle, maxChars)
+
+	const sourceChars = maxChars - middle.length
+	const headChars = Math.max(1, Math.floor(sourceChars * HEAD_SHARE))
+	const tailChars = Math.max(0, sourceChars - headChars)
+	return `${safeHead(output, headChars)}${middle}${safeTail(output, tailChars)}`
+}
+
 export interface ToolOutputBudgetResult {
 	/** What the model sees. */
 	readonly output: string
@@ -127,15 +178,6 @@ export function applyToolOutputBudget(opts: ApplyToolOutputBudgetOptions): ToolO
 		return { output, originalLength, truncated: false }
 	}
 
-	// Both slices are derived from `maxChars` so the preview honours the
-	// budget it is enforcing. `slice(-0)` returns the WHOLE string, so the
-	// zero-tail case must be branched, not computed.
-	const headChars = Math.max(1, Math.floor(maxChars * HEAD_SHARE))
-	const tailChars = Math.max(0, maxChars - headChars)
-	const head = output.slice(0, headChars)
-	const tail = tailChars > 0 ? output.slice(-tailChars) : ''
-	const omitted = originalLength - head.length - tail.length
-
 	const spillPath = opts.spillDir
 		? spill(opts.spillDir, opts.toolUseId, output, opts.onError)
 		: undefined
@@ -148,14 +190,7 @@ export function applyToolOutputBudget(opts: ApplyToolOutputBudgetOptions): ToolO
 		: 'The full output was not retained. Re-run with a narrower query, a line range, or a filter.'
 
 	return {
-		output: [
-			head,
-			'',
-			`[... ${omitted.toLocaleString()} characters omitted — "${opts.toolName}" returned ${originalLength.toLocaleString()} characters, over the ${maxChars.toLocaleString()}-character budget ...]`,
-			recovery,
-			'',
-			tail,
-		].join('\n'),
+		output: boundedPreview(output, maxChars, opts.toolName, recovery),
 		originalLength,
 		truncated: true,
 		...(spillPath ? { spillPath } : {}),

package/src/runtime/query/tooling.ts

@@ -1,8 +1,10 @@
+import type { AuthorizationGate } from '../../authorization/gate.js'
 import type { PluginLifecycleManager } from '../../plugin/lifecycle.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import type { RunId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import type { PermissionMode } from '../../types/permission/index.js'
+import type { AuditEventInput } from '../../types/run/audit.js'
 import type { RunEvent } from '../../types/run/index.js'
 import type {
 	RequestToolPause,
@@ -41,6 +43,10 @@ export interface ToolingBootstrapConfig {
 	maxToolContentBytes?: number
 	toolOutputDir?: string
 	repairToolCall?: RepairToolCall
+	/** Operator authorization shared with the direct-call review path. */
+	authorizationGate?: AuthorizationGate
+	/** Durable refusal recorder for nested authorization decisions. */
+	recordAudit?: (input: AuditEventInput) => Promise<unknown>
 	/** Builds the durable-pause seam for one tool call; see ToolContext.requestPause. */
 	toolPause?: (toolUseId: string) => RequestToolPause
 }
@@ -81,6 +87,10 @@ export class ToolingBootstrap {
 					: {}),
 				...(config.toolOutputDir !== undefined ? { toolOutputDir: config.toolOutputDir } : {}),
 				...(config.repairToolCall !== undefined ? { repairToolCall: config.repairToolCall } : {}),
+				...(config.authorizationGate !== undefined
+					? { authorizationGate: config.authorizationGate }
+					: {}),
+				...(config.recordAudit !== undefined ? { recordAudit: config.recordAudit } : {}),
 				...(config.toolPause !== undefined ? { toolPause: config.toolPause } : {}),
 			},
 			activityStore,