@namzu/sdk 52.4.0 → 52.5.0

package/src/runtime/query/auto-review/transcript.ts

@@ -0,0 +1,159 @@
+/**
+ * What the auto-review classifier is shown of the conversation.
+ *
+ * Three kinds of entry and no more: the person's own messages, the agent's
+ * prose, and one short line per tool call, written by the tool itself
+ * (`ToolDefinition.classifierInput`). Tool RESULTS are never included. A result
+ * is whatever a command printed or a page said, which is exactly where an
+ * injected instruction would sit, and a classifier that read it could be
+ * argued out of a block by the text it is supposed to be guarding against.
+ * Kernel-written context (project instructions, reminders, compaction summaries)
+ * is left out too: it was not written by the person.
+ */
+
+import type { ToolManager } from '../../../toolsets/manager.js'
+import type { Message } from '../../../types/message/index.js'
+
+/** One entry of the projected transcript, before it is rendered. */
+export type TranscriptEntry =
+	| { readonly kind: 'user'; readonly text: string }
+	| { readonly kind: 'assistant'; readonly text: string }
+	| { readonly kind: 'tool'; readonly name: string; readonly input: string }
+
+export interface ProjectionOptions {
+	/** Where tool definitions are looked up for `classifierInput`. Absent: every call is compact JSON. */
+	readonly tools?: Pick<ToolManager, 'get'>
+	/** Tool-call ids to leave out, because they are the action under review. */
+	readonly excludeCallIds?: ReadonlySet<string>
+	/** The most characters one entry keeps. Default 2000. */
+	readonly maxEntryChars?: number
+}
+
+const DEFAULT_ENTRY_CHARS = 2_000
+
+/**
+ * A file a host inlined into the person's message (`@path`). Its content is
+ * whatever the file says, not the person's words, so a second guard removes it
+ * even from a message that carries no provenance; the host's own marking
+ * (`source`) is the first.
+ */
+const INLINED_FILE_BLOCK = /<file\b[^>]*>[\s\S]*?<\/file>/gi
+
+function clip(text: string, limit: number): string {
+	return text.length <= limit
+		? text
+		: `${text.slice(0, limit)}... [${text.length - limit} more characters]`
+}
+
+function parseArguments(raw: string): unknown {
+	try {
+		return JSON.parse(raw)
+	} catch {
+		return raw
+	}
+}
+
+/** The line shown for a call, and whether it had to be cut to fit. */
+export interface ProjectedCall {
+	readonly text: string
+	/** The call is longer than the limit: `text` is a prefix and the rest was never shown. */
+	readonly truncated: boolean
+}
+
+/**
+ * The line shown for a call: the tool's own account of it, or the input as
+ * compact JSON when the tool has none or its account is empty or throws.
+ * `truncated` is true when what the tool (or the JSON) said was longer than
+ * `limit`, so a caller judging THIS call can refuse to judge a prefix of it.
+ */
+export function projectAction(
+	name: string,
+	input: unknown,
+	tools: Pick<ToolManager, 'get'> | undefined,
+	limit: number = DEFAULT_ENTRY_CHARS,
+): ProjectedCall {
+	const tool = tools?.get(name) ?? tools?.get(name.toLowerCase())
+	let text: string | undefined
+	if (tool?.classifierInput !== undefined) {
+		try {
+			const described = tool.classifierInput(input as never)
+			if (typeof described === 'string' && described.trim() !== '') text = described
+		} catch {
+			// A tool that cannot describe its own call is shown as its input.
+		}
+	}
+	if (text === undefined) {
+		try {
+			text = JSON.stringify(input) ?? ''
+		} catch {
+			text = String(input)
+		}
+	}
+	return { text: clip(text, limit), truncated: text.length > limit }
+}
+
+/** {@link projectAction}'s text, for a line of history where a cut is only context. */
+export function projectCall(
+	name: string,
+	input: unknown,
+	tools: Pick<ToolManager, 'get'> | undefined,
+	limit: number = DEFAULT_ENTRY_CHARS,
+): string {
+	return projectAction(name, input, tools, limit).text
+}
+
+/** The conversation as the classifier sees it, oldest first. */
+export function projectTranscript(
+	messages: readonly Message[],
+	options: ProjectionOptions = {},
+): TranscriptEntry[] {
+	const limit = options.maxEntryChars ?? DEFAULT_ENTRY_CHARS
+	const entries: TranscriptEntry[] = []
+	for (const message of messages) {
+		if (message.role === 'user') {
+			// A user-role message the kernel wrote (instructions, reminders, a goal
+			// round) is not the person speaking.
+			if (message.source !== undefined) continue
+			if (typeof message.content === 'string') {
+				const spoken = message.content.replace(INLINED_FILE_BLOCK, ' ').trim()
+				if (spoken !== '') entries.push({ kind: 'user', text: clip(spoken, limit) })
+			}
+			continue
+		}
+		if (message.role !== 'assistant') continue
+		if (typeof message.content === 'string' && message.content.trim() !== '') {
+			entries.push({ kind: 'assistant', text: clip(message.content, limit) })
+		}
+		for (const call of message.toolCalls ?? []) {
+			if (options.excludeCallIds?.has(call.id)) continue
+			entries.push({
+				kind: 'tool',
+				name: call.function.name,
+				input: projectCall(
+					call.function.name,
+					parseArguments(call.function.arguments),
+					options.tools,
+					limit,
+				),
+			})
+		}
+	}
+	return entries
+}
+
+/**
+ * One entry as a line of JSON, with `<` escaped so that nothing in it can
+ * close or open an element of the prompt around it.
+ */
+export function renderEntry(entry: TranscriptEntry): string {
+	const body =
+		entry.kind === 'tool' ? { tool: entry.name, input: entry.input } : { [entry.kind]: entry.text }
+	return JSON.stringify(body).replaceAll('<', '\\u003c')
+}
+
+/** The size of a rendered transcript, for the decision whether it is too long. */
+export function renderedLength(lines: readonly string[]): number {
+	let total = 0
+	for (const line of lines) total += line.length + 1
+	return total
+}

package/src/runtime/query/auto-review/verdict.ts

@@ -0,0 +1,50 @@
+/** Reading the classifier's answer. Anything that is not clearly a verdict is not one. */
+
+export interface ParsedVerdict {
+	readonly block: boolean
+	/** The name of the rule the classifier says applies, for a block. */
+	readonly rule?: string
+	/** One plain sentence, for a block. */
+	readonly reason?: string
+}
+
+const MAX_FIELD_CHARS = 300
+
+function field(text: string, name: string): string | undefined {
+	const pattern = new RegExp(`<${name}>([\\s\\S]*?)</${name}>`, 'gi')
+	let last: string | undefined
+	for (const match of text.matchAll(pattern)) last = match[1]
+	const value = last?.replace(/\s+/g, ' ').trim()
+	if (value === undefined || value === '') return undefined
+	return value.length > MAX_FIELD_CHARS ? `${value.slice(0, MAX_FIELD_CHARS)}...` : value
+}
+
+/**
+ * The verdict in `text`, or `undefined` when there is none to be read.
+ *
+ * Reasoning in a `<thinking>` element is removed first, so a verdict element
+ * the model merely discussed there does not count. Verdicts outside it must
+ * agree: an answer that both blocks and allows has no verdict, which the caller
+ * treats as a block, so a reply cannot be steered into allow by a verdict
+ * element the model was only quoting. The closing tag is optional because the first pass stops on it. A
+ * `<thinking>` that never closes means the answer was cut off before it
+ * decided, and reads as no verdict.
+ */
+export function parseVerdict(text: string): ParsedVerdict | undefined {
+	let visible = text.replace(/<thinking>[\s\S]*?<\/thinking>/gi, ' ')
+	if (/<thinking>/i.test(visible)) return undefined
+	visible = visible.trim()
+	const decisions = new Set<string>()
+	for (const match of visible.matchAll(/<verdict>\s*(block|allow)\b/gi)) {
+		decisions.add((match[1] as string).toLowerCase())
+	}
+	if (decisions.size !== 1) return undefined
+	if (decisions.has('allow')) return { block: false }
+	const rule = field(visible, 'rule')
+	const reason = field(visible, 'reason')
+	return {
+		block: true,
+		...(rule !== undefined ? { rule } : {}),
+		...(reason !== undefined ? { reason } : {}),
+	}
+}

package/src/runtime/query/executor.ts

@@ -1019,13 +1019,40 @@ export class ToolExecutor {
 				!hostModifiedCallIds?.has(toolCall.id),
 			)
 			calls.set(toolCall.id, call)
-			const escalation = await this.escalationOf(call)
+			const escalation = await this.escalationOrUnfinished(call)
 			if (escalation) escalations.set(toolCall.id, escalation)
 		}
 		this.config.abortSignal.throwIfAborted()
 		return this.publishPreparedBatch(calls, escalations)
 	}
 
+	/**
+	 * {@link escalationOf}, except that a check which itself throws is not
+	 * read as "nothing found". The failure becomes an escalation of its own
+	 * (`unfinishedCheck`), which no mode approves in advance: a call whose
+	 * safety checks did not run is the one a person must look at.
+	 */
+	private async escalationOrUnfinished(
+		call: PreparedDirectCall,
+	): Promise<ToolCallEscalation | undefined> {
+		try {
+			return await this.escalationOf(call)
+		} catch (error) {
+			this.config.abortSignal.throwIfAborted()
+			// A fixed sentence and a code, never the error's own message: this text
+			// goes into the audit trail and the prompt a person or the classifier
+			// reads, and a message can carry a path or a command line.
+			const code = (error as { code?: unknown } | null)?.code
+			const label =
+				typeof code === 'string' && /^[\w.-]{1,40}$/.test(code)
+					? code
+					: error instanceof Error && /^\w{1,40}$/.test(error.name)
+						? error.name
+						: 'unknown'
+			return { unfinishedCheck: `the safety checks did not finish (${label})` }
+		}
+	}
+
 	/**
 	 * What a prepared call reaches past the turn's boundary, decided on the
 	 * value that will execute — after repairs and pre-tool hooks, so a hook
@@ -1180,7 +1207,7 @@ export class ToolExecutor {
 			if (changedCallIds.has(toolCall.id)) {
 				const call = await prepareDirectCall(this.admissionHost(), toolCall, false)
 				calls.set(toolCall.id, call)
-				const escalation = await this.escalationOf(call)
+				const escalation = await this.escalationOrUnfinished(call)
 				if (escalation) escalations.set(toolCall.id, escalation)
 				else escalations.delete(toolCall.id)
 			}

package/src/runtime/query/index.ts

@@ -1535,7 +1535,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 						sessionId: ctx.sessionId,
 						turnId: ctx.turnId,
 						toolUseId,
-						parkHandler: (request) => approvalPolicy.current.handler(request),
+						parkHandler: (request, context) => approvalPolicy.current.handler(request, context),
 						recorder: questionParks,
 						pendingAnswers,
 					}),
@@ -1769,7 +1769,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			log: ctx.log,
 			// Read through the box on every call, so a swap lands on the next
 			// question rather than the next turn.
-			resumeHandler: (request) => approvalPolicy.current.handler(request),
+			resumeHandler: (request, context) => approvalPolicy.current.handler(request, context),
 			takeApprovalPolicyChange: () => approvalPolicy.takeUnannouncedChange(),
 			promptContributions,
 			...(params.steering ? { steering: params.steering } : {}),

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

@@ -15,7 +15,11 @@ import type { ActivityStore } from '../../../../store/activity/memory.js'
 import type { ToolManager } from '../../../../toolsets/manager.js'
 import type { TaskScheduler } from '../../../../types/agent/scheduler.js'
 import type { WorkingMemoryProvider } from '../../../../types/agent/working-memory.js'
-import type { HITLResumeDecision, ResumeHandler } from '../../../../types/hitl/index.js'
+import type {
+	HITLResumeDecision,
+	ResumeContext,
+	ResumeHandler,
+} from '../../../../types/hitl/index.js'
 import type { CheckpointId } from '../../../../types/ids/index.js'
 import type { DurableInboundSource } from '../../../../types/message/inbound-delivery.js'
 import type { LLMProvider } from '../../../../types/provider/index.js'
@@ -419,6 +423,15 @@ export async function awaitDecisionDurably(
  * turns into `setStopReason('cancelled') + markCancelled + stop`. Fails closed:
  * a resume-handler rejection also resolves to `abort` rather than hanging.
  */
+/** What a resume handler may read besides the request; see {@link ResumeContext}. */
+function resumeContextOf(ctx: IterationContext): ResumeContext {
+	const signal = ctx.abortController?.signal
+	return {
+		transcript: () => ctx.recorder.messages,
+		...(signal ? { signal } : {}),
+	}
+}
+
 export async function awaitDecisionOrAbort(
 	ctx: IterationContext,
 	request: Parameters<ResumeHandler>[0],
@@ -427,7 +440,8 @@ export async function awaitDecisionOrAbort(
 	// No abort signal wired (e.g. a minimal test harness) → behave exactly as a
 	// direct resumeHandler await, no race. In production TurnContextFactory always
 	// provides the controller, so the race below is live.
-	if (!signal) return ctx.resumeHandler(request)
+	const resumeContext = resumeContextOf(ctx)
+	if (!signal) return ctx.resumeHandler(request, resumeContext)
 	const abortDecision: HITLResumeDecision = {
 		action: 'abort',
 		reason: 'run aborted while parked for HITL',
@@ -441,7 +455,7 @@ export async function awaitDecisionOrAbort(
 			resolve(abortDecision)
 		}
 		signal.addEventListener('abort', onAbort, { once: true })
-		Promise.resolve(ctx.resumeHandler(request)).then(
+		Promise.resolve(ctx.resumeHandler(request, resumeContext)).then(
 			(decision) => {
 				if (settled) return
 				settled = true

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

@@ -1,3 +1,4 @@
+import { allowRuleScope } from '../../../../authorization/gate.js'
 import type { AuthorizationGate } from '../../../../authorization/index.js'
 import { isTrustedReadOnly } from '../../../../tools/trusted-read-only.js'
 import type { ToolSourceRef } from '../../../../toolsets/types.js'
@@ -22,6 +23,9 @@ interface VerificationAwareContext extends IterationContext {
 
 /** Why an escalated call cannot be waved through by the rule that would otherwise allow it. */
 function escalationReason(escalation: ToolCallSummary['escalation']): string {
+	if (escalation?.unfinishedCheck !== undefined) {
+		return `the safety checks on this call did not finish (${escalation.unfinishedCheck})`
+	}
 	if (escalation?.unknownProgram !== undefined) {
 		return `this call's program cannot be verified ahead of time (${escalation.unknownProgram})`
 	}
@@ -153,6 +157,8 @@ export async function* runToolReview(
 								decision: 'review' as const,
 								reason: hookAskedReason(hookPermission.reason),
 								explicitReview: true as const,
+								// Immune to a mode that auto-approves, as a rule's ask is.
+								askRule: true as const,
 							}
 						: { decision: 'review' as const },
 				...(requiresApproval ? { requiresApproval: true as const } : {}),
@@ -410,6 +416,17 @@ export async function* runToolReview(
 				reason,
 			})
 		}
+		if (tc.escalation?.unfinishedCheck !== undefined) {
+			await ctx.recorder.recordAudit({
+				what: {
+					action: 'unfinished_check',
+					tool: tc.name,
+					resource: tc.escalation.unfinishedCheck,
+				},
+				outcome: 'refused',
+				reason,
+			})
+		}
 	}
 
 	// Gate-denied ids survive the whole function: a later human approval
@@ -450,6 +467,9 @@ export async function* runToolReview(
 			}),
 		}))
 		for (const gr of gateResults) {
+			// Before the overrides below: only a rule that was WRITTEN to ask a
+			// person, not an allow demoted to a question, is an ask rule.
+			const ruleAsked = gr.gateResult.decision === 'review' && gr.gateResult.matchedRule !== null
 			// An `allow` rule was written about a tool, not about a path outside
 			// the working directory or a command outside the sandbox, which
 			// were refused outright when it was written. So an escalated call
@@ -491,6 +511,10 @@ export async function* runToolReview(
 				...(gateResult.decision === 'review' && (gateResult.matchedRule || hookAsked)
 					? { explicitReview: true as const }
 					: {}),
+				...(ruleAsked || hookAsked ? { askRule: true as const } : {}),
+				...(gateResult.decision === 'allow' && allowRuleScope(gateResult.matchedRule)
+					? { allowScope: allowRuleScope(gateResult.matchedRule) }
+					: {}),
 			}
 		}
 
@@ -601,6 +625,12 @@ export async function* runToolReview(
 		gateDenied.size === 0 &&
 		escalated().length === 0 &&
 		requiresApproval().length === 0 &&
+		// A remembered grant is an answer to an earlier question, never to an
+		// operator's ask rule or a hook's ask: those exist to put THIS call to a
+		// person each time.
+		toolCallSummaries.every(
+			(tc) => !tc.authorization?.askRule && !tc.authorization?.explicitReview,
+		) &&
 		toolCallSummaries.every((tc) => ctx.toolGrants?.covers(tc))
 	) {
 		ctx.log.debug('Every tool call is covered by an approval already granted', {
@@ -781,6 +811,17 @@ export async function* runToolReview(
 					reason: "the turn's review approved this call",
 				})
 			}
+			if (tc.escalation?.unfinishedCheck !== undefined) {
+				await ctx.recorder.recordAudit({
+					what: {
+						action: 'unfinished_check',
+						tool: tc.name,
+						resource: tc.escalation.unfinishedCheck,
+					},
+					outcome: 'approved',
+					reason: "the turn's review approved this call",
+				})
+			}
 		}
 	}
 

package/src/runtime/query/path-escalation.ts

@@ -16,7 +16,7 @@
  */
 
 import { homedir } from 'node:os'
-import { isAbsolute, relative, resolve } from 'node:path'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
 
 import { isProtectedPath } from '../../authorization/protected-paths.js'
 import { dangerousRemoval } from '../../authorization/removal.js'
@@ -156,14 +156,40 @@ export async function shellEscalations(
 	const protectedPaths = new Set<string>()
 	const home = homedir()
 	if (cwd !== undefined) {
+		// A link made earlier in this very line leads somewhere that cannot be
+		// read before the line runs: `ln -s /etc l && cd l && echo x > passwd`
+		// writes /etc/passwd through a name that is inside the roots. Every
+		// operand of an `ln` is such a name (the link is the last, but the
+		// check does not guess which), and a path at or under one is outside.
+		const madeHere = reading.invocations
+			.filter((invocation) => invocation.program === 'ln')
+			.flatMap((invocation) => invocation.args.map((arg) => arg.value))
+			.filter((value) => value !== '' && !value.startsWith('-'))
+			.map((value) => resolve(cwd, value))
 		for (const use of access.uses) {
 			for (const spelled of expandBraces(use.path)) {
 				const settled = settle(spelled, home)
 				const unresolved = use.unresolved || 'unresolved' in settled
 				const base = 'path' in settled ? settled.path : spelled
-				const absolute = isAbsolute(base) ? resolve(base) : resolve(cwd, base)
-				if (use.access === 'write' && (await isProtectedWrite(spelled, absolute, context.roots))) {
-					protectedPaths.add(absolute)
+				// Where a relative path may start from. Usually the directory the
+				// line began in; after a literal `cd <relative>` also the directory
+				// that moved to. Both are checked, because the `cd` may sit in a
+				// subshell or a pipeline and not apply to this command at all: a
+				// path is only called inside when it is inside under every reading.
+				const starts = [cwd]
+				const moved =
+					use.directory !== undefined && 'relative' in use.directory
+						? resolve(cwd, use.directory.relative)
+						: undefined
+				if (moved !== undefined) starts.push(moved)
+				const absolutes = isAbsolute(base)
+					? [resolve(base)]
+					: starts.map((from) => resolve(from, base))
+				if (use.access === 'write') {
+					for (const candidate of absolutes) {
+						if (await isProtectedWrite(spelled, candidate, context.roots))
+							protectedPaths.add(candidate)
+					}
 				}
 				if (!context.reviewOutside) continue
 				if (unresolved) {
@@ -173,18 +199,27 @@ export async function shellEscalations(
 					continue
 				}
 				if (
-					access.changesDirectory &&
+					use.directory !== undefined &&
+					'unknown' in use.directory &&
 					use.access === 'write' &&
 					!isAbsolute(base) &&
 					!spelled.startsWith('~')
 				) {
-					// A `cd` earlier in the line moves a relative target somewhere the
-					// roots cannot be compared with.
+					// A `cd` earlier in the line, to somewhere the reader cannot name,
+					// moves a relative target out of reach of a comparison with the roots.
 					outside.add(spelled)
 					continue
 				}
-				const reached = await pathOutsideRoots(context.roots, beforeGlob(absolute))
-				if (reached !== undefined) outside.add(reached)
+				for (const candidate of absolutes) {
+					if (
+						madeHere.some((link) => candidate === link || candidate.startsWith(`${link}${sep}`))
+					) {
+						outside.add(candidate)
+						continue
+					}
+					const reached = await pathOutsideRoots(context.roots, beforeGlob(candidate))
+					if (reached !== undefined) outside.add(reached)
+				}
 			}
 		}
 	}

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

@@ -535,6 +535,17 @@ export async function applyPendingResume(
 				reason: "the turn's review approved this call, answered across a restart",
 			})
 		}
+		if (call.escalation?.unfinishedCheck !== undefined) {
+			await recorder.recordAudit({
+				what: {
+					action: 'unfinished_check',
+					tool: call.name,
+					resource: call.escalation.unfinishedCheck,
+				},
+				outcome: 'approved',
+				reason: "the turn's review approved this call, answered across a restart",
+			})
+		}
 	}
 
 	// The parked assistant message is already in the log: it goes back into
@@ -589,6 +600,9 @@ export function escalationRefusal(
 	) {
 		return refusal
 	}
+	if (escalation.unfinishedCheck !== undefined && shown?.unfinishedCheck === undefined) {
+		return refusal
+	}
 	if (escalation.sandboxEscape && (!shown?.sandboxEscape || !confirmed?.includes(id))) {
 		return 'Refused after resume: running this command outside the sandbox needs a person to confirm it for this call, and the durable approval did not.'
 	}