@namzu/sdk 30.2.0 → 31.0.0

package/src/registry/command/kernel-commands.ts

@@ -1,4 +1,15 @@
+import type { SessionGoalActivation } from '../../manager/goal/activation.js'
+import {
+	GoalExistsError,
+	GoalNotFoundError,
+	GoalSessionNotFoundError,
+	GoalTransitionError,
+	type SessionGoalStore,
+	StaleGoalError,
+} from '../../store/goal/index.js'
 import type { HostCommandDescriptor } from '../../types/command/index.js'
+import type { GoalRef, SessionGoal } from '../../types/goal/index.js'
+import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { Skill } from '../../types/skills/index.js'
 import { isInvocableBy, skillInvocation } from '../../types/skills/index.js'
 import type { TaskStore } from '../../types/task/index.js'
@@ -7,10 +18,10 @@ import type { TaskStore } from '../../types/task/index.js'
  * The commands whose facts the kernel already owns.
  *
  * A registry with nothing in it is a declaration, and this repo has a rule
- * about those. These two are the ones a host currently has to reach into
- * kernel internals to answer: what work is tracked, and who this run may
- * delegate to. Both were already computed here and had no way out that did
- * not go through a specific host's UI code.
+ * about those. These are facts a host would otherwise have to reach into
+ * kernel internals to answer: the current Session goal, tracked work,
+ * operator-invocable skills, and the agents this run may delegate to. Each is
+ * computed or owned here and should not acquire a second host-specific source.
  *
  * Deliberately NOT here: anything that would need a decision the kernel
  * cannot make. `/clear` is about a transcript a host owns, `/login` about
@@ -30,10 +41,218 @@ export interface KernelCommandOptions {
 	 * is different from having none registered.
 	 */
 	readonly skills?: readonly Skill[]
+	/** Exact durable conversation scope behind the direct-human `/goal` command. */
+	readonly goal?: GoalCommandScope
+}
+
+export interface GoalCommandScope {
+	readonly store: SessionGoalStore
+	readonly sessionId: SessionId
+	readonly tenantId: TenantId
+	/** Process-local permission for automatic continuation. */
+	readonly activation?: SessionGoalActivation
+}
+
+const GOAL_USAGE = 'Usage: /goal [<objective>|clear|edit <objective>|pause|resume]'
+
+type ParsedGoalCommand =
+	| { readonly kind: 'show' }
+	| { readonly kind: 'create'; readonly objective: string }
+	| { readonly kind: 'edit'; readonly objective: string }
+	| { readonly kind: 'invalid-edit' }
+	| { readonly kind: 'pause' }
+	| { readonly kind: 'resume' }
+	| { readonly kind: 'clear' }
+
+function parseGoalCommand(args: readonly string[]): ParsedGoalCommand {
+	const input = args.join(' ').trim()
+	if (input.length === 0) return { kind: 'show' }
+	const control = input.toLowerCase()
+	if (control === 'clear') return { kind: 'clear' }
+	if (control === 'pause') return { kind: 'pause' }
+	if (control === 'resume') return { kind: 'resume' }
+	if (control === 'edit') return { kind: 'invalid-edit' }
+	if (/^edit(?=\s)/iu.test(input)) return { kind: 'edit', objective: input.slice(4).trim() }
+	return { kind: 'create', objective: input }
+}
+
+function goalRef(goal: SessionGoal): GoalRef {
+	return { id: goal.id, revision: goal.revision }
+}
+
+function goalCommands(goal: SessionGoal, armed: boolean): string {
+	if (goal.phase === 'active') {
+		return `${armed ? '' : '/goal resume, '}/goal edit <objective>, /goal pause, /goal clear`
+	}
+	if (goal.phase === 'paused' || goal.phase === 'blocked') {
+		return '/goal edit <objective>, /goal resume, /goal clear'
+	}
+	return '/goal <objective>, /goal clear'
+}
+
+function renderGoal(title: string, goal: SessionGoal, armed: boolean): string {
+	return [
+		title,
+		`Status: ${goal.phase}`,
+		`Automatic continuation: ${armed ? 'armed' : 'disarmed'}`,
+		`Rounds admitted: ${goal.roundsAdmitted} / ${goal.maxGoalRounds}`,
+		...(goal.blockedReason
+			? [`Blocker: ${goal.blockedReason.code}: ${goal.blockedReason.message}`]
+			: []),
+		`Objective: ${goal.objective}`,
+		'',
+		`Commands: ${goalCommands(goal, armed)}`,
+	].join('\n')
+}
+
+function renderScopedGoal(title: string, goal: SessionGoal, scope: GoalCommandScope): string {
+	return renderGoal(title, goal, scope.activation?.isArmed(scope.sessionId, goal) ?? false)
+}
+
+function missingGoal(action: string) {
+	return {
+		kind: 'refused' as const,
+		reason: `No goal is currently set; /goal ${action} requires one. ${GOAL_USAGE}`,
+	}
+}
+
+async function runGoalCommand(scope: GoalCommandScope | undefined, args: readonly string[]) {
+	if (!scope) {
+		return {
+			kind: 'refused' as const,
+			reason: 'Goals need a durable session. This host did not supply one for the current command.',
+		}
+	}
+	const command = parseGoalCommand(args)
+	try {
+		const current = await scope.store.getGoal(scope.sessionId, scope.tenantId)
+		switch (command.kind) {
+			case 'show':
+				return current
+					? { kind: 'ack' as const, message: renderScopedGoal('Goal', current, scope) }
+					: {
+							kind: 'ack' as const,
+							message: `No goal is currently set.\n${GOAL_USAGE}`,
+						}
+			case 'invalid-edit':
+				return {
+					kind: 'refused' as const,
+					reason: `Goal editing requires a replacement objective.\n${GOAL_USAGE}`,
+				}
+			case 'create': {
+				if (current && current.phase !== 'complete') {
+					return {
+						kind: 'refused' as const,
+						reason: `A goal is already ${current.phase}. Use /goal edit <objective> to change it or /goal clear before replacing it.`,
+					}
+				}
+				const created = await scope.store.createGoal(
+					{ sessionId: scope.sessionId, objective: command.objective },
+					scope.tenantId,
+				)
+				scope.activation?.arm(created)
+				return {
+					kind: 'ack' as const,
+					message: renderScopedGoal('Goal created', created, scope),
+				}
+			}
+			case 'edit': {
+				if (!current) return missingGoal('edit')
+				if (current.phase === 'complete') {
+					const replacement = await scope.store.createGoal(
+						{ sessionId: scope.sessionId, objective: command.objective },
+						scope.tenantId,
+					)
+					scope.activation?.arm(replacement)
+					return {
+						kind: 'ack' as const,
+						message: renderScopedGoal('Goal created', replacement, scope),
+					}
+				}
+				const wasArmed = scope.activation?.isArmed(scope.sessionId, current) ?? false
+				const edited = await scope.store.editGoal(
+					scope.sessionId,
+					scope.tenantId,
+					goalRef(current),
+					{ objective: command.objective },
+				)
+				if (wasArmed) scope.activation?.arm(edited)
+				return {
+					kind: 'ack' as const,
+					message: renderScopedGoal('Goal updated', edited, scope),
+				}
+			}
+			case 'pause': {
+				if (!current) return missingGoal('pause')
+				const paused = await scope.store.pauseGoal(
+					scope.sessionId,
+					scope.tenantId,
+					goalRef(current),
+				)
+				scope.activation?.disarm(scope.sessionId)
+				return {
+					kind: 'ack' as const,
+					message: renderScopedGoal('Goal paused', paused, scope),
+				}
+			}
+			case 'resume': {
+				if (!current) return missingGoal('resume')
+				if (current.phase === 'active') {
+					scope.activation?.arm(current)
+					return {
+						kind: 'ack' as const,
+						message: renderScopedGoal('Goal armed', current, scope),
+					}
+				}
+				const resumed = await scope.store.resumeGoal(
+					scope.sessionId,
+					scope.tenantId,
+					goalRef(current),
+				)
+				scope.activation?.arm(resumed)
+				return {
+					kind: 'ack' as const,
+					message: renderScopedGoal('Goal resumed', resumed, scope),
+				}
+			}
+			case 'clear': {
+				if (!current) {
+					scope.activation?.disarm(scope.sessionId)
+					return { kind: 'ack' as const, message: 'No goal to clear.' }
+				}
+				await scope.store.clearGoal(scope.sessionId, scope.tenantId, goalRef(current))
+				scope.activation?.disarm(scope.sessionId)
+				return { kind: 'ack' as const, message: 'Goal cleared.' }
+			}
+		}
+	} catch (error) {
+		if (
+			error instanceof GoalExistsError ||
+			error instanceof GoalNotFoundError ||
+			error instanceof GoalTransitionError ||
+			error instanceof StaleGoalError
+		) {
+			return {
+				kind: 'refused' as const,
+				reason:
+					'The goal command is not valid for the current state. Run /goal to view available commands.',
+			}
+		}
+		if (error instanceof GoalSessionNotFoundError) {
+			return { kind: 'refused' as const, reason: error.message }
+		}
+		throw error
+	}
 }
 
 export function kernelHostCommands(options: KernelCommandOptions): HostCommandDescriptor[] {
 	return [
+		{
+			name: 'goal',
+			description: 'Persist or inspect a completion goal for this conversation.',
+			hint: '[<objective>|clear|edit <objective>|pause|resume]',
+			handler: async ({ args }) => await runGoalCommand(options.goal, args),
+		},
 		{
 			name: 'tasks',
 			description: 'List the work this run is tracking.',

package/src/run/reporter.ts

@@ -343,6 +343,16 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'message_history_repaired':
+				log.warn('Repaired provider-invalid tool history', {
+					[NAMZU.RUN_ID]: event.runId,
+					'namzu.history.source': event.source,
+					'namzu.history.duplicate_tool_results_removed': event.duplicateToolResultsRemoved,
+					'namzu.history.orphaned_tool_results_removed': event.orphanedToolResultsRemoved,
+					'namzu.history.synthetic_tool_results_inserted': event.syntheticToolResultsInserted,
+				})
+				break
+
 			case 'tool_progress':
 				// Debug, not info: a long tool can emit many of these and they
 				// are a live-view signal, not a run milestone.

package/src/run-query/index.ts

@@ -27,6 +27,38 @@ export interface RunQueryOptions {
 	readonly now?: () => number
 }
 
+export type RunTranscriptUnavailableReason =
+	| 'message-snapshot-not-persisted'
+	| 'message-snapshot-unverified'
+	| 'message-snapshot-out-of-sync'
+
+/**
+ * Refusal to call a partial or unverifiable reconstruction "complete".
+ */
+export class RunTranscriptUnavailableError extends Error {
+	readonly reason: RunTranscriptUnavailableReason
+	readonly eventHeadSeq: number | undefined
+	readonly snapshotThroughEventSeq: number | undefined
+
+	constructor(input: {
+		reason: RunTranscriptUnavailableReason
+		eventHeadSeq?: number
+		snapshotThroughEventSeq?: number
+	}) {
+		const detail =
+			input.reason === 'message-snapshot-not-persisted'
+				? 'the surviving message snapshot was never persisted or its publication was interrupted'
+				: input.reason === 'message-snapshot-unverified'
+					? 'the surviving messages use the legacy format and carry no event-log boundary'
+					: `the surviving message snapshot ends at event ${input.snapshotThroughEventSeq ?? 'unknown'}, but the durable log ends at event ${input.eventHeadSeq ?? 'unknown'}`
+		super(`Complete run transcript unavailable: ${detail}.`)
+		this.name = 'RunTranscriptUnavailableError'
+		this.reason = input.reason
+		this.eventHeadSeq = input.eventHeadSeq
+		this.snapshotThroughEventSeq = input.snapshotThroughEventSeq
+	}
+}
+
 /** What one compaction pass removed. */
 export interface ShedPass {
 	readonly iteration: number
@@ -53,17 +85,7 @@ export class RunQuery {
 	 * was reading during an incident.
 	 */
 	async shedHistory(): Promise<readonly ShedPass[]> {
-		const passes: ShedPass[] = []
-		for (const event of await this.events()) {
-			if (event.type !== 'compaction_shed') continue
-			passes.push({
-				iteration: event.iteration,
-				reason: event.reason,
-				messages: event.messages,
-				seq: event.seq,
-			})
-		}
-		return passes
+		return shedPassesFrom(await this.events())
 	}
 
 	/**
@@ -80,10 +102,43 @@ export class RunQuery {
 	 * the conversation is missing from this list, which is the question
 	 * somebody reconstructing an incident is actually asking.
 	 */
-	async fullTranscript(messages: readonly Message[]): Promise<readonly Message[]> {
-		const shed = await this.shedHistory()
-		if (shed.length === 0) return messages
-		return [...shed.flatMap((pass) => pass.messages), ...messages]
+	async fullTranscript(messages?: readonly Message[]): Promise<readonly Message[]> {
+		if (messages !== undefined) {
+			const shed = await this.shedHistory()
+			if (shed.length === 0) return messages
+			return [...shed.flatMap((pass) => pass.messages), ...messages]
+		}
+
+		// Read the log first and compare the snapshot to that exact head. A
+		// previous pause may have left a perfectly valid messages file under the
+		// same run id; only the boundary says whether it belongs to THIS head.
+		const events = await this.events()
+		const eventHeadSeq = events.at(-1)?.seq ?? 0
+		const snapshot = await this.options.store.readMessages()
+
+		if (snapshot.kind === 'unavailable') {
+			throw new RunTranscriptUnavailableError({
+				reason: 'message-snapshot-not-persisted',
+				eventHeadSeq,
+			})
+		}
+		if (snapshot.kind === 'legacy-unverified') {
+			throw new RunTranscriptUnavailableError({
+				reason: 'message-snapshot-unverified',
+				eventHeadSeq,
+			})
+		}
+		if (snapshot.throughEventSeq !== eventHeadSeq) {
+			throw new RunTranscriptUnavailableError({
+				reason: 'message-snapshot-out-of-sync',
+				eventHeadSeq,
+				snapshotThroughEventSeq: snapshot.throughEventSeq,
+			})
+		}
+
+		const shed = shedPassesFrom(events)
+		if (shed.length === 0) return snapshot.messages
+		return [...shed.flatMap((pass) => pass.messages), ...snapshot.messages]
 	}
 
 	/**
@@ -106,3 +161,17 @@ export class RunQuery {
 		return registry.get<RunStatusState>(RUN_STATUS_READ_MODEL_ID)
 	}
 }
+
+function shedPassesFrom(events: readonly PersistedRunEvent[]): ShedPass[] {
+	const passes: ShedPass[] = []
+	for (const event of events) {
+		if (event.type !== 'compaction_shed') continue
+		passes.push({
+			iteration: event.iteration,
+			reason: event.reason,
+			messages: event.messages,
+			seq: event.seq,
+		})
+	}
+	return passes
+}

package/src/runtime/query/context.ts

@@ -235,9 +235,19 @@ export class RunContextFactory {
 			// takes an AbortController and what arrives here is a bare
 			// AbortSignal, so the reason is forwarded by hand rather than by
 			// reaching for a helper that does not fit.
-			config.signal.addEventListener('abort', () => abortController.abort(config.signal?.reason), {
-				once: true,
-			})
+			// AbortSignal does not replay an event that happened before a
+			// listener was installed. Mirror that state synchronously or a caller
+			// that withdrew authority before `query()` began receives a live run
+			// controller, allowing provider and tool work to start anyway.
+			if (config.signal.aborted) {
+				abortController.abort(config.signal.reason)
+			} else {
+				config.signal.addEventListener(
+					'abort',
+					() => abortController.abort(config.signal?.reason),
+					{ once: true },
+				)
+			}
 		}
 
 		const cwd = config.workingDirectory ?? process.cwd()

package/src/runtime/query/executor.ts

@@ -44,6 +44,7 @@ import { generateToolCallId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
 import { compressShellOutput } from '../../utils/shell-compress.js'
 import { type BackgroundJobRegistry, bindOwner } from '../jobs/registry.js'
+import type { ToolResultObservation } from './project-instructions.js'
 import {
 	DEFAULT_MAX_TOOL_OUTPUT_CHARS,
 	applyToolOutputBudget,
@@ -256,6 +257,8 @@ export interface ToolCallOutcome {
 export interface ToolExecutionBatch {
 	messages: Message[]
 	results: ToolCallOutcome[]
+	/** Actual registry executions, including calls dispatched by another tool. */
+	observations: ToolResultObservation[]
 }
 
 /**
@@ -418,7 +421,11 @@ export class ToolExecutor {
 	 * a scope its first half installed. That is precisely the incoherent
 	 * batch this line exists to make impossible.
 	 */
-	private skillScope?: { skill: string; allowedTools: readonly string[]; adoptedInBatch: number }
+	private skillScope?: {
+		skill: string
+		allowedTools: readonly string[]
+		adoptedInBatch: number
+	}
 	private batchCounter = 0
 
 	/**
@@ -455,7 +462,7 @@ export class ToolExecutor {
 	): Promise<ToolExecutionBatch> {
 		const toolCalls = response.message.toolCalls
 		if (!toolCalls) {
-			return { messages: [], results: [] }
+			return { messages: [], results: [], observations: [] }
 		}
 
 		this.batchCounter += 1
@@ -488,7 +495,11 @@ export class ToolExecutor {
 		// One context per call so each execution can see its own
 		// `toolUseId`. The base context is built once; we spread + add
 		// per-call to keep allocations cheap.
-		const baseContext = this.buildToolContext()
+		const observations: ToolResultObservation[] = []
+		const recordObservation = (observation: ToolResultObservation): void => {
+			observations.push(observation)
+		}
+		const baseContext = this.buildToolContext(recordObservation)
 
 		// Respect each tool's `concurrencySafe` flag. Read-only tools
 		// (ls/grep/glob/…) run in parallel; tools that mutate shared state
@@ -544,7 +555,7 @@ export class ToolExecutor {
 				// that made it. The base context has no `toolUseId`, and a
 				// closure built there would report every nested call as
 				// parentless.
-				dispatchTool: (name, input) => this.dispatchNested(name, input, ctx),
+				dispatchTool: (name, input) => this.dispatchNested(name, input, ctx, recordObservation),
 				// Per-call for the same reason: a pause has to be routed back
 				// to the call that raised it, and a batch can raise several.
 				...(this.config.toolPause ? { requestPause: this.config.toolPause(toolCall.id) } : {}),
@@ -563,7 +574,7 @@ export class ToolExecutor {
 				},
 			}
 			const run = async () => {
-				results[i] = await this.executeSingle(toolCall, ctx)
+				results[i] = await this.executeSingle(toolCall, ctx, recordObservation)
 			}
 			const gated = async () => {
 				await gate.acquire()
@@ -594,7 +605,12 @@ export class ToolExecutor {
 			const toolCall = toolCalls[i] as ToolCall
 			const toolName = toolCall.function.name
 			const message = `Error: Tool "${toolName}" did not complete — the batch failed before it produced a result.`
-			results[i] = { toolCallId: toolCall.id, toolName, output: message, isError: true }
+			results[i] = {
+				toolCallId: toolCall.id,
+				toolName,
+				output: message,
+				isError: true,
+			}
 			await this.emitEvent({
 				type: 'tool_completed',
 				runId: this.config.runId,
@@ -613,7 +629,7 @@ export class ToolExecutor {
 			createToolMessage(r.content ?? r.output, r.toolCallId, r.isError),
 		)
 
-		return { messages, results }
+		return { messages, results, observations }
 	}
 
 	/**
@@ -634,6 +650,7 @@ export class ToolExecutor {
 		name: string,
 		input: unknown,
 		context: ToolContext,
+		recordObservation: (observation: ToolResultObservation) => void,
 	): Promise<ToolResult> {
 		const parent = context.toolUseId
 		const via = parent ? { tool: name, toolUseId: parent as ToolUseId } : undefined
@@ -665,11 +682,21 @@ export class ToolExecutor {
 			durationMs: Date.now() - startedAt,
 			...(via ? { via } : {}),
 		})
+		recordObservation({
+			runId: this.config.runId,
+			toolUseId: nestedId,
+			toolName: name,
+			input,
+			result,
+			...(parent ? { parentToolUseId: parent } : {}),
+		})
 
 		return result
 	}
 
-	private buildToolContext(): ToolContext {
+	private buildToolContext(
+		recordObservation: (observation: ToolResultObservation) => void = () => {},
+	): ToolContext {
 		const context: ToolContext = {
 			runId: this.config.runId,
 			workingDirectory: this.config.workingDirectory,
@@ -702,13 +729,20 @@ export class ToolExecutor {
 			// dispatching outside a batch has no parent call to name. The
 			// per-call context below overrides it with one that does; see
 			// `dispatchNested`.
-			dispatchTool: (name, input) => this.dispatchNested(name, input, context),
+			dispatchTool: (name, input) => this.dispatchNested(name, input, context, recordObservation),
 			sandbox: this.config.sandbox,
 			fileReadTracker: this.fileReadTracker,
 			// Bound to this run, once. Binding here rather than passing the
 			// owner from the tool is what makes the scoping structural: there
 			// is no argument a tool could pass to reach another run's jobs.
-			...(this.config.backgroundJobs
+			//
+			// The registry's process substrate is the HOST. It must not coexist
+			// with a Sandbox in one tool context: handing both to every tool lets
+			// any of them call `backgroundJobs.start()` and escape the boundary
+			// that its foreground work would use. A sandbox-aware persistent
+			// process capability needs its own execution seam; until one exists,
+			// the safe composition is to withhold this host capability entirely.
+			...(this.config.backgroundJobs && !this.config.sandbox
 				? {
 						backgroundJobs: bindOwner(this.config.backgroundJobs, this.config.runId, {
 							workingDirectory: this.config.workingDirectory,
@@ -724,6 +758,7 @@ export class ToolExecutor {
 	private async executeSingle(
 		toolCall: ToolCall,
 		toolContext: ToolContext,
+		recordObservation: (observation: ToolResultObservation) => void,
 	): Promise<ToolCallOutcome> {
 		let toolName = toolCall.function.name
 
@@ -754,7 +789,12 @@ export class ToolExecutor {
 				result: message,
 				isError: true,
 			})
-			return { toolCallId: toolCall.id, toolName, output: message, isError: true }
+			return {
+				toolCallId: toolCall.id,
+				toolName,
+				output: message,
+				isError: true,
+			}
 		}
 
 		// A malformed call used to cost a full model round trip to fix: the
@@ -797,7 +837,12 @@ export class ToolExecutor {
 				result: message,
 				isError: true,
 			})
-			return { toolCallId: toolCall.id, toolName, output: message, isError: true }
+			return {
+				toolCallId: toolCall.id,
+				toolName,
+				output: message,
+				isError: true,
+			}
 		}
 
 		let input: unknown = resolved.input
@@ -1064,6 +1109,13 @@ export class ToolExecutor {
 			...(budgeted.truncated ? { outputTruncated: true } : {}),
 			...(budgeted.spillPath ? { outputSpillPath: budgeted.spillPath } : {}),
 		})
+		recordObservation({
+			runId: this.config.runId,
+			toolUseId: toolCall.id,
+			toolName,
+			input,
+			result,
+		})
 
 		const resolveContent = (): { content?: ToolResultContent } => {
 			if (postOverride?.content !== undefined) {
@@ -1210,7 +1262,12 @@ export class ToolExecutor {
 		if (!this.config.pluginManager) return { kind: 'continue', input }
 		const results = await this.config.pluginManager.executeHooks(
 			'pre_tool_use',
-			{ runId: this.config.runId, toolName, toolInput: input },
+			{
+				runId: this.config.runId,
+				toolName,
+				toolInput: input,
+				signal: this.config.abortSignal,
+			},
 			this.emitEvent,
 		)
 		return this.interpretPreToolResults(toolName, input, results)
@@ -1363,7 +1420,10 @@ export class ToolExecutor {
 			// Either the model named a tool that does not exist, or this
 			// registry does not implement `get`. Both are the registry's to
 			// answer; a repairer still gets offered the `unknown_tool` case.
-			return { reason: 'unknown_tool', message: `Error: Unknown tool "${toolName}"` }
+			return {
+				reason: 'unknown_tool',
+				message: `Error: Unknown tool "${toolName}"`,
+			}
 		}
 
 		// A registry that hands back a tool with no schema has nothing to
@@ -1396,7 +1456,9 @@ export class ToolExecutor {
 				toolCall,
 				reason: failure.reason,
 				message: failure.message,
-				...(tool ? { tool, jsonSchema: renderToolSchema(tool.inputSchema) } : {}),
+				...(tool
+					? { tool, jsonSchema: tool.modelInputSchema ?? renderToolSchema(tool.inputSchema) }
+					: {}),
 				availableTools: this.config.tools.listNames(),
 			})
 		} catch (err) {
@@ -1454,7 +1516,13 @@ export class ToolExecutor {
 		if (!this.config.pluginManager) return { override: null, retry: false }
 		const results = await this.config.pluginManager.executeHooks(
 			'post_tool_use',
-			{ runId: this.config.runId, toolName, toolInput: input, toolResult },
+			{
+				runId: this.config.runId,
+				toolName,
+				toolInput: input,
+				toolResult,
+				signal: this.config.abortSignal,
+			},
 			this.emitEvent,
 		)
 		let override: PostToolOverride | null = null
@@ -1590,7 +1658,12 @@ export class ToolExecutor {
 			result: outcome.output,
 			isError: outcome.kind === 'error',
 		})
-		return { toolCallId, toolName, output: outcome.output, isError: outcome.kind === 'error' }
+		return {
+			toolCallId,
+			toolName,
+			output: outcome.output,
+			isError: outcome.kind === 'error',
+		}
 	}
 
 	/**

package/src/runtime/query/guard.ts

@@ -87,6 +87,18 @@ export class GuardCoordinator {
 		return Math.max(0, finalizeAt - (Date.now() - this.startTime))
 	}
 
+	/**
+	 * Wall-clock left before the run's hard timeout.
+	 *
+	 * Setup work that happens before the first iteration cannot rely on
+	 * {@link beforeIteration}: there is no iteration boundary to sample while
+	 * that work is pending. Callers use this value to put the same run-owned
+	 * deadline around such work instead of inventing a second clock.
+	 */
+	remainingUntilTimeoutMs(): number {
+		return Math.max(0, this.limitConfig.timeoutMs - (Date.now() - this.startTime))
+	}
+
 	beforeIteration(runMgr: RunPersistence, abortSignal: AbortSignal): GuardCheckResult {
 		const limitState = {
 			aborted: abortSignal.aborted,