@namzu/sdk 36.0.0 → 38.0.0

package/src/manager/agent/lifecycle.ts

@@ -1,4 +1,5 @@
 import { AGENT_MANAGER_DEFAULTS } from '../../constants/agent/index.js'
+import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
 import { GENAI } from '../../constants/telemetry/index.js'
 import type { AgentRegistry } from '../../registry/agent/definitions.js'
 import {
@@ -91,6 +92,18 @@ interface AgentManagerBaseDeps {
  */
 export type AgentManagerDeps = AgentManagerBaseDeps & TopicManagerDependency
 
+/** Internal backpressure: the parent's unmeasured request owns its budget until its receipt. */
+class ParentBudgetRequestPending extends Error {}
+
+interface PendingSpawn {
+	ready: boolean
+	readonly task: AgentTask
+	readonly options: SendMessageOptions
+	readonly context: AgentTaskContext
+	readonly listener?: RunEventListener
+	readonly removeAbortListener: () => void
+}
+
 interface ChildSpawnRecord {
 	subSessionId: SubSessionId
 	childSessionId: SessionId
@@ -141,6 +154,12 @@ export class AgentManager {
 	private spawnLocks: Map<SessionId, Promise<void>> = new Map()
 	private deps: AgentManagerDeps
 	private topicManager: TopicManager
+	private readonly pendingSpawns = new Map<SessionId, PendingSpawn[]>()
+	private readonly drainingParents = new Set<SessionId>()
+	private readonly executingTasks = new Set<TaskId>()
+	private readonly cancelingTasks = new Set<TaskId>()
+	private admissionTimer: ReturnType<typeof setTimeout> | undefined
+	private disposed = false
 
 	constructor(
 		registry: AgentRegistry,
@@ -149,6 +168,9 @@ export class AgentManager {
 	) {
 		this.registry = registry
 		this.config = { ...AGENT_MANAGER_DEFAULTS, ...config }
+		const maxPending = this.config.maxPendingTasks ?? 128
+		if (!Number.isSafeInteger(maxPending) || maxPending < 1)
+			throw new Error('maxPendingTasks must be a positive safe integer')
 		this.log = resolveLogger(deps.log).child({
 			[SCOPE_ATTRIBUTE]: 'manager/agent/lifecycle',
 		})
@@ -161,6 +183,182 @@ export class AgentManager {
 		context: AgentTaskContext,
 		listener?: RunEventListener,
 	): Promise<AgentTask> {
+		if (this.disposed) throw new Error('Agent manager is disposed')
+		if (this.config.capacityBehavior === 'queue')
+			return this.enqueueMessage(options, context, listener)
+		return this.startMessage(options, context, listener)
+	}
+
+	private async enqueueMessage(
+		options: SendMessageOptions,
+		context: AgentTaskContext,
+		listener?: RunEventListener,
+	): Promise<AgentTask> {
+		context.parentAbortController.signal.throwIfAborted()
+		if (context.depth >= this.config.maxDepth)
+			throw new Error(`Max task depth ${this.config.maxDepth} exceeded`)
+		if (options.tenantId !== context.tenantId)
+			throw new Error('Tenant mismatch: cross-tenant spawn rejected')
+		const definition = this.registry.getOrThrow(options.agentId)
+		const count = [...this.pendingSpawns.values()].reduce((sum, queue) => sum + queue.length, 0)
+		if (count >= (this.config.maxPendingTasks ?? 128))
+			throw new Error(
+				`Delegation queue is full (${this.config.maxPendingTasks ?? 128} pending tasks). Wait for existing tasks before submitting more work.`,
+			)
+		const task: AgentTask = {
+			taskId: generateTaskId(),
+			agentId: options.agentId,
+			agent: definition.typedAgent,
+			childAbortController: createChildAbortController(context.parentAbortController),
+			context,
+			state: 'pending',
+			pendingMessages: [],
+			createdAt: Date.now(),
+			runEventListener: listener,
+		}
+		this.instances.set(task.taskId, task)
+		const onAbort = (): void => {
+			// Before admission this observer owns cancellation. Once child scope
+			// exists, startup rollback may abort its controller for a configuration
+			// error; that is a failure, not a user cancellation.
+			if (task.context === context || context.parentAbortController.signal.aborted)
+				this.cancel(task.taskId, 'parent')
+		}
+		task.childAbortController.signal.addEventListener('abort', onAbort, { once: true })
+		const entry: PendingSpawn = {
+			ready: false,
+			task,
+			options,
+			context,
+			listener,
+			removeAbortListener: () =>
+				task.childAbortController.signal.removeEventListener('abort', onAbort),
+		}
+		const queue = this.pendingSpawns.get(options.parentSessionId) ?? []
+		queue.push(entry)
+		this.pendingSpawns.set(options.parentSessionId, queue)
+		this.emit({
+			type: 'pending',
+			taskId: task.taskId,
+			agentId: options.agentId,
+			parentAgentId: context.parentAgentId,
+			depth: context.depth,
+		})
+		try {
+			await listener?.({
+				type: 'agent_pending',
+				runId: context.parentRunId,
+				taskId: task.taskId,
+				parentAgentId: context.parentAgentId,
+				childAgentId: options.agentId,
+				depth: context.depth,
+			})
+			entry.ready = true
+		} catch (error) {
+			this.failAdmission(entry, error)
+		}
+		this.pumpAdmissions(options.parentSessionId)
+		return task
+	}
+
+	private pumpAdmissions(parentSessionId: SessionId): void {
+		if (this.disposed || this.drainingParents.has(parentSessionId)) return
+		this.drainingParents.add(parentSessionId)
+		void this.drainAdmissions(parentSessionId)
+			.finally(() => {
+				this.drainingParents.delete(parentSessionId)
+				// External handoffs and metadata changes have no manager event. A
+				// single slow, unref'ed timer observes those without spinning or
+				// keeping a host alive. Actual completions wake admission directly.
+				if (!this.disposed && this.pendingSpawns.size > 0 && !this.admissionTimer) {
+					this.admissionTimer = setTimeout(() => {
+						this.admissionTimer = undefined
+						for (const parent of this.pendingSpawns.keys()) this.pumpAdmissions(parent)
+					}, 250)
+					this.admissionTimer.unref?.()
+				}
+			})
+			.catch((error) =>
+				this.log.error('Delegation admission failed', {
+					'exception.message': toErrorMessage(error),
+				}),
+			)
+	}
+
+	private async drainAdmissions(parentSessionId: SessionId): Promise<void> {
+		const queue = this.pendingSpawns.get(parentSessionId)
+		if (!queue) return
+		while (!this.disposed && queue.length > 0) {
+			const entry = queue[0]
+			if (!entry) break
+			if (isTerminalAgentTaskState(entry.task.state)) {
+				entry.removeAbortListener()
+				queue.shift()
+				continue
+			}
+			// A concurrent enqueue can pump this same FIFO while the head's
+			// pending listener still owns its acknowledgement. Do not provision
+			// or spend until that acknowledgement succeeds.
+			if (!entry.ready) return
+			try {
+				await entry.options.beforeStart?.()
+				entry.task.childAbortController.signal.throwIfAborted()
+				await this.validateSpawn(entry.options, entry.context)
+				entry.task.childAbortController.signal.throwIfAborted()
+				await this.startMessage(entry.options, entry.context, entry.listener, entry.task)
+				entry.removeAbortListener()
+			} catch (error) {
+				if (
+					(error instanceof ParentBudgetRequestPending ||
+						(error instanceof DelegationCapacityExceeded && error.details.dimension === 'width')) &&
+					!isTerminalAgentTaskState(entry.task.state)
+				)
+					return
+				this.failAdmission(entry, error)
+			}
+			queue.shift()
+		}
+		if (queue.length === 0 && this.pendingSpawns.get(parentSessionId) === queue)
+			this.pendingSpawns.delete(parentSessionId)
+	}
+
+	private failAdmission(entry: PendingSpawn, reason: unknown): void {
+		entry.removeAbortListener()
+		const task = entry.task
+		if (isTerminalAgentTaskState(task.state)) return
+		task.childAbortController.abort(reason)
+		const error = toErrorMessage(reason)
+		task.result = {
+			runId: entry.context.parentRunId,
+			status: 'failed',
+			usage: { ...EMPTY_TOKEN_USAGE },
+			cost: { ...ZERO_COST },
+			iterations: 0,
+			durationMs: Date.now() - task.createdAt,
+			messages: [],
+			lastError: error,
+		}
+		task.state = 'failed'
+		task.completedAt = Date.now()
+		this.emit({ type: 'failed', taskId: task.taskId, error })
+		this.emitRunEvent(task, {
+			type: 'agent_failed',
+			runId: entry.context.parentRunId,
+			taskId: task.taskId,
+			error,
+		})
+		this.scheduleEviction(task.taskId)
+		this.resolveCompletionCallbacks(task.taskId)
+	}
+
+	private async startMessage(
+		options: SendMessageOptions,
+		context: AgentTaskContext,
+		listener?: RunEventListener,
+		queuedTask?: AgentTask,
+	): Promise<AgentTask> {
+		await options.beforeStart?.()
+		queuedTask?.childAbortController.signal.throwIfAborted()
 		if (context.depth >= this.config.maxDepth) {
 			throw new Error(
 				`Max task depth ${this.config.maxDepth} exceeded (current: ${context.depth}). Recursive agent delegation is limited to prevent resource exhaustion.`,
@@ -200,23 +398,53 @@ export class AgentManager {
 		// Reserve synchronously before provisioning yields. The authority is shared
 		// across managers and nested sessions, while the session lock below only
 		// serializes filesystem capacity checks.
+		// Queued siblings share the available budget with the parent. The first
+		// of eight children receives at most one ninth; later siblings receive
+		// comparable grants instead of a geometric 1/2, 1/4, ... starvation tail.
+		let budgetShares = 1
+		if (queuedTask) {
+			const project = await requireOpenProject(
+				this.deps.sessionStore,
+				context.projectId,
+				context.tenantId,
+				'spawn',
+			)
+			const children = await this.deps.sessionStore.getChildren(
+				options.parentSessionId,
+				context.tenantId,
+			)
+			const active = children.filter(
+				(child) =>
+					child.status !== 'idle' && child.status !== 'failed' && child.status !== 'archived',
+			).length
+			budgetShares = Math.max(2, project.config.maxDelegationWidth - active + 1)
+		}
+		context.parentAbortController.signal.throwIfAborted()
+		queuedTask?.childAbortController.signal.throwIfAborted()
 		const remaining = context.budget.remaining
 		const maxAllocation = Number.isFinite(remaining)
-			? Math.floor(remaining * this.config.maxBudgetFraction)
-			: (options.budgetAllocation?.tokenBudget ??
-				(options.configOverrides?.tokenBudget === 0
-					? 200_000
-					: (options.configOverrides?.tokenBudget ?? 200_000)))
+			? Math.floor(Math.min(remaining * this.config.maxBudgetFraction, remaining / budgetShares))
+			: (options.budgetAllocation?.tokenBudget ?? options.configOverrides?.tokenBudget ?? 200_000)
 		const allocatedTokens = Math.min(
 			options.budgetAllocation?.tokenBudget ?? maxAllocation,
 			maxAllocation,
 		)
-		if (!Number.isSafeInteger(allocatedTokens) || allocatedTokens <= 0) {
+		if (
+			!Number.isSafeInteger(allocatedTokens) ||
+			allocatedTokens < 0 ||
+			(allocatedTokens === 0 && Number.isFinite(remaining))
+		) {
 			throw new NamzuError({
 				code: 'invalid_config',
-				message: `Cannot spawn "${options.agentId}": the parent has ${remaining} tokens remaining; a child allocation must be a finite positive integer.`,
+				message: `Cannot spawn "${options.agentId}": the parent has ${remaining} tokens remaining; a child allocation must be a finite positive integer, or zero under an unlimited parent budget.`,
 			})
 		}
+		// No await between this check and reserve: a parent's response may start
+		// during the scope reads above. Its own in-flight request is temporary
+		// backpressure; descendant requests are expected during a fan-out.
+		// Invalid/zero allocations above still fail rather than waiting forever.
+		if (queuedTask && context.budget.hasInFlightRequest)
+			throw new ParentBudgetRequestPending('The parent provider request is still in flight')
 		const childBudget = context.budget.reserve(allocatedTokens)
 		let spawnRecord: ChildSpawnRecord
 		try {
@@ -230,9 +458,12 @@ export class AgentManager {
 		let childAbortController: AbortController | undefined
 		let agentTask: AgentTask | undefined
 		try {
-			childAbortController = createChildAbortController(context.parentAbortController)
+			childAbortController =
+				queuedTask?.childAbortController ??
+				createChildAbortController(context.parentAbortController)
 
-			const taskId = generateTaskId()
+			childAbortController.signal.throwIfAborted()
+			const taskId = queuedTask?.taskId ?? generateTaskId()
 
 			const childParentActor: ActorRef = {
 				kind: 'agent',
@@ -279,40 +510,42 @@ export class AgentManager {
 				...(resolvedDenies.length > 0 ? { toolDenies: resolvedDenies } : {}),
 			}
 
-			agentTask = {
+			agentTask = Object.assign(queuedTask ?? {}, {
 				taskId,
 				agentId: options.agentId,
 				agent,
 				childAbortController,
 				context: childContext,
 				state: 'pending',
-				pendingMessages: [],
-				createdAt: Date.now(),
+				pendingMessages: queuedTask?.pendingMessages ?? [],
+				createdAt: queuedTask?.createdAt ?? Date.now(),
 				runEventListener: listener,
-			}
+			} satisfies AgentTask)
 
 			childAbortController.signal.throwIfAborted()
 			this.instances.set(taskId, agentTask)
 			if (resolvedDenies.length > 0) spawnRecord.resolvedToolDenies = resolvedDenies
 			this.spawnRecords.set(taskId, spawnRecord)
-			this.emit({
-				type: 'pending',
-				taskId,
-				agentId: options.agentId,
-				parentAgentId: context.parentAgentId,
-				depth: context.depth,
-			})
-
-			if (listener) {
-				await listener({
-					type: 'agent_pending',
-					runId: context.parentRunId,
+			if (!queuedTask)
+				this.emit({
+					type: 'pending',
 					taskId,
+					agentId: options.agentId,
 					parentAgentId: context.parentAgentId,
-					childAgentId: options.agentId,
 					depth: context.depth,
 				})
 
+			if (listener) {
+				if (!queuedTask)
+					await listener({
+						type: 'agent_pending',
+						runId: context.parentRunId,
+						taskId,
+						parentAgentId: context.parentAgentId,
+						childAgentId: options.agentId,
+						depth: context.depth,
+					})
+
 				const lineage: Lineage = {
 					parentSessionId: spawnRecord.parentSessionId,
 					rootSessionId: spawnRecord.rootSessionId,
@@ -454,9 +687,11 @@ export class AgentManager {
 				})
 			}
 			childConfig.tokenBudget =
-				childConfig.tokenBudget === 0
-					? allocatedTokens
-					: Math.min(childConfig.tokenBudget, allocatedTokens)
+				allocatedTokens === 0
+					? childConfig.tokenBudget
+					: childConfig.tokenBudget === 0
+						? allocatedTokens
+						: Math.min(childConfig.tokenBudget, allocatedTokens)
 			childBudget.narrow(childConfig.tokenBudget)
 
 			// Stamped AFTER the builder, for the fourth time and the same reason:
@@ -503,17 +738,35 @@ export class AgentManager {
 
 			await childBudget.flush()
 			childAbortController.signal.throwIfAborted()
-			this.runChild(agentTask, options, childConfig, listener).catch(async (err) => {
-				// A thrown invocation supplied no final usage receipt. Keep its
-				// reservation, including when its task handle was canceled or evicted.
-				let failure = err
-				try {
-					await childBudget.flush()
-				} catch (writeError) {
-					failure = writeError
-				}
-				this.markFailed(taskId, toErrorMessage(failure))
-			})
+			this.executingTasks.add(taskId)
+			const runningTask = agentTask
+			this.runChild(runningTask, options, childConfig, listener)
+				.catch(async (err) => {
+					// A thrown invocation supplied no final usage receipt. Keep its
+					// reservation, including when its task handle was canceled or evicted.
+					let failure = err
+					try {
+						await childBudget.flush()
+					} catch (writeError) {
+						failure = writeError
+					}
+					// Cancellation may already have published a terminal handle. Its
+					// invocation has only NOW stopped; release the persisted edge here.
+					if (!this.instances.has(taskId) || isTerminalAgentTaskState(runningTask.state)) {
+						await this.failSubSession(spawnRecord)
+					} else this.markFailed(taskId, toErrorMessage(failure))
+				})
+				.finally(() => {
+					this.executingTasks.delete(taskId)
+					if (!this.instances.has(taskId)) this.spawnRecords.delete(taskId)
+					this.pumpAdmissions(options.parentSessionId)
+				})
+				.catch((error) =>
+					this.log.warn('Child cleanup failed', {
+						'namzu.task.id': taskId,
+						'exception.message': toErrorMessage(error),
+					}),
+				)
 
 			return agentTask
 		} catch (err) {
@@ -521,7 +774,7 @@ export class AgentManager {
 			// provisioned resources are still ours to return. A builder/listener
 			// failure must not strand a pending task the caller never received.
 			if (agentTask) {
-				await this.rollbackUnstartedSpawn(agentTask, spawnRecord, err)
+				await this.rollbackUnstartedSpawn(agentTask, spawnRecord, err, queuedTask !== undefined)
 			} else {
 				childAbortController?.abort()
 				childBudget.settle(0)
@@ -536,6 +789,7 @@ export class AgentManager {
 		agentTask: AgentTask,
 		spawnRecord: ChildSpawnRecord,
 		reason: unknown,
+		retainHandle = false,
 	): Promise<void> {
 		agentTask.childAbortController.abort()
 		agentTask.context.budget.settle(0)
@@ -559,7 +813,20 @@ export class AgentManager {
 			}
 		}
 		this.clearEvictionTimer(agentTask.taskId)
-		this.instances.delete(agentTask.taskId)
+		if (retainHandle) {
+			agentTask.result ??= {
+				runId: agentTask.context.parentRunId,
+				status: 'failed',
+				usage: { ...EMPTY_TOKEN_USAGE },
+				cost: { ...ZERO_COST },
+				iterations: 0,
+				durationMs: Date.now() - agentTask.createdAt,
+				messages: [],
+				lastError: toErrorMessage(reason),
+			}
+			agentTask.completedAt = Date.now()
+			this.scheduleEviction(agentTask.taskId)
+		} else this.instances.delete(agentTask.taskId)
 		this.spawnRecords.delete(agentTask.taskId)
 		this.resolveCompletionCallbacks(agentTask.taskId)
 		await this.rollbackSpawnResources(spawnRecord)
@@ -581,14 +848,22 @@ export class AgentManager {
 	}
 
 	cancel(taskId: TaskId, cause?: CancelCause): void {
+		if (this.cancelingTasks.has(taskId)) return
 		const agentTask = this.instances.get(taskId)
 		if (!agentTask || isTerminalAgentTaskState(agentTask.state)) return
 
 		// Was the bare string `'canceled'`, which `abortReasonText` suppresses
 		// by name — its docblock cites this exact call site — so the child's
 		// run saw a cancellation with no attributable origin at all.
-		agentTask.childAbortController.abort(cause ? new RunCancelled(cause) : undefined)
-		this.markCanceled(taskId, cause)
+		// Abort listeners run synchronously. A pending task's parent observer
+		// must not reenter this method and replace an explicit user's cause.
+		this.cancelingTasks.add(taskId)
+		try {
+			agentTask.childAbortController.abort(cause ? new RunCancelled(cause) : undefined)
+			this.markCanceled(taskId, cause)
+		} finally {
+			this.cancelingTasks.delete(taskId)
+		}
 	}
 
 	cancelAll(parentRunId: RunId, cause: CancelCause = 'parent'): void {
@@ -687,12 +962,18 @@ export class AgentManager {
 			if (isTerminalAgentTaskState(agentTask.state)) {
 				this.clearEvictionTimer(taskId)
 				this.instances.delete(taskId)
-				this.spawnRecords.delete(taskId)
+				if (!this.executingTasks.has(taskId)) this.spawnRecords.delete(taskId)
 			}
 		}
 	}
 
 	dispose(): void {
+		this.disposed = true
+		if (this.admissionTimer) clearTimeout(this.admissionTimer)
+		this.admissionTimer = undefined
+		for (const queue of this.pendingSpawns.values())
+			for (const entry of queue) entry.removeAbortListener()
+		this.pendingSpawns.clear()
 		for (const taskId of this.instances.keys()) {
 			this.clearEvictionTimer(taskId)
 		}
@@ -704,7 +985,8 @@ export class AgentManager {
 			this.cancel(taskId)
 		}
 		this.instances.clear()
-		this.spawnRecords.clear()
+		for (const taskId of this.spawnRecords.keys())
+			if (!this.executingTasks.has(taskId)) this.spawnRecords.delete(taskId)
 		this.listeners.length = 0
 	}
 
@@ -748,10 +1030,10 @@ export class AgentManager {
 		}
 	}
 
-	private async provisionSpawnUnlocked(
+	private async validateSpawn(
 		options: SendMessageOptions,
 		context: AgentTaskContext,
-	): Promise<ChildSpawnRecord> {
+	): Promise<void> {
 		// Phase 9: deps are unconditional required. Every spawn produces a
 		// SubSession + Session + WorkspaceRef triple (Convention #0: no
 		// partial/legacy path).
@@ -782,6 +1064,8 @@ export class AgentManager {
 				`Parent session ${options.parentSessionId} not found for tenant ${context.tenantId} — spawn rejected`,
 			)
 		}
+		if (parentSession.status === 'archived')
+			throw new Error('Delegation parent session is archived')
 		if (parentSession.topicId !== context.topicId) {
 			throw new Error(
 				`Topic mismatch on spawn: parent session ${parentSession.id} is on topic ${parentSession.topicId}, but context.topicId=${context.topicId}. Cross-topic spawn is forbidden (session-hierarchy.md §6.3).`,
@@ -812,6 +1096,15 @@ export class AgentManager {
 			project.config.maxDelegationWidth,
 			context.tenantId,
 		)
+	}
+
+	private async provisionSpawnUnlocked(
+		options: SendMessageOptions,
+		context: AgentTaskContext,
+	): Promise<ChildSpawnRecord> {
+		await this.validateSpawn(options, context)
+		context.parentAbortController.signal.throwIfAborted()
+		const store = this.deps.sessionStore
 
 		// Ancestry walk gives both the child depth and the root session id
 		// attached to every sub-session event from here down.
@@ -1228,6 +1521,7 @@ export class AgentManager {
 	}
 
 	private scheduleEviction(taskId: TaskId): void {
+		if (this.disposed) return
 		const agentTask = this.instances.get(taskId)
 		if (!agentTask) return
 
@@ -1235,7 +1529,7 @@ export class AgentManager {
 
 		const timer = setTimeout(() => {
 			this.instances.delete(taskId)
-			this.spawnRecords.delete(taskId)
+			if (!this.executingTasks.has(taskId)) this.spawnRecords.delete(taskId)
 			this.evictionTimers.delete(taskId)
 			this.log.info('Agent task evicted', { 'namzu.agent.task_id': taskId })
 		}, this.config.evictionMs)
@@ -1274,15 +1568,19 @@ export class AgentManager {
 
 	private emitRunEvent(agentTask: AgentTask, event: RunEvent): void {
 		if (!agentTask.runEventListener) return
-		try {
-			agentTask.runEventListener(event)
-		} catch (err) {
+		const reportFailure = (error: unknown): void => {
 			this.log.error('RunEvent emission error', {
 				'namzu.event.type': event.type,
-				'namzu.task.id': agentTask.taskId,
-				'exception.message': toErrorMessage(err),
+				'exception.message': toErrorMessage(error),
 			})
 		}
+		try {
+			// Terminal observation must not delay completion or leak a rejected
+			// listener promise into the host as an unhandled rejection.
+			void Promise.resolve(agentTask.runEventListener(event)).catch(reportFailure)
+		} catch (error) {
+			reportFailure(error)
+		}
 	}
 }
 

package/src/manager/run/persistence.ts

@@ -306,6 +306,7 @@ export class RunPersistence {
 	}
 
 	markFailed(error: string, providerError?: ProviderErrorInfo): void {
+		this.clearStructuredOutput()
 		this.run.status = 'failed'
 		this.run.stopReason = 'error'
 		this.run.lastError = error
@@ -314,6 +315,7 @@ export class RunPersistence {
 	}
 
 	markCancelled(): void {
+		this.clearStructuredOutput()
 		this.run.status = 'cancelled'
 		this.run.stopReason = 'cancelled'
 		this.run.endedAt = Date.now()
@@ -459,6 +461,11 @@ export class RunPersistence {
 	 * and without the override flag it would walk the tail and put the stale
 	 * prose back.
 	 */
+	/** Invalidate a structured value without replacing the host's textual result. */
+	clearStructuredOutput(): void {
+		delete this.run.structuredOutput
+	}
+
 	setStructuredOutput(value: unknown): void {
 		this.run.structuredOutput = value
 		this.setResult(typeof value === 'string' ? value : JSON.stringify(value))

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

@@ -49,11 +49,17 @@ export const CODING_AGENT_WORKING_DOCTRINE = `## How you work
 - Reference code as \`path:line\` so the user can jump to it.
 - Correct an earlier statement only when the error would change the user's code, conclusions or decisions; state it once, plainly, and continue. No apologies, no tally of past mistakes.
 
+### Using available evidence
+- Carry the active task and established facts across turns. A question or status request during ongoing work does not cancel that work unless the user says so. Ask for clarification when the intended change is genuinely unspecified; do not ask the user to repeat information already available.
+- Treat a successful tool result together with its exact inputs as evidence of what happened. Content you successfully wrote is available evidence, just like content you read. An announced action, proposed call, failed call, or another agent's unsupported claim is not proof of completion.
+- Reuse relevant evidence still available in conversation instead of observing it again by habit. Distinguish the last observed state from a guarantee that external state has not changed. Re-observe when evidence is missing, partial or invalidated, when another actor may have changed the target, or when freshness matters to the next action. If a check or exact-match edit reports a mismatch, inspect the current state and revise the action; do not force the old plan through.
+- When an observation is needed, ask the narrowest question that resolves the uncertainty. For a known file, inspect that file rather than listing the whole working directory. Recover missing observations with read-only tools, not by repeating a state-changing action.
+
 ### Reading and editing code
-- Read a file before you edit it, and read enough of the surrounding code to match its comment density, naming and idiom. Code that reads like the file it lives in is the goal; code that reads like a different author is a defect.
-- Prefer the dedicated tools over shell equivalents: \`read\` over \`cat\`, the \`grep\` tool over running \`grep\` or \`rg\` through bash, \`glob\` over \`find\` or \`ls -R\`, \`edit\` over \`sed -i\`. To change an existing file use \`edit\`; use \`write\` only to create a file or when the user asked for a whole-file rewrite. The dedicated tools are bounded, previewable and permission-aware; a shell command is none of those.
-- Independent tool calls go in one response. Reading three files, or running a grep and a glob, does not need three turns. Tools that mutate the workspace — \`bash\`, \`edit\`, \`write\` — are applied one after another even when you emit them together; read-only tools run in parallel.
-- After a change, run the checks that would catch a mistake in it — the package's tests, typecheck, lint — before you report it done. A change you did not verify is a change you are guessing about.
+- Before editing, use the relevant file content already available from a successful read or write; if it is unavailable or may be stale, read the needed portion. Read additional surrounding code when needed to match its naming and idiom. Respect project instructions and tool-specific prerequisites even when they require a fresh read.
+- Prefer the dedicated tools over shell equivalents: \`read\` over \`cat\`, the \`grep\` tool over running \`grep\` or \`rg\` through \`bash\`, \`glob\` over \`find\` or \`ls -R\`, \`edit\` over \`sed -i\`. To change an existing file use \`edit\`; use \`write\` only to create a file or when the user asked for a whole-file rewrite. Prefer their structured inputs and focused results; use shell commands when the task needs them, within the same configured permissions.
+- Independent tool calls go in one response. Reading three files, or running a grep and a glob, does not need three turns. Only group independent operations. Wait for a mutation to finish before an observation or another action that depends on it; runtime ordering and concurrency limits remain authoritative.
+- Match verification to the task and its risk. For a simple text-file operation, use the successful tool result and known content; do not run unrelated project tests or repeat a read merely to restate that result. For code changes, run the relevant tests, typecheck or lint that would catch a mistake, and follow required project checks. Never claim checks you did not run.
 - Never leave the working tree in a state you have not described. If you created scratch files, say where; if you touched files outside the request, say which.
 
 ### Working with git
@@ -72,7 +78,7 @@ export const CODING_AGENT_WORKING_DOCTRINE = `## How you work
  */
 export const CODING_AGENT_DELEGATION_DOCTRINE = `### Planning and delegating
 - For work that is genuinely multi-step — 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. Do not open one for a single inspect-edit-test cycle; the list is for the user to follow, and a list of one item tells them nothing.
-- When the \`Agent\` tool is available, delegate genuinely independent work through it and give each delegation a short, specific description; the user watches those descriptions, not the prompts. Each sub-agent starts with no context, so the prompt must carry everything it needs.
+- When the \`Agent\` tool is available, delegate genuinely independent work through it and give each delegation a short, specific description; the user watches those descriptions, not the prompts. Give each sub-agent the objective, relevant context and completion criteria; do not assume it sees context the delegation interface did not supply.
 - 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.`
 
 /**