@namzu/sdk 53.2.2 → 55.0.0

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

@@ -2,20 +2,35 @@ 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'
-import type { ToolCallDeclined, ToolCallSummary } from '../../../../types/hitl/index.js'
+import type {
+	HITLResumeDecision,
+	ToolCallDeclined,
+	ToolCallSummary,
+} from '../../../../types/hitl/index.js'
 import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
 import type { SessionEvent } from '../../../../types/session/index.js'
 import type { ShellDialect } from '../../../../types/tool/index.js'
 import { DECLINED_TOOL_CALL_FEEDBACK } from '../../declined.js'
-import type { PreparedToolBatch, ToolCallDeclines, ToolCallDenials } from '../../executor.js'
+import type {
+	PreparedToolBatch,
+	ReviewedExecution,
+	ToolCallDeclines,
+	ToolCallDenials,
+} from '../../executor.js'
 import {
 	awaitProjectInstructionCallback,
 	replaceProjectInstructionSnapshot,
 } from '../../project-instructions.js'
 import { attachRepeatNotice } from '../../repeat-call.js'
 import { isReviewExempt } from '../../review-policy.js'
-import { attachNotice, attachSteering, formatJobNote, formatMonitorNote } from '../../steering.js'
+import {
+	formatJobNote,
+	formatMonitorNote,
+	takeNoticeMessage,
+	takeSteeringMessage,
+} from '../../steering.js'
 import { type IterationContext, awaitDecisionDurably } from './context.js'
+import { PerCallReview } from './per-call-review.js'
 
 interface VerificationAwareContext extends IterationContext {
 	readonly verificationGate?: AuthorizationGate
@@ -197,7 +212,10 @@ export async function* runToolReview(
 	let declines: ToolCallDeclines | undefined
 
 	/** Executes the batch, answering every call, and appends the results. */
-	const settleBatch = async (denials?: ToolCallDenials): Promise<void> => {
+	const settleBatch = async (
+		denials?: ToolCallDenials,
+		review?: ReviewedExecution,
+	): Promise<void> => {
 		const startedAt = Date.now()
 		const batch = await ctx.toolExecutor.executeBatch(
 			response,
@@ -205,6 +223,7 @@ export async function* runToolReview(
 			undefined,
 			preparedBatch,
 			declines,
+			review,
 		)
 		toolMs += Date.now() - startedAt
 		executed = batch.results
@@ -240,40 +259,42 @@ export async function* runToolReview(
 			const notice = ctx.repeatCalls?.record(summary.name, summary.input)
 			if (notice) notices.push(notice)
 		}
-		// Guidance the host queued while this batch was running rides out on
-		// the last result. This is the only legal slot for it: a `tool_use`
-		// block must be answered by a `tool_result` with the same id, so a
-		// user message wedged between them is rejected by the provider. Same
-		// delivery a denial already uses, without the refusal.
+		// What the host or the kernel queued while this batch was running reaches
+		// the model as messages of their own right after the batch. A tool result
+		// stays what the tool returned: instructions written into it read as tool
+		// output, and a `tool_use` block still gets its `tool_result` first.
 		let jobNoticeDelivered = false
 		let monitorNoticeDelivered = false
-		for (const msg of attachRepeatNotice(
-			attachNotice(
-				attachNotice(
-					attachSteering(batch.messages, ctx.steering, ctx.onSteeringDelivered),
-					ctx.jobNotices,
-					formatJobNote,
-					// The exits that text accounts for have now been read, so the
-					// record of them stops being pending work. Left standing, it
-					// buys the model a turn the next time any job queues a notice.
-					() => {
-						ctx.awaitedJobs?.noticesDelivered()
-						jobNoticeDelivered = true
-					},
-				),
-				ctx.monitorNotices,
-				formatMonitorNote,
-				// Same rule for what a monitor said: read here, so a turn holding
-				// itself open for the monitor does not spend a turn re-reading it.
-				() => {
-					ctx.awaitedJobs?.monitorNoticesDelivered()
-					monitorNoticeDelivered = true
-				},
-			),
-			notices,
-		)) {
+		for (const msg of attachRepeatNotice(batch.messages, notices)) {
 			ctx.recorder.pushMessage(msg)
 		}
+		const steering = takeSteeringMessage(batch.messages, ctx.steering, ctx.onSteeringDelivered)
+		if (steering) ctx.recorder.pushMessage(steering)
+		const jobNotice = takeNoticeMessage(
+			batch.messages,
+			ctx.jobNotices,
+			formatJobNote,
+			// The exits that text accounts for have now been read, so the
+			// record of them stops being pending work. Left standing, it
+			// buys the model a turn the next time any job queues a notice.
+			() => {
+				ctx.awaitedJobs?.noticesDelivered()
+				jobNoticeDelivered = true
+			},
+		)
+		if (jobNotice) ctx.recorder.pushMessage(jobNotice)
+		const monitorNotice = takeNoticeMessage(
+			batch.messages,
+			ctx.monitorNotices,
+			formatMonitorNote,
+			// Same rule for what a monitor said: read here, so a turn holding
+			// itself open for the monitor does not spend a turn re-reading it.
+			() => {
+				ctx.awaitedJobs?.monitorNoticesDelivered()
+				monitorNoticeDelivered = true
+			},
+		)
+		if (monitorNotice) ctx.recorder.pushMessage(monitorNotice)
 		if (jobNoticeDelivered) ctx.onJobNoticeDelivered?.()
 		if (monitorNoticeDelivered) ctx.onMonitorNoticeDelivered?.()
 		// The complete tool-result batch is already in history before host policy
@@ -305,9 +326,10 @@ export async function* runToolReview(
 	/** Stream recorded starts and progress while execution itself remains pending. */
 	const settle = async function* (
 		denials?: ToolCallDenials,
+		review?: ReviewedExecution,
 	): AsyncGenerator<SessionEvent, void, unknown> {
 		if (!ctx.onPendingEvents) {
-			await settleBatch(denials)
+			await settleBatch(denials, review)
 			return
 		}
 		const wakeup = () => {
@@ -322,7 +344,7 @@ export async function* runToolReview(
 		const unsubscribe = ctx.onPendingEvents(() => wake.notify())
 		// Start the captured batch before yielding. Live observation must not
 		// create a new mutation window before execution validates its payload.
-		const execution = settleBatch(denials).then(
+		const execution = settleBatch(denials, review).then(
 			() => {
 				settled = { ok: true }
 				wake.notify()
@@ -711,24 +733,6 @@ export async function* runToolReview(
 		}
 	}
 
-	const reviewCheckpoint = await ctx.checkpointMgr.create(ctx.recorder, iterationNum)
-
-	await ctx.emitEvent({
-		type: 'tool_review_requested',
-		turnId: ctx.recorder.turnId,
-		toolCalls: toolCallSummaries,
-		iteration: iterationNum,
-	})
-	yield* ctx.drainPending()
-
-	const reviewDecision = await awaitDecisionDurably(ctx, reviewCheckpoint, {
-		type: 'tool_review',
-		sessionId: ctx.recorder.sessionId,
-		turnId: ctx.recorder.turnId,
-		checkpointId: reviewCheckpoint.id,
-		toolCalls: toolCallSummaries,
-	})
-
 	/**
 	 * The escalations this decision lets through, on the record, and the
 	 * escapes it did not confirm, refused.
@@ -742,8 +746,9 @@ export async function* runToolReview(
 	const settleEscalations = async (
 		denials: Map<string, string>,
 		confirmed: readonly string[] | undefined,
+		only?: readonly ToolCallSummary[],
 	): Promise<void> => {
-		for (const tc of escalated()) {
+		for (const tc of only ? only.filter((call) => call.escalation !== undefined) : escalated()) {
 			const denied = denials.get(tc.id)
 			if (denied !== undefined) {
 				// A crossing that was asked about and refused is on the record
@@ -825,6 +830,105 @@ export async function* runToolReview(
 		}
 	}
 
+	/**
+	 * The record of calls approved without anyone being asked: by a skill's
+	 * `allowed-tools`, or by a `pre_tool_use` hook's `allow`. Only a call that
+	 * carried the mark counts: a policy that lists an unmarked id has not been
+	 * given a skill's or a hook's word for it.
+	 */
+	const recordGrantAudits = async (
+		decision: HITLResumeDecision,
+		calls: readonly ToolCallSummary[],
+	): Promise<void> => {
+		if (decision.action !== 'approve_tools') return
+		if (decision.skillGranted) {
+			const listed = new Set(decision.skillGranted)
+			for (const tc of calls) {
+				if (!listed.has(tc.id) || !tc.skillGrant || gateDenied.has(tc.id)) continue
+				await ctx.recorder.recordAudit({
+					what: { action: 'tool_call', tool: tc.name },
+					outcome: 'approved',
+					reason: `pre-approved by the allowed-tools of skill "${tc.skillGrant.skill}" for this turn; nobody was asked`,
+				})
+			}
+		}
+		if (decision.hookGranted) {
+			const listed = new Set(decision.hookGranted)
+			for (const tc of calls) {
+				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`,
+				})
+			}
+		}
+	}
+
+	// Opt-in: ask about one call at a time while the batch runs. Everything
+	// above has already run on the batch as a whole, because those checks are
+	// about the calls and not about who answers.
+	if (ctx.perCallReview) {
+		const reviewedIds = new Set(toolCallSummaries.map((tc) => tc.id))
+		const walk = new PerCallReview({
+			ctx,
+			iteration: iterationNum,
+			toolCalls,
+			summaries: () => toolCallSummaries,
+			gateDenied,
+			reviewAllowed,
+			unreviewedIds: new Set(
+				preparedBatch ? toolCalls.filter((tc) => !reviewedIds.has(tc.id)).map((tc) => tc.id) : [],
+			),
+			settleEscalations,
+			recordGrantAudits,
+			evaluateGate: (tc) =>
+				ctx.verificationGate?.evaluate({
+					toolName: tc.name,
+					toolInput: tc.input,
+					toolDef: ctx.tools.get(tc.name),
+					...dialectFor(tc.name),
+					...sourceFor(tc.name),
+				}).decision,
+		})
+		try {
+			await walk.askTogetherFirst()
+			const denials = new Map([...gateDenied, ...walk.denials])
+			if (walk.declines.size > 0) declines = walk.declines
+			yield* settle(denials, walk)
+			yield* ctx.drainPending()
+			if (walk.endsTurn) {
+				// Every call is answered by now. The turn stops the way an
+				// interrupt stops it, so nothing downstream reads the stop as a
+				// result the model should react to.
+				ctx.recorder.setStopReason('cancelled')
+				ctx.recorder.markCancelled()
+				return finish('stop')
+			}
+			return finish(denials.size + walk.refusedCount >= toolCalls.length ? 'rejected' : 'executed')
+		} finally {
+			walk.dispose()
+		}
+	}
+
+	const reviewCheckpoint = await ctx.checkpointMgr.create(ctx.recorder, iterationNum)
+
+	await ctx.emitEvent({
+		type: 'tool_review_requested',
+		turnId: ctx.recorder.turnId,
+		toolCalls: toolCallSummaries,
+		iteration: iterationNum,
+	})
+	yield* ctx.drainPending()
+
+	const reviewDecision = await awaitDecisionDurably(ctx, reviewCheckpoint, {
+		type: 'tool_review',
+		sessionId: ctx.recorder.sessionId,
+		turnId: ctx.recorder.turnId,
+		checkpointId: reviewCheckpoint.id,
+		toolCalls: toolCallSummaries,
+	})
+
 	switch (reviewDecision.action) {
 		case 'reject_tools': {
 			await ctx.emitEvent({
@@ -846,6 +950,12 @@ export async function* runToolReview(
 			await settleEscalations(denials, undefined)
 			yield* settle(denials)
 			yield* ctx.drainPending()
+			if (reviewDecision.endTurn) {
+				// Every call is answered above; the turn then stops as an interrupt does.
+				ctx.recorder.setStopReason('cancelled')
+				ctx.recorder.markCancelled()
+				return finish('stop')
+			}
 			return finish('rejected')
 		}
 
@@ -961,34 +1071,9 @@ export async function* runToolReview(
 			if (reviewDecision.action === 'approve_tools' && reviewDecision.remember) {
 				ctx.toolGrants?.grant(reviewDecision.remember)
 			}
-			// A call nobody was asked about, approved because a skill said so,
-			// is on the record naming that skill. Only a call that carried the
-			// mark counts: a policy that lists an unmarked id has not been
-			// given a skill's word for it.
-			if (reviewDecision.action === 'approve_tools' && reviewDecision.skillGranted) {
-				const listed = new Set(reviewDecision.skillGranted)
-				for (const tc of toolCallSummaries) {
-					if (!listed.has(tc.id) || !tc.skillGrant || gateDenied.has(tc.id)) continue
-					await ctx.recorder.recordAudit({
-						what: { action: 'tool_call', tool: tc.name },
-						outcome: 'approved',
-						reason: `pre-approved by the allowed-tools of skill "${tc.skillGrant.skill}" for this turn; nobody was asked`,
-					})
-				}
-			}
-
-			// 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`,
-					})
-				}
-			}
+			// A call nobody was asked about, approved because a skill or a hook
+			// said so, is on the record naming which.
+			await recordGrantAudits(reviewDecision, toolCallSummaries)
 
 			await ctx.emitEvent({
 				type: 'tool_review_completed',

package/src/runtime/query/iteration/step-context.ts

@@ -1,4 +1,6 @@
 import { createRuntimeContextMessage } from '../../../types/message/index.js'
+import type { Message } from '../../../types/message/index.js'
+import { isOperatorUserMessage } from '../steering.js'
 
 /**
  * Request-only context, as the model reads it: a runtime-context user
@@ -15,3 +17,30 @@ export function stepContextMessage(content: string) {
 		'step-context',
 	)
 }
+
+/**
+ * Put `blocks` in front of the operator's new message when that message is
+ * what the model is about to answer, so the request is the last thing it
+ * reads and the longest data comes before it. Only the reminders and other
+ * request-only context may follow that message: once the turn has an
+ * assistant or tool message after it, the blocks stay at the end of the
+ * history, where a caching driver ends its breakpoint before them, so the
+ * tool loop of a long turn is not re-read at full price on every step.
+ *
+ * Reminders and notices that follow the operator's message stay where they
+ * are: they are short, and the edge after the request is where they are read.
+ */
+export function placeBeforeLatestOperatorMessage(history: Message[], blocks: readonly Message[]) {
+	if (blocks.length === 0) return
+	let at = history.length
+	for (let i = history.length - 1; i >= 0; i--) {
+		const message = history[i] as Message
+		if (isOperatorUserMessage(message)) {
+			at = i
+			break
+		}
+		// A reply or a tool result after the message: the model has moved on.
+		if (message.role === 'assistant' || message.role === 'tool') break
+	}
+	history.splice(at, 0, ...blocks)
+}

package/src/runtime/query/iteration/step-shaping.ts

@@ -20,7 +20,7 @@ import { toErrorMessage } from '../../../utils/error.js'
 import { createCallbackInference } from '../callback-inference.js'
 import { measureContext } from './phases/compaction.js'
 import type { IterationContext } from './phases/index.js'
-import { stepContextMessage } from './step-context.js'
+import { placeBeforeLatestOperatorMessage, stepContextMessage } from './step-context.js'
 
 /**
  * How the next request is shaped: admission, preparation, and the context
@@ -58,6 +58,7 @@ export function appendWorkContext(
 		ctx.toolExecutor.describeFileEvidence(messages),
 	].filter((content): content is string => Boolean(content))
 	if (contributions.length === 0) return
+	const placed: Message[] = []
 	let room = stepContext(shaping, stepNumber, prepared).contextBudget?.remainingTokens ?? 0
 	// Leave room for the actual task; admit whole contributions, never dangling partial references.
 	if (room < 1_500) return
@@ -66,9 +67,12 @@ export function appendWorkContext(
 		const message = stepContextMessage(content)
 		const tokens = estimateMessageTokens(message)
 		if (tokens > Math.min(2_000, room - 1_000)) continue
-		messages.push(message)
+		placed.push(message)
 		room -= tokens
 	}
+	// Per-turn data goes in front of the operator's new message while that is
+	// what the model is answering, like the other blocks of request-only data.
+	placeBeforeLatestOperatorMessage(messages, placed)
 }
 
 export function stepContext(

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

@@ -53,7 +53,9 @@ import {
 	awaitProjectInstructionCallback,
 	collapseProjectInstructionSnapshots,
 	isProjectInstructionMessage,
+	latestProjectInstructionSnapshot,
 	replaceProjectInstructionSnapshot,
+	sameProjectInstructionSnapshot,
 } from './project-instructions.js'
 import type { PromptCache } from './prompt-cache.js'
 import { resolveMaxRequestRichContentBytes } from './request-rich-content.js'
@@ -640,11 +642,26 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 				// be erased merely because cancellation arrived before this catch ran.
 				if (!preparationSignal.aborted || error !== preparationSignal.reason) throw error
 			}
-			if (snapshot !== undefined) {
+			// The snapshot a conversation already holds stays where it is. Moving an
+			// unchanged copy to this turn's front would rewrite everything after its
+			// old position on every request, so the provider's cache would reuse
+			// almost none of the history. Only a changed snapshot is sent again, at
+			// the tail just before the new message, and it replaces the old copy.
+			const standing = latestProjectInstructionSnapshot([
+				...history.map((entry) => entry.message),
+				...resolvedInitialMessages,
+			])
+			const unchanged =
+				snapshot !== undefined &&
+				snapshot !== null &&
+				standing !== undefined &&
+				sameProjectInstructionSnapshot(standing, snapshot)
+			if (snapshot !== undefined && !unchanged) {
 				resolvedInitialMessages = replaceProjectInstructionSnapshot(
 					resolvedInitialMessages,
 					snapshot,
 					'before-latest-user',
+					history.map((entry) => entry.message),
 				)
 			}
 		}

package/src/runtime/query/project-instructions.ts

@@ -126,10 +126,31 @@ function assertsProjectInstructionMessage(message: UserMessage): asserts message
 }
 
 /**
- * Keep only the latest structurally valid project snapshot, at its own
- * chronological position. Invalid tagged provenance refuses before a provider
- * can be called; an untrusted persisted object cannot acquire policy status by
- * spelling one discriminator.
+ * The line that opens a changed copy of the project instructions. The copy is
+ * complete, so the model can drop the earlier one outright.
+ */
+export const PROJECT_INSTRUCTION_UPDATE_HEADER =
+	'Updated project instructions. These replace the project instructions given earlier in this conversation in full; a rule that appears only in the earlier copy no longer applies.\n\n'
+
+function isUpdate(message: UserMessage): boolean {
+	return message.source?.type === 'project-instructions' && message.source.update === true
+}
+
+/** The policy text of a snapshot, without the header an update carries. */
+export function projectInstructionBody(message: UserMessage): string {
+	const content = typeof message.content === 'string' ? message.content : ''
+	return isUpdate(message) && content.startsWith(PROJECT_INSTRUCTION_UPDATE_HEADER)
+		? content.slice(PROJECT_INSTRUCTION_UPDATE_HEADER.length)
+		: content
+}
+
+/**
+ * Keep the project policy a request needs, each at its own chronological
+ * position. A plain snapshot supersedes every earlier one. A changed copy
+ * (`source.update`) supersedes the copies before it but leaves the first one
+ * in place, so the request keeps its shape up to the change. Invalid tagged
+ * provenance refuses before a provider can be called; an untrusted persisted
+ * object cannot acquire policy status by spelling one discriminator.
  */
 export function collapseProjectInstructionSnapshots(messages: readonly Message[]): Message[] {
 	let latest = -1
@@ -140,9 +161,21 @@ export function collapseProjectInstructionSnapshots(messages: readonly Message[]
 		latest = index
 	}
 	if (latest < 0) return [...messages]
+	const latestMessage = messages[latest] as UserMessage
+	// The base is the earliest copy, kept only while the latest is an update of it.
+	let base = -1
+	if (isUpdate(latestMessage)) {
+		for (let index = 0; index < latest; index += 1) {
+			const message = messages[index]
+			if (message && isProjectInstructionMessage(message)) {
+				base = index
+				break
+			}
+		}
+	}
 	return messages.flatMap((message, index) => {
 		if (message.role === 'user' && message.source?.type === 'project-instructions') {
-			return index === latest
+			return index === latest || index === base
 				? [message.retain === true ? message : { ...message, retain: true }]
 				: []
 		}
@@ -150,9 +183,42 @@ export function collapseProjectInstructionSnapshots(messages: readonly Message[]
 	})
 }
 
+function canonical(message: UserMessage): unknown {
+	// Through JSON, as the durable record went: an explicitly undefined field and
+	// a missing one are the same message.
+	return JSON.parse(
+		JSON.stringify({
+			content: projectInstructionBody(message),
+			attachments: message.attachments,
+			source: message.source ? { ...message.source, update: undefined } : message.source,
+			cacheHint: message.cacheHint,
+		}),
+	)
+}
+
+/** Whether two snapshots say the same thing, ignoring ids, timestamps and `retain`. */
+export function sameProjectInstructionSnapshot(a: UserMessage, b: UserMessage): boolean {
+	return isDeepStrictEqual(canonical(a), canonical(b))
+}
+
+/** The latest project-instruction snapshot in `messages`, if there is one. */
+export function latestProjectInstructionSnapshot(
+	messages: readonly Message[],
+): UserMessage | undefined {
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		const message = messages[index]
+		if (message && isProjectInstructionMessage(message)) return message
+	}
+	return undefined
+}
+
 /**
  * Replace project policy without mutating the caller's history.
  *
+ * The first copy a conversation holds keeps its place. A changed snapshot is
+ * sent as a complete update at the tail (`source.update`), which replaces the
+ * earlier updates and tells the model it supersedes the first copy; the
+ * request is unchanged up to the update, so a provider's cache still covers it.
  * Runtime updates append after the finalized tool batch. A host seeding a new
  * human turn uses `before-latest-user`, so the policy is context for that
  * request rather than a reply after it.
@@ -161,53 +227,68 @@ export function replaceProjectInstructionSnapshot(
 	messages: readonly Message[],
 	snapshot: UserMessage | null,
 	placement: 'append' | 'before-latest-user' = 'append',
+	/** Messages the conversation already holds ahead of `messages`; read for the first copy, never changed. */
+	held: readonly Message[] = [],
 ): Message[] {
 	if (snapshot) assertsProjectInstructionMessage(snapshot)
 	// Validate every tagged predecessor before removing it. A host-authoritative
 	// replacement must not turn malformed persisted provenance into a silent
 	// success merely because the bad record happens to be superseded.
 	const validated = collapseProjectInstructionSnapshots(messages)
-	let current: UserMessage | undefined
-	for (let index = validated.length - 1; index >= 0; index -= 1) {
-		const message = validated[index]
-		if (message && isProjectInstructionMessage(message)) {
-			current = message
-			break
-		}
-	}
+	const all = collapseProjectInstructionSnapshots([...held, ...messages])
+	const current = latestProjectInstructionSnapshot(all)
 	if (
 		snapshot !== null &&
 		current !== undefined &&
-		isDeepStrictEqual(
-			{
-				content: current.content,
-				attachments: current.attachments,
-				source: current.source,
-				cacheHint: current.cacheHint,
-			},
-			{
-				content: snapshot.content,
-				attachments: snapshot.attachments,
-				source: snapshot.source,
-				cacheHint: snapshot.cacheHint,
-			},
-		)
+		sameProjectInstructionSnapshot(current, snapshot)
 	) {
 		return validated
 	}
 	if (snapshot === null && current === undefined) return validated
-	const without = validated.filter(
-		(message) => !(message.role === 'user' && message.source?.type === 'project-instructions'),
-	)
+	const isPolicy = (message: Message): boolean =>
+		message.role === 'user' && message.source?.type === 'project-instructions'
+	const without = validated.filter((message) => !isPolicy(message))
 	if (!snapshot) return without
-	const retained = snapshot.retain === true ? snapshot : { ...snapshot, retain: true }
-	if (placement === 'append') return [...without, retained]
-	let insertion = without.length
-	for (let index = without.length - 1; index >= 0; index -= 1) {
-		if (without[index]?.role === 'user') {
-			insertion = index
-			break
+	const place = (list: readonly Message[], message: UserMessage): Message[] => {
+		if (placement === 'append') return [...list, message]
+		let insertion = list.length
+		for (let index = list.length - 1; index >= 0; index -= 1) {
+			if (list[index]?.role === 'user') {
+				insertion = index
+				break
+			}
 		}
+		return [...list.slice(0, insertion), message, ...list.slice(insertion)]
+	}
+	const base = all.find(
+		(message): message is UserMessage => isProjectInstructionMessage(message) && !isUpdate(message),
+	)
+	const body = projectInstructionBody(snapshot)
+	if (base === undefined) {
+		const first: UserMessage =
+			snapshot.retain === true && !isUpdate(snapshot)
+				? snapshot
+				: {
+						...snapshot,
+						content: body,
+						source: {
+							type: 'project-instructions',
+							files: snapshot.source.files,
+						},
+						retain: true,
+					}
+		return place(without, first)
+	}
+	const update: UserMessage = {
+		...snapshot,
+		content: PROJECT_INSTRUCTION_UPDATE_HEADER + body,
+		source: {
+			type: 'project-instructions',
+			files: snapshot.source.files,
+			update: true,
+		},
+		retain: true,
 	}
-	return [...without.slice(0, insertion), retained, ...without.slice(insertion)]
+	const kept = validated.filter((message) => !isPolicy(message) || message === base)
+	return place(kept, update)
 }