@namzu/sdk 57.0.0 → 58.0.0

package/src/prompt/coding-agent-doctrine.ts

@@ -79,7 +79,8 @@ export const CODING_AGENT_WORKING_DOCTRINE = `## How you work
  */
 export const CODING_AGENT_DELEGATION_DOCTRINE = `### Planning and delegating
 - For work of three or more steps — several files, several distinct stages, anything you would write a checklist for — open a task list with \`task_create\` and keep it current with \`task_update\`, marking each step done when it is done rather than at the end. Skip it for a single inspect-edit-test cycle or a two-step job: the list is for the user to follow, and a list of one or two items tells them nothing.
-- When the \`Agent\` tool is available, delegate independent work through it and give each delegation a short, specific description; the user watches those descriptions, not the prompts. Brief each sub-agent with four things: the objective; what is out of bounds; which tools and sources to use; and the shape of the reply you want, such as a short summary with a file path for anything long. It starts with none of your context and returns what you ask for.
+- When the \`Agent\` tool is available, delegate independent work through it and give each delegation a short, specific description; the user watches those descriptions, not the prompts. Brief each sub-agent with four things: the objective; what is out of bounds; which tools and sources to use; and the shape of the reply you want, such as a short summary with a file path for anything long. A fresh sub-agent starts with none of your context and returns what you ask for.
+- When the \`Agent\` tool lists a \`fork\` type, use \`subagent_type: "fork"\` when a side task would fill your context with output you will not need again, such as an open-ended survey. A fork starts from this conversation under your own instructions, so its prompt is only the directive: what to do and where its scope ends, without the background. Never write or guess what a fork will find before its report arrives. A fork cannot start forks of its own.
 - When delegated agents finish, tell the user what each one found in your next message. Their results reach you and not the user, so a result you do not pass on stays unseen.
 - Delegate lookups — where something is defined, which files reference it, how a module works — with \`subagent_type: "explore"\`: it has reading and searching tools only and never interrupts the user for permission. Reserve the default sub-agent for work that changes files or runs commands.`
 

package/src/public-runtime.ts

@@ -485,6 +485,7 @@ export {
 	loadSkill,
 	resolveSkillChain,
 	SKILL_FRONTMATTER_KEYS,
+	SKILL_FRONTMATTER_TOLERATED_KEYS,
 	SkillCollisionError,
 	SkillRegistry,
 } from './skills/index.js'
@@ -1323,6 +1324,10 @@ export { isWorkingMemoryMessage } from './runtime/query/iteration/phases/working
 // `any` — and the first host to try (`@namzu/cli`'s `/compact`) did exactly
 // that before this line existed.
 export type { CompactNowInput, CompactionResult } from './compaction/manual.js'
+export type {
+	CompactionSummaryRoute,
+	CompactionSummaryRouter,
+} from './compaction/model-summary.js'
 
 export {
 	buildVerifiedSummary,
@@ -1517,6 +1522,7 @@ export {
 	SKILL_INVOCATION_DEFAULT,
 	isInvocableBy,
 	skillInvocation,
+	skillModelDescription,
 } from './types/skills/index.js'
 
 // Reaching the web. Fetching ships guarded because its rules are about the

package/src/public-tools.ts

@@ -79,6 +79,8 @@ export {
 	backgroundTasksDisabled,
 	execHostShell,
 } from './tools/builtins/bash.js'
+// Authorization and execution must agree after a session carries its shell cwd.
+export { effectiveBashWorkingDirectory } from './tools/builtins/bash-cwd.js'
 export {
 	CODE_ANALYSIS_TOOL_NAME,
 	CodeAnalysisTool,

package/src/public-types.ts

@@ -231,8 +231,13 @@ export type {
 	SkippedAgentFile,
 } from './agents/file-definitions.js'
 export type {
+	HttpHookEntry,
+	PromptHookEntry,
 	ShellHookEntry,
 	ShellHookEvent,
+	ShellHookHandler,
+	ShellHookJudge,
+	ShellHookOnFailure,
 	ShellHookInput,
 	ShellHookOptions,
 	ShellHookOutcome,

package/src/runtime/query/executor.ts

@@ -14,6 +14,11 @@ import { ProbeVetoError } from '../../probe/errors.js'
 import { probe as defaultProbeRegistry } from '../../probe/registry.js'
 import type { ProbeEnforcement } from '../../probe/registry.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
+import {
+	effectiveBashWorkingDirectory,
+	pinBashWorkingDirectory,
+} from '../../tools/builtins/bash-cwd.js'
+import { BashTool } from '../../tools/builtins/bash.js'
 import { fingerprintContent } from '../../tools/builtins/content-fingerprint.js'
 import { sandboxShellSpawn, withoutBashStartup } from '../../tools/command-shell.js'
 import { isAlwaysDestructive } from '../../tools/defineTool.js'
@@ -99,6 +104,9 @@ import {
 export type { EmitEvent } from './events.js'
 import type { EmitEvent, SessionEventDraft } from './events.js'
 
+/** Input and identity needed by the shared direct/nested safety checks. */
+type PreparedSafetyCall = Pick<PreparedDirectCall, 'kind' | 'toolName' | 'input'>
+
 export type PreparedDirectCall =
 	| {
 			readonly kind: 'ready'
@@ -703,10 +711,12 @@ export class ToolExecutor {
 	private log: Logger
 	private workingStateManager?: WorkingStateManager
 	private historyView?: () => readonly Message[]
+	private systemPromptView?: () => string | undefined
 	private probes: ProbeEnforcement
 	private parentSpan?: Span
 	private readonly toolCallBudget?: ToolCallBudget
 	private readonly preparedBatches = new WeakSet<PreparedToolBatch>()
+	private readonly preparedBashDirectories = new WeakMap<PreparedSafetyCall, string>()
 	/** Ephemeral proof of actual execution; restored messages do not acquire it. */
 	private readonly recordedObservations = new Map<
 		string,
@@ -761,6 +771,11 @@ export class ToolExecutor {
 		this.historyView = view
 	}
 
+	/** The system prompt assembled for the current iteration, for `ToolContext.conversation`. */
+	setSystemPromptView(view: () => string | undefined): void {
+		this.systemPromptView = view
+	}
+
 	private receiptVisible = (callId: string, renderedFingerprint: string): boolean => {
 		const history = this.historyView?.()
 		if (!history) return false
@@ -1174,7 +1189,7 @@ export class ToolExecutor {
 	 * safety checks did not run is the one a person must look at.
 	 */
 	private async escalationOrUnfinished(
-		call: PreparedDirectCall,
+		call: PreparedSafetyCall,
 	): Promise<ToolCallEscalation | undefined> {
 		try {
 			return await this.escalationOf(call)
@@ -1206,12 +1221,19 @@ export class ToolExecutor {
 	 * roots is not mounted there to be approved. The escape is looked at only
 	 * WITH one, since without one there is nothing to escape.
 	 */
-	private async escalationOf(call: PreparedDirectCall): Promise<ToolCallEscalation | undefined> {
+	private async escalationOf(call: PreparedSafetyCall): Promise<ToolCallEscalation | undefined> {
 		if (call.kind === 'synthetic') return undefined
 		const tool = this.config.tools.get(call.toolName)
 		if (!tool || call.input === null || typeof call.input !== 'object') return undefined
 		const input = call.input as Record<string, unknown>
 		const sandboxed = this.sandboxed
+		const shellCwd =
+			tool.execute === BashTool.execute
+				? effectiveBashWorkingDirectory(this.config.sessionId, this.config.workingDirectory, {
+						sandboxed,
+					})
+				: undefined
+		if (shellCwd !== undefined) this.preparedBashDirectories.set(call, shellCwd)
 		let outsidePaths: string[] | undefined
 		if (
 			this.config.outsideRootAccess === 'review' &&
@@ -1234,7 +1256,7 @@ export class ToolExecutor {
 			tool.sandboxEscapeArgument !== undefined &&
 			input[tool.sandboxEscapeArgument] === true
 		const unknownProgram = this.unknownProgramOf(tool, input, sandboxed)
-		const reaches = await this.pathEscalationsOf(tool, input, sandboxed)
+		const reaches = await this.pathEscalationsOf(tool, input, sandboxed, shellCwd)
 		if (reaches.outsidePaths.length > 0) {
 			outsidePaths = [...new Set([...(outsidePaths ?? []), ...reaches.outsidePaths])]
 		}
@@ -1275,6 +1297,7 @@ export class ToolExecutor {
 		>,
 		input: Record<string, unknown>,
 		sandboxed: boolean,
+		shellCwd?: string,
 	): Promise<{
 		outsidePaths: readonly string[]
 		protectedPaths: readonly string[]
@@ -1297,6 +1320,7 @@ export class ToolExecutor {
 				const dialect = tool.commandDialect?.({ sandboxed }) ?? 'sh'
 				const found = await shellEscalations(line, dialect, {
 					roots,
+					...(shellCwd !== undefined ? { cwd: shellCwd } : {}),
 					reviewOutside: this.config.outsideRootAccess === 'review' && !sandboxed,
 				})
 				protectedPaths.push(...found.protectedPaths)
@@ -1592,6 +1616,10 @@ export class ToolExecutor {
 				...(this.config.toolPause ? { requestPause: this.config.toolPause(toolCall.id) } : {}),
 				report: (message: string, fraction?: number) => progress.report(message, fraction),
 			}
+			if (preparedCall) {
+				const cwd = this.preparedBashDirectories.get(preparedCall)
+				if (cwd !== undefined) pinBashWorkingDirectory(ctx, cwd)
+			}
 			const run = async () => {
 				try {
 					results[i] = await this.executeSingle(
@@ -1843,7 +1871,10 @@ export class ToolExecutor {
 		signal.throwIfAborted()
 		// Preparation detaches input synchronously before its first await.
 		// Admission must not add an earlier yield where the caller can mutate it.
-		const preparedCall = await this.prepareNestedCall(name, input, signal)
+		const preparedCall = {
+			...(await this.prepareNestedCall(name, input, signal)),
+			toolName: name,
+		}
 		signal.throwIfAborted()
 		if (this.toolCallBudget) {
 			const refusal = await this.toolCallBudget.admit(1, 'nested', signal)
@@ -1926,12 +1957,15 @@ export class ToolExecutor {
 		} catch {
 			needsApproval = true
 		}
-		if (needsApproval || (gateResult && gateResult.decision !== 'allow')) {
-			const reason = needsApproval
-				? `Blocked: "${name}" requires the person's approval for every call, and an approval cannot be requested from inside another tool. Call it directly.`
-				: gateResult?.decision === 'deny'
-					? `Blocked by the authorization gate: ${gateResult.reason}`
-					: `Blocked by the authorization gate: this nested call requires an explicit allow rule because an operator review cannot be opened from inside another tool. ${gateResult?.reason}`
+		const nestedEscalation = await this.escalationOrUnfinished(preparedCall)
+		if (nestedEscalation || needsApproval || (gateResult && gateResult.decision !== 'allow')) {
+			const reason = nestedEscalation
+				? 'Blocked: this nested call reaches a protected path, removal floor, outside-root boundary or another safety escalation. Call it directly so it can be reviewed.'
+				: needsApproval
+					? `Blocked: "${name}" requires the person's approval for every call, and an approval cannot be requested from inside another tool. Call it directly.`
+					: gateResult?.decision === 'deny'
+						? `Blocked by the authorization gate: ${gateResult.reason}`
+						: `Blocked by the authorization gate: this nested call requires an explicit allow rule because an operator review cannot be opened from inside another tool. ${gateResult?.reason}`
 			const output = deniedToolOutput(name, reason)
 			// Same fail-closed durability rule as a direct gate denial: if the
 			// configured session log cannot record the refusal, do not quietly carry
@@ -2004,6 +2038,8 @@ export class ToolExecutor {
 			report: (message: string, fraction?: number) => progress.report(message, fraction),
 		}
 
+		const nestedCwd = this.preparedBashDirectories.get(preparedCall)
+		if (nestedCwd !== undefined) pinBashWorkingDirectory(childContext, nestedCwd)
 		await this.emitEvent({
 			type: 'tool_executing',
 			turnId: this.config.turnId,
@@ -2213,6 +2249,14 @@ export class ToolExecutor {
 			sandbox: this.config.sandbox,
 			fileReadTracker: this.fileReadTracker,
 			receiptVisible: this.receiptVisible,
+			...(this.historyView
+				? {
+						conversation: {
+							messages: () => this.historyView?.() ?? [],
+							systemPrompt: () => this.systemPromptView?.(),
+						},
+					}
+				: {}),
 			...(this.config.codeAnalysis ? { codeAnalysis: this.config.codeAnalysis } : {}),
 			// Bound to this turn, once. Binding here rather than passing the
 			// owner from the tool is what makes the scoping structural: there

package/src/runtime/query/index.ts

@@ -10,6 +10,7 @@ import { SkillGrantSet } from '../../authorization/skill-grant.js'
 import { repairToolMessageHistory, toolHistoryRepairChanged } from '../../compaction/dangling.js'
 import { extractFromUserMessage } from '../../compaction/extractor.js'
 import { WorkingStateManager } from '../../compaction/manager.js'
+import type { CompactionSummaryRouter } from '../../compaction/model-summary.js'
 import type { ContextReducer } from '../../compaction/reducer.js'
 import { serializeState as serializeWorkingState } from '../../compaction/serializer.js'
 import { restoreWorkingState, snapshotWorkingState } from '../../compaction/wire.js'
@@ -552,6 +553,8 @@ export interface QueryParams {
 	allowedTools?: string[]
 	agentId: string
 	agentName: string
+	/** Application-owned agent kind for lifecycle hooks; defaults to agentName. */
+	agentType?: string
 	workingDirectory?: string
 	/**
 	 * Directories besides the working directory the file tools may reach,
@@ -821,6 +824,12 @@ export interface QueryParams {
 	 */
 	postCompactionContext?: () => string | undefined | Promise<string | undefined>
 
+	/**
+	 * Names the model that writes a compaction summary. Asked once per pass;
+	 * resolving nothing, or a call that fails, keeps the extracted summary.
+	 */
+	compactionSummaryRoute?: CompactionSummaryRouter
+
 	/**
 	 * Where this conversation's durable state lives.
 	 *
@@ -1064,6 +1073,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 		approvalPolicy,
 		eventTranslator,
 		executeUserInterruptHooks,
+		executeTurnFailureHooks,
 		pendingHistoryRepairs,
 		initialMessages,
 		historyIds,
@@ -1841,6 +1851,9 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			...(params.postCompactionContext
 				? { postCompactionContext: params.postCompactionContext }
 				: {}),
+			...(params.compactionSummaryRoute
+				? { compactionSummaryRoute: params.compactionSummaryRoute }
+				: {}),
 			...(providerContextWindow !== undefined ? { providerContextWindow } : {}),
 			resolveModelContextWindow: async (model) => {
 				if (!modelContextWindows.has(model)) {
@@ -1867,6 +1880,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			pluginManager: params.pluginManager,
 			...(params.parentSessionId !== undefined ? { parentSessionId: params.parentSessionId } : {}),
 			...(params.parentTurnId !== undefined ? { parentTurnId: params.parentTurnId } : {}),
+			agentType: params.agentType ?? params.agentName,
 		})
 
 		const tracer = getTracer()
@@ -2031,6 +2045,33 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 					'namzu.runtime.resume_from_checkpoint': params.resumeFromCheckpoint ?? null,
 				})
 
+				// A child session is starting: its hooks may add context for the
+				// child's turn, before the child's first prompt is seen.
+				if (params.pluginManager && params.parentSessionId !== undefined) {
+					const startResults = await params.pluginManager.executeHooks(
+						'subagent_start',
+						{
+							turnId: ctx.turnId,
+							sessionId: params.sessionId,
+							parentSessionId: params.parentSessionId,
+							...(params.parentTurnId !== undefined ? { parentTurnId: params.parentTurnId } : {}),
+							agentType: params.agentType ?? params.agentName,
+							signal: ctx.abortController.signal,
+						},
+						eventTranslator.emitEvent,
+					)
+					const startAnnotations = applyLifecycleHookResults('subagent_start', startResults)
+					if (startAnnotations.length > 0) {
+						promptContributions.replace({
+							id: 'hooks:subagent_start',
+							placement: 'context',
+							render: () =>
+								`Context from the operator's hooks:\n\n${startAnnotations.join('\n\n')}`,
+						})
+					}
+					yield* eventTranslator.drainPending()
+				}
+
 				// The operator's prompt, before the model sees it. A hook may
 				// refuse it — the turn ends here, before a prompt is built — or add
 				// to what the model is told; the addition rides the prompt as a
@@ -2351,6 +2392,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 						? `${segments.static}\n\n---\n\n${segments.dynamic}`
 						: segments.static
 
+				toolExecutor.setSystemPromptView(() => assembledPrompt)
 				ctx.recorder.markRunning()
 				// A resumed turn already began; `turn_resuming` above continued it.
 				if (!params.resumeFromCheckpoint) {
@@ -2788,6 +2830,8 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				ctx.recorder.setSteps(iterationOrchestrator.getSteps())
 				await executeUserInterruptHooks(err)
 				yield* eventTranslator.drainPending()
+				await executeTurnFailureHooks(err)
+				yield* eventTranslator.drainPending()
 				yield* resultAssembler.handleError(err, rootSpan)
 			} finally {
 				// A pending acquisition is withdrawn and awaited first, so a handle

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

@@ -79,7 +79,7 @@ import {
 } from './outstanding-work.js'
 import { runAdvisoryPhase } from './phases/advisory.js'
 import { runIterationCheckpoint } from './phases/checkpoint.js'
-import { compactionBreaker } from './phases/compaction-breaker.js'
+import { compactionBreaker, estimateRefillTokens } from './phases/compaction-breaker.js'
 import {
 	AUTOMATIC_COMPACTION_FAILED,
 	OVERFLOW_RELIEF_LIMIT,
@@ -319,7 +319,7 @@ export class IterationOrchestrator {
 		const feedback: string[] = []
 		const ask = async (
 			event: 'turn_end' | 'subagent_stop',
-			extra: { parentSessionId?: SessionId; parentTurnId?: TurnId },
+			extra: { parentSessionId?: SessionId; parentTurnId?: TurnId; agentType?: string },
 		): Promise<void> => {
 			const results = await manager.executeHooks(
 				event,
@@ -346,6 +346,7 @@ export class IterationOrchestrator {
 			await ask('subagent_stop', {
 				parentSessionId: this.ctx.parentSessionId,
 				...(this.ctx.parentTurnId !== undefined ? { parentTurnId: this.ctx.parentTurnId } : {}),
+				...(this.ctx.agentType !== undefined ? { agentType: this.ctx.agentType } : {}),
 			})
 			yield* this.ctx.drainPending()
 		}
@@ -2176,6 +2177,7 @@ export class IterationOrchestrator {
 						}
 						// A rung that sheds too little to change the verdict is not worth a
 						// provider call; climb to the next one at once.
+						const tokensBeforeRelief = estimateRefillTokens(recorder.messages)
 						let shed = false
 						while (!shed && overflowReliefs < OVERFLOW_RELIEF_LIMIT) {
 							overflowReliefs++
@@ -2185,7 +2187,13 @@ export class IterationOrchestrator {
 							// Clearing results is a compaction too: only summaries and reducers
 							// recorded themselves, so a clear-only relief was invisible to the
 							// breaker.
-							compactionBreaker(this.ctx)?.recordCompaction(iterationNum)
+							// Record the whole ladder once, including any insufficient first
+							// rung, against the same estimator the refill check uses.
+							compactionBreaker(this.ctx)?.recordCompaction(
+								iterationNum,
+								tokensBeforeRelief,
+								estimateRefillTokens(recorder.messages),
+							)
 							this.ctx.log.info('Retrying the turn after relieving a context overflow', {
 								[NAMZU.TURN_ID]: recorder.turnId,
 								[NAMZU.ITERATION]: iterationNum,

package/src/runtime/query/iteration/phases/compaction-breaker.ts

@@ -7,10 +7,10 @@
  *   and the turn carries on, silently as far as the person is concerned (a log
  *   line and a `breaker_open` event, no sentence); a pass the provider forces
  *   by rejecting the prompt is not gated, so the reactive ladder still runs.
- * - Three compactions in a row, each followed by the context filling back up
- *   within three iterations: something in the loop (a huge file read, a tool
- *   that prints without limit) refills the window faster than any summary can
- *   empty it. The turn stops, because carrying on only buys the same wall.
+ * - Three compactions in a row, each followed by the history regaining all
+ *   space shed within three iterations: something in the loop (a huge file
+ *   read, a tool that prints without limit) refills the window faster than a
+ *   summary can empty it. The turn stops, because carrying on buys the same wall.
  *
  * Off unless `compactionConfig.circuitBreaker` is true: stopping compaction,
  * and above all stopping a turn, is not something a host had before.
@@ -19,11 +19,31 @@
  * share a count.
  */
 
+import { estimateMessageTokens } from '../../../../compaction/token-estimate.js'
+import { type Message, isTurnContextEntry } from '../../../../types/message/index.js'
+import { isReminderMessage } from '../../reminders.js'
 import type { IterationContext } from './context.js'
 
+/**
+ * Conversation growth for the refill guard. Compaction sheds host reminders
+ * and recorded context so the host can announce them again; their return is
+ * not evidence of a tool refilling the window. Budgeting still includes them.
+ * Use provenance, not text that an operator or tool could happen to quote.
+ */
+export function estimateRefillTokens(messages: readonly Message[]): number {
+	return messages.reduce(
+		(total, message) =>
+			total +
+			(isReminderMessage(message) || isTurnContextEntry(message)
+				? 0
+				: estimateMessageTokens(message)),
+		0,
+	)
+}
+
 /** Consecutive failed passes after which automatic compaction stops. */
 export const COMPACTION_FAILURE_LIMIT = 3
-/** A compaction followed by a trigger sooner than this many iterations is a refill. */
+/** A full refill sooner than this many iterations counts toward the limit. */
 export const COMPACTION_REFILL_ITERATIONS = 3
 /** Consecutive refills that stop the turn. */
 export const COMPACTION_REFILL_LIMIT = 3
@@ -41,6 +61,8 @@ export class CompactionBreaker {
 	private refills = 0
 	private pendingRefills = 0
 	private lastCompactedIteration: number | undefined
+	private lastTokensBefore = 0
+	private lastTokensAfter = 0
 	private failureNoticeSent = false
 	private stopReason: string | undefined
 
@@ -69,18 +91,25 @@ export class CompactionBreaker {
 	 * A summary or reducer pass is about to run at `iteration`. True when it
 	 * would be the third refill in a row, in which case it must not run.
 	 */
-	wouldTrip(iteration: number): boolean {
+	wouldTrip(iteration: number, tokens: number): boolean {
+		// Iteration distance alone confuses continued pressure with a refill:
+		// a small reduction may leave the prompt above its trigger. Compare the
+		// same history estimator on both sides, never provider usage against an
+		// estimate. Count only when new context has replaced ALL the space shed.
+		const refilled = this.lastTokensAfter < this.lastTokensBefore && tokens >= this.lastTokensBefore
 		const quick =
 			this.lastCompactedIteration !== undefined &&
 			iteration - this.lastCompactedIteration < COMPACTION_REFILL_ITERATIONS
-		this.pendingRefills = quick ? this.refills + 1 : 0
+		this.pendingRefills = quick && refilled ? this.refills + 1 : 0
 		return this.pendingRefills >= COMPACTION_REFILL_LIMIT
 	}
 
-	/** The pass that `wouldTrip` allowed completed at `iteration`. */
-	recordCompaction(iteration: number): void {
+	/** The allowed pass completed; both sizes must use the same history estimator. */
+	recordCompaction(iteration: number, tokensBefore: number, tokensAfter: number): void {
 		this.refills = this.pendingRefills
 		this.lastCompactedIteration = iteration
+		this.lastTokensBefore = tokensBefore
+		this.lastTokensAfter = tokensAfter
 		this.recordRelief()
 	}
 

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

@@ -3,6 +3,7 @@ import {
 	resolveTriggerThreshold,
 } from '../../../../compaction/context-window.js'
 import { findDanglingMessages } from '../../../../compaction/dangling.js'
+import { replaceableSummaries, summarizeWithModel } from '../../../../compaction/model-summary.js'
 import {
 	type CompactionPlan,
 	DEFAULT_SOFT_TARGET,
@@ -28,7 +29,11 @@ import { invariants } from '../../../../invariants/index.js'
 import { resolveTaskModel } from '../../../../model-router/task-router.js'
 import type { Message } from '../../../../types/message/index.js'
 import { applyLifecycleHookResults } from '../../plugin-hooks.js'
-import { COMPACTION_REFILL_MESSAGE, compactionBreaker } from './compaction-breaker.js'
+import {
+	COMPACTION_REFILL_MESSAGE,
+	compactionBreaker,
+	estimateRefillTokens,
+} from './compaction-breaker.js'
 import type { IterationContext } from './context.js'
 import { isWorkingMemoryMessage } from './working-memory.js'
 
@@ -442,7 +447,10 @@ export async function stopOnRefill(ctx: IterationContext): Promise<boolean> {
 	if (!breaker) return false
 	// Already announced: the turn is on its way out; do not say it twice.
 	if (breaker.stop !== undefined) return true
-	if (!breaker.wouldTrip(ctx.recorder.currentIteration)) return false
+	if (
+		!breaker.wouldTrip(ctx.recorder.currentIteration, estimateRefillTokens(ctx.recorder.messages))
+	)
+		return false
 	ctx.log.warn('Compaction keeps refilling — stopping the turn', {
 		[NAMZU.TURN_ID]: ctx.recorder.turnId,
 		[NAMZU.ITERATION]: ctx.recorder.currentIteration,
@@ -508,6 +516,7 @@ async function applyReducer(
 	const messages = ctx.recorder.messages
 	const before = messages.length
 	const beforeChars = totalChars(messages)
+	const beforeTokens = estimateRefillTokens(messages)
 
 	let next: readonly Message[] | undefined
 	try {
@@ -594,7 +603,11 @@ async function applyReducer(
 		reduction.contextWindowTokens,
 		measurement.windowSource,
 	)
-	compactionBreaker(ctx)?.recordCompaction(ctx.recorder.currentIteration)
+	compactionBreaker(ctx)?.recordCompaction(
+		ctx.recorder.currentIteration,
+		beforeTokens,
+		estimateRefillTokens(messages),
+	)
 }
 
 /**
@@ -960,7 +973,51 @@ async function runCompactionCheckInner(
 
 	let compactedContent: string
 
-	if (config.llmVerification && manager.slotCount() < config.richStateThreshold) {
+	// A model the host set aside writes the summary when it can. Its own cost
+	// goes on the turn's ledger at the price of the model that answered. When
+	// there is no such model, or its call does not give a summary, the
+	// extracted state below is used, with its verifier step where that applies.
+	let modelRoute: { providerId: string; model: string } | undefined
+	const modelWritten = !ctx.compactionSummaryRoute
+		? undefined
+		: await summarizeWithModel({
+				manager,
+				olderMessages,
+				previousSummaries: replaceableSummaries(systemMessages),
+				config,
+				resolveRoute: async (signal) => {
+					const route = await ctx.compactionSummaryRoute?.(signal)
+					if (route) {
+						modelRoute = {
+							providerId: route.providerId ?? ctx.recorder.servingProviderId,
+							model: route.model,
+						}
+					}
+					return route
+				},
+				onUsage: (usage) => {
+					if (modelRoute) ctx.recorder.accumulateUsage(usage, modelRoute)
+				},
+				signal: ctx.abortController.signal,
+				onFallback: (reason, error) => {
+					if (reason === 'no_route') return
+					if (error !== undefined) noteCompactionError(ctx, error)
+					ctx.log.warn(
+						'The model-written compaction summary was not used — using the extracted state',
+						{
+							[NAMZU.TURN_ID]: ctx.recorder.turnId,
+							'namzu.runtime.reason': reason,
+							...(error !== undefined
+								? { 'exception.message': error instanceof Error ? error.message : String(error) }
+								: {}),
+						},
+					)
+				},
+			})
+
+	if (modelWritten !== undefined) {
+		compactedContent = modelWritten
+	} else if (config.llmVerification && manager.slotCount() < config.richStateThreshold) {
 		// Named once and used twice on purpose. The model the summariser is
 		// asked for is also the model its tokens are priced at, and computing
 		// the two separately is how they drift — a router that sends compaction
@@ -1077,6 +1134,7 @@ async function runCompactionCheckInner(
 
 	const live = ctx.recorder.messages
 	const oldCount = live.length
+	const beforeTokens = estimateRefillTokens(live)
 	// Retained history can survive in full while a summary adds another copy
 	// of its facts. Even an unretained span may be smaller than the cumulative
 	// summary. Compare both candidates with the same estimator, rather than
@@ -1151,5 +1209,9 @@ async function runCompactionCheckInner(
 		reachedResetThreshold: reachedReset,
 	})
 	await emitContextUsageSnapshot(ctx, newEstimate, budget, window.source)
-	compactionBreaker(ctx)?.recordCompaction(ctx.recorder.currentIteration)
+	compactionBreaker(ctx)?.recordCompaction(
+		ctx.recorder.currentIteration,
+		beforeTokens,
+		estimateRefillTokens(live),
+	)
 }

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

@@ -2,6 +2,7 @@ import type { AdvisoryContext } from '../../../../advisory/context.js'
 import type { SkillGrantSet } from '../../../../authorization/skill-grant.js'
 import type { AgentBus } from '../../../../bus/index.js'
 import type { WorkingStateManager } from '../../../../compaction/manager.js'
+import type { CompactionSummaryRouter } from '../../../../compaction/model-summary.js'
 import type { ContextReducer } from '../../../../compaction/reducer.js'
 import type { CompactionConfig } from '../../../../config/runtime.js'
 import { NAMZU } from '../../../../constants/telemetry/index.js'
@@ -259,6 +260,9 @@ export interface IterationContext {
 	/** Host text appended to the restored context after a compaction. */
 	readonly postCompactionContext?: () => string | undefined | Promise<string | undefined>
 
+	/** Where a model-written compaction summary is asked for; see {@link CompactionSummaryRouter}. */
+	readonly compactionSummaryRoute?: CompactionSummaryRouter
+
 	readonly workingStateManager?: WorkingStateManager
 
 	/**
@@ -280,6 +284,8 @@ export interface IterationContext {
 	/** The delegating session, when this turn is a child's: `subagent_stop` names it. */
 	readonly parentSessionId?: import('../../../../types/ids/index.js').SessionId
 	readonly parentTurnId?: import('../../../../types/ids/index.js').TurnId
+	/** The agent this turn runs, named to `subagent_stop` hooks of a child. */
+	readonly agentType?: string
 
 	/**
 	 * Override for {@link PARK_RECORD_DELAY_MS}. Internal; tests set `0` to