@namzu/sdk 27.1.0 → 28.0.0

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

@@ -3,23 +3,27 @@ import type { AgentBus } from '../../../../bus/index.js'
 import type { WorkingStateManager } from '../../../../compaction/manager.js'
 import type { ContextReducer } from '../../../../compaction/reducer.js'
 import type { CompactionConfig } from '../../../../config/runtime.js'
-import type { CompletionInbox } from '../../../../gateway/completion-inbox.js'
+import { NAMZU } from '../../../../constants/telemetry/index.js'
 import type { PlanManager } from '../../../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../../../manager/run/persistence.js'
+import type { PromptContributionRegistry } from '../../../../prompt/contributions.js'
 import type { ServingMember } from '../../../../provider/fallback.js'
+import type { CompletionInbox } from '../../../../scheduler/completion-inbox.js'
 import type { ActivityStore } from '../../../../store/activity/memory.js'
-import type { TaskGateway } from '../../../../types/agent/gateway.js'
+import type { TaskScheduler } from '../../../../types/agent/scheduler.js'
 import type { WorkingMemoryProvider } from '../../../../types/agent/working-memory.js'
 import type {
 	HITLResumeDecision,
 	IterationCheckpoint,
 	ResumeHandler,
 } from '../../../../types/hitl/index.js'
+import type { CheckpointId } from '../../../../types/ids/index.js'
 import type { LLMProvider } from '../../../../types/provider/index.js'
 import type { TaskRouterConfig } from '../../../../types/router/index.js'
 import type { ReviewAnswer } from '../../../../types/run/answer-review.js'
 import type {
 	AgentRunConfig,
+	BeforeStep,
 	PrepareStepChain,
 	RunEvent,
 	StepResult,
@@ -33,6 +37,7 @@ import type { CheckpointManager } from '../../checkpoint.js'
 import type { EmitEvent } from '../../events.js'
 import type { ToolExecutor } from '../../executor.js'
 import type { GuardCoordinator } from '../../guard.js'
+import type { RepeatCallTracker } from '../../repeat-call.js'
 import type { SteeringChannel } from '../../steering.js'
 import type { ToolGrantSet } from '../../tool-grants.js'
 
@@ -92,6 +97,27 @@ export interface IterationContext {
 	readonly log: Logger
 	readonly resumeHandler: ResumeHandler
 
+	/**
+	 * The policy change the model has not been told about, if there is one.
+	 *
+	 * Read-and-CLEAR: calling this marks the change announced, so the caller
+	 * must be the one that actually puts it in front of the model. Optional
+	 * because a host driving the phases directly may have no policy box, and
+	 * a run with no changes to report behaves identically either way.
+	 */
+	readonly takeApprovalPolicyChange?: () =>
+		| import('../../../../types/hitl/policy.js').ApprovalPolicyChange
+		| undefined
+
+	/**
+	 * Contributions that report state changing DURING the run.
+	 *
+	 * Rendered into the ephemeral trailing message once per iteration, never
+	 * into the system prompt — see `PromptPlacement`'s note on why `turn` is
+	 * a third thing rather than a looser `dynamic`.
+	 */
+	readonly promptContributions?: PromptContributionRegistry
+
 	/**
 	 * Guidance a host may hand to the turn while it runs.
 	 *
@@ -102,7 +128,7 @@ export interface IterationContext {
 	readonly checkpointMgr: CheckpointManager
 	readonly planManager: PlanManager
 
-	readonly taskGateway?: TaskGateway
+	readonly taskGateway?: TaskScheduler
 
 	/**
 	 * Completions no call is waiting for, on their way to the transcript.
@@ -122,12 +148,39 @@ export interface IterationContext {
 	 * asked about again. Absent on paths that do not review tools.
 	 */
 	readonly toolGrants?: ToolGrantSet
+	/**
+	 * Absent when the host opted out with `repeatCallAdvisory: false`. The
+	 * opt-out is the ABSENCE, not a flag read at every call site, so a code
+	 * path that forgets to check the flag cannot advise anyway.
+	 */
+	readonly repeatCalls?: RepeatCallTracker
 
 	/** Per-task model overrides. Consulted for the compaction summary call. */
 	readonly taskRouter?: TaskRouterConfig
 
 	readonly compactionConfig?: CompactionConfig
 
+	/**
+	 * What the driver said this model's context window is, resolved once.
+	 *
+	 * Carried rather than asked for, because both readers are synchronous
+	 * and in the hot loop — turning either into an await would put a network
+	 * round trip on every iteration of every run. `undefined` covers both
+	 * "the driver has no such member" and "it asked and does not know",
+	 * which are different facts to the DRIVER and the same fact here: fall
+	 * through to the table.
+	 */
+	readonly providerContextWindow?: number
+
+	/**
+	 * Text queued for this run since its last turn.
+	 *
+	 * Drained at the iteration boundary — the same seam `completionInbox`
+	 * uses, which is the established place for putting a user message in
+	 * after tool results and before the next turn.
+	 */
+	readonly inboundMessages?: () => readonly import('../../../../types/message/index.js').Message[]
+
 	readonly workingStateManager?: WorkingStateManager
 
 	/**
@@ -142,7 +195,7 @@ export interface IterationContext {
 
 	readonly agentBus?: AgentBus
 
-	readonly verificationGate?: import('../../../../verification/gate.js').VerificationGate
+	readonly verificationGate?: import('../../../../authorization/gate.js').AuthorizationGate
 
 	readonly pluginManager?: import('../../../../plugin/lifecycle.js').PluginLifecycleManager
 
@@ -154,6 +207,7 @@ export interface IterationContext {
 
 	/** Host hook that shapes each step before the model call. */
 	readonly prepareStep?: PrepareStepChain
+	readonly beforeStep?: BeforeStep
 }
 
 export type PhaseSignal = 'continue' | 'stop'
@@ -200,9 +254,9 @@ export async function awaitDecisionDurably(
 			// with it — the in-process await is still perfectly valid, it is
 			// only the cross-process handoff that is lost. Loudly, though.
 			ctx.log.error('Failed to record a HITL park — the run is not resumable across a restart', {
-				runId: ctx.runMgr.id,
-				checkpointId: checkpoint.id,
-				error: err instanceof Error ? err.message : String(err),
+				[NAMZU.RUN_ID]: ctx.runMgr.id,
+				'namzu.checkpoint.id': checkpoint.id,
+				'exception.message': err instanceof Error ? err.message : String(err),
 			})
 		}
 	}
@@ -269,9 +323,9 @@ export async function awaitDecisionDurably(
 		if (recorded) {
 			await ctx.checkpointMgr.unpark(checkpoint.id, decision).catch((err: unknown) => {
 				ctx.log.error('Failed to clear a recorded HITL park', {
-					runId: ctx.runMgr.id,
-					checkpointId: checkpoint.id,
-					error: err instanceof Error ? err.message : String(err),
+					[NAMZU.RUN_ID]: ctx.runMgr.id,
+					'namzu.checkpoint.id': checkpoint.id,
+					'exception.message': err instanceof Error ? err.message : String(err),
 				})
 				return null
 			})
@@ -336,7 +390,12 @@ export async function awaitDecisionOrAbort(
 export async function* handleHITLDecision(
 	ctx: IterationContext,
 	decision: HITLResumeDecision,
-	checkpointId: string,
+	// `CheckpointId`, not `string`. Both callers already hold one — they pass
+	// `IterationCheckpoint.id` — so the parameter was widened for nothing and
+	// the widening is what forced the `as \`cp_${string}\`` cast below. A
+	// narrower parameter costs no caller anything and makes the cast
+	// unnecessary rather than merely shorter.
+	checkpointId: CheckpointId,
 	context: string,
 ): AsyncGenerator<RunEvent, PhaseSignal> {
 	switch (decision.action) {
@@ -344,31 +403,33 @@ export async function* handleHITLDecision(
 			await ctx.emitEvent({
 				type: 'run_paused',
 				runId: ctx.runMgr.id,
-				checkpointId: checkpointId as `cp_${string}`,
+				checkpointId,
 				reason: decision.reason,
 			})
 			yield* ctx.drainPending()
 			ctx.runMgr.setStopReason('paused')
-			ctx.log.info(`Run paused at ${context}`, {
-				sessionId: ctx.runMgr.id,
-				reason: decision.reason,
+			ctx.log.info('Run paused', {
+				'namzu.run.phase': context,
+				[NAMZU.RUN_ID]: ctx.runMgr.id,
+				'namzu.runtime.reason': decision.reason,
 			})
 			return 'stop'
 		}
 		case 'abort': {
 			ctx.runMgr.setStopReason('cancelled')
 			ctx.runMgr.markCancelled()
-			ctx.log.info(`Run aborted at ${context}`, {
-				sessionId: ctx.runMgr.id,
-				reason: decision.reason,
+			ctx.log.info('Run aborted', {
+				'namzu.run.phase': context,
+				[NAMZU.RUN_ID]: ctx.runMgr.id,
+				'namzu.runtime.reason': decision.reason,
 			})
 			return 'stop'
 		}
 		case 'reject_plan': {
 			ctx.runMgr.setStopReason('plan_rejected')
 			ctx.log.info('Plan rejected by user', {
-				sessionId: ctx.runMgr.id,
-				feedback: decision.feedback,
+				[NAMZU.RUN_ID]: ctx.runMgr.id,
+				'namzu.runtime.feedback': decision.feedback,
 			})
 			return 'stop'
 		}
@@ -377,7 +438,7 @@ export async function* handleHITLDecision(
 				ctx.planManager.approve()
 				ctx.planManager.startExecution()
 			}
-			ctx.log.info('Plan approved by user', { sessionId: ctx.runMgr.id })
+			ctx.log.info('Plan approved by user', { [NAMZU.RUN_ID]: ctx.runMgr.id })
 			return 'continue'
 		}
 		case 'continue':

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

@@ -1,12 +1,13 @@
+import type { AuthorizationGate } from '../../../../authorization/index.js'
 import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
 import type { RunEvent } from '../../../../types/run/index.js'
-import type { VerificationGate } from '../../../../verification/index.js'
 import type { ToolCallDenials } from '../../executor.js'
+import { attachRepeatNotice } from '../../repeat-call.js'
 import { attachSteering } from '../../steering.js'
 import { type IterationContext, awaitDecisionDurably } from './context.js'
 
 interface VerificationAwareContext extends IterationContext {
-	readonly verificationGate?: VerificationGate
+	readonly verificationGate?: AuthorizationGate
 }
 
 export type ToolReviewDecision = 'executed' | 'rejected' | 'stop'
@@ -83,12 +84,20 @@ export async function* runToolReview(
 		const batch = await ctx.toolExecutor.executeBatch(response, denials)
 		toolMs += Date.now() - startedAt
 		executed = batch.results
+		// Recorded AFTER execution and never before it: this advises, it does
+		// not deny, so the call has already run and its real result is in the
+		// batch. Wiring it ahead of `executeBatch` would make it a gate.
+		const notices = []
+		for (const summary of toolCallSummaries) {
+			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.
-		for (const msg of attachSteering(batch.messages, ctx.steering)) {
+		for (const msg of attachRepeatNotice(attachSteering(batch.messages, ctx.steering), notices)) {
 			ctx.runMgr.pushMessage(msg)
 		}
 	}
@@ -125,7 +134,17 @@ export async function* runToolReview(
 
 		for (const gr of gateResults) {
 			if (gr.gateResult.decision === 'deny') {
-				gateDenied.set(gr.toolCall.id, `Blocked by the verification gate: ${gr.gateResult.reason}`)
+				const reason = `Blocked by the verification gate: ${gr.gateResult.reason}`
+				gateDenied.set(gr.toolCall.id, reason)
+				// A gate denial is a refusal — first-class in the audit trail, never
+				// an absent record (LOG-14, design §5). Written here, once per
+				// denied call, regardless of which path the rest of this function
+				// takes afterwards.
+				await ctx.runMgr.recordAudit({
+					what: { action: 'tool_call', tool: gr.toolCall.name },
+					outcome: 'refused',
+					reason,
+				})
 			}
 		}
 
@@ -134,7 +153,7 @@ export async function* runToolReview(
 
 		if (allAllowed) {
 			ctx.log.debug('Verification gate: all tool calls pre-approved', {
-				tools: gateResults.map((gr) => gr.toolCall.name),
+				'namzu.tool.names': gateResults.map((gr) => gr.toolCall.name),
 			})
 			await settle()
 			yield* ctx.drainPending()
@@ -143,7 +162,7 @@ export async function* runToolReview(
 
 		if (allDenied) {
 			ctx.log.debug('Verification gate: all tool calls denied', {
-				tools: gateResults.map((gr) => gr.toolCall.name),
+				'namzu.tool.names': gateResults.map((gr) => gr.toolCall.name),
 			})
 			await settle(gateDenied)
 			yield* ctx.drainPending()
@@ -151,7 +170,7 @@ export async function* runToolReview(
 		}
 
 		ctx.log.debug('Verification gate: mixed decisions, proceeding to review', {
-			decisions: gateResults.map((gr) => ({
+			'namzu.runtime.decisions': gateResults.map((gr) => ({
 				tool: gr.toolCall.name,
 				decision: gr.gateResult.decision,
 			})),
@@ -171,7 +190,7 @@ export async function* runToolReview(
 		toolCallSummaries.every((tc) => ctx.toolGrants?.covers(tc))
 	) {
 		ctx.log.debug('Every tool call is covered by an approval already granted', {
-			tools: toolCallSummaries.map((tc) => tc.name),
+			'namzu.tool.names': toolCallSummaries.map((tc) => tc.name),
 		})
 		await settle()
 		yield* ctx.drainPending()
@@ -301,7 +320,7 @@ export async function* runToolReview(
 		// and proceed with execution rather than stalling the run.
 		case 'answer_question': {
 			ctx.log.warn('Unexpected plan decision during tool review', {
-				action: reviewDecision.action,
+				'namzu.runtime.action': reviewDecision.action,
 			})
 			await settle(gateDenied)
 			yield* ctx.drainPending()

package/src/runtime/query/iteration/phases/working-memory.ts

@@ -1,3 +1,4 @@
+import { NAMZU } from '../../../../constants/telemetry/index.js'
 import { createSystemMessage } from '../../../../types/message/index.js'
 import type { IterationContext } from './context.js'
 
@@ -47,8 +48,8 @@ export async function refreshWorkingMemory(ctx: IterationContext): Promise<void>
 			})) ?? ''
 	} catch (err) {
 		ctx.log.warn('workingMemoryProvider failed; keeping prior slot', {
-			runId: ctx.runMgr.id,
-			error: err instanceof Error ? err.message : String(err),
+			[NAMZU.RUN_ID]: ctx.runMgr.id,
+			'exception.message': err instanceof Error ? err.message : String(err),
 		})
 		return
 	}

package/src/runtime/query/iteration/stream-turn.ts

@@ -419,9 +419,9 @@ export async function* streamProviderTurn(
 				if (fragment) {
 					if (!bucket.id) {
 						log.warn('tool_input_delta arrived before tool id was known; dropping fragment', {
-							runId,
-							index: tc.index,
-							length: fragment.length,
+							[NAMZU.RUN_ID]: runId,
+							'namzu.runtime.index': tc.index,
+							'namzu.runtime.length': fragment.length,
 						})
 					} else {
 						bucket.argsBuf += fragment
@@ -447,9 +447,9 @@ export async function* streamProviderTurn(
 					} catch (err) {
 						bucket.inputTruncated = true
 						log.warn('tool input JSON parse failed at content_block_stop', {
-							runId,
-							toolUseId: endId,
-							error: err instanceof Error ? err.message : String(err),
+							[NAMZU.RUN_ID]: runId,
+							'namzu.runtime.tool_use_id': endId,
+							'exception.message': err instanceof Error ? err.message : String(err),
 						})
 					}
 					bucket.parsed = parsed
@@ -559,10 +559,10 @@ export async function* streamProviderTurn(
 			bucket.inputTruncated = truncated
 			if (truncated) {
 				log.warn('tool input truncated by upstream cutoff (no toolCallEnd, argsBuf unparsable)', {
-					runId,
-					toolUseId: bucket.id,
-					toolName: bucket.name,
-					bufferLength: bucket.argsBuf.length,
+					[NAMZU.RUN_ID]: runId,
+					'namzu.runtime.tool_use_id': bucket.id,
+					[GENAI.TOOL_NAME]: bucket.name,
+					'namzu.runtime.buffer_length': bucket.argsBuf.length,
 				})
 			}
 			await emitEvent({
@@ -610,10 +610,10 @@ export async function* streamProviderTurn(
 
 	if (recoveredToolInputFromStreamError) {
 		log.warn('provider stream failed after tool input; surfacing tool call to executor', {
-			runId,
-			iteration,
-			error: streamError,
-			toolCallCount: toolCalls.length,
+			[NAMZU.RUN_ID]: runId,
+			[NAMZU.ITERATION]: iteration,
+			'exception.message': streamError,
+			'namzu.runtime.tool_call_count': toolCalls.length,
 		})
 	}
 

package/src/runtime/query/{context-cache.ts → prompt-cache.ts}

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto'
+import type { PromptContributionRegistry } from '../../prompt/contributions.js'
 import type { AgentRuntimeContext } from '../../types/agent/base.js'
 import type { AgentContextLevel } from '../../types/agent/factory.js'
 import type { AgentPersona } from '../../types/persona/index.js'
@@ -7,7 +8,7 @@ import type { Skill } from '../../types/skills/index.js'
 import type { ToolRegistryContract } from '../../types/tool/index.js'
 import { PromptBuilder, type PromptSegments } from './prompt.js'
 
-export interface ContextCacheConfig {
+export interface PromptCacheConfig {
 	agentId: string
 	projectId: ProjectId
 }
@@ -20,9 +21,10 @@ export interface PromptCacheInput {
 	tools: ToolRegistryContract
 	allowedTools?: string[]
 	runtimeContext?: AgentRuntimeContext
+	contributions?: PromptContributionRegistry
 }
 
-export class ContextCache {
+export class PromptCache {
 	readonly projectId: ProjectId
 	readonly agentId: string
 
@@ -31,7 +33,7 @@ export class ContextCache {
 	private cachedStaticSegment: string | undefined
 	private cachedStaticHash: string | undefined
 
-	constructor(config: ContextCacheConfig) {
+	constructor(config: PromptCacheConfig) {
 		this.projectId = config.projectId
 		this.agentId = config.agentId
 	}
@@ -51,6 +53,7 @@ export class ContextCache {
 			tools: input.tools,
 			allowedTools: input.allowedTools,
 			runtimeContext: input.runtimeContext,
+			...(input.contributions ? { contributions: input.contributions } : {}),
 		})
 
 		this.cachedPrompt = builder.build()
@@ -82,6 +85,7 @@ export class ContextCache {
 			tools: input.tools,
 			allowedTools: input.allowedTools,
 			runtimeContext: input.runtimeContext,
+			...(input.contributions ? { contributions: input.contributions } : {}),
 		})
 
 		const segments = builder.buildSegmented(contextLevel, workingDirectory)
@@ -114,6 +118,14 @@ export class ContextCache {
 			input.persona?.identity?.description ?? '',
 			input.basePrompt ?? '',
 			...(input.skills?.map((s) => s.metadata.name) ?? []),
+			// The STATIC ones only, because this hash guards the static
+			// segment. A `dynamic` or `turn` contributor coming or going does
+			// not change the cached prefix, and folding it in here would
+			// invalidate that prefix for a change it does not describe.
+			...(input.contributions
+				?.list()
+				.filter((c) => c.placement === 'static')
+				.map((c) => c.id) ?? []),
 		]
 
 		return createHash('sha256').update(parts.join('\0')).digest('hex').slice(0, 16)
@@ -129,6 +141,14 @@ export class ContextCache {
 			...(input.skills?.map((s) => s.metadata.name) ?? []),
 			...(input.allowedTools ?? []),
 			JSON.stringify(input.runtimeContext ?? {}),
+			// Ids and placements, not rendered text. Rendering every
+			// contribution to hash it would run them twice per request for a
+			// value the cache exists to avoid computing — and a contributor
+			// whose OUTPUT changes while its id does not is exactly the one
+			// that must declare `dynamic` or `turn` rather than `static`.
+			// Hashing the identity is what catches the change this cache can
+			// actually be wrong about: a different SET of contributors.
+			...(input.contributions?.list().map((c) => `${c.id}:${c.placement}`) ?? []),
 		]
 
 		return createHash('sha256').update(parts.join('\0')).digest('hex').slice(0, 16)

package/src/runtime/query/prompt.ts

@@ -1,5 +1,10 @@
 import { FILESYSTEM_TOOLS } from '../../constants/tools/index.js'
 import { assembleSystemPrompt, renderSkillsSection } from '../../persona/assembler.js'
+import {
+	type PromptContributionContext,
+	type PromptContributionRegistry,
+	SKILLS_CONTRIBUTION_ID,
+} from '../../prompt/contributions.js'
 import type { AgentRuntimeContext } from '../../types/agent/base.js'
 import type { AgentContextLevel } from '../../types/agent/factory.js'
 import type { AgentPersona } from '../../types/persona/index.js'
@@ -25,6 +30,15 @@ export interface PromptBuilderConfig {
 	tools: ToolRegistryContract
 	allowedTools?: string[]
 	runtimeContext?: AgentRuntimeContext
+	/**
+	 * What else goes in the prompt, beyond what this builder knows about.
+	 *
+	 * Absent means exactly what it meant before this existed: the fixed
+	 * list. A capability that needs the model to know something registers
+	 * here instead of arguing for a branch or splicing into `systemPrompt`
+	 * and losing whatever was there.
+	 */
+	contributions?: PromptContributionRegistry
 }
 
 function buildEnvContext(workingDirectory: string, runtimeContext?: AgentRuntimeContext): string {
@@ -97,6 +111,81 @@ export class PromptBuilder {
 		this.config = config
 	}
 
+	/**
+	 * The context every contribution is rendered against.
+	 *
+	 * `workingDirectory` is a call argument rather than config, so it is
+	 * threaded rather than read off `this`.
+	 */
+	private contributionContext(workingDirectory?: string): PromptContributionContext {
+		return {
+			...(workingDirectory === undefined ? {} : { workingDirectory }),
+			...(this.config.runtimeContext ? { runtimeContext: this.config.runtimeContext } : {}),
+			...(this.config.skills ? { skills: this.config.skills } : {}),
+			...(this.config.allowedTools ? { allowedTools: this.config.allowedTools } : {}),
+		}
+	}
+
+	/**
+	 * Skills, once, in the slot they were always in.
+	 *
+	 * The registry renders at the END of the prompt, and skills belong where
+	 * they have always been: immediately after the persona or system prompt.
+	 * So the built-in contribution is rendered IN PLACE here rather than
+	 * being left to the tail — a host that registers it gets the seam, not a
+	 * reordered prompt.
+	 *
+	 * This is also what makes it a real contributor rather than a decorative
+	 * one. Written first as "the builder renders skills, and the registry
+	 * skips its own copy", which a mutation caught immediately: the
+	 * contribution could be deleted with no observable effect, because the
+	 * builder's own branch rendered skills either way. A seam whose first
+	 * consumer is inert proves nothing about the seam.
+	 *
+	 * The persona branch is the exception and stays one:
+	 * `assembleSystemPrompt(persona, skills)` places skills inside the
+	 * persona's own section ordering, relative to constraints and output
+	 * discipline. Routing it through here would silently reorder every
+	 * persona-driven prompt in the estate.
+	 */
+	private renderSkillsInPlace(): string | null {
+		const contribution = this.config.contributions
+			?.list()
+			.find((c) => c.id === SKILLS_CONTRIBUTION_ID)
+		if (contribution) return contribution.render(this.contributionContext())
+		return renderSkillsSection(this.config.skills)
+	}
+
+	/**
+	 * `static` and `dynamic` only, and the signature says so.
+	 *
+	 * A `turn` contribution rendered here would land in the system prompt —
+	 * cached for the run under `static`, or read as a standing instruction
+	 * under `dynamic`. Either way the state it exists to report goes stale
+	 * silently, which is the exact failure `turn` was added to avoid. The
+	 * iteration loop renders those, into the ephemeral message.
+	 */
+	private renderContributions(
+		placement: 'static' | 'dynamic',
+		workingDirectory?: string,
+	): readonly string[] {
+		const registry = this.config.contributions
+		if (!registry) return []
+		const context = this.contributionContext(workingDirectory)
+		return (
+			registry
+				.list()
+				.filter((contribution) => contribution.placement === placement)
+				// Skills is rendered IN PLACE by `renderSkillsInPlace`, so the tail
+				// must not render it again. Unconditional, not branch-dependent:
+				// under a persona it is already inside the persona section, and
+				// otherwise it is already in its own slot above.
+				.filter((contribution) => contribution.id !== SKILLS_CONTRIBUTION_ID)
+				.map((contribution) => contribution.render(context))
+				.filter((text): text is string => typeof text === 'string' && text.trim().length > 0)
+		)
+	}
+
 	build(contextLevel: AgentContextLevel = 'full', workingDirectory?: string): string {
 		const parts: string[] = []
 
@@ -109,12 +198,12 @@ export class PromptBuilder {
 		} else if (this.config.persona) {
 			parts.push(assembleSystemPrompt(this.config.persona, this.config.skills))
 		} else {
-			const skillSection = renderSkillsSection(this.config.skills)
+			const skillSection = this.renderSkillsInPlace()
 			if (skillSection) parts.push(skillSection)
 		}
 
 		if (this.config.systemPrompt) {
-			const skillSection = renderSkillsSection(this.config.skills)
+			const skillSection = this.renderSkillsInPlace()
 			if (skillSection) parts.push(skillSection)
 		}
 
@@ -139,6 +228,14 @@ export class PromptBuilder {
 			}
 		}
 
+		// Static then dynamic, in that order and nothing between them,
+		// because that is exactly how `buildSegmented` is rejoined upstream:
+		// `${static}\n\n---\n\n${dynamic}`. The two methods produce the same
+		// prompt for the same input, and a run that hits the prompt cache
+		// must not be asking a different question from one that misses it.
+		parts.push(...this.renderContributions('static', workingDirectory))
+		parts.push(...this.renderContributions('dynamic', workingDirectory))
+
 		return parts.join('\n\n---\n\n')
 	}
 
@@ -167,12 +264,12 @@ export class PromptBuilder {
 				dynamicParts.push(`## Session Context\n${this.config.persona.sessionContext.trim()}`)
 			}
 		} else {
-			const skillSection = renderSkillsSection(this.config.skills)
+			const skillSection = this.renderSkillsInPlace()
 			if (skillSection) staticParts.push(skillSection)
 		}
 
 		if (this.config.systemPrompt) {
-			const skillSection = renderSkillsSection(this.config.skills)
+			const skillSection = this.renderSkillsInPlace()
 			if (skillSection) staticParts.push(skillSection)
 		}
 
@@ -197,6 +294,9 @@ export class PromptBuilder {
 			}
 		}
 
+		staticParts.push(...this.renderContributions('static', workingDirectory))
+		dynamicParts.push(...this.renderContributions('dynamic', workingDirectory))
+
 		return {
 			static: staticParts.join(separator),
 			dynamic: dynamicParts.join(separator),