@namzu/sdk 62.6.0 → 62.7.0

package/src/runtime/query/iteration/index.ts

@@ -31,11 +31,12 @@ import { getTracer } from '../../../telemetry/runtime-accessors.js'
 import { STRUCTURED_OUTPUT_TOOL_NAME } from '../../../tools/builtins/structuredOutput.js'
 import type { ToolManager } from '../../../toolsets/manager.js'
 import { RECALLED_MEMORY_ENTRY_KEY, recalledMemoryIds } from '../../../turn/memory-recall.js'
-import type { CostInfo, TokenUsage } from '../../../types/common/index.js'
+import { type CostInfo, type TokenUsage, promptSizeOf } from '../../../types/common/index.js'
 import { NamzuError } from '../../../types/errors/index.js'
 import type { MessageId, SessionId, TurnId } from '../../../types/ids/index.js'
 import {
 	type Message,
+	type ToolCall,
 	type UserMessage,
 	createAssistantMessage,
 	createRuntimeContextMessage,
@@ -54,6 +55,7 @@ import type {
 	StepProvenance,
 	StepResult,
 	StopReason,
+	TurnOutcome,
 } from '../../../types/session/index.js'
 import type { LLMToolSchema } from '../../../types/tool/index.js'
 import { toErrorMessage } from '../../../utils/error.js'
@@ -79,7 +81,8 @@ import {
 } from '../request-rich-content.js'
 import { withoutVoidAssistantTurns } from '../request-void-turns.js'
 import { formatSteeringNote, isOperatorUserMessage } from '../steering.js'
-import { COMPLETION_AUDIT_MESSAGE, CompletionAudit } from '../turn/completion-audit.js'
+import { CompletionAudit } from '../turn/completion-audit.js'
+import { type OutcomeCall, OutcomeLedger, type PendingOutcomeCall } from '../turn/outcome-ledger.js'
 import {
 	FORCED_STEP_MESSAGE,
 	REASONING_CAPPED_MESSAGE,
@@ -107,6 +110,7 @@ import {
 	measureContext,
 	relieveOverflow,
 	runCompactionCheck,
+	runStaleResultClear,
 	stopOnRefill,
 } from './phases/compaction.js'
 import { runHandoffPause } from './phases/handoff.js'
@@ -333,6 +337,9 @@ export class IterationOrchestrator {
 	private readonly stallMonitor?: StallMonitor
 	/** Holds the turn back once when it changed files and checked nothing afterwards. */
 	private readonly completionAudit?: CompletionAudit
+	/** What the turn changed and what checked it; see {@link OutcomeLedger}. Kept whether or not the host asked. */
+	private readonly outcomeLedger: OutcomeLedger
+	private outcomeHydrated = false
 	/** The next step must call a tool, at low effort: set by the stall monitor or a capped step. */
 	private forceActionNextStep = false
 	/** Steps in a row cut at the per-step reasoning cap; past a few the cap stops applying. */
@@ -359,6 +366,10 @@ export class IterationOrchestrator {
 	private turnEndFired = false
 	/** A hook already kept this turn going once: it is asked again with `stop_hook_active`. */
 	private stopHookActive = false
+	/** End-of-turn refusals honoured since the last tool call. */
+	private consecutiveHookRefusals = 0
+	/** The cap was reached and its notice recorded; refusals are ignored for the rest of the turn. */
+	private hookRefusalCapReached = false
 	get turnEndHooksFired(): boolean {
 		return this.turnEndFired
 	}
@@ -371,12 +382,22 @@ export class IterationOrchestrator {
 	 * are returned, joined, as feedback for the model. A hook that asks for the
 	 * turn to halt wins over any such feedback (`takeHalt`). With nothing asked,
 	 * the events have fired for this turn and the finalizer does not repeat them.
+	 *
+	 * Refusals are counted in a row (a tool call in between starts the count
+	 * over). Once `maxHookRefusals` have been honoured the next one is not: the
+	 * turn ends, with one notice that names the hook.
 	 */
 	private async *askStopHooks(): AsyncGenerator<SessionEvent, string | undefined> {
 		const manager = this.ctx.pluginManager
 		if (!manager) return undefined
 		const recorder = this.ctx.recorder
 		const feedback: string[] = []
+		const refusers: string[] = []
+		const emit = async (event: SessionEvent): Promise<void> => {
+			if (event.type === 'plugin_hook_completed' && event.result.action === 'skip')
+				refusers.push(String(event.pluginId))
+			await this.ctx.emitEvent(event)
+		}
 		const ask = async (
 			event: 'turn_end' | 'subagent_stop',
 			extra: {
@@ -394,7 +415,7 @@ export class IterationOrchestrator {
 					...(this.stopHookActive ? { stopHookActive: true } : {}),
 					signal: this.ctx.abortController.signal,
 				},
-				this.ctx.emitEvent,
+				emit,
 			)
 			applyLifecycleHookResults(event, results)
 			for (const result of results) {
@@ -414,10 +435,35 @@ export class IterationOrchestrator {
 			})
 			yield* this.ctx.drainPending()
 		}
-		if (feedback.length === 0) {
+		// Once the cap has been reached, refusals stay ignored for the rest of the turn,
+		// whatever a tool call does to the count; a halt was already passed on above.
+		if (feedback.length === 0 || this.hookRefusalCapReached) {
+			this.turnEndFired = true
+			return undefined
+		}
+		const limit = this.ctx.turnConfig.maxHookRefusals ?? 0
+		if (limit > 0 && this.consecutiveHookRefusals >= limit) {
+			// The turn has been kept going `limit` times in a row. A hook that
+			// still refuses is not going to stop; say so once, and let the turn end.
 			this.turnEndFired = true
+			if (!this.hookRefusalCapReached) {
+				this.hookRefusalCapReached = true
+				const names = [...new Set(refusers)]
+				const who = names.length > 0 ? names.map((n) => `"${n}"`).join(', ') : 'A hook'
+				recorder.pushMessage(
+					createRuntimeContextMessage(
+						`${who} asked for more before this turn could end ${limit} times in a row. Namzu is ending the turn anyway and will not honour further requests from it this turn.`,
+						'hook-feedback',
+					),
+				)
+				this.ctx.log.warn('Hook refusal limit reached — ending the turn', {
+					[NAMZU.TURN_ID]: recorder.turnId,
+					'namzu.runtime.limit': limit,
+				})
+			}
 			return undefined
 		}
+		this.consecutiveHookRefusals++
 		this.stopHookActive = true
 		return feedback.join('\n')
 	}
@@ -436,6 +482,13 @@ export class IterationOrchestrator {
 			},
 		}
 		if (ctx.turnConfig.completionAudit === true) this.completionAudit = new CompletionAudit()
+		this.outcomeLedger = new OutcomeLedger(ctx.turnConfig.outcome)
+		ctx.checkpointMgr.setOutcomeSource?.(() => {
+			this.hydrateOutcome()
+			return this.outcomeLedger.recorded
+				? (this.outcomeLedger.snapshot() as unknown as Record<string, unknown>)
+				: undefined
+		})
 		if (ctx.turnConfig.reasoning?.stall !== false) {
 			this.stallMonitor = new StallMonitor(ctx.turnConfig.reasoning?.stall || undefined)
 		}
@@ -817,6 +870,7 @@ export class IterationOrchestrator {
 					// edge BEFORE compaction runs (so the refreshed slot is what
 					// compaction preserves). No-op when no provider is configured.
 					await refreshWorkingMemory(this.ctx)
+					if (iterationNum === 1) await runStaleResultClear(this.ctx)
 					await runCompactionCheck(this.ctx)
 					yield* this.ctx.drainPending()
 					if (this.stopForCompactionBreaker()) break
@@ -1340,7 +1394,7 @@ export class IterationOrchestrator {
 						'namzu.runtime.has_content':
 							response.message.content !== null && response.message.content.length > 0,
 						'namzu.runtime.tool_call_count': response.message.toolCalls?.length ?? 0,
-						[GENAI.USAGE_INPUT_TOKENS]: response.usage.promptTokens,
+						[GENAI.USAGE_INPUT_TOKENS]: promptSizeOf(response.usage),
 						[GENAI.USAGE_OUTPUT_TOKENS]: response.usage.completionTokens,
 						'namzu.usage.total_tokens': recorder.tokenUsage.totalTokens,
 						'namzu.runtime.total_cost': recorder.costInfo.totalCost,
@@ -1457,7 +1511,7 @@ export class IterationOrchestrator {
 					yield* this.ctx.drainPending()
 
 					iterSpan.setAttributes({
-						[GENAI.USAGE_INPUT_TOKENS]: response.usage.promptTokens,
+						[GENAI.USAGE_INPUT_TOKENS]: promptSizeOf(response.usage),
 						[GENAI.USAGE_OUTPUT_TOKENS]: response.usage.completionTokens,
 					})
 					iterSpan.setStatus({ code: SpanStatusCode.OK })
@@ -1951,17 +2005,15 @@ export class IterationOrchestrator {
 						// back to the model and the turn goes on.
 						// Files were changed and nothing checked them afterwards: ask once
 						// for a check before the turn is allowed to end.
-						if (
-							!forceFinalize &&
-							closingStopReason === undefined &&
-							this.completionAudit?.takeBlock()
-						) {
+						const auditReminder =
+							!forceFinalize && closingStopReason === undefined
+								? this.completionAudit?.takeReminder(() => this.outcomeLedger.peek())
+								: undefined
+						if (auditReminder !== undefined) {
 							this.ctx.log.info('Files changed and nothing checked them — asking for a check', {
 								[NAMZU.TURN_ID]: recorder.turnId,
 							})
-							recorder.pushMessage(
-								createRuntimeContextMessage(COMPLETION_AUDIT_MESSAGE, 'progress-nudge'),
-							)
+							recorder.pushMessage(createRuntimeContextMessage(auditReminder, 'progress-nudge'))
 							continue
 						}
 						if (!forceFinalize && closingStopReason === undefined) {
@@ -1989,6 +2041,10 @@ export class IterationOrchestrator {
 						break
 					}
 
+					// A real tool call: whatever a hook refused before it is behind us.
+					this.consecutiveHookRefusals = 0
+
+					await this.outcomeBefore(response)
 					const reviewOutcome = yield* runToolReview(this.ctx, response, iterationNum)
 
 					// The step record is built even for a rejected batch: a turn that
@@ -2013,6 +2069,7 @@ export class IterationOrchestrator {
 					this.reasoningOnlyRetried = false
 					this.observeStall(response, reviewOutcome.results)
 					this.observeAudit(response, reviewOutcome.results)
+					await this.outcomeObserve(iterationNum, response, reviewOutcome.results)
 
 					if (reviewOutcome.decision === 'stop') {
 						return
@@ -3334,6 +3391,102 @@ export class IterationOrchestrator {
 		}
 	}
 
+	/**
+	 * Take back the outcome record a checkpoint kept. Done at first use rather
+	 * than at construction: the checkpoint is read after this is built. A turn
+	 * resumed from a checkpoint with no record cannot say what came before it,
+	 * so it keeps none.
+	 */
+	private hydrateOutcome(): void {
+		if (this.outcomeHydrated) return
+		this.outcomeHydrated = true
+		const restored = this.ctx.checkpointMgr.restoredOutcome
+		if (restored?.resumed !== true) return
+		if (restored.snapshot === undefined) this.outcomeLedger.markUnrecorded()
+		else this.outcomeLedger.restore(restored.snapshot)
+	}
+
+	/** Whether a call is one the outcome record may treat as only looking. */
+	private lookedOnly(toolName: string, input: unknown): boolean {
+		try {
+			return !callChangedState(toolName, this.ctx.tools.get(toolName)?.isReadOnly?.(input), false)
+		} catch {
+			return false
+		}
+	}
+
+	private parsedInput(call: ToolCall | undefined): unknown {
+		try {
+			return call ? JSON.parse(call.function.arguments) : undefined
+		} catch {
+			return undefined
+		}
+	}
+
+	/**
+	 * Before a step's calls run: the first one that could change the workspace
+	 * takes the starting fingerprint. A failure here must not fail the turn.
+	 */
+	async outcomeBefore(response: ChatCompletionResponse): Promise<void> {
+		try {
+			this.hydrateOutcome()
+			const pending: PendingOutcomeCall[] = (response.message.toolCalls ?? []).map((call) => {
+				const input = this.parsedInput(call)
+				return {
+					toolName: call.function.name,
+					input,
+					readOnly: this.lookedOnly(call.function.name, input),
+				}
+			})
+			await this.outcomeLedger.before(pending)
+		} catch (err) {
+			this.ctx.log.warn('The outcome record could not take its starting point', {
+				'exception.message': toErrorMessage(err),
+			})
+		}
+	}
+
+	/** Feed the outcome record the calls of one finished step. */
+	async outcomeObserve(
+		step: number,
+		response: ChatCompletionResponse,
+		results: readonly ToolCallOutcome[],
+	): Promise<void> {
+		try {
+			this.hydrateOutcome()
+			const calls = new Map((response.message.toolCalls ?? []).map((c) => [c.id, c]))
+			const seen: OutcomeCall[] = results.map((result) => {
+				const input = this.parsedInput(calls.get(result.toolCallId))
+				return {
+					toolName: result.toolName,
+					input,
+					isError: result.isError,
+					...(result.skipped ? { skipped: true } : {}),
+					readOnly: this.lookedOnly(result.toolName, input),
+					...(result.facts ? { facts: result.facts } : {}),
+				}
+			})
+			await this.outcomeLedger.observe(step, seen)
+		} catch (err) {
+			this.ctx.log.warn('The outcome record could not read a step', {
+				'exception.message': toErrorMessage(err),
+			})
+		}
+	}
+
+	/** The outcome record as the turn leaves it; `undefined` when none was kept. */
+	async takeOutcome(): Promise<TurnOutcome | undefined> {
+		try {
+			this.hydrateOutcome()
+			return await this.outcomeLedger.finish()
+		} catch (err) {
+			this.ctx.log.warn('The outcome record could not be settled', {
+				'exception.message': toErrorMessage(err),
+			})
+			return undefined
+		}
+	}
+
 	/** Feed the completion audit the calls of one finished step. */
 	private observeAudit(
 		response: ChatCompletionResponse,

package/src/runtime/query/iteration/phases/compaction.ts

@@ -21,6 +21,7 @@ import {
 	isCompactionMessage,
 } from '../../../../compaction/summary.js'
 import { estimateMessagesTokens } from '../../../../compaction/token-estimate.js'
+import { clearStaleToolResults } from '../../../../compaction/tool-result-editing.js'
 import { buildVerifiedSummaryWithBoundedProvider } from '../../../../compaction/verifier.js'
 import type { CompactionConfig } from '../../../../config/runtime.js'
 import { CHARS_PER_TOKEN } from '../../../../constants/limits.js'
@@ -172,7 +173,7 @@ async function commitToolResultClear(
 	plan: ToolResultClearPlan,
 	contextWindowTokens: number,
 	windowSource: 'config' | 'provider' | 'model-table' | 'default',
-	reason: 'threshold' | 'overflow',
+	reason: 'threshold' | 'overflow' | 'manual',
 ): Promise<void> {
 	// A shorter replacement also removes evidence. Preserve its original
 	// content in the same archive used by whole-message compaction before
@@ -184,7 +185,56 @@ async function commitToolResultClear(
 	ctx.recorder.clearLastPromptTokens?.()
 	await emitToolResultClear(ctx, plan)
 	await emitContextUsageSnapshot(ctx, estimateTokens(ctx), contextWindowTokens, windowSource)
-	compactionBreaker(ctx)?.recordRelief()
+	// A host-requested pass is not the kernel's own relief of a full context,
+	// so it must not reset the breaker's failure streak.
+	if (reason !== 'manual') compactionBreaker(ctx)?.recordRelief()
+}
+
+/**
+ * The first request of a turn, for a host that said the prompt cache is gone:
+ * shed old, large tool results now, since the prefix is re-read at full price
+ * either way. Does nothing unless `clearStaleToolResultsAtStart` is set and the
+ * clear would save at least its floor. Reuses the in-turn clear, so the same
+ * results are protected, the originals are recorded before they are replaced,
+ * and the host gets the same `compaction_tool_results_cleared` event. It is
+ * not a threshold pass: the `pre_compact` / `post_compact` hooks, the
+ * near-limit and busy guards and the circuit breaker's relief count do not
+ * see it.
+ */
+export async function runStaleResultClear(ctx: IterationContext): Promise<void> {
+	const config = ctx.compactionConfig
+	const option = config?.clearStaleToolResultsAtStart
+	if (!config || !option) return
+	if (config.strategy === 'disabled' || config.clearToolResults === false) return
+	// The pass promises the originals stay in the log. With the log switched
+	// off, replacing them would lose them, so the pass does not run.
+	if (config.recordShedHistory === false) return
+
+	const live = ctx.recorder.messages
+	const edit = clearStaleToolResults(live, {
+		keepRecentToolResults: option.keepRecentToolResults ?? config.keepRecentToolResults,
+		minCharsToClear: config.minToolResultCharsToClear,
+		...(config.preserveToolResultsFrom ? { preserveTools: config.preserveToolResultsFrom } : {}),
+	})
+	if (edit.clearedCount === 0) return
+	const reclaimedTokens = estimateMessagesTokens(live) - estimateMessagesTokens(edit.messages)
+	if (reclaimedTokens < option.minSavedTokens) return
+
+	const window = activeContextWindow(ctx)
+	await commitToolResultClear(
+		ctx,
+		{
+			kind: 'cleared',
+			messages: edit.messages,
+			clearedCount: edit.clearedCount,
+			charsReclaimed: edit.charsReclaimed,
+			reclaimedTokens,
+			reliefWasEnough: true,
+		},
+		window.tokens,
+		window.source,
+		'manual',
+	)
 }
 
 /**
@@ -628,7 +678,7 @@ async function recordShed(
 	ctx: IterationContext,
 	before: readonly Message[],
 	after: readonly Message[],
-	reason: 'threshold' | 'overflow',
+	reason: 'threshold' | 'overflow' | 'manual',
 ): Promise<void> {
 	if (ctx.compactionConfig?.recordShedHistory === false) return
 

package/src/runtime/query/iteration/phases/context.ts

@@ -471,6 +471,12 @@ function resumeContextOf(ctx: IterationContext, scope?: AskScope): ResumeContext
 	return {
 		transcript: () => ctx.recorder.messages,
 		...(signal ? { signal } : {}),
+		...(typeof ctx.toolExecutor?.launchedScripts === 'function'
+			? {
+					launchedScripts: (callId, line, dialect) =>
+						ctx.toolExecutor.launchedScripts(callId, line, dialect),
+				}
+			: {}),
 	}
 }
 

package/src/runtime/query/iteration/stream-turn.ts

@@ -21,7 +21,7 @@ import {
 	recordTokenUsage,
 } from '../../../telemetry/metrics.js'
 import { getTracer } from '../../../telemetry/runtime-accessors.js'
-import { mergeTokenUsage } from '../../../types/common/index.js'
+import { mergeTokenUsage, promptSizeOf } from '../../../types/common/index.js'
 import { NamzuError } from '../../../types/errors/index.js'
 import type { ToolUseId } from '../../../types/ids/index.js'
 import type {
@@ -196,7 +196,7 @@ async function settleCancelledTurn(args: {
 		recordTokenUsage(args.model, args.usage)
 		recordModelDuration(args.model, Date.now() - args.startedAt)
 		args.span.setAttributes({
-			[GENAI.USAGE_INPUT_TOKENS]: args.usage.promptTokens,
+			[GENAI.USAGE_INPUT_TOKENS]: promptSizeOf(args.usage),
 			[GENAI.USAGE_OUTPUT_TOKENS]: args.usage.completionTokens,
 			[NAMZU.CACHE_READ_TOKENS]: args.usage.cachedTokens ?? 0,
 			[NAMZU.CACHE_WRITE_TOKENS]: args.usage.cacheWriteTokens ?? 0,
@@ -1128,7 +1128,7 @@ export async function* streamProviderTurn(
 		[GENAI.RESPONSE_MODEL]: response.model,
 		[GENAI.RESPONSE_ID]: response.id,
 		[GENAI.RESPONSE_FINISH_REASONS]: [response.finishReason],
-		[GENAI.USAGE_INPUT_TOKENS]: usage.promptTokens,
+		[GENAI.USAGE_INPUT_TOKENS]: promptSizeOf(usage),
 		[GENAI.USAGE_OUTPUT_TOKENS]: usage.completionTokens,
 		[NAMZU.CACHE_READ_TOKENS]: usage.cachedTokens ?? 0,
 		[NAMZU.CACHE_WRITE_TOKENS]: usage.cacheWriteTokens ?? 0,

package/src/runtime/query/prelude-lease.ts

@@ -99,6 +99,17 @@ export class PreludeSessionLease {
 			}
 			return
 		}
+		// A renewal is two durable replaces and four fsyncs; the prelude asks
+		// three times in a few milliseconds. While the holding has more than
+		// half its time left the heartbeat has nothing to add, and what the
+		// question is really about, whether anyone took the session, is
+		// answered by reading the fence, as it is for a supplied lease.
+		await this.#renewal
+		if (this.#renewalError !== undefined) throw this.#renewalError
+		if (this.#current.expiresAt - Date.now() >= DEFAULT_TURN_LEASE_TTL_MS / 2) {
+			const held = await this.#log.lease()
+			if (held?.fence === this.#current.fence && held.holder === this.#current.holder) return
+		}
 		this.#queueRenewal()
 		await this.#renewal
 		if (this.#renewalError !== undefined) throw this.#renewalError
@@ -107,6 +118,14 @@ export class PreludeSessionLease {
 	/** Hand the freshest token to TurnRecorder while this heartbeat covers open(). */
 	async transfer(): Promise<SessionLease> {
 		await this.assertCurrent()
+		// The recorder's own heartbeat first fires half a lifetime after it
+		// opens, so it must be handed a full lifetime, not whatever was left
+		// when the last confirmation read the fence.
+		if (this.ownsLease) {
+			this.#queueRenewal()
+			await this.#renewal
+			if (this.#renewalError !== undefined) throw this.#renewalError
+		}
 		this.#transferred = true
 		return this.#current
 	}

package/src/runtime/query/prepare-turn.ts

@@ -430,7 +430,11 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 		]
 		assertCostIsAttributable(chain, params.pricing)
 		assertBudgetIsMeasurable(params)
-		const withRecovery = (provider: LLMProvider): LLMProvider => {
+		// When the caller asks for it (`retry.overloadedFallOverAfter`), a member
+		// with a successor leaves after that many overloaded answers in a row
+		// instead of spending the whole budget on a saturated provider; the last
+		// member has nowhere to go, so it keeps the full budget whatever was asked.
+		const withRecovery = (provider: LLMProvider, hasSuccessor: boolean): LLMProvider => {
 			const withIdleBound = withStreamIdleTimeout(provider, {
 				idleTimeoutMs: streamIdleTimeoutMs,
 				log,
@@ -439,7 +443,12 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 			return params.retry === false
 				? metered
 				: withProviderRetry(metered, {
-						config: params.retry,
+						config: {
+							...params.retry,
+							overloadedFallOverAfter: hasSuccessor
+								? (params.retry?.overloadedFallOverAfter ?? 0)
+								: 0,
+						},
 						log,
 						canRetry: () => budget.remaining > 0,
 					})
@@ -455,9 +464,9 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 			current: { index: 0, providerId: params.provider.id },
 		}
 		const resilientProvider = withProviderFallback(
-			chain.map((member) => ({
+			chain.map((member, position) => ({
 				...member,
-				provider: withRecovery(member.provider),
+				provider: withRecovery(member.provider, position < chain.length - 1),
 			})),
 			{
 				log,

package/src/runtime/query/review-policy.ts

@@ -37,6 +37,7 @@ import { isTrustedReadOnly } from '../../tools/trusted-read-only.js'
 import type { ToolManager } from '../../toolsets/manager.js'
 import type {
 	HITLResumeDecision,
+	LaunchedScript,
 	ResumeContext,
 	ResumeHandler,
 	ToolCallDeclined,
@@ -933,6 +934,36 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 	/** Set once the classifier has said the conversation is too long, until it judges something. */
 	let transcriptTooLong = false
 	const toolOf = (name: string) => registry?.get(name) ?? registry?.get(name.toLowerCase())
+	/** The script files a shell call launches that the agent wrote, read now; none for any other call. */
+	const launchedScriptsOf = async (
+		tc: ToolCallSummary,
+		context: ResumeContext | undefined,
+	): Promise<readonly LaunchedScript[]> => {
+		if (context?.launchedScripts === undefined) return []
+		const tool = toolOf(tc.name)
+		const argument = tool?.commandArgument
+		if (tool === undefined || argument === undefined) return []
+		const line = (tc.input as Record<string, unknown> | null)?.[argument]
+		if (typeof line !== 'string') return []
+		try {
+			return await context.launchedScripts(
+				tc.id,
+				line,
+				tool.commandDialect?.({ sandboxed: false }) ?? 'sh',
+			)
+		} catch {
+			// Reading a script is an addition to the review. A failure to do it is
+			// said to the reviewer rather than hidden.
+			return [
+				{
+					path: '(unknown)',
+					origin: 'unknown',
+					state: 'unreadable',
+					note: 'reading the script files this line launches failed, so what they run is not known',
+				},
+			]
+		}
+	}
 	const rootsNow = (): readonly string[] =>
 		typeof options.roots === 'function' ? options.roots() : (options.roots ?? [])
 	const exempt: ReviewExemption =
@@ -1215,9 +1246,11 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 				for (const tc of live) {
 					// The questions a person must answer are asked of a person, never of a model.
 					if (isBypassImmune(tc) || (await neverSent(tc, request.sessionId))) continue
+					const scripts = await launchedScriptsOf(tc, context)
 					const decision = await classifier.review({
 						call: tc,
 						transcript,
+						...(scripts.length > 0 ? { scripts } : {}),
 						...(registry ? { tools: registry } : {}),
 						...(context?.signal ? { signal: context.signal } : {}),
 					})

package/src/runtime/query/tooling.ts

@@ -32,6 +32,8 @@ export interface ToolingBootstrapConfig {
 	scratchpadDirectory?: string
 	/** See `QueryParams.outsideRootAccess`. */
 	outsideRootAccess?: 'refuse' | 'review'
+	/** See `QueryParams.outsideRootRefusal`. */
+	outsideRootRefusal?: string
 	/** See `QueryParams.sandboxEscape`. */
 	sandboxEscape?: 'refuse' | 'review'
 	/** A resolver, so an approval inside a turn can change it. See the executor. */
@@ -103,6 +105,7 @@ export class ToolingBootstrap {
 					: {}),
 				...(config.scratchpadDirectory ? { scratchpadDirectory: config.scratchpadDirectory } : {}),
 				...(config.outsideRootAccess ? { outsideRootAccess: config.outsideRootAccess } : {}),
+				...(config.outsideRootRefusal ? { outsideRootRefusal: config.outsideRootRefusal } : {}),
 				...(config.sandboxEscape ? { sandboxEscape: config.sandboxEscape } : {}),
 				permissionMode: config.permissionMode,
 				env: config.env,