@namzu/sdk 49.0.0 → 50.0.0

package/src/runtime/query/iteration/outstanding-work.ts

@@ -1,6 +1,7 @@
 import { NAMZU } from '../../../constants/telemetry/index.js'
 import { formatCompletionNotification } from '../../../scheduler/completion-inbox.js'
 import { DELEGATION_TIMEOUT_MS } from '../../../tools/coordinator/index.js'
+import type { TaskHandle } from '../../../types/agent/scheduler.js'
 import { createRuntimeContextMessage } from '../../../types/message/index.js'
 import type { SessionEvent } from '../../../types/session/index.js'
 import { readPositiveIntEnv } from '../../../utils/env.js'
@@ -160,7 +161,7 @@ export async function* holdForOutstandingWork(
 	ctx: IterationContext,
 	iterationNum: number,
 	hasToolCalls: boolean,
-	deliverInbound: () => number,
+	deliverInbound: () => number | Promise<number>,
 ): AsyncGenerator<SessionEvent, boolean> {
 	const inbox = ctx.completionInbox?.hasPendingWork ? ctx.completionInbox : undefined
 	const jobs = ctx.awaitedJobs?.hasPendingWork ? ctx.awaitedJobs : undefined
@@ -197,6 +198,7 @@ export async function* holdForOutstandingWork(
 			...(inbox ? [inbox.waitForArrival(graceMs, waiting.signal)] : []),
 			...(jobs ? [jobs.waitForArrival(graceMs, waiting.signal)] : []),
 			...(ctx.waitForInbound ? [ctx.waitForInbound(waiting.signal)] : []),
+			...(ctx.durableInbound?.wait ? [ctx.durableInbound.wait(waiting.signal)] : []),
 		])
 	} catch (error) {
 		if (!runSignal.aborted) throw error
@@ -206,6 +208,8 @@ export async function* holdForOutstandingWork(
 	}
 	runSignal.throwIfAborted()
 
+	// The arrival/inbound/grace race already decided how long this hold may
+	// wait. Pending tracking is not a reason to extend it or delay steering.
 	const arrived = ctx.completionInbox?.drain() ?? []
 	if (arrived.length > 0) {
 		ctx.recorder.pushMessage(
@@ -213,7 +217,7 @@ export async function* holdForOutstandingWork(
 		)
 	}
 	const exited = deliverAwaitedJobExits(ctx)
-	const inbound = deliverInbound()
+	const inbound = await deliverInbound()
 	if (arrived.length === 0 && !exited && inbound === 0) return false
 	await ctx.emitEvent({
 		type: 'iteration_completed',
@@ -264,6 +268,37 @@ export function deliverAwaitedJobExits(ctx: IterationContext): boolean {
 	return true
 }
 
+/** Await arrived tracking writes within the caller's existing turn deadline. */
+export async function drainArrivedTaskCompletions(ctx: IterationContext): Promise<TaskHandle[]> {
+	const inbox = ctx.completionInbox
+	if (!inbox) return []
+	const runSignal = ctx.abortController.signal
+	if (runSignal.aborted) return []
+	const remainingMs = ctx.guard.remainingUntilTimeoutMs()
+	if (remainingMs <= 0) return inbox.drain()
+	const waiting = new AbortController()
+	const abort = (): void => waiting.abort(runSignal.reason)
+	runSignal.addEventListener('abort', abort, { once: true })
+	if (runSignal.aborted) abort()
+	let timer: ReturnType<typeof setTimeout> | undefined
+	const armDeadline = (): void => {
+		const remaining = ctx.guard.remainingUntilTimeoutMs()
+		if (remaining <= 0) waiting.abort()
+		else if (Number.isFinite(remaining)) {
+			// Node timers cannot represent more than a signed 32-bit delay.
+			// Recheck long deadlines instead of truncating the turn's timeout.
+			timer = setTimeout(armDeadline, Math.min(remaining, 2_147_483_647))
+		}
+	}
+	armDeadline()
+	try {
+		return await inbox.drainAsync(waiting.signal)
+	} finally {
+		if (timer !== undefined) clearTimeout(timer)
+		runSignal.removeEventListener('abort', abort)
+	}
+}
+
 /**
  * Account for outstanding work on the way out: deliver what arrived, and
  * say what did not.
@@ -275,10 +310,11 @@ export function deliverAwaitedJobExits(ctx: IterationContext): boolean {
  *  - **What has already arrived is delivered.** It makes no false claim,
  *    and dropping it is pure loss — the message rides out on
  *    `Turn.messages`, so a host reads it and the next turn of a continued
- *    thread starts with it. This does NOT wait: a hold buys the model a
- *    turn in which to USE a result, and on an exit whose answer is already
- *    decided there is no such turn, so waiting would delay a settled answer
- *    to append text this turn will not read. The bounded hold stays where it
+ *    thread starts with it. A hold buys the model a turn in which to USE a
+ *    result; an exit whose answer is already decided has no such turn.
+ *    Pending tracking writes remain queued. The exit delivers only ready
+ *    completions, so it never delays a settled answer to append text this
+ *    turn will not read. The bounded hold stays where it
  *    was, on the exits that do have a turn left.
  *  - **What is still running is NAMED, not cancelled.** Giving up on a wait
  *    is a statement about the waiter, not about the work — the rule
@@ -320,7 +356,19 @@ export function recordAbandonedWork(ctx: IterationContext): void {
 }
 
 export function deliverArrivedCompletions(ctx: IterationContext): void {
-	const unheard = ctx.completionInbox?.drain() ?? []
+	let unheard: TaskHandle[]
+	try {
+		// No finalizer waits for persistence that may ignore cancellation.
+		// Pending gates stay queued and their tracking writes keep running.
+		unheard = ctx.completionInbox?.drain() ?? []
+	} catch (error) {
+		if (!ctx.abortController.signal.aborted) throw error
+		ctx.log.warn('Task tracking failed while the turn was cancelled; its result remains queued', {
+			[NAMZU.TURN_ID]: ctx.recorder.turnId,
+			'exception.message': error instanceof Error ? error.message : String(error),
+		})
+		return
+	}
 	if (unheard.length === 0) return
 
 	// Fix the turn's answer BEFORE appending anything after it.

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

@@ -17,6 +17,7 @@ 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 { CheckpointId } from '../../../../types/ids/index.js'
+import type { DurableInboundSource } from '../../../../types/message/inbound-delivery.js'
 import type { LLMProvider } from '../../../../types/provider/index.js'
 import type { TaskRouterConfig } from '../../../../types/router/index.js'
 import type { ReviewAnswer } from '../../../../types/session/answer-review.js'
@@ -106,6 +107,8 @@ export interface IterationContext {
 	readonly activityStore: ActivityStore
 	readonly emitEvent: EmitEvent
 	readonly drainPending: () => Generator<SessionEvent>
+	/** Internal live-event wake; omitted only by legacy phase fixtures. */
+	readonly onPendingEvents?: (listener: () => void) => () => void
 	readonly abortController: AbortController
 	readonly log: Logger
 	readonly resumeHandler: ResumeHandler
@@ -226,6 +229,7 @@ export interface IterationContext {
 	readonly resumedInput?: readonly import('../../../../types/message/index.js').Message[]
 	/** Observes pending input without draining it; abort releases the waiter. */
 	readonly waitForInbound?: (signal: AbortSignal) => Promise<void>
+	readonly durableInbound?: DurableInboundSource
 
 	/** Live project policy; separate from human inbound continuation. */
 	readonly projectInstructionContext?: ProjectInstructionContext

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

@@ -1,11 +1,12 @@
 import type { AuthorizationGate } from '../../../../authorization/index.js'
+import { isTrustedReadOnly } from '../../../../tools/trusted-read-only.js'
 import type { ToolSourceRef } from '../../../../toolsets/types.js'
-import type { ToolCallSummary } from '../../../../types/hitl/index.js'
+import type { 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, ToolCallDenials } from '../../executor.js'
+import type { PreparedToolBatch, ToolCallDeclines, ToolCallDenials } from '../../executor.js'
 import {
 	awaitProjectInstructionCallback,
 	replaceProjectInstructionSnapshot,
@@ -97,9 +98,13 @@ export async function* runToolReview(
 		return finish('executed')
 	}
 
-	const prepareForReview = async (): Promise<PreparedToolBatch | undefined> => {
+	const prepareForReview = async (
+		hostModifiedCallIds?: ReadonlySet<string>,
+	): Promise<PreparedToolBatch | undefined> => {
 		const prepare = ctx.toolExecutor.prepareBatchForReview
-		return typeof prepare === 'function' ? prepare.call(ctx.toolExecutor, response) : undefined
+		return typeof prepare === 'function'
+			? prepare.call(ctx.toolExecutor, response, hostModifiedCallIds)
+			: undefined
 	}
 	let preparedBatch = await prepareForReview()
 	const summariesFor = (prepared: PreparedToolBatch | undefined): ToolCallSummary[] => {
@@ -157,28 +162,51 @@ export async function* runToolReview(
 		return merged ?? denials
 	}
 
+	/** Set only where a person's No is known, so a policy refusal never lands in it. */
+	let declines: ToolCallDeclines | undefined
+
 	/** Executes the batch, answering every call, and appends the results. */
-	const settle = async (denials?: ToolCallDenials): Promise<void> => {
+	const settleBatch = async (denials?: ToolCallDenials): Promise<void> => {
 		const startedAt = Date.now()
 		const batch = await ctx.toolExecutor.executeBatch(
 			response,
 			withRepeatRefusals(denials),
 			undefined,
 			preparedBatch,
+			declines,
 		)
 		toolMs += Date.now() - startedAt
 		executed = batch.results
+		// Registry receipts are ordered by actual completion, include nested
+		// dispatches, and exclude denials/recovered results. A successful possible
+		// mutation permits another experiment; unrelated reads cannot do so.
+		for (const observation of batch.observations) {
+			const tracker = ctx.repeatCalls
+			if (!tracker) break
+			if (
+				observation.result.success &&
+				!isTrustedReadOnly(
+					ctx.tools.get(observation.toolName),
+					observation.input,
+					ctx.toolExecutor.toolSource(observation.toolName),
+				)
+			)
+				tracker.stateMayHaveChanged()
+			tracker.recordOutcome(observation.toolName, observation.input, {
+				failed: !observation.result.success,
+				result: {
+					output: observation.result.output,
+					error: observation.result.error,
+					content: observation.result.content,
+				},
+			})
+		}
 		// Recorded AFTER execution, with the real result: the notice advises
 		// on the call that already ran, and the failure count is what the
 		// refusal above reads on the NEXT identical call.
 		const notices = []
 		for (const summary of toolCallSummaries) {
-			const outcome = batch.results.find((result) => result.toolCallId === summary.id)
-			const notice = ctx.repeatCalls?.record(
-				summary.name,
-				summary.input,
-				outcome ? { failed: outcome.isError === true } : undefined,
-			)
+			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
@@ -231,8 +259,62 @@ export async function* runToolReview(
 		}
 	}
 
+	/** Stream recorded starts and progress while execution itself remains pending. */
+	const settle = async function* (
+		denials?: ToolCallDenials,
+	): AsyncGenerator<SessionEvent, void, unknown> {
+		if (!ctx.onPendingEvents) {
+			await settleBatch(denials)
+			return
+		}
+		const wakeup = () => {
+			let notify!: () => void
+			const promise = new Promise<void>((resolve) => {
+				notify = resolve
+			})
+			return { promise, notify }
+		}
+		let wake = wakeup()
+		let settled: { ok: true } | { ok: false; error: unknown } | undefined
+		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(
+			() => {
+				settled = { ok: true }
+				wake.notify()
+			},
+			(error) => {
+				settled = { ok: false, error }
+				wake.notify()
+			},
+		)
+		try {
+			while (true) {
+				yield* ctx.drainPending()
+				if (settled) break
+				await wake.promise
+				wake = wakeup()
+			}
+			if (!settled.ok) throw settled.error
+		} finally {
+			unsubscribe()
+			if (!settled) {
+				ctx.abortController.abort(
+					new DOMException(
+						'The query consumer stopped reading during tool execution.',
+						'AbortError',
+					),
+				)
+				// Tool cancellation and its receipts settle before the query can
+				// release the recorder, sandbox or other borrowed turn resources.
+				await execution
+			}
+		}
+	}
+
 	if (toolCallSummaries.length === 0) {
-		await settle()
+		yield* settle()
 		yield* ctx.drainPending()
 		return finish('executed')
 	}
@@ -264,7 +346,11 @@ export async function* runToolReview(
 		}
 		if (tc.escalation?.unknownProgram !== undefined) {
 			await ctx.recorder.recordAudit({
-				what: { action: 'unknown_program', tool: tc.name, resource: tc.escalation.unknownProgram },
+				what: {
+					action: 'unknown_program',
+					tool: tc.name,
+					resource: tc.escalation.unknownProgram,
+				},
 				outcome: 'refused',
 				reason,
 			})
@@ -366,7 +452,7 @@ export async function* runToolReview(
 			ctx.log.debug('Authorization gate: all tool calls pre-approved', {
 				'namzu.tool.names': gateResults.map((gr) => gr.toolCall.name),
 			})
-			await settle()
+			yield* settle()
 			yield* ctx.drainPending()
 			return finish('executed')
 		}
@@ -381,7 +467,7 @@ export async function* runToolReview(
 				const reason = gateDenied.get(tc.id)
 				if (reason !== undefined) await recordRefusedEscalation(tc, reason)
 			}
-			await settle(gateDenied)
+			yield* settle(gateDenied)
 			yield* ctx.drainPending()
 			return finish('rejected')
 		}
@@ -434,7 +520,7 @@ export async function* runToolReview(
 		ctx.log.debug('Every tool call is covered by an approval already granted', {
 			'namzu.tool.names': toolCallSummaries.map((tc) => tc.name),
 		})
-		await settle()
+		yield* settle()
 		yield* ctx.drainPending()
 		return finish('executed')
 	}
@@ -535,8 +621,15 @@ export async function* runToolReview(
 
 			const feedback = reviewDecision.feedback || DECLINED_TOOL_CALL_FEEDBACK
 			const denials = new Map(denyAll(feedback))
+			if (reviewDecision.declined) {
+				const declined: ToolCallDeclined = reviewDecision.declined
+				// A call the gate already refused was never the person's to decline.
+				declines = new Map(
+					toolCalls.filter((tc) => !gateDenied.has(tc.id)).map((tc) => [tc.id, declined]),
+				)
+			}
 			await settleEscalations(denials, undefined)
-			await settle(denials)
+			yield* settle(denials)
 			yield* ctx.drainPending()
 			return finish('rejected')
 		}
@@ -552,6 +645,7 @@ export async function* runToolReview(
 			// Gate denials are the floor; per-call human denials add to them.
 			const denials = new Map(gateDenied)
 			const modifiedCallIds = new Set<string>()
+			const humanDenied = new Map<string, ToolCallDeclined>()
 
 			for (const mod of reviewDecision.modifications) {
 				if (mod.action === 'modify' && mod.modifiedInput !== undefined) {
@@ -564,6 +658,8 @@ export async function* runToolReview(
 				}
 				if (mod.action === 'deny' && !denials.has(mod.toolCallId)) {
 					denials.set(mod.toolCallId, DECLINED_TOOL_CALL_FEEDBACK)
+					// A per-call deny is the person's own answer; gate denials above are not.
+					humanDenied.set(mod.toolCallId, {})
 				}
 			}
 
@@ -576,7 +672,7 @@ export async function* runToolReview(
 				preparedBatch =
 					preparedBatch && typeof reprepare === 'function'
 						? await reprepare.call(ctx.toolExecutor, response, preparedBatch, modifiedCallIds)
-						: await prepareForReview()
+						: await prepareForReview(modifiedCallIds)
 				toolCallSummaries = summariesFor(preparedBatch)
 			}
 			if (ctx.verificationGate && modifiedCallIds.size > 0) {
@@ -606,7 +702,8 @@ export async function* runToolReview(
 
 			await settleEscalations(denials, reviewDecision.confirmedEscalations)
 			const everythingDenied = denials.size === toolCalls.length
-			await settle(denials)
+			if (humanDenied.size > 0) declines = humanDenied
+			yield* settle(denials)
 			yield* ctx.drainPending()
 			return finish(everythingDenied ? 'rejected' : 'executed')
 		}
@@ -680,7 +777,7 @@ export async function* runToolReview(
 				denials,
 				reviewDecision.action === 'approve_tools' ? reviewDecision.confirmedEscalations : undefined,
 			)
-			await settle(denials)
+			yield* settle(denials)
 			yield* ctx.drainPending()
 			return finish(denials.size === toolCalls.length ? 'rejected' : 'executed')
 		}
@@ -696,7 +793,7 @@ export async function* runToolReview(
 			})
 			const denials = new Map(gateDenied)
 			await settleEscalations(denials, undefined)
-			await settle(denials)
+			yield* settle(denials)
 			yield* ctx.drainPending()
 			return finish('executed')
 		}

package/src/runtime/query/observation-context.ts

@@ -3,7 +3,7 @@ import { findRetainedIndices } from '../../compaction/retention.js'
 import { estimateMessageTokens } from '../../compaction/token-estimate.js'
 import { isClearedToolResult } from '../../compaction/tool-result-editing.js'
 import type { ToolManager } from '../../toolsets/manager.js'
-import type { Message, ToolMessage } from '../../types/message/index.js'
+import type { Message, ToolCall, ToolMessage } from '../../types/message/index.js'
 
 /**
  * Request-only exact observation masking. Every reference targets a full result
@@ -15,14 +15,19 @@ export function projectObservationContext(
 	messages: Message[],
 	tools: Pick<ToolManager, 'get'>,
 	preserveToolResultsFrom: readonly string[] = [],
+	observationKey?: (call: ToolCall, message: ToolMessage) => string | undefined,
 ): Message[] {
-	const calls = new Map<string, { name: string; arguments: string } | null>()
+	// Historical model input is not a new tool invocation. Its schema may contain
+	// refinements, transforms or defaults with effects, so only an executor-owned
+	// record of an actual observation may authorize request-only masking.
+	if (!observationKey) return messages
+	const calls = new Map<string, ToolCall | null>()
 	for (const message of messages) {
 		if (message.role !== 'assistant') continue
 		for (const call of message.toolCalls ?? []) {
 			// Ambiguous IDs cannot prove which observation belongs to which call.
 			if (calls.has(call.id)) calls.set(call.id, null)
-			else calls.set(call.id, call.metadata?.inputTruncated ? null : call.function)
+			else calls.set(call.id, call.metadata?.inputTruncated ? null : call)
 		}
 	}
 	const resultCounts = new Map<string, number>()
@@ -47,26 +52,27 @@ export function projectObservationContext(
 		)
 			continue
 		const call = calls.get(message.toolCallId)
-		if (!call || preserveToolResultsFrom.includes(call.name)) continue
-		const definition = tools.get(call.name)
-		if (!definition) continue
+		if (!call || preserveToolResultsFrom.includes(call.function.name)) continue
+		if (!tools.get(call.function.name)) continue
+		let executionKey: string | undefined
 		try {
-			const input = definition.inputSchema.safeParse(JSON.parse(call.arguments))
-			if (
-				!input.success ||
-				definition.isReadOnly?.(input.data) !== true ||
-				definition.isDestructive?.(input.data) === true
-			)
-				continue
+			executionKey = observationKey(call, message)
 		} catch {
-			// Classification is advisory; invalid input or a broken custom predicate
-			// must leave evidence intact, not abort the request.
+			// Missing or broken trusted classification leaves the full result intact.
 			continue
 		}
+		if (executionKey === undefined) continue
 		// Exact arguments intentionally: equivalent JSON with different formatting
 		// is a missed optimization, not permission to merge different file ranges.
 		const key = createHash('sha256')
-			.update(JSON.stringify([call.name, call.arguments, message.content]))
+			.update(
+				JSON.stringify([
+					call.function.name,
+					call.function.arguments,
+					message.content,
+					executionKey,
+				]),
+			)
 			.digest('hex')
 		const representative = representatives.get(key)
 		if (!representative) {

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

@@ -371,7 +371,7 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 	// The preflight refuses an already foreign log before opening a budget or
 	// draining queued topic messages. Repeat after claiming the writer lease:
 	// another process may have opened a log that was empty at preflight time.
-	await assertSessionLogAttribution(storage.log, params)
+	await assertSessionLogAttribution(storage.log, params, { execution: 'kernel' })
 	const preludeLease = await PreludeSessionLease.acquire(
 		storage.log,
 		params.sessionId,
@@ -381,7 +381,7 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 	let releaseOwnedLease = () => preludeLease.release()
 	try {
 		await preludeLease.assertCurrent()
-		await assertSessionLogAttribution(storage.log, params)
+		await assertSessionLogAttribution(storage.log, params, { execution: 'kernel' })
 		const savedBudget = await savedBudgetReference(params, turnId, storage, selectedResumeState)
 		const budget = await resolveQueryBudget(params, turnId, storage.tokenBudget, savedBudget)
 		const log = TurnContextFactory.buildLogger({

package/src/runtime/query/prompt-cache.ts

@@ -20,6 +20,7 @@ export interface PromptCacheInput {
 	basePrompt?: string
 	tools: ToolManager
 	allowedTools?: string[]
+	sandboxed?: boolean
 	runtimeContext?: AgentRuntimeContext
 	contributions?: PromptContributionRegistry
 }
@@ -46,6 +47,7 @@ export class PromptCache {
 			basePrompt: input.basePrompt,
 			tools: input.tools,
 			allowedTools: input.allowedTools,
+			sandboxed: input.sandboxed,
 			runtimeContext: input.runtimeContext,
 			...(input.contributions ? { contributions: input.contributions } : {}),
 		})
@@ -83,6 +85,7 @@ export class PromptCache {
 			basePrompt: input.basePrompt,
 			tools: input.tools,
 			allowedTools: input.allowedTools,
+			sandboxed: input.sandboxed,
 			runtimeContext: input.runtimeContext,
 			...(input.contributions ? { contributions: input.contributions } : {}),
 		})

package/src/runtime/query/prompt.ts

@@ -29,6 +29,8 @@ export interface PromptBuilderConfig {
 
 	tools: ToolManager
 	allowedTools?: string[]
+	/** Command-tool dialects describe guest tools when a sandbox is supplied. */
+	sandboxed?: boolean
 	runtimeContext?: AgentRuntimeContext
 	/**
 	 * What else goes in the prompt, beyond what this builder knows about.
@@ -46,7 +48,7 @@ function buildEnvContext(workingDirectory: string, config: PromptBuilderConfig):
 	const lines = [
 		`<env>
 Working directory: ${workingDirectory}
-Platform: ${process.platform}`,
+${config.sandboxed ? 'Host platform' : 'Platform'}: ${process.platform}`,
 	]
 
 	if (runtimeContext?.label) {
@@ -121,6 +123,29 @@ function hasFilesystemTools(tools: ToolManager, allowedTools?: string[]): boolea
 	})
 }
 
+/** The actual execution dialect, independent of the host operating system. */
+function buildShellContext(config: PromptBuilderConfig): string | undefined {
+	const lines: string[] = []
+	for (const name of config.allowedTools ?? config.tools.listNames()) {
+		const tool = config.tools.get(name)
+		if (
+			!tool?.commandArgument ||
+			!tool.commandDialect ||
+			config.tools.availability(name) !== 'active'
+		)
+			continue
+		const dialect = tool.commandDialect({ sandboxed: config.sandboxed === true })
+		lines.push(
+			`Execution shell for ${name}: ${dialect}${config.sandboxed ? ' (sandbox guest)' : ' (host)'}.`,
+		)
+		if (dialect === 'cmd')
+			lines.push(
+				'Use native Windows CMD command syntax. Single quotes do not quote arguments; backslashes do not escape shell operators. PowerShell syntax requires explicitly invoking PowerShell. Command-specific automatic permission grants are unavailable; an exact-call review may be required.',
+			)
+	}
+	return lines.length > 0 ? lines.join('\n') : undefined
+}
+
 export class PromptBuilder {
 	private config: PromptBuilderConfig
 
@@ -250,6 +275,9 @@ export class PromptBuilder {
 		// `${static}\n\n---\n\n${dynamic}`. The two methods produce the same
 		// prompt for the same input, and a turn that hits the prompt cache
 		// must not be asking a different question from one that misses it.
+		const shellContext = buildShellContext(this.config)
+		if (shellContext) parts.push(shellContext)
+
 		parts.push(...this.renderContributions('static', workingDirectory))
 		parts.push(...this.renderContributions('dynamic', workingDirectory))
 
@@ -311,6 +339,9 @@ export class PromptBuilder {
 			}
 		}
 
+		const shellContext = buildShellContext(this.config)
+		if (shellContext) dynamicParts.push(shellContext)
+
 		staticParts.push(...this.renderContributions('static', workingDirectory))
 		dynamicParts.push(...this.renderContributions('dynamic', workingDirectory))