@namzu/sdk 51.1.0 → 52.1.0

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

@@ -12,6 +12,7 @@ import {
 	replaceProjectInstructionSnapshot,
 } from '../../project-instructions.js'
 import { attachRepeatNotice } from '../../repeat-call.js'
+import { isReviewExempt } from '../../review-policy.js'
 import { attachNotice, attachSteering, formatJobNote } from '../../steering.js'
 import { type IterationContext, awaitDecisionDurably } from './context.js'
 
@@ -25,11 +26,23 @@ function escalationReason(escalation: ToolCallSummary['escalation']): string {
 		return `this call's program cannot be verified ahead of time (${escalation.unknownProgram})`
 	}
 	if (escalation?.sandboxEscape) return "this call asks to run outside the turn's sandbox"
+	if (escalation?.dangerousRemoval !== undefined) {
+		return `this call removes something catastrophic (${escalation.dangerousRemoval})`
+	}
+	if (escalation?.protectedPaths?.length) {
+		return `this call writes a protected ${escalation.protectedPaths.length === 1 ? 'path' : 'paths'} (${escalation.protectedPaths.join(', ')})`
+	}
 	if (escalation?.outsidePaths?.length)
 		return `this call reaches ${escalation.outsidePaths.length === 1 ? 'a path' : 'paths'} outside the turn's boundary`
 	return "this call reaches past the turn's boundary, which a rule cannot approve on its own"
 }
 
+function hookAskedReason(reason: string | undefined): string {
+	return reason
+		? `a hook asked that a person approve this call: ${reason}`
+		: 'a hook asked that a person approve this call'
+}
+
 export type ToolReviewDecision = 'executed' | 'rejected' | 'stop'
 
 /**
@@ -124,15 +137,27 @@ export async function* runToolReview(
 			const isDestructive = tool?.isDestructive ? tool.isDestructive(tc.input) : false
 			const requiresApproval = tool?.requiresApproval ? tool.requiresApproval(tc.input) : false
 			const escalation = 'escalation' in tc ? tc.escalation : undefined
+			const hookPermission = 'hookPermission' in tc ? tc.hookPermission : undefined
 
 			return {
 				id: tc.id,
 				name: tc.name,
 				input: tc.input,
 				isDestructive,
-				authorization: { decision: 'review' },
+				// A hook that asked for a person is an explicit review: a call the
+				// tool declares read-only, or one a rule would allow, is still put
+				// to one.
+				authorization:
+					hookPermission?.decision === 'ask'
+						? {
+								decision: 'review' as const,
+								reason: hookAskedReason(hookPermission.reason),
+								explicitReview: true as const,
+							}
+						: { decision: 'review' as const },
 				...(requiresApproval ? { requiresApproval: true as const } : {}),
 				...(escalation ? { escalation } : {}),
+				...(hookPermission ? { hookPermission } : {}),
 			}
 		})
 	}
@@ -355,6 +380,24 @@ export async function* runToolReview(
 				reason,
 			})
 		}
+		for (const path of tc.escalation?.protectedPaths ?? []) {
+			await ctx.recorder.recordAudit({
+				what: { action: 'protected_path_write', tool: tc.name, resource: path },
+				outcome: 'refused',
+				reason,
+			})
+		}
+		if (tc.escalation?.dangerousRemoval !== undefined) {
+			await ctx.recorder.recordAudit({
+				what: {
+					action: 'dangerous_removal',
+					tool: tc.name,
+					resource: tc.escalation.dangerousRemoval,
+				},
+				outcome: 'refused',
+				reason,
+			})
+		}
 	}
 
 	// Gate-denied ids survive the whole function: a later human approval
@@ -419,11 +462,21 @@ export async function* runToolReview(
 					reason: `${gr.gateResult.reason}; but the tool itself declares this call always needs a person's approval, which a rule cannot waive`,
 				}
 			}
+			// A hook that asked for a person can only ADD a review, like the two
+			// overrides above: a `deny` stays a denial.
+			const hookAsked = gr.toolCall.hookPermission?.decision === 'ask'
+			if (hookAsked && gr.gateResult.decision === 'allow') {
+				gr.gateResult = {
+					decision: 'review',
+					matchedRule: gr.gateResult.matchedRule,
+					reason: `${gr.gateResult.reason}; but ${hookAskedReason(gr.toolCall.hookPermission?.reason)}`,
+				}
+			}
 			const { toolCall, gateResult } = gr
 			toolCall.authorization = {
 				decision: gateResult.decision,
 				...(gateResult.reason ? { reason: gateResult.reason } : {}),
-				...(gateResult.decision === 'review' && gateResult.matchedRule
+				...(gateResult.decision === 'review' && (gateResult.matchedRule || hookAsked)
 					? { explicitReview: true as const }
 					: {}),
 			}
@@ -498,6 +551,27 @@ export async function* runToolReview(
 		}
 	}
 
+	// A `pre_tool_use` hook's `allow`, marked on the calls it covers on the
+	// same terms as a skill's grant above and honoured by the review policy,
+	// never decided here. A deny, an explicit review (a rule's, or a hook's own
+	// `ask`), a destructive call, a path outside the roots, a sandbox escape and
+	// a tool's own `requiresApproval` all leave the call unmarked, so it is
+	// reviewed as though no hook had spoken.
+	/** Whether a hook's `allow` may stand in for a person on this call. */
+	const hookMayAllow = (tc: ToolCallSummary): boolean =>
+		!gateDenied.has(tc.id) &&
+		tc.authorization?.decision !== 'deny' &&
+		!tc.authorization?.explicitReview &&
+		!tc.isDestructive &&
+		tc.escalation === undefined &&
+		!tc.requiresApproval
+	for (const tc of toolCallSummaries) {
+		if (tc.hookPermission?.decision !== 'allow' || !hookMayAllow(tc)) continue
+		tc.hookGrant = {
+			...(tc.hookPermission.reason ? { reason: tc.hookPermission.reason } : {}),
+		}
+	}
+
 	// Already approved, at a scope the approver chose — and nothing the
 	// operator's policy denied, because `gateDenied` is checked first.
 	// Re-asking about a call somebody has already said yes to is how an
@@ -525,6 +599,76 @@ export async function* runToolReview(
 		return finish('executed')
 	}
 
+	// A person is about to be asked. `permission_request` hooks may answer
+	// first, per call: `skip` refuses it (and always wins), `allow` approves it
+	// on the same terms as a `pre_tool_use` allow. A read the review policy
+	// would not have asked about is not a question and is not offered.
+	if (ctx.pluginManager) {
+		const questions = toolCallSummaries.filter(
+			(tc) =>
+				!gateDenied.has(tc.id) &&
+				tc.authorization?.decision !== 'deny' &&
+				tc.authorization?.decision !== 'allow' &&
+				(tc.authorization?.explicitReview === true ||
+					tc.escalation !== undefined ||
+					tc.requiresApproval === true ||
+					tc.isDestructive ||
+					!isReviewExempt(ctx.tools, tc.name, tc.input)),
+		)
+		for (const tc of questions) {
+			const answers = await ctx.pluginManager.executeHooks(
+				'permission_request',
+				{
+					sessionId: ctx.recorder.sessionId,
+					turnId: ctx.recorder.turnId,
+					toolName: tc.name,
+					toolInput: tc.input,
+					signal: ctx.abortController.signal,
+				},
+				ctx.emitEvent,
+			)
+			// The hooks answered side by side: a refusal from any of them stands,
+			// whatever the others allowed.
+			const refusal = answers.find((answer) => answer.action === 'skip')
+			for (const answer of answers) {
+				if ((answer.action === 'continue' || answer.action === 'skip') && answer.halt) {
+					ctx.toolExecutor.requestHalt?.(answer.halt.reason)
+				}
+			}
+			if (refusal?.action === 'skip') {
+				const reason = `Blocked by a permission_request hook: ${refusal.reason}`
+				gateDenied.set(tc.id, reason)
+				tc.authorization = { decision: 'deny', reason }
+				await ctx.recorder.recordAudit({
+					what: { action: 'tool_call', tool: tc.name },
+					outcome: 'refused',
+					reason,
+				})
+				continue
+			}
+			for (const answer of answers) {
+				if (
+					answer.action === 'continue' &&
+					answer.permission?.decision === 'allow' &&
+					hookMayAllow(tc)
+				) {
+					tc.hookGrant = {
+						...(answer.permission.reason ? { reason: answer.permission.reason } : {}),
+					}
+				}
+			}
+		}
+		if (toolCallSummaries.every((tc) => gateDenied.has(tc.id))) {
+			for (const tc of escalated()) {
+				const reason = gateDenied.get(tc.id)
+				if (reason !== undefined) await recordRefusedEscalation(tc, reason)
+			}
+			yield* settle(gateDenied)
+			yield* ctx.drainPending()
+			return finish('rejected')
+		}
+	}
+
 	const reviewCheckpoint = await ctx.checkpointMgr.create(ctx.recorder, iterationNum)
 
 	await ctx.emitEvent({
@@ -607,6 +751,24 @@ export async function* runToolReview(
 					reason: "the turn's review approved this call",
 				})
 			}
+			for (const path of tc.escalation?.protectedPaths ?? []) {
+				await ctx.recorder.recordAudit({
+					what: { action: 'protected_path_write', tool: tc.name, resource: path },
+					outcome: 'approved',
+					reason: "the turn's review approved this call",
+				})
+			}
+			if (tc.escalation?.dangerousRemoval !== undefined) {
+				await ctx.recorder.recordAudit({
+					what: {
+						action: 'dangerous_removal',
+						tool: tc.name,
+						resource: tc.escalation.dangerousRemoval,
+					},
+					outcome: 'approved',
+					reason: "the turn's review approved this call",
+				})
+			}
 		}
 	}
 
@@ -762,6 +924,19 @@ export async function* runToolReview(
 				}
 			}
 
+			// The same for a call a hook's `allow` approved.
+			if (reviewDecision.action === 'approve_tools' && reviewDecision.hookGranted) {
+				const listed = new Set(reviewDecision.hookGranted)
+				for (const tc of toolCallSummaries) {
+					if (!listed.has(tc.id) || !tc.hookGrant || gateDenied.has(tc.id)) continue
+					await ctx.recorder.recordAudit({
+						what: { action: 'tool_call', tool: tc.name },
+						outcome: 'approved',
+						reason: `pre-approved by a pre_tool_use hook${tc.hookGrant.reason ? ` (${tc.hookGrant.reason})` : ''}; nobody was asked`,
+					})
+				}
+			}
+
 			await ctx.emitEvent({
 				type: 'tool_review_completed',
 				turnId: ctx.recorder.turnId,

package/src/runtime/query/iteration/provider-rejected-image.ts

@@ -1,4 +1,5 @@
 import { isProviderRequestError } from '../../../provider/errors.js'
+import { isImageInputRefusal } from '../../../provider/image-input-refusal.js'
 import type { Message } from '../../../types/message/index.js'
 import type {
 	ChatCompletionParams,
@@ -8,8 +9,11 @@ import type {
 import {
 	type RequestImageIdentity,
 	findSingleRequestImage,
+	projectRequestRichContent,
 	projectRequestWithoutImage,
+	requestHasImages,
 } from '../request-rich-content.js'
+import type { RequestRepair } from './request-repair.js'
 
 const IMAGE_REJECTION_PATTERNS: readonly RegExp[] = [
 	/\binvalid[_ -]?image\b/i,
@@ -52,6 +56,24 @@ function throwIfAborted(signal: AbortSignal | undefined): void {
 	if (signal?.aborted) throw signal.reason
 }
 
+/** The provider and model that refused a request for holding an image. */
+export interface TextOnlyModelRefusal {
+	readonly providerId: string
+	readonly model: string | undefined
+}
+
+/** See {@link streamWithProviderRejectedImageRecovery}. */
+export interface TextOnlyModelRecovery {
+	/**
+	 * Who is serving the request. A fallback chain reports its head's id and
+	 * moves between members, so without this the refusal would be filed against
+	 * a model that never saw the request. Read when the refusal arrives.
+	 */
+	readonly servedBy?: () => { readonly providerId: string; readonly model?: string }
+	/** The retry without images was accepted: `refused` cannot read images. */
+	readonly onAccepted: (refused: TextOnlyModelRefusal) => void | Promise<void>
+}
+
 /**
  * Retry one provider-invalid request without its only distinct image.
  *
@@ -65,29 +87,73 @@ export async function* streamWithProviderRejectedImageRecovery(
 	params: ChatCompletionParams,
 	onAccepted: (identity: RequestImageIdentity) => Promise<void>,
 	onRequest?: (messages: readonly Message[]) => void,
+	textOnly?: TextOnlyModelRecovery,
+	repair?: RequestRepair,
 ): AsyncIterable<StreamChunk> {
+	// Every send, including the retries below, goes through the request repair.
+	// They share one repair budget: the original request and its retries are
+	// one request to the person, and each resend is a paid call.
+	const session = repair?.session()
+	const send = (request: ChatCompletionParams): AsyncIterable<StreamChunk> =>
+		repair ? repair.stream(provider, request, session) : provider.chatStream(request)
 	const candidate = findSingleRequestImage(params.messages)
 	onRequest?.(params.messages)
-	if (candidate === null) {
-		yield* provider.chatStream(params)
+	if (candidate === null && !requestHasImages(params.messages)) {
+		yield* send(params)
 		return
 	}
 
 	let produced = false
 	let confidence: ImageRejectionConfidence | null = null
+	let refused: TextOnlyModelRefusal | null = null
 	try {
-		for await (const chunk of provider.chatStream(params)) {
+		for await (const chunk of send(params)) {
 			if (isAcceptedChunk(chunk)) produced = true
 			yield chunk
 		}
 		return
 	} catch (error) {
 		throwIfAborted(params.signal)
+		if (produced) throw error
+		// A fault in one image (the server's own `invalid_image`, or wording that
+		// says an image could not be decoded) is about that image, not about the
+		// model, and it wins: the model reads images, so it keeps the others.
 		confidence = classifyProviderRejectedImageError(error)
-		if (produced || confidence === null) throw error
+		if (confidence === null && isImageInputRefusal(error)) {
+			// A model that reads text only refuses the request however many images
+			// it holds, so every image goes. Named now, while the member that
+			// refused is still the one serving.
+			const served = textOnly?.servedBy?.()
+			refused = {
+				providerId: served?.providerId ?? provider.id,
+				model: served?.model ?? params.model,
+			}
+		} else if (confidence === null || candidate === null) {
+			throw error
+		}
 	}
 
 	throwIfAborted(params.signal)
+	if (refused !== null) {
+		// One retry, without any image. The stored conversation is untouched, so
+		// a model that does read images gets them again.
+		const messages = projectRequestRichContent(params.messages, 0, { imagesReadable: false })
+		onRequest?.(messages)
+		let accepted = false
+		let reportedError = false
+		for await (const chunk of send({ ...params, messages })) {
+			if (chunk.error !== undefined) reportedError = true
+			if (!accepted && isAcceptedChunk(chunk)) {
+				throwIfAborted(params.signal)
+				await textOnly?.onAccepted(refused)
+				accepted = true
+			}
+			yield chunk
+		}
+		if (!accepted && !reportedError) await textOnly?.onAccepted(refused)
+		return
+	}
+	if (candidate === null) return
 	const retryParams: ChatCompletionParams = {
 		...params,
 		messages: projectRequestWithoutImage(params.messages, candidate),
@@ -95,7 +161,7 @@ export async function* streamWithProviderRejectedImageRecovery(
 	let accepted = false
 	let retryReportedError = false
 	onRequest?.(retryParams.messages)
-	for await (const chunk of provider.chatStream(retryParams)) {
+	for await (const chunk of send(retryParams)) {
 		if (chunk.error !== undefined) retryReportedError = true
 		if (!accepted && isAcceptedChunk(chunk)) {
 			throwIfAborted(params.signal)