@namzu/sdk 51.1.0 → 52.1.0

package/src/runtime/query/executor.ts

@@ -32,7 +32,7 @@ import {
 	createToolMessage,
 } from '../../types/message/index.js'
 import type { PermissionMode } from '../../types/permission/index.js'
-import type { PluginHookResult } from '../../types/plugin/index.js'
+import type { PluginHookPermission, PluginHookResult } from '../../types/plugin/index.js'
 import type { ChatCompletionResponse } from '../../types/provider/index.js'
 import type { Sandbox } from '../../types/sandbox/index.js'
 import type { AuditEventInput } from '../../types/session/audit.js'
@@ -65,6 +65,7 @@ import { type BackgroundJobRegistry, type JobProcess, bindOwner } from '../jobs/
 import {
 	type ToolAdmissionHost,
 	formatFailedToolOutput,
+	hookNote,
 	isUnregistered,
 	prepareDirectCall,
 	runPreToolHook,
@@ -73,14 +74,17 @@ import {
 import { describeVisibleFileEvidence } from './file-evidence-context.js'
 import { seedObservationLedger } from './file-evidence-seed.js'
 import { DEFAULT_TOOL_RESULT_GUARDRAILS } from './guardrail-presets.js'
+import { declaredWriteEscalation, shellEscalations } from './path-escalation.js'
 import type { ToolResultObservation } from './project-instructions.js'
 import { savedPresentation } from './saved-presentation.js'
 import { ToolCallBudget, assertMaxToolCalls } from './tool-call-budget.js'
 import {
 	DEFAULT_MAX_TOOL_OUTPUT_CHARS,
+	DEFAULT_MAX_TOOL_OUTPUT_CHARS_PER_MESSAGE,
 	type ToolOutputBudgetResult,
 	applyToolOutputBudget,
 	describeDroppedContent,
+	fitResultsToMessageBudget,
 	measureContentBytes,
 } from './tool-output-budget.js'
 
@@ -94,6 +98,7 @@ export type PreparedDirectCall =
 			readonly toolName: string
 			readonly input: unknown
 			readonly prepared: PreparedToolExecution
+			readonly hook?: PreToolHookNotes
 	  }
 	| {
 			readonly kind: 'legacy'
@@ -101,6 +106,7 @@ export type PreparedDirectCall =
 			readonly toolName: string
 			readonly input: unknown
 			readonly inputFailure?: CompletedToolRecord['inputFailure']
+			readonly hook?: PreToolHookNotes
 	  }
 	| {
 			readonly kind: 'synthetic'
@@ -129,6 +135,8 @@ export interface PreparedToolBatch {
 		readonly input: unknown
 		/** What the prepared value reaches past the turn's boundary; see `ToolCallSummary.escalation`. */
 		readonly escalation?: ToolCallEscalation
+		/** What a `pre_tool_use` hook asked for this call's approval; see `ToolCallSummary.hookPermission`. */
+		readonly hookPermission?: PluginHookPermission
 	}[]
 }
 
@@ -137,6 +145,16 @@ interface OwnedPreparedToolBatch extends PreparedToolBatch {
 	readonly escalations: ReadonlyMap<string, ToolCallEscalation>
 }
 
+/**
+ * A nested call cannot open a review from inside the tool that issued it, so
+ * a hook that asked for a person to approve it can only be answered with a
+ * refusal. Silence would run the call the hook wanted a person to see.
+ */
+function askedNestedMessage(toolName: string, outcome: PreToolHookOutcome): string | undefined {
+	if (outcome.kind !== 'continue' || outcome.permission?.decision !== 'ask') return undefined
+	return `Blocked: a hook asked that a person approve "${toolName}", and an approval cannot be requested from inside another tool. Call it directly.`
+}
+
 function assertUniqueToolCallIds(toolCalls: readonly ToolCall[]): void {
 	const seen = new Set<string>()
 	for (const [index, toolCall] of toolCalls.entries()) {
@@ -420,6 +438,8 @@ export interface ToolExecutorConfig {
 	 * {@link DEFAULT_MAX_TOOL_OUTPUT_CHARS}; set `0` to disable.
 	 */
 	maxToolOutputChars?: number
+	/** See QueryParams.maxToolOutputCharsPerMessage. */
+	maxToolOutputCharsPerMessage?: number
 	/** See QueryParams.retainedToolPreviewChars; applies to the recorded host output. */
 	retainedToolPreviewChars?: number
 
@@ -493,8 +513,16 @@ interface PostToolOverride {
 	readonly content?: ToolResultContent
 }
 
+/** What `pre_tool_use` hooks said about a call beyond running it or not. */
+export interface PreToolHookNotes {
+	/** The strictest permission answer among the hooks: `ask` outranks `allow`. */
+	readonly permission?: PluginHookPermission
+	/** Hook text for the model, appended to what it reads of this call. */
+	readonly context?: string
+}
+
 export type PreToolHookOutcome =
-	| { kind: 'continue'; input: unknown; modified: boolean }
+	| ({ kind: 'continue'; input: unknown; modified: boolean } & PreToolHookNotes)
 	| { kind: 'skip'; input: unknown; output: string }
 	| { kind: 'error'; input: unknown; output: string }
 
@@ -625,6 +653,7 @@ export class ToolExecutor {
 	/** Set per turn by the orchestrator; see {@link setStepAllowedTools}. */
 	private stepAllowedTools?: readonly string[]
 	private readonly fileReadTracker: FileReadTracker
+	private sandboxGate?: () => Promise<void>
 	/** A ledger is rebuilt from history at most once; a second pass would re-append its chains. */
 	private fileObservationsSeeded = false
 
@@ -658,6 +687,25 @@ export class ToolExecutor {
 
 	setSandbox(sandbox: Sandbox): void {
 		this.config = { ...this.config, sandbox }
+		this.sandboxGate = undefined
+	}
+
+	/**
+	 * Hold tool admission until a sandbox that is still being acquired exists.
+	 * The gate rejects when none will, and the turn settles that rejection. It
+	 * is cleared by {@link setSandbox}, so a turn pays the check once.
+	 */
+	setSandboxGate(gate: () => Promise<void>): void {
+		this.sandboxGate = gate
+	}
+
+	private async awaitSandbox(): Promise<void> {
+		await this.sandboxGate?.()
+	}
+
+	/** True once the turn has a sandbox, or is certain to get one before a tool runs. */
+	private get sandboxed(): boolean {
+		return this.config.sandbox !== undefined || this.sandboxGate !== undefined
 	}
 
 	/** Classify only the exact successful result executed by this executor. */
@@ -743,7 +791,7 @@ export class ToolExecutor {
 			messages,
 			this.fileReadTracker,
 			this.config.workingDirectory,
-			this.config.sandbox !== undefined,
+			this.sandboxed,
 		)
 	}
 
@@ -925,7 +973,7 @@ export class ToolExecutor {
 		const tool = this.config.tools.get(toolName)
 		return (
 			tool?.commandDialect?.({
-				sandboxed: this.config.sandbox !== undefined,
+				sandboxed: this.sandboxed,
 			}) ?? 'sh'
 		)
 	}
@@ -951,6 +999,7 @@ export class ToolExecutor {
 		hostModifiedCallIds?: ReadonlySet<string>,
 	): Promise<PreparedToolBatch> {
 		assertUniqueToolCallIds(response.message.toolCalls ?? [])
+		if ((response.message.toolCalls ?? []).length > 0) await this.awaitSandbox()
 		const calls = new Map<string, PreparedDirectCall>()
 		const escalations = new Map<string, ToolCallEscalation>()
 		for (const toolCall of response.message.toolCalls ?? []) {
@@ -984,7 +1033,7 @@ export class ToolExecutor {
 		const tool = this.config.tools.get(call.toolName)
 		if (!tool || call.input === null || typeof call.input !== 'object') return undefined
 		const input = call.input as Record<string, unknown>
-		const sandboxed = this.config.sandbox !== undefined
+		const sandboxed = this.sandboxed
 		let outsidePaths: string[] | undefined
 		if (
 			this.config.outsideRootAccess === 'review' &&
@@ -1003,11 +1052,80 @@ export class ToolExecutor {
 			tool.sandboxEscapeArgument !== undefined &&
 			input[tool.sandboxEscapeArgument] === true
 		const unknownProgram = this.unknownProgramOf(tool, input, sandboxed)
-		if (!outsidePaths && !sandboxEscape && unknownProgram === undefined) return undefined
+		const reaches = await this.pathEscalationsOf(tool, input, sandboxed)
+		if (reaches.outsidePaths.length > 0) {
+			outsidePaths = [...new Set([...(outsidePaths ?? []), ...reaches.outsidePaths])]
+		}
+		const protectedPaths = reaches.protectedPaths
+		const removal = reaches.dangerousRemoval
+		if (
+			!outsidePaths &&
+			!sandboxEscape &&
+			unknownProgram === undefined &&
+			protectedPaths.length === 0 &&
+			removal === undefined
+		) {
+			return undefined
+		}
 		return {
 			...(outsidePaths ? { outsidePaths } : {}),
 			...(sandboxEscape ? { sandboxEscape: true as const } : {}),
 			...(unknownProgram !== undefined ? { unknownProgram } : {}),
+			...(protectedPaths.length > 0 ? { protectedPaths } : {}),
+			...(removal !== undefined ? { dangerousRemoval: removal } : {}),
+		}
+	}
+
+	/**
+	 * What the call's own arguments write or remove that no mode may approve in
+	 * advance, and, for a shell line, the paths outside the roots it names.
+	 *
+	 * The protected-path and removal floors hold whether or not the turn reviews
+	 * outside paths and whether or not it is sandboxed: they are about what the
+	 * write plants and what the removal destroys, not about where the turn is
+	 * allowed to look. The outside-path half follows `outsideRootAccess`, as the
+	 * file tools' own does.
+	 */
+	private async pathEscalationsOf(
+		tool: Pick<
+			ToolDefinition,
+			'pathArgument' | 'commandArgument' | 'commandDialect' | 'isReadOnly'
+		>,
+		input: Record<string, unknown>,
+		sandboxed: boolean,
+	): Promise<{
+		outsidePaths: readonly string[]
+		protectedPaths: readonly string[]
+		dangerousRemoval?: string
+	}> {
+		const roots = toolRoots(this.config)
+		const protectedPaths: string[] = []
+		let outsidePaths: readonly string[] = []
+		let removal: string | undefined
+		if (tool.pathArgument !== undefined && tool.isReadOnly?.(input) !== true) {
+			const value = input[tool.pathArgument]
+			if (typeof value === 'string') {
+				const hit = await declaredWriteEscalation(roots, value)
+				if (hit !== undefined) protectedPaths.push(hit)
+			}
+		}
+		if (tool.commandArgument !== undefined) {
+			const line = input[tool.commandArgument]
+			if (typeof line === 'string') {
+				const dialect = tool.commandDialect?.({ sandboxed }) ?? 'sh'
+				const found = await shellEscalations(line, dialect, {
+					roots,
+					reviewOutside: this.config.outsideRootAccess === 'review' && !sandboxed,
+				})
+				protectedPaths.push(...found.protectedPaths)
+				outsidePaths = found.outsidePaths
+				removal = found.dangerousRemoval
+			}
+		}
+		return {
+			outsidePaths,
+			protectedPaths: [...new Set(protectedPaths)],
+			...(removal !== undefined ? { dangerousRemoval: removal } : {}),
 		}
 	}
 
@@ -1022,7 +1140,10 @@ export class ToolExecutor {
 	 * outside one.
 	 */
 	private unknownProgramOf(
-		tool: { commandArgument?: string; commandDialect?: ToolDefinition['commandDialect'] },
+		tool: {
+			commandArgument?: string
+			commandDialect?: ToolDefinition['commandDialect']
+		},
 		input: Record<string, unknown>,
 		sandboxed: boolean,
 	): string | undefined {
@@ -1069,11 +1190,13 @@ export class ToolExecutor {
 			)
 			.map((call) => {
 				const escalation = escalations.get(call.toolCall.id)
+				const hookPermission = call.hook?.permission
 				return {
 					id: call.toolCall.id,
 					name: call.toolName,
 					input: call.input,
 					...(escalation ? { escalation } : {}),
+					...(hookPermission ? { hookPermission } : {}),
 				}
 			})
 		const batch: OwnedPreparedToolBatch = Object.freeze({
@@ -1097,6 +1220,7 @@ export class ToolExecutor {
 			return { messages: [], results: [], observations: [] }
 		}
 		assertUniqueToolCallIds(toolCalls)
+		if (toolCalls.length > 0) await this.awaitSandbox()
 
 		// Sampled here, once, and held for every call below. See the note on
 		// `permissionMode` in the config type.
@@ -1327,6 +1451,8 @@ export class ToolExecutor {
 			})
 		}
 
+		this.fitBatchToMessageBudget(results)
+
 		// isError and rich content were computed and then discarded here: the
 		// tuple narrowed to {toolCallId, output} BEFORE the message was built,
 		// so the failure signal and any image block were structurally lost at
@@ -1338,6 +1464,51 @@ export class ToolExecutor {
 		return { messages, results, observations }
 	}
 
+	/**
+	 * Hold the batch's combined result text under the per-message cap.
+	 *
+	 * Runs once, on the settled batch and before the results become history
+	 * messages, so what it writes is what every later request replays.
+	 */
+	private fitBatchToMessageBudget(results: ToolCallOutcome[]): void {
+		const maxChars =
+			this.config.maxToolOutputCharsPerMessage ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS_PER_MESSAGE
+		const replacements = fitResultsToMessageBudget(
+			results.map((r) => ({
+				toolCallId: r.toolCallId,
+				toolName: r.toolName,
+				output: r.output,
+				// A result carrying rich content or a structured-output copy is
+				// not text the model reads alone, and a self-limiting tool has
+				// already decided its own size.
+				replaceable:
+					r.content === undefined &&
+					r.structuredResultJson === undefined &&
+					this.config.tools.get(r.toolName)?.selfLimitingOutput !== true,
+			})),
+			{
+				maxChars,
+				spillDir: this.outputDirectory(),
+				onError: (message) =>
+					this.log.warn('Failed to retain a tool output replaced for the message budget', {
+						[NAMZU.TURN_ID]: this.config.turnId,
+						'exception.message': message,
+					}),
+			},
+		)
+		if (replacements.size === 0) return
+		for (const [i, r] of results.entries()) {
+			const replacement = replacements.get(r.toolCallId)
+			if (replacement === undefined) continue
+			results[i] = { ...r, output: replacement.output }
+		}
+		this.log.warn("Tool results exceeded the message's combined budget", {
+			[NAMZU.TURN_ID]: this.config.turnId,
+			'namzu.runtime.replaced_count': replacements.size,
+			'namzu.runtime.message_budget_chars': maxChars,
+		})
+	}
+
 	/**
 	 * Run a tool on behalf of another tool, and put it on the record.
 	 *
@@ -1802,8 +1973,10 @@ export class ToolExecutor {
 		let input: unknown
 		let prepared: PreparedToolExecution | undefined
 		let inputFailure: ToolCallOutcome['inputFailure']
+		let preparedHookContext: string | undefined
 
 		if (preparedCall?.kind === 'ready' || preparedCall?.kind === 'legacy') {
+			preparedHookContext = preparedCall.hook?.context
 			input = preparedCall.input
 			prepared = preparedCall.kind === 'ready' ? preparedCall.prepared : undefined
 			if (preparedCall.kind === 'legacy') inputFailure = preparedCall.inputFailure
@@ -1824,6 +1997,7 @@ export class ToolExecutor {
 			if (admitted.kind === 'synthetic') return this.recordSyntheticPreparation(admitted)
 			toolName = admitted.toolName
 			input = admitted.input
+			preparedHookContext = admitted.hook?.context
 			prepared = admitted.kind === 'ready' ? admitted.prepared : undefined
 			if (admitted.kind === 'legacy') inputFailure = admitted.inputFailure
 		}
@@ -2029,7 +2203,11 @@ export class ToolExecutor {
 				]
 			}
 		}
-		const maxToolOutputChars = this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS
+		// A tool that bounds its own output is exempt from the DEFAULT per-result
+		// cap only; a host that set the cap explicitly still gets it.
+		const maxToolOutputChars =
+			this.config.maxToolOutputChars ??
+			(executedDefinition?.selfLimitingOutput === true ? 0 : DEFAULT_MAX_TOOL_OUTPUT_CHARS)
 		const sourceOutput = output
 		// This owner-bound channel follows the selected receipt after both result
 		// screening and post-tool replacement. ToolResult.data and raw input can
@@ -2085,13 +2263,26 @@ export class ToolExecutor {
 			})
 		}
 		output = budgeted.output
-		const modelContent =
+		let modelContent =
 			selectedContent === undefined
 				? undefined
 				: this.budgetContent(selectedContent, toolName, toolCall.id, {
 						sourceOutput,
 						budgeted,
 					})
+		// What hooks said about this call rides with its result, in the model's
+		// receipt and the host's alike, framed as a hook's words. Added after
+		// the output budget so a bounded result is never trimmed to make room
+		// for it; the note has its own bound (`hookNote`).
+		const hookTexts = [preparedHookContext, post.context].filter(
+			(text): text is string => text !== undefined && text.length > 0,
+		)
+		if (hookTexts.length > 0) {
+			const note = hookNote(hookTexts)
+			output = `${output}\n\n${note}`
+			if (typeof modelContent === 'string') modelContent = `${modelContent}\n\n${note}`
+			else if (modelContent) modelContent = [...modelContent, { type: 'text', text: note }]
+		}
 
 		// 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
@@ -2438,9 +2629,25 @@ export class ToolExecutor {
 			emitEvent: this.emitEvent,
 			log: this.log,
 			allowedTools: this.effectiveAllowedTools(),
+			requestHalt: (reason) => this.requestHalt(reason),
 		}
 	}
 
+	/** Why a hook asked for the turn to stop, until the iteration loop reads it. */
+	private haltReason: string | undefined
+
+	/** The first request wins: a later hook does not rewrite why the turn stopped. */
+	requestHalt(reason: string): void {
+		this.haltReason ??= reason
+	}
+
+	/** Read and clear a hook's request to stop the turn. */
+	takeHalt(): string | undefined {
+		const reason = this.haltReason
+		this.haltReason = undefined
+		return reason
+	}
+
 	private async prepareNestedCall(
 		toolName: string,
 		input: unknown,
@@ -2468,6 +2675,14 @@ export class ToolExecutor {
 					...(preOutcome.kind === 'skip' ? { skipped: true as const } : {}),
 				}
 			}
+			const nestedAsk = askedNestedMessage(toolName, preOutcome)
+			if (nestedAsk)
+				return {
+					kind: 'synthetic',
+					input: preOutcome.input,
+					message: nestedAsk,
+					isError: true,
+				}
 			return { kind: 'legacy', input: preOutcome.input }
 		}
 
@@ -2513,6 +2728,15 @@ export class ToolExecutor {
 				...(preOutcome.kind === 'skip' ? { skipped: true as const } : {}),
 			}
 		}
+		const nestedAsk = askedNestedMessage(toolName, preOutcome)
+		if (nestedAsk) {
+			return {
+				kind: 'synthetic',
+				input: preOutcome.input,
+				message: nestedAsk,
+				isError: true,
+			}
+		}
 		if (!preOutcome.modified) {
 			return {
 				kind: 'ready',
@@ -2571,12 +2795,17 @@ export class ToolExecutor {
 	/**
 	 * @returns `override` — text replacing the tool's output, or `null`.
 	 *   `retry` — the hook asked for the tool to run again.
+	 *   `context` — what the hooks want the model to read beside the result.
 	 */
 	private async runPostToolHook(
 		toolName: string,
 		input: unknown,
 		toolResult: ToolResult,
-	): Promise<{ override: PostToolOverride | null; retry: boolean }> {
+	): Promise<{
+		override: PostToolOverride | null
+		retry: boolean
+		context?: string
+	}> {
 		if (!this.config.pluginManager) return { override: null, retry: false }
 		let results: PluginHookResult[]
 		try {
@@ -2592,6 +2821,26 @@ export class ToolExecutor {
 				},
 				this.emitEvent,
 			)
+			// A failed call is announced a second time, by name, so a hook that
+			// only cares about failures need not read every result. After
+			// `post_tool_use`, so the existing hooks see exactly what they saw.
+			if (!toolResult.success) {
+				results = [
+					...results,
+					...(await this.config.pluginManager.executeHooks(
+						'post_tool_use_failure',
+						{
+							sessionId: this.config.sessionId,
+							turnId: this.config.turnId,
+							toolName,
+							toolInput: input,
+							toolResult,
+							signal: this.config.abortSignal,
+						},
+						this.emitEvent,
+					)),
+				]
+			}
 		} catch (error) {
 			if (!this.config.abortSignal.aborted) throw error
 			// The tool has already returned. Cancellation of a later redaction
@@ -2608,9 +2857,12 @@ export class ToolExecutor {
 		}
 		let override: PostToolOverride | null = null
 		let retry = false
+		const contexts: string[] = []
 		for (const result of results) {
 			switch (result.action) {
 				case 'continue':
+					if (result.context) contexts.push(result.context)
+					if (result.halt) this.requestHalt(result.halt.reason)
 					continue
 				case 'error':
 					override = { output: `Error: ${result.message}`, isError: true }
@@ -2646,7 +2898,11 @@ export class ToolExecutor {
 				}
 			}
 		}
-		return { override, retry }
+		return {
+			override,
+			retry,
+			...(contexts.length > 0 ? { context: contexts.join('\n') } : {}),
+		}
 	}
 
 	/**

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

@@ -53,6 +53,12 @@ export interface TurnFinalization {
 	 * immediately before the record is written.
 	 */
 	readonly takeSteps: () => readonly StepResult[]
+	/**
+	 * Whether the loop already fired `turn_end` (and `subagent_stop`) when the
+	 * model finished, so a hook could keep the turn going. Fired there, it is
+	 * not fired again here.
+	 */
+	readonly turnEndHooksFired?: () => boolean
 	readonly workingStateManager: WorkingStateManager | undefined
 	readonly resultAssembler: ResultAssembler
 	readonly rootSpan: Span
@@ -71,7 +77,7 @@ export async function* finalizeTurn(
 		rootSpan,
 	} = finalization
 
-	if (params.pluginManager) {
+	if (params.pluginManager && finalization.turnEndHooksFired?.() !== true) {
 		const hookResults = await params.pluginManager.executeHooks(
 			'turn_end',
 			{ sessionId: ctx.sessionId, turnId: ctx.turnId, signal: ctx.abortController.signal },