@namzu/sdk 45.0.0 → 46.0.0

package/src/public-runtime.ts

@@ -423,6 +423,7 @@ export {
 	discoverSkills,
 	loadSkill,
 	resolveSkillChain,
+	SKILL_FRONTMATTER_KEYS,
 	SkillRegistry,
 } from './skills/index.js'
 // The one frontmatter reader. `loadSkill` is built on it, and a host reading
@@ -631,6 +632,26 @@ export {
 	formatCompletionNotification,
 } from './scheduler/completion-inbox.js'
 
+// Scheduled jobs: WHEN something is due, and nothing about how a host stores
+// or runs a job. The time engine and the evaluator are pure (`Intl` for time
+// zones, no clock, no I/O); the CLI keeps its job files and history to itself.
+export {
+	countOccurrences,
+	describeSchedule,
+	evaluateJob,
+	hostTimeZone,
+	nextFireTime,
+	parseCronExpression,
+	parseDuration,
+	parseScheduleSpec,
+	previousFireTime,
+	SCHEDULE_CATCH_UP_WINDOW_MS,
+	SCHEDULE_LATE_GRACE_MS,
+	ScheduleValidationError,
+	upcomingFireTimes,
+	validateTimeZone,
+} from './schedules/index.js'
+
 // ─── providers, sandbox, vault ───────────────────────────────────────────
 
 export {
@@ -899,6 +920,17 @@ export {
 	AuthorizationGate,
 } from './authorization/index.js'
 
+// The one reader of a bash command line the gate itself uses. A host that
+// writes a `predicate` rule about what a line runs decides on this reading,
+// so its rule and the SDK's own never disagree about where a quote ends.
+// `nestedShellCommand` says which `-c` payloads that reading already
+// includes, so a host treats every other text a program runs as unread.
+export {
+	NESTED_SHELLS,
+	lexShellCommandLine,
+	nestedShellCommand,
+} from './authorization/shell-lexer.js'
+
 // NZ-BOOT-03: the module-attributed invariant registry. `compaction.ts` and
 // `claim-disk.ts` register themselves against the shared `invariants`
 // instance at import time (see each file); `namzu doctor` and any host can
@@ -1276,6 +1308,8 @@ export {
 	REVIEW_EXEMPT_WRITES,
 	REVIEW_MODES,
 	SANDBOX_ESCAPE_UNATTENDED_REFUSAL,
+	SCREEN_CONSENT_DECLINED_FEEDBACK,
+	SCREEN_CONSENT_UNATTENDED_REFUSAL,
 	STRICT_MODE_REFUSAL,
 	batchNeedsReview,
 	createReviewHandler,
@@ -1283,6 +1317,8 @@ export {
 	isReviewExempt,
 	isReviewMode,
 } from './runtime/query/review-policy.js'
+// What the model is told when a person declines a call without words of their own.
+export { DECLINED_TOOL_CALL_FEEDBACK } from './runtime/query/declined.js'
 
 // The system prompt is open: a contribution registry the assembler
 // consumes, with skills as its first contributor. See `prompt/contributions.ts`.
@@ -1405,7 +1441,13 @@ export type {
 export type { BroadcastHandoffDeps } from './session/handoff/broadcast.js'
 export type { SingleHandoffDeps } from './session/handoff/single.js'
 export type { InterventionChainLoader } from './session/intervention/prev-artifact.js'
-export type { ActionInput } from './tools/builtins/computer-use.js'
+export type {
+	ActionInput,
+	ComputerUseTool,
+	ComputerUseToolOptions,
+	ImageSize,
+	ScreenshotLimits,
+} from './tools/builtins/computer-use.js'
 export type { Project } from './types/project/entity.js'
 export type { CreatedLogger } from './utils/log/create-logger.js'
 export type {

package/src/public-tools.ts

@@ -66,7 +66,21 @@ export { WaitForJobTool } from './tools/builtins/wait-for-job.js'
 // NOT in the default builtin set: a turn with no skills has nothing for it
 // to do, and offering a tool that can only refuse is worse than not
 // offering it. Hosts register it alongside a skills registry.
-export { SKILL_TOOL_NAME, SkillTool, parseAllowedTools } from './tools/builtins/skill.js'
+// `createSkillTool` takes what the host knows about where its model's tools
+// run: `resolveModelDirectory` names the directory the model can open for
+// each skill, which a sandboxed host's own path is not.
+export {
+	SKILL_TOOL_NAME,
+	SkillTool,
+	createSkillTool,
+	parseAllowedTools,
+} from './tools/builtins/skill.js'
+export type {
+	SkillDirectoryContext,
+	SkillDirectoryRequest,
+	SkillDirectoryResolver,
+	SkillToolOptions,
+} from './tools/builtins/skill.js'
 // Both declare `category: 'network'`, which is what the authorization
 // presets branch on. NOT in the default builtin set: a turn with no web
 // provider has nothing for them to do, and only the `unattended` preset --
@@ -105,8 +119,35 @@ export {
 } from './tools/builtins/structuredOutput.js'
 export {
 	COMPUTER_USE_TOOL_NAME,
+	HIGH_RES_SCREENSHOT_LIMITS,
+	STANDARD_SCREENSHOT_LIMITS,
+	computerUseUnavailableReason,
 	createComputerUseTool,
+	screenshotTargetSize,
 } from './tools/builtins/computer-use.js'
+// The browser contract: the two tools over a host a separate package
+// provides, and the canonicalisers a host and a site-rule compiler must share
+// with the tools so every party reads one spelling of an address.
+export {
+	BROWSER_ACT_TOOL_NAME,
+	BROWSER_TOOL_NAME,
+	browserHostErrorOf,
+	createBrowserTools,
+	formatBrowserPageHeader,
+	isBrowserCallReadOnly,
+} from './tools/builtins/browser.js'
+export {
+	BROWSER_URL_MAX_LENGTH,
+	canonicalizeBrowserOrigin,
+	canonicalizeBrowserSitePattern,
+	canonicalizeBrowserUrl,
+	isCloudMetadataHost,
+} from './tools/builtins/browser-url.js'
+export {
+	BROWSER_FILL_FORM_MAX_FIELDS,
+	BROWSER_SNAPSHOT_MAX_CHARS,
+	BROWSER_WAIT_MAX_MS,
+} from './types/browser/index.js'
 
 // ─── Domain tool builders ────────────────────────────────────────────────
 
@@ -129,6 +170,18 @@ export {
 } from './tools/coordinator/ask-user-question.js'
 export { buildAgentTool, type AgentToolOptions } from './tools/coordinator/agent.js'
 
+// Scheduled jobs and in-session loops, over host callbacks: the host stores
+// jobs, draws the confirmation and computes every field it shows. Register
+// only where a person can confirm (never headless, scheduled or delegated).
+export {
+	buildScheduleTools,
+	buildSessionLoopTools,
+	revealHiddenCharacters,
+	scanSchedulePrompt,
+	SCHEDULE_TOOL_NAME,
+	SESSION_LOOP_TOOL_NAME,
+} from './tools/schedules/index.js'
+
 // ─── RAG tool builder ────────────────────────────────────────────────────
 
 export { createRAGTool } from './rag/index.js'

package/src/public-types.ts

@@ -62,6 +62,13 @@ export type * from './types/sandbox/index.js'
 export type * from './types/structured-output/index.js'
 export type * from './types/invocation/index.js'
 export type * from './types/computer-use/index.js'
+export type * from './types/browser/index.js'
+export type { BrowserActToolInput, BrowserToolInput } from './tools/builtins/browser.js'
+export type {
+	BrowserOriginVerdict,
+	BrowserSitePatternVerdict,
+	BrowserUrlVerdict,
+} from './tools/builtins/browser-url.js'
 export type * from './types/authorization/index.js'
 export type * from './types/bus/index.js'
 export type * from './types/probe/index.js'
@@ -115,6 +122,7 @@ export type { PricingSubject } from './manager/session/turn-recorder.js'
 export type {
 	FrontmatterOptions,
 	FrontmatterValue,
+	ParseFrontmatterOptions,
 	ParsedFrontmatter,
 } from './utils/frontmatter.js'
 export type {
@@ -262,6 +270,14 @@ export type { AgentBusConfig } from './bus/index.js'
 export type { ToolCallContext } from './authorization/index.js'
 export type { PermissionPreset } from './authorization/index.js'
 export type { EvaluateRuleOptions } from './authorization/rules.js'
+export type {
+	ShellCommand,
+	NestedShellCommand,
+	ShellLexOptions,
+	ShellLexResult,
+	ShellRedirection,
+	ShellWord,
+} from './authorization/shell-lexer.js'
 
 export type {
 	DiskSessionStoreConfig,
@@ -388,6 +404,7 @@ export type {
 	ReviewExemption,
 	ReviewMode,
 	ReviewPolicyOptions,
+	ScreenConsentRecord,
 	ToolReviewAnswer,
 	ToolReviewPrompt,
 	ToolReviewRequest,
@@ -629,3 +646,41 @@ export type {
 	ParsedSessionLogLine,
 	SessionLogLineFault,
 } from './session/log-hash.js'
+
+// Scheduled jobs: the time engine's and evaluator's types. The unions here
+// may grow in a minor release; switch over them with a `default:` branch.
+export type {
+	CronExpression,
+	DescribeScheduleOptions,
+	OccurrenceCount,
+	ParseScheduleOptions,
+	ScheduleAtSpec,
+	ScheduleCronSpec,
+	ScheduleDecision,
+	ScheduleEvaluationInput,
+	ScheduleEvaluationJob,
+	ScheduleEvaluationState,
+	ScheduleEverySpec,
+	ScheduleFireTrigger,
+	ScheduleJobLifecycle,
+	ScheduleMissedReason,
+	ScheduleObservedGap,
+	ScheduleSkipReason,
+	ScheduleSpec,
+} from './schedules/index.js'
+export type {
+	ScheduleBrowserGrant,
+	ScheduleBrowserSiteLevel,
+	ScheduleConfirmAnswer,
+	ScheduleConfirmRequest,
+	ScheduleJobChanges,
+	ScheduleJobDraft,
+	ScheduleJobPreview,
+	ScheduleJobSummary,
+	ScheduleJobUpdateProposal,
+	ScheduleRuleEffect,
+	ScheduleToolHost,
+	ScheduleUpdateRequest,
+	SessionLoop,
+	SessionLoopHost,
+} from './tools/schedules/index.js'

package/src/registry/tool/callable.ts

@@ -0,0 +1,37 @@
+import type { ToolRegistryContract } from '../../types/tool/index.js'
+
+/**
+ * The tools a call on this step can reach: registered now, active, and on
+ * the step's allow-list when it has one. In registry order.
+ *
+ * This is what every "Available: …" a model is shown must say, because a
+ * model takes it literally and calls the next name on it. Two answers used
+ * to build that list separately and disagreed. A refusal echoed the step's
+ * allow-list, which is a snapshot taken when the request was built and so
+ * can name a tool unregistered since — a connector that disconnected — or
+ * one that is deferred or suspended, which the executor refuses. An
+ * unknown-tool error listed the whole registry, which on a narrowed step is
+ * mostly tools the step refuses. Each sent the model to a name the other
+ * one answered, and a run went round between them until it was stopped.
+ *
+ * `allowed` absent means the step is not narrowed. An EMPTY list is a step
+ * that may call nothing, and the answer is then empty too.
+ */
+export function callableToolNames(
+	tools: Pick<ToolRegistryContract, 'listNames' | 'getAvailability'>,
+	allowed: readonly string[] | undefined,
+): string[] {
+	const permitted = allowed === undefined ? undefined : new Set(allowed)
+	return tools
+		.listNames()
+		.filter(
+			(name) =>
+				(permitted === undefined || permitted.has(name)) &&
+				tools.getAvailability(name) === 'active',
+		)
+}
+
+/** The list as a model reads it: comma-separated, or `(none)`. */
+export function formatToolNames(names: readonly string[]): string {
+	return names.length > 0 ? names.join(', ') : '(none)'
+}

package/src/registry/tool/execute.ts

@@ -20,6 +20,7 @@ import type {
 import { toErrorMessage } from '../../utils/error.js'
 import { cloneJsonValue as clonePreparedInput } from '../../utils/json-snapshot.js'
 import { ManagedRegistry } from '../ManagedRegistry.js'
+import { callableToolNames, formatToolNames } from './callable.js'
 import { renderToolSchema, toolWireSchema } from './schema.js'
 import { ToolResultHalted, screenToolResult } from './screen.js'
 
@@ -636,9 +637,15 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 				// that may call nothing, and treating it as "no restriction" is
 				// the fail-open reading this codebase has already been bitten by
 				// once, in the delegate roster.
+				//
+				// What it says is available is what would run, not the list
+				// itself: the list was taken when the request was built, and a
+				// name on it may since have been unregistered, or be deferred or
+				// suspended. Echoing it sent a model to a name that was then
+				// answered "unknown tool". See `callableToolNames`.
 				const allowed = context.allowedTools
 				if (allowed !== undefined && !allowed.includes(toolName)) {
-					const msg = `Tool "${toolName}" is not available on this step. Available: ${allowed.length > 0 ? allowed.join(', ') : '(none)'}`
+					const msg = `Tool "${toolName}" is not available on this step. Available: ${formatToolNames(callableToolNames(this, allowed))}`
 					this.log.warn('Blocked a tool outside the step allow-list', {
 						[GENAI.TOOL_NAME]: toolName,
 						'namzu.registry.allowed': allowed.length,

package/src/runtime/query/declined.ts

@@ -0,0 +1,12 @@
+/**
+ * What the model is told when a person declines its tool calls and gave no
+ * words of their own.
+ *
+ * "Declined" alone reads to a model as an obstacle to route around: in a live
+ * session an operator refused a browser navigation and the model fetched the
+ * same page through web search instead. The refusal is about the outcome, not
+ * the tool, so the text says so — for every tool, since any of them can be
+ * swapped for another that reaches the same place.
+ */
+export const DECLINED_TOOL_CALL_FEEDBACK =
+	'The user declined this. Do not get the same content or result another way (another tool, another site or address, or a web search) unless you ask the user first and they agree. Say what you wanted to do, or carry on without it.'

package/src/runtime/query/executor/tool-call-admission.ts

@@ -1,4 +1,5 @@
 import { GENAI, NAMZU } from '../../../constants/telemetry/index.js'
+import { callableToolNames, formatToolNames } from '../../../registry/tool/callable.js'
 import { renderToolSchema } from '../../../registry/tool/schema.js'
 import type { ToolCall } from '../../../types/message/index.js'
 import type { PluginHookResult } from '../../../types/plugin/index.js'
@@ -24,16 +25,43 @@ import { skippedToolResultText } from '../plugin-hooks.js'
  * here dispatches a tool, and nothing here writes a result: that is the
  * executor's half.
  *
- * The family reads exactly three things off the executor it serves, and they
+ * The family reads exactly four things off the executor it serves, and they
  * arrive as one value rather than as a captured reference: the tool registry
- * config, the event sink and the logger. `config` in particular is read
- * per call and never held — `ToolExecutor.setSandbox` REPLACES it, so a host
- * captured once would hand the next admission a stale sandbox.
+ * config, the event sink, the logger and the current step's allow-list.
+ * `config` in particular is read per call and never held —
+ * `ToolExecutor.setSandbox` REPLACES it, so a host captured once would hand
+ * the next admission a stale sandbox.
  */
 export interface ToolAdmissionHost {
 	readonly config: ToolExecutorConfig
 	readonly emitEvent: EmitEvent
 	readonly log: Logger
+	/**
+	 * What the current step may call: the step's own list where
+	 * `prepareStep` gave one, the turn's `allowedTools` otherwise, absent
+	 * when nothing narrowed the turn. NOT `config.allowedTools`, which is
+	 * only the turn's; the step's list lives on the executor.
+	 *
+	 * Required, with `undefined` as a value, so that a host has to say.
+	 * Leaving it out would list the whole registry to a model on a narrowed
+	 * step, which is the answer that sent a model round in a circle.
+	 */
+	readonly allowedTools: readonly string[] | undefined
+}
+
+/**
+ * The answer to a call naming a tool the registry does not hold, without
+ * the `Error: ` a direct call's result carries.
+ *
+ * It lists what the current step can call — the same list a step refusal
+ * gives — rather than what the registry holds. The registry's own
+ * "Not found" lists every tool it has, and on a narrowed step that is
+ * mostly tools the next call would be refused.
+ */
+export function unknownToolMessage(host: ToolAdmissionHost, toolName: string): string {
+	return `Unknown tool "${toolName}". Available: ${formatToolNames(
+		callableToolNames(host.config.tools, host.allowedTools),
+	)}`
 }
 
 export async function runPreToolHook(
@@ -163,7 +191,11 @@ export async function prepareDirectCall(
 		try {
 			preparation = prepare.call(host.config.tools, toolName, parsed)
 		} catch (err) {
-			const message = `Error: Unknown or unavailable tool "${toolName}": ${toErrorMessage(err)}`
+			// A name the registry does not hold gets the step's list, not the
+			// registry's "Not found", which lists everything it holds.
+			const message = isUnregistered(host, toolName)
+				? `Error: ${unknownToolMessage(host, toolName)}`
+				: `Error: Unknown or unavailable tool "${toolName}": ${toErrorMessage(err)}`
 			const repair =
 				!repairUsed && host.config.repairToolCall
 					? await requestRepair(host, toolCall, toolName, {
@@ -295,13 +327,15 @@ function interpretPreToolResults(
  * broken will not do better on a second look, and an unbounded loop
  * here is a hang rather than a degradation.
  *
- * `invalid_json` is the ONLY failure that stops the call here, and it
- * stopped it before this function existed too. `unknown_tool` and
- * `schema_validation` merely OFFER the repair and otherwise fall
- * through to the registry, which reports both with better messages —
- * its schema error already ships a "Required: <field>: <type>" hint the
- * model can self-correct from. So with no repairer configured this is
- * behaviorally identical to the bare `JSON.parse` it replaced.
+ * `invalid_json` stops the call here, and it stopped it before this
+ * function existed too. So does an `unknown_tool` the registry confirms
+ * it does not hold: the registry's own answer to that is "Not found",
+ * listing every tool it has, where the model needs the ones this step can
+ * call — see `unknownToolMessage`. `schema_validation`, and an unknown
+ * tool on a registry that cannot say, merely OFFER the repair and
+ * otherwise fall through to the registry, whose schema error already
+ * ships a "Required: <field>: <type>" hint the model can self-correct
+ * from.
  */
 export async function resolveCall(
 	host: ToolAdmissionHost,
@@ -322,7 +356,10 @@ export async function resolveCall(
 				: null
 
 		if (!repair) {
-			if (failure.reason === 'invalid_json') {
+			if (
+				failure.reason === 'invalid_json' ||
+				(failure.reason === 'unknown_tool' && isUnregistered(host, toolName))
+			) {
 				return { ok: false, toolName, message: failure.message }
 			}
 			return { ok: true, toolName, input: parseArguments(raw) }
@@ -392,11 +429,13 @@ function inspectCall(
 	const tool = host.config.tools.get?.(toolName)
 	if (!tool) {
 		// 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.
+		// registry does not implement `get`. A repairer gets offered both;
+		// only the first is answered here, and with the step's list.
 		return {
 			reason: 'unknown_tool',
-			message: `Error: Unknown tool "${toolName}"`,
+			message: isUnregistered(host, toolName)
+				? `Error: ${unknownToolMessage(host, toolName)}`
+				: `Error: Unknown tool "${toolName}"`,
 		}
 	}
 
@@ -416,6 +455,11 @@ function inspectCall(
 	return null
 }
 
+/** The registry says it does not hold this name — not merely that it cannot look it up. */
+export function isUnregistered(host: ToolAdmissionHost, toolName: string): boolean {
+	return typeof host.config.tools.has === 'function' && !host.config.tools.has(toolName)
+}
+
 async function requestRepair(
 	host: ToolAdmissionHost,
 	toolCall: ToolCall,

package/src/runtime/query/executor.ts

@@ -39,6 +39,7 @@ import type {
 	SkillRegistryRef,
 	ToolContext,
 	ToolDispatchOptions,
+	ToolHandoff,
 	ToolRegistryContract,
 	ToolResult,
 } from '../../types/tool/index.js'
@@ -54,11 +55,13 @@ import { type BackgroundJobRegistry, type JobProcess, bindOwner } from '../jobs/
 import {
 	type ToolAdmissionHost,
 	formatFailedToolOutput,
+	isUnregistered,
 	prepareDirectCall,
 	repairTruncatedCall,
 	resolveCall,
 	runPreToolHook,
 	truncatedToolInputMessage,
+	unknownToolMessage,
 } from './executor/tool-call-admission.js'
 import { describeVisibleFileEvidence } from './file-evidence-context.js'
 import { seedObservationLedger } from './file-evidence-seed.js'
@@ -489,6 +492,8 @@ export interface ToolCallOutcome {
 	/** Rich form for the model, when the tool supplied one. */
 	content?: ToolResultContent
 	isError?: boolean
+	/** The tool asked for a person; see `ToolResult.handoff`. */
+	handoff?: ToolHandoff
 }
 
 export interface ToolExecutionBatch {
@@ -1446,9 +1451,16 @@ export class ToolExecutor {
 	}
 
 	private resultPresentation(name: string, input: unknown, result: ToolResult) {
-		if (!result.success) return {}
 		try {
 			const view = this.config.tools.get(name)?.presentResult?.(input, result)
+			// A failed call carries one view only: the person's No on the tool's
+			// own screen, which a host draws as cancelled rather than failed and
+			// cannot tell apart from the result text alone.
+			if (!result.success) {
+				return view?.kind === 'generic' && view.outcome === 'cancelled'
+					? { presentation: { kind: 'generic', label: view.label, outcome: 'cancelled' } as const }
+					: {}
+			}
 			if (view?.kind !== 'diff') return {}
 			const serialized = JSON.stringify(view)
 			if (serialized.length > (this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS))
@@ -2004,6 +2016,12 @@ export class ToolExecutor {
 			// a result whose image is unaffected — and a hook that needs it gone
 			// says so with `content`, which wins over both.
 			...(modelContent !== undefined ? { content: modelContent } : {}),
+			// Carried whatever a post-tool hook did to the text: the request is
+			// the tool's statement about the world, not about its output, and a
+			// hook that redacts a sign-in page has not signed anyone in.
+			...(result.handoff !== undefined && !this.config.abortSignal.aborted
+				? { handoff: result.handoff }
+				: {}),
 		}
 	}
 
@@ -2186,10 +2204,12 @@ export class ToolExecutor {
 	}
 
 	/**
-	 * The three things the admission family reads off this executor.
+	 * The four things the admission family reads off this executor.
 	 *
 	 * Built per call rather than held: `setSandbox` REPLACES `config`, so a
-	 * host captured once would hand the next admission a stale sandbox.
+	 * host captured once would hand the next admission a stale sandbox. The
+	 * allow-list is the step's, taken the same way and for a like reason:
+	 * `setStepAllowedTools` replaces it every step.
 	 *
 	 * The one way this differs from the inline code it replaced, which
 	 * re-read `this.config` at every use: an admission that spans a
@@ -2200,7 +2220,12 @@ export class ToolExecutor {
 	 * before the loop, so nothing in this tree can tell them apart.
 	 */
 	private admissionHost(): ToolAdmissionHost {
-		return { config: this.config, emitEvent: this.emitEvent, log: this.log }
+		return {
+			config: this.config,
+			emitEvent: this.emitEvent,
+			log: this.log,
+			allowedTools: this.effectiveAllowedTools(),
+		}
 	}
 
 	private async prepareNestedCall(
@@ -2235,10 +2260,16 @@ export class ToolExecutor {
 		try {
 			preparation = prepare.call(this.config.tools, toolName, input)
 		} catch (err) {
+			// A name the registry does not hold is answered with what this step
+			// can call, as a model's own call is; the registry's "Not found"
+			// lists everything it holds.
+			const host = this.admissionHost()
 			return {
 				kind: 'synthetic',
 				input,
-				message: `Tool "${toolName}" could not be prepared: ${toErrorMessage(err)}`,
+				message: isUnregistered(host, toolName)
+					? unknownToolMessage(host, toolName)
+					: `Tool "${toolName}" could not be prepared: ${toErrorMessage(err)}`,
 				isError: true,
 			}
 		}

package/src/runtime/query/index.ts

@@ -1462,6 +1462,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			provider: resilientProvider,
 			providerCapabilities: capabilities,
 			strictCapabilities: params.strictCapabilities === true,
+			...(params.parentSessionId !== undefined ? { delegated: true } : {}),
 			servingMember: () => serving.current,
 			turnConfig,
 			...(params.stopWhen ? { stopWhen: params.stopWhen } : {}),

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

@@ -71,6 +71,7 @@ import {
 	relieveOverflow,
 	runCompactionCheck,
 } from './phases/compaction.js'
+import { runHandoffPause } from './phases/handoff.js'
 import type { IterationContext } from './phases/index.js'
 import { runPlanGate } from './phases/plan.js'
 import { runToolReview } from './phases/tool-review.js'
@@ -1421,6 +1422,13 @@ export class IterationOrchestrator {
 						return
 					}
 
+					// A tool asked for a person. The whole batch is committed; the
+					// turn parks here rather than asking the model what to do about
+					// something only the operator can do.
+					if ((yield* runHandoffPause(this.ctx, iterationNum, reviewOutcome.results)) === 'stop') {
+						return
+					}
+
 					if (reviewOutcome.decision === 'rejected') {
 						continue
 					}

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

@@ -44,6 +44,12 @@ import type { ToolGrantSet } from '../../tool-grants.js'
 
 export interface IterationContext {
 	readonly provider: LLMProvider
+	/**
+	 * The turn runs in a delegated child session. A tool's request for a
+	 * person then fails the turn instead of pausing it: nobody is watching
+	 * a child to resume it, and its parent is waiting on a result.
+	 */
+	readonly delegated?: boolean
 	/** Driver-level request shapes negotiated for this turn. */
 	readonly providerCapabilities?: ResolvedProviderCapabilities
 	/** Refuse a capability mismatch instead of emitting a warning and degrading. */