@namzu/sdk 61.4.0 → 62.1.0

package/src/public-runtime.ts

@@ -591,6 +591,7 @@ export {
 	isMemoryName,
 	memoryIndexLine,
 	memoryLinkNames,
+	memoryOrigin,
 	renderMemoryIndex,
 	slugifyMemoryName,
 } from './store/index.js'
@@ -1498,6 +1499,7 @@ export {
 	isReviewExempt,
 	isReviewMode,
 	modeReviewsAllowedCalls,
+	mustAskPerson,
 } from './runtime/query/review-policy.js'
 // The model that decides, in the `classify` review mode, what a person would
 // otherwise be asked. See `runtime/query/auto-review/`.
@@ -1529,8 +1531,6 @@ export {
 	PromptContributionRegistry,
 	SKILLS_CONTRIBUTION_ID,
 	codingAgentDoctrineContribution,
-	createResidentStepContributions,
-	createResidentStepContext,
 	skillsContribution,
 } from './prompt/index.js'
 
@@ -1694,23 +1694,13 @@ export {
 	diffRequestContext,
 } from './runtime/query/request-context.js'
 
-export {
-	DiskResidentStore,
-	ResidentConflictError,
-} from './manager/resident/store.js'
-export { runResident, stepResident } from './manager/resident/loop.js'
-export { DiskResidentAgenda } from './manager/resident/agenda.js'
-export { inspectResidentConsumption } from './manager/resident/consumption.js'
-export { ResidentHost } from './manager/resident/host.js'
-
-export { createResidentSelector } from './manager/resident/initiative.js'
-export { validateResidentProposal } from './manager/resident/proposal.js'
-
-export { deliverResidentMessage } from './manager/resident/outbox.js'
-export { createResidentDeliveryWindow } from './manager/resident/delivery-window.js'
-
 export { hashLearningSkill, projectLearning } from './learning/skill.js'
 export { runLearningCycle } from './learning/cycle.js'
+export {
+	DiskLearningGuidance,
+	LearningGuidanceConflictError,
+	earlierGuidanceDirectory,
+} from './learning/guidance.js'
 export {
 	LEARNING_FLOOR_COMPONENTS,
 	LEARNING_SURFACE_KINDS,
@@ -1744,23 +1734,12 @@ export {
 	classifyEvidenceSource,
 	EVIDENCE_RECORD_GUIDANCE,
 } from './store/evidence/source-kind.js'
-export { createResidentToolEvidenceSource } from './manager/resident/tool-evidence.js'
-
-export { createResidentEvidenceRecallStep } from './manager/resident/evidence-recall.js'
 
 export {
 	SqliteLearningStore,
 	runStoredLearningCycle,
 	runStoredLearningFromObservations,
 } from './learning/store.js'
-export {
-	SqliteResidentLearningStore,
-	hashResidentSkill,
-	projectResidentLearning,
-	runResidentLearningCycle,
-	runStoredResidentLearningCycle,
-	runStoredResidentLearningFromObservations,
-} from './learning/deprecated.js'
 
 // ─── sessions, turns and the session log ─────────────────────────────────
 //

package/src/public-tools.ts

@@ -41,7 +41,6 @@ export type { UntrustedEnvelope, WrapUntrustedOptions } from './tools/untrusted-
 // ─── Built-in tools ──────────────────────────────────────────────────────
 
 export { getBuiltinTools } from './tools/builtins/index.js'
-export { buildResidentHistoryTools } from './tools/resident-history.js'
 // A host compiling operator permissions has a tool name and needs an argument
 // to attach a pattern to. Without one it can only match against the serialised
 // input, which is how an `allow` for `git status*` came to approve
@@ -270,7 +269,5 @@ export {
 	seedObservationLedger,
 } from './runtime/query/file-evidence-seed.js'
 
-export { buildResidentToolEvidenceTools } from './tools/resident-tool-evidence.js'
-
 export { createPalMessagingTools } from './pals/communication/tools.js'
 export { createPalOperatorMessagingTools } from './pals/communication/operator.js'

package/src/public-types.ts

@@ -218,6 +218,7 @@ export type {
 	MemoryContentRejection,
 	MemoryImportOutcome,
 	RenderedMemoryIndex,
+	MemoryOrigin,
 	Timestamped,
 } from './store/index.js'
 
@@ -457,6 +458,7 @@ export type {
 } from './runtime/query/auto-review/index.js'
 
 export type {
+	MustAskCall,
 	ReviewExemption,
 	ReviewMode,
 	ReviewPolicyOptions,
@@ -471,9 +473,6 @@ export type {
 	PromptContribution,
 	PromptContributionContext,
 	PromptPlacement,
-	ResidentStepPromptOptions,
-	ResidentStepContextOptions,
-	ResidentStepContextBundle,
 } from './prompt/index.js'
 
 export type {
@@ -532,89 +531,6 @@ export type {
 	RequestContextChange,
 } from './runtime/query/request-context.js'
 
-export type {
-	ResidentDecision,
-	ResidentState,
-	ResidentStore,
-} from './manager/resident/store.js'
-export type {
-	ResidentActivityScope,
-	ResidentAdmission,
-	ResidentSettlement,
-	ResidentActivityOptions,
-	ResidentActivityPage,
-	ResidentActivitySource,
-} from './manager/resident/activity.js'
-export type {
-	ResidentConsumptionReceipt,
-	ResidentConsumptionResolver,
-	ResidentConsumptionOptions,
-	ResidentConsumptionAttempt,
-	ResidentConsumptionReport,
-} from './manager/resident/consumption.js'
-export type {
-	ResidentHistoryScope,
-	ResidentHistoryAddress,
-	ResidentHistoryMatch,
-	ResidentHistorySearchOptions,
-	ResidentHistorySearchResult,
-	ResidentHistoryReadOptions,
-	ResidentHistoryText,
-	ResidentHistoryReadResult,
-	ResidentHistorySource,
-} from './manager/resident/history.js'
-export type {
-	ResidentStep,
-	ResidentStepResult,
-	ResidentLoopOptions,
-} from './manager/resident/loop.js'
-export type { ResidentExecutionStore } from './manager/resident/store.js'
-export type {
-	ResidentAgendaState,
-	ResidentAgendaStore,
-	ResidentPursuit,
-} from './manager/resident/agenda.js'
-export type {
-	ResidentHostResult,
-	ResidentHostRunOptions,
-	ResidentPursuitStep,
-} from './manager/resident/host.js'
-
-export type {
-	ResidentObservation,
-	ResidentFeedback,
-	ResidentSelectionConfig,
-	ResidentCandidate,
-	ResidentSelection,
-	ResidentSelector,
-} from './manager/resident/initiative.js'
-export type {
-	ResidentHostOptions,
-	ResidentObserver,
-} from './manager/resident/host.js'
-export type {
-	ResidentProposal,
-	ResidentProposalLimits,
-	ResidentProposalOrigin,
-} from './manager/resident/proposal.js'
-
-export type { ResidentMessageFactory } from './manager/resident/host.js'
-export type {
-	ResidentMessageInput,
-	ResidentOutboxMessage,
-	ResidentDeliveryOutcome,
-	ResidentOutboxStore,
-	ResidentDeliveryGate,
-	ResidentMessageTransport,
-	ResidentDeliveryOptions,
-	ResidentDeliveryResult,
-} from './manager/resident/outbox.js'
-export type { ResidentDeliveryWindowConfig } from './manager/resident/delivery-window.js'
-
-export type {
-	ResidentStepContext,
-	ResidentContextualStep,
-} from './manager/resident/host.js'
 export type {
 	LearningEvidence,
 	LearningSkillCandidate,
@@ -639,6 +555,10 @@ export type {
 	LearningCycleOptions,
 	LearningCycleResult,
 } from './learning/cycle.js'
+export type {
+	DiskLearningGuidanceOptions,
+	LearningGuidanceState,
+} from './learning/guidance.js'
 
 export type {
 	LearningModel,
@@ -669,13 +589,6 @@ export type {
 	LearningLeakSubject,
 } from './learning/leak-tripwire.js'
 
-export type {
-	ResidentArchiveRequest,
-	ResidentArchiveEntry,
-	ResidentArchivePage,
-	ResidentArchiveListOptions,
-} from './manager/resident/agenda.js'
-
 export type {
 	SessionEvidenceScope,
 	SessionEvidenceSourceOptions,
@@ -692,18 +605,7 @@ export type {
 	SessionTextEvidenceSource,
 } from './store/evidence/types.js'
 export type { EvidenceRecordKind } from './store/evidence/source-kind.js'
-export type {
-	ResidentToolEvidenceScope,
-	ResidentSettledInvocation,
-	ResidentToolEvidenceOptions,
-	ResidentToolEvidenceSearchOptions,
-	ResidentToolEvidenceSearchResult,
-	ResidentToolEvidenceReadOptions,
-	ResidentToolEvidenceReadResult,
-	ResidentToolEvidenceSource,
-} from './manager/resident/tool-evidence.js'
 
-export type { ResidentEvidenceRecallOptions } from './manager/resident/evidence-recall.js'
 export type {
 	JsonClaimValue,
 	JsonClaimRequirement,
@@ -871,36 +773,3 @@ export type {
 } from './pals/activity/subscription-policy.js'
 export type { PalActivitySubscriptionRunnerOptions } from './pals/activity/subscriptions.js'
 export type { PalActivityCausalityOptions } from './pals/activity/causality.js'
-
-// Deprecated resident-prefixed names, kept until the next major.
-export type {
-	ResidentLearningEvidence,
-	ResidentSkillCandidate,
-	ResidentLearnedSkill,
-	ResidentLearningState,
-	ResidentProfileUpdate,
-	ResidentSkillEvaluation,
-	ResidentLearningProjectionOptions,
-	ResidentLearningSource,
-	ResidentLearningProjection,
-	ResidentLearningStage,
-	ResidentLearningReceipt,
-	ResidentLearningConsumption,
-	ResidentLearningCycleEvent,
-	ResidentLearningCycleContext,
-	ResidentLearningGenerationContext,
-	ResidentLearningExplorationContext,
-	ResidentLearningExploration,
-	ResidentLearningEvaluationContext,
-	ResidentLearningCycleOptions,
-	ResidentLearningCycleResult,
-	SqliteResidentLearningStoreOptions,
-	ResidentLearningArtifact,
-	ResidentLearningRecordedUsage,
-	ResidentLearningCycleSummary,
-	ResidentLearningDiscoveryOptions,
-	ResidentLearningDiscoveryResult,
-	ResidentLearningObservation,
-	ResidentLearningObservationRecord,
-	ResidentLearningTarget,
-} from './learning/deprecated.js'

package/src/runtime/query/iteration/index.ts

@@ -42,9 +42,10 @@ import {
 	createToolMessage,
 } from '../../../types/message/index.js'
 import { classifyProviderError, readOutputOverflow } from '../../../types/provider/errors.js'
-import type { ChatCompletionResponse } from '../../../types/provider/index.js'
+import type { ChatCompletionResponse, ReasoningEffort } from '../../../types/provider/index.js'
 import type { AnswerReview, AnswerReviewContext } from '../../../types/session/answer-review.js'
 import type {
+	RecalledMemory,
 	SessionEvent,
 	StepFailure,
 	StepProvenance,
@@ -75,6 +76,15 @@ import {
 } from '../request-rich-content.js'
 import { withoutVoidAssistantTurns } from '../request-void-turns.js'
 import { formatSteeringNote, isOperatorUserMessage } from '../steering.js'
+import { COMPLETION_AUDIT_MESSAGE, CompletionAudit } from '../turn/completion-audit.js'
+import {
+	FORCED_STEP_MESSAGE,
+	REASONING_CAPPED_MESSAGE,
+	REASONING_ONLY_MESSAGE,
+	StallMonitor,
+	callChangedState,
+	reasoningCapChars,
+} from '../turn/stall-monitor.js'
 import { effortForModel } from './effort-clamp.js'
 import { parseNativeCandidate } from './native-output.js'
 import {
@@ -119,6 +129,9 @@ import {
 } from './step-shaping.js'
 import { streamProviderTurn } from './stream-turn.js'
 
+/** Capped steps in a row after which the per-step cap stops applying for the turn's next step. */
+const MAX_CAPPED_STREAK = 3
+
 type ReviewRequest = Pick<AnswerReviewContext, 'requestMessages' | 'latestUserMessage'>
 
 /** A host reviewer is not the model transport, even when its cause is an HTTP failure. */
@@ -299,6 +312,16 @@ export class IterationOrchestrator {
 	private stopDeferredForOutstandingWork = false
 	/** Nudges sent since the model last finished a call without hitting its output cap. */
 	private outputContinuations = 0
+	/** Watches the turn's steps for reasoning that piles up while nothing changes. */
+	private readonly stallMonitor?: StallMonitor
+	/** Holds the turn back once when it changed files and checked nothing afterwards. */
+	private readonly completionAudit?: CompletionAudit
+	/** The next step must call a tool, at low effort: set by the stall monitor or a capped step. */
+	private forceActionNextStep = false
+	/** Steps in a row cut at the per-step reasoning cap; past a few the cap stops applying. */
+	private cappedStreak = 0
+	/** A reply that held only reasoning was already answered with one more request. */
+	private reasoningOnlyRetried = false
 	/**
 	 * The model a refused request moved to. Once set it replaces the model the
 	 * step asked for, for the rest of the turn: the request that was refused
@@ -393,6 +416,10 @@ export class IterationOrchestrator {
 				this.rememberUserMessage(createRuntimeContextMessage(text, 'steering'))
 			},
 		}
+		if (ctx.turnConfig.completionAudit === true) this.completionAudit = new CompletionAudit()
+		if (ctx.turnConfig.reasoning?.stall !== false) {
+			this.stallMonitor = new StallMonitor(ctx.turnConfig.reasoning?.stall || undefined)
+		}
 		ctx.checkpointMgr.setLatestUserMessageSource(() => this.latestUserMessage)
 		ctx.checkpointMgr.setAnswerReviewAttemptsSource?.(() => this.answerReviewAttempts)
 		ctx.checkpointMgr.setStructuredReviewAttemptsSource?.(() => this.structuredReviewAttempts)
@@ -861,7 +888,16 @@ export class IterationOrchestrator {
 					// history now, after its last message, so this request and every
 					// later one begin with it. Nothing is inserted ahead of a message
 					// that is already recorded.
-					appendRecordedContext(recorder, step.recordedContext, this.ctx.log)
+					const recalled: RecalledMemory[] = []
+					appendRecordedContext(recorder, step.recordedContext, this.ctx.log, undefined, (item) =>
+						recalled.push(...(item.recalledMemories ?? [])),
+					)
+					if (recalled.length > 0)
+						await this.ctx.emitEvent?.({
+							type: 'memory_recalled',
+							turnId: recorder.turnId,
+							memories: recalled,
+						})
 					const baseMessages = recorder.messages
 
 					// Step guidance is appended to the REQUEST, never pushed onto
@@ -1063,6 +1099,11 @@ export class IterationOrchestrator {
 					// died part-way has already emitted both `message_started` and
 					// `message_completed` under this id, which is the trail a
 					// reader wants most on exactly that turn.
+					// A step the loop forces to act runs at low effort with a tool call
+					// required, for this step only. Low is used only where the model
+					// is known to offer it; effort is refused, not clamped.
+					const forcedAction = this.forceActionNextStep && !forceFinalize && llmTools.length > 0
+					this.forceActionNextStep = false
 					stepMessageId = generateMessageId()
 					const requestedMember = this.ctx.servingMember?.() ?? {
 						index: 0,
@@ -1092,12 +1133,30 @@ export class IterationOrchestrator {
 							})
 						}
 					}
+					// A forced action step runs at low effort, where the model is known
+					// to offer it; effort is refused, not clamped.
+					const offeredEfforts = this.ctx.provider.reasoningEffortLevelsFor?.(stepModel)
+					const stepEffort: ReasoningEffort | undefined =
+						forcedAction && requestEffort && (offeredEfforts?.includes('low') ?? false)
+							? 'low'
+							: requestEffort
+					// A provider that refuses a forced tool choice (some models do, and
+					// so does manual extended thinking) is not sent one: the step keeps
+					// its low effort and asks in words, on this request only.
+					const forcedChoiceRefused =
+						forcedAction &&
+						this.ctx.provider.acceptsForcedToolChoiceFor?.(stepModel, turnConfig.thinking) === false
 					const operatorInputAtDispatch = this.latestUserMessage
 					const latestReviewUserMessage =
 						(this.ctx.reviewAnswer || this.ctx.structuredOutput?.review) && operatorInputAtDispatch
 							? structuredClone(operatorInputAtDispatch)
 							: undefined
-					const { response, messageId, requestMessages } = yield* streamProviderTurn(
+					const {
+						response,
+						messageId,
+						requestMessages,
+						reasoningCapped = false,
+					} = yield* streamProviderTurn(
 						this.ctx.provider,
 						{
 							model: stepModel,
@@ -1114,7 +1173,9 @@ export class IterationOrchestrator {
 									}
 								: {}),
 							providerRoute: requestedRoute,
-							messages,
+							messages: forcedChoiceRefused
+								? [...messages, createRuntimeContextMessage(FORCED_STEP_MESSAGE, 'progress-nudge')]
+								: messages,
 							tools: llmTools.length > 0 ? llmTools : undefined,
 							...(enforceToolInputSchema ? { enforceToolInputSchema } : {}),
 							// The forced-final turn wins: a step that asked to force a
@@ -1126,14 +1187,16 @@ export class IterationOrchestrator {
 								forceFinalize && llmTools.length > 0
 									? 'none'
 									: llmTools.length > 0
-										? step.toolChoice
+										? forcedAction && !forcedChoiceRefused
+											? (step.toolChoice ?? 'required')
+											: step.toolChoice
 										: undefined,
 							temperature: step.temperature ?? turnConfig.temperature,
 							maxTokens:
 								outputCapOverride ?? step.maxResponseTokens ?? turnConfig.maxResponseTokens,
 							cacheControl: { type: 'auto' },
 							...(turnConfig.thinking ? { thinking: turnConfig.thinking } : {}),
-							...(requestEffort ? { effort: requestEffort } : {}),
+							...(stepEffort ? { effort: stepEffort } : {}),
 							...(!forceFinalize && turnConfig.webSearch
 								? { webSearch: turnConfig.webSearch }
 								: {}),
@@ -1159,8 +1222,15 @@ export class IterationOrchestrator {
 							this.ctx.reviewAnswer || this.ctx.structuredOutput?.review || this.ctx.advisoryCtx,
 						),
 						recorder.sessionId,
+						// Applies only to a step that can act. Stops after a few capped
+						// steps in a row, so a model that cannot act within the allowance
+						// still gets to finish.
+						this.cappedStreak >= MAX_CAPPED_STREAK || forceFinalize || llmTools.length === 0
+							? undefined
+							: reasoningCapChars(turnConfig.reasoning, stepEffort),
 					)
 					stepResponse = response
+					this.cappedStreak = reasoningCapped ? this.cappedStreak + 1 : 0
 					const reviewRequest: ReviewRequest = {
 						...(requestMessages ? { requestMessages } : {}),
 						...(latestReviewUserMessage ? { latestUserMessage: latestReviewUserMessage } : {}),
@@ -1461,6 +1531,28 @@ export class IterationOrchestrator {
 							costBefore,
 						})
 
+						// The step spent its whole reasoning allowance before acting. Tell
+						// the model so and make the next step an action step.
+						if (reasoningCapped && !forceFinalize) {
+							this.ctx.log.info('Reasoning reached the per-step cap — asking the model to act', {
+								[NAMZU.TURN_ID]: recorder.turnId,
+								[NAMZU.ITERATION]: iterationNum,
+							})
+							recorder.pushMessage(
+								createRuntimeContextMessage(REASONING_CAPPED_MESSAGE, 'progress-nudge'),
+							)
+							this.forceActionNextStep = true
+							this.observeStall(response, [])
+							await this.ctx.emitEvent({
+								type: 'iteration_completed',
+								turnId: recorder.turnId,
+								iteration: iterationNum,
+								hasToolCalls: false,
+							})
+							yield* this.ctx.drainPending()
+							continue
+						}
+
 						if (this.ctx.structuredOutput?.mode === 'native') {
 							const candidate = await parseNativeCandidate(
 								this.ctx.structuredOutput.schema,
@@ -1745,6 +1837,28 @@ export class IterationOrchestrator {
 						let closingStopReason: StopReason | undefined = forceFinalize
 							? guardResult.stopReason
 							: undefined
+						const reasoningOnly = !hasContent && (response.message.reasoning?.length ?? 0) > 0
+						if (hasContent) this.reasoningOnlyRetried = false
+						// A reply of reasoning alone is not an end: ask once more, plainly,
+						// before the closing request below.
+						if (reasoningOnly && !forceFinalize && !this.reasoningOnlyRetried) {
+							this.reasoningOnlyRetried = true
+							this.ctx.log.warn('Reply held reasoning only — asking once more', {
+								[NAMZU.TURN_ID]: recorder.turnId,
+								[NAMZU.ITERATION]: iterationNum,
+							})
+							recorder.pushMessage(
+								createRuntimeContextMessage(REASONING_ONLY_MESSAGE, 'progress-nudge'),
+							)
+							await this.ctx.emitEvent({
+								type: 'iteration_completed',
+								turnId: recorder.turnId,
+								iteration: iterationNum,
+								hasToolCalls: false,
+							})
+							yield* this.ctx.drainPending()
+							continue
+						}
 						if (!hasContent && !forceFinalize) {
 							this.ctx.log.warn('Empty completion detected — requesting final summary', {
 								[NAMZU.ITERATION]: iterationNum,
@@ -1755,6 +1869,23 @@ export class IterationOrchestrator {
 								'end_turn',
 							)
 							yield* this.ctx.drainPending()
+							// Never end silently: if even the closing request produced nothing,
+							// say so in plain words and how to go on.
+							if (
+								reasoningOnly &&
+								closingStopReason === undefined &&
+								!(
+									(
+										[...recorder.messages].reverse().find((m) => m.role === 'assistant') as
+											| { content?: string | null }
+											| undefined
+									)?.content ?? ''
+								).length
+							) {
+								recorder.setLastError(
+									'The model stopped after thinking without giving an answer or taking an action, even when asked again. Say "continue" and it will pick the work up from here.',
+								)
+							}
 						}
 
 						await this.ctx.emitEvent({
@@ -1787,6 +1918,21 @@ export class IterationOrchestrator {
 						// The model is done and has no tool calls. A `turn_end` (or
 						// `subagent_stop`) hook may refuse to let it be: its reason goes
 						// back to the model and the turn goes on.
+						// Files were changed and nothing checked them afterwards: ask once
+						// for a check before the turn is allowed to end.
+						if (
+							!forceFinalize &&
+							closingStopReason === undefined &&
+							this.completionAudit?.takeBlock()
+						) {
+							this.ctx.log.info('Files changed and nothing checked them — asking for a check', {
+								[NAMZU.TURN_ID]: recorder.turnId,
+							})
+							recorder.pushMessage(
+								createRuntimeContextMessage(COMPLETION_AUDIT_MESSAGE, 'progress-nudge'),
+							)
+							continue
+						}
 						if (!forceFinalize && closingStopReason === undefined) {
 							const feedback = yield* this.askStopHooks()
 							const stoppedByHook = this.ctx.toolExecutor.takeHalt?.()
@@ -1833,6 +1979,9 @@ export class IterationOrchestrator {
 						usageBefore,
 						costBefore,
 					})
+					this.reasoningOnlyRetried = false
+					this.observeStall(response, reviewOutcome.results)
+					this.observeAudit(response, reviewOutcome.results)
 
 					if (reviewOutcome.decision === 'stop') {
 						return
@@ -3118,6 +3267,69 @@ export class IterationOrchestrator {
 		}
 	}
 
+	/** Feed the completion audit the calls of one finished step. */
+	private observeAudit(
+		response: ChatCompletionResponse,
+		results: readonly ToolCallOutcome[],
+	): void {
+		const audit = this.completionAudit
+		if (!audit) return
+		const calls = new Map((response.message.toolCalls ?? []).map((c) => [c.id, c]))
+		audit.observe(
+			results.map((result) => {
+				let input: unknown
+				try {
+					const call = calls.get(result.toolCallId)
+					input = call ? JSON.parse(call.function.arguments) : undefined
+				} catch {
+					input = undefined
+				}
+				return { toolName: result.toolName, input, isError: result.isError }
+			}),
+		)
+	}
+
+	/**
+	 * Feed the stall monitor one finished step and act on its verdict: a nudge
+	 * is recorded as a message, a force makes the next step an action step.
+	 */
+	private observeStall(
+		response: ChatCompletionResponse,
+		results: readonly ToolCallOutcome[],
+	): void {
+		const monitor = this.stallMonitor
+		if (!monitor) return
+		const calls = new Map((response.message.toolCalls ?? []).map((c) => [c.id, c]))
+		let changedState = false
+		for (const result of results) {
+			const call = calls.get(result.toolCallId)
+			let readOnly: boolean | undefined
+			try {
+				const input = call ? JSON.parse(call.function.arguments) : undefined
+				readOnly = this.ctx.tools.get(result.toolName)?.isReadOnly?.(input)
+			} catch {
+				readOnly = undefined
+			}
+			if (callChangedState(result.toolName, readOnly, result.isError)) changedState = true
+		}
+		const reasoningChars = (response.message.reasoning ?? []).reduce(
+			(n, block) => n + (block.text?.length ?? 0),
+			0,
+		)
+		const directive = monitor.observe({ reasoningChars, changedState })
+		if (directive.kind === 'nudge') {
+			this.ctx.log.info('Many steps without a change — nudging the model to act', {
+				[NAMZU.TURN_ID]: this.ctx.recorder.turnId,
+			})
+			this.ctx.recorder.pushMessage(createRuntimeContextMessage(directive.text, 'progress-nudge'))
+		} else if (directive.kind === 'force') {
+			this.ctx.log.info('Still no change after the nudge — forcing an action step', {
+				[NAMZU.TURN_ID]: this.ctx.recorder.turnId,
+			})
+			this.forceActionNextStep = true
+		}
+	}
+
 	private async requestFinalResponse(
 		model: string,
 		reason: StopReason,

package/src/runtime/query/iteration/phases/per-call-review.ts

@@ -573,11 +573,13 @@ export class PerCallReview implements ReviewedExecution {
 				for (const call of calls) {
 					const mods = decision.modifications.filter((mod) => mod.toolCallId === call.id)
 					if (mods.some((mod) => mod.action === 'deny')) {
-						verdicts.set(call.id, {
-							run: false,
-							reason: DECLINED_TOOL_CALL_FEEDBACK,
-							declined: {},
-						})
+						const policy = decision.policyRefusals?.[call.id]
+						verdicts.set(
+							call.id,
+							policy !== undefined
+								? { run: false, reason: policy }
+								: { run: false, reason: DECLINED_TOOL_CALL_FEEDBACK, declined: {} },
+						)
 					} else if (mods.some((mod) => mod.action === 'modify')) {
 						verdicts.set(call.id, { run: false, reason: EDIT_NOT_OFFERED })
 					} else if (mods.some((mod) => mod.action === 'approve')) {

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

@@ -1127,9 +1127,11 @@ 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, {})
+					const policy = reviewDecision.policyRefusals?.[mod.toolCallId]
+					denials.set(mod.toolCallId, policy ?? DECLINED_TOOL_CALL_FEEDBACK)
+					// A per-call deny is the person's own answer; gate denials and a
+					// policy's refusal of one call are not.
+					if (policy === undefined) humanDenied.set(mod.toolCallId, {})
 				}
 			}
 

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

@@ -26,6 +26,7 @@ export function appendRecordedContext(
 	items: readonly RecordedContextItem[] | undefined,
 	log: Pick<Logger, 'warn'>,
 	at: Date = new Date(),
+	onAppended?: (item: RecordedContextItem) => void,
 ): Message[] {
 	const appended: Message[] = []
 	for (const item of items ?? []) {
@@ -43,6 +44,7 @@ export function appendRecordedContext(
 		const entry = createTurnContextEntry(item.key, text, at, { later: earlier.length > 0 })
 		recorder.pushMessage(entry)
 		appended.push(entry)
+		onAppended?.(item)
 	}
 	return appended
 }