@namzu/sdk 45.0.0 → 45.1.0

package/src/authorization/gate.ts

@@ -57,15 +57,27 @@ export function describeRule(rule: AuthorizationRule): string {
 			// Names the argument, not just the pattern. That is what tells a
 			// model whether a different value could get through — which is the
 			// difference between rewording once and rewording forever.
-			const verb = rule.decision === 'deny' ? 'denied' : 'allowed'
+			const verb =
+				rule.decision === 'deny'
+					? 'denied'
+					: rule.decision === 'review'
+						? 'sent for review'
+						: 'allowed'
 			return `${verb} because the \`${rule.argument}\` argument matched ${rule.pattern} (this rule applies to ${rule.toolNames.join(', ')})`
 		}
 
 		case 'custom_pattern': {
 			const where = rule.target === 'both' ? 'name or arguments' : rule.target
-			const verb = rule.decision === 'deny' ? 'denied' : 'allowed'
+			const verb =
+				rule.decision === 'deny'
+					? 'denied'
+					: rule.decision === 'review'
+						? 'sent for review'
+						: 'allowed'
 			return `${verb} by a pattern rule matching the ${where}: ${rule.pattern}`
 		}
+		case 'predicate':
+			return rule.description
 		default: {
 			const exhaustive: never = rule
 			return `matched an unrecognised rule: ${JSON.stringify(exhaustive)}`

package/src/authorization/rules.ts

@@ -134,19 +134,33 @@ export function evaluateRule(
 			// A command line is not one string, and testing it as one is how a
 			// prohibition gets bypassed: `^git push` sees `git push origin main`
 			// and does not see `true; git push origin main`. See
-			// `decomposeCommandLine` for the measurement and for why the two
+			// `decomposeCommandLine` for the measurement and for why the
 			// decisions must read the result differently.
-			const { segments, opaque } = decomposeCommandLine(subject, dialect)
-
-			if (rule.decision === 'deny') {
+			//
+			// An argument the tool declares as a canonical URL is not a command
+			// line, and cutting it at `&` would make an `allow` for a site
+			// decline every address with a query string. See
+			// `ToolDefinition.urlArgument`.
+			const isUrl = toolDef?.urlArgument === rule.argument
+			const { segments, opaque } = isUrl
+				? { segments: [subject], opaque: false }
+				: decomposeCommandLine(subject, dialect)
+
+			if (rule.decision === 'deny' || rule.decision === 'review') {
 				// ANY segment. The whole subject is tested first so an
 				// unanchored deny keeps matching across a boundary, which
 				// splitting alone would have taken away. Then each command's
 				// words as bash passes them, so that `'git' push` is `git push`.
-				if (compiledPattern.test(subject)) return 'deny'
-				if (segments.some((segment) => compiledPattern.test(segment))) return 'deny'
+				//
+				// `review` reads like `deny`, because it is a restriction too: a
+				// rule that asks before `git push` must ask before
+				// `true; git push` as well. Matching too much costs a prompt;
+				// matching too little skips the question the operator asked for.
+				if (compiledPattern.test(subject)) return rule.decision
+				if (segments.some((segment) => compiledPattern.test(segment))) return rule.decision
+				if (isUrl) return null
 				return decodedCommands(subject, dialect).some((text) => compiledPattern.test(text))
-					? 'deny'
+					? rule.decision
 					: null
 			}
 
@@ -165,6 +179,22 @@ export function evaluateRule(
 			return null
 		}
 
+		case 'predicate': {
+			// A rule that throws has not decided the call is safe. Reading the
+			// exception as "no opinion" would let the next rule, or the mode,
+			// approve what this one was written to refuse.
+			try {
+				return rule.decide({
+					toolName,
+					toolInput,
+					toolDef,
+					commandDialect: dialect,
+				})
+			} catch {
+				return 'deny'
+			}
+		}
+
 		default: {
 			const _exhaustive: never = rule
 			throw new Error(`Unhandled verification rule type: ${(_exhaustive as { type: string }).type}`)

package/src/authorization/shell-lexer.ts

@@ -83,6 +83,13 @@ export interface ShellRedirection {
 	readonly fd?: string
 	/** The target word. For a here-document, its delimiter. */
 	readonly target: ShellWord
+	/**
+	 * A here-document's body as written, up to its delimiter line, once the
+	 * lexer has read it: the text the command reads on its input, which is
+	 * a command line of its own when the command is a shell (`bash <<EOF`).
+	 * Absent for every other operator and for a body the line never reached.
+	 */
+	readonly body?: string
 }
 
 /** One simple command. */
@@ -118,6 +125,13 @@ export interface ShellLexResult {
 	 * (`{ a; } > f`) that belong to no single simple command.
 	 */
 	readonly redirections: readonly ShellRedirection[]
+	/**
+	 * Words that belong to no simple command: a `for` or `select` loop's
+	 * variable and the words of its list, and a `case` statement's subject
+	 * and patterns. `for d in ~/x; do rm -r "$d"; done` passes `~/x` to `rm`
+	 * although no command lists it.
+	 */
+	readonly compoundWords: readonly ShellWord[]
 	/** True when {@link commands} may not be everything the line runs. */
 	readonly opaque: boolean
 	/** False when parsing stopped early: a syntax error or an unsupported construct. */
@@ -169,6 +183,7 @@ export function lexShellCommandLine(line: string, options: ShellLexOptions = {})
 	return {
 		commands: context.commands,
 		redirections: context.redirections,
+		compoundWords: context.compoundWords,
 		opaque: context.reasons.size > 0,
 		complete: context.complete,
 		reasons: [...context.reasons],
@@ -178,6 +193,7 @@ export function lexShellCommandLine(line: string, options: ShellLexOptions = {})
 class Context {
 	readonly commands: ShellCommand[] = []
 	readonly redirections: ShellRedirection[] = []
+	readonly compoundWords: ShellWord[] = []
 	readonly reasons = new Set<string>()
 	complete = true
 	/**
@@ -358,6 +374,8 @@ interface PendingHeredoc {
 	readonly delimiter: string
 	readonly stripTabs: boolean
 	readonly quoted: boolean
+	/** The redirection the body belongs to, filled in when it is read. */
+	readonly redirection: { body?: string }
 }
 
 type Last =
@@ -790,6 +808,7 @@ class Parser {
 		}
 		const name = this.takePlainWord()
 		if (name.kind !== 'word') throw this.unexpected(name)
+		this.context.compoundWords.push(name.word)
 		this.newlines()
 		token = this.peek()
 		if (token.kind === 'word' && !token.word.quoted && token.word.value === 'in') {
@@ -807,7 +826,10 @@ class Parser {
 			}
 			for (;;) {
 				token = this.takePlainWord()
-				if (token.kind === 'word') continue
+				if (token.kind === 'word') {
+					this.context.compoundWords.push(token.word)
+					continue
+				}
 				if (token.kind === 'newline' || (token.kind === 'op' && token.op === ';')) break
 				throw this.unexpected(token)
 			}
@@ -854,6 +876,7 @@ class Parser {
 		this.take()
 		const subject = this.takePlainWord()
 		if (subject.kind !== 'word') throw this.unexpected(subject)
+		this.context.compoundWords.push(subject.word)
 		this.newlines()
 		const keyword = this.take()
 		if (keyword.kind !== 'word' || keyword.word.quoted || keyword.word.value !== 'in') {
@@ -887,6 +910,7 @@ class Parser {
 				patterns()
 				const pattern = this.take()
 				if (pattern.kind !== 'word') throw this.unexpected(pattern)
+				this.context.compoundWords.push(pattern.word)
 				const next = this.take()
 				if (next.kind === 'op' && next.op === '|') continue
 				if (next.kind === 'op' && next.op === ')') break
@@ -1114,6 +1138,11 @@ class Parser {
 			// Ubuntu ship).
 			this.context.opaque('quoted or expanding target of >& or <&')
 		}
+		const redirection: { -readonly [K in keyof ShellRedirection]: ShellRedirection[K] } = {
+			operator: operator.op,
+			...(operator.fd !== undefined ? { fd: operator.fd } : {}),
+			target: target.word,
+		}
 		if (operator.op === '<<' || operator.op === '<<-') {
 			if (target.word.value.includes('\n')) {
 				// Bash starts the body at the newline inside the delimiter, so
@@ -1125,13 +1154,10 @@ class Parser {
 					delimiter: target.word.value,
 					stripTabs: operator.op === '<<-',
 					quoted: target.word.quoted,
+					redirection,
 				})
 		}
-		return {
-			operator: operator.op,
-			...(operator.fd !== undefined ? { fd: operator.fd } : {}),
-			target: target.word,
-		}
+		return redirection
 	}
 
 	/**
@@ -1641,7 +1667,9 @@ class Parser {
 			const heredoc = this.heredocs.shift() as PendingHeredoc
 			let i = this.pos
 			const bodyStart = i
+			let bodyEnd = i
 			for (;;) {
+				bodyEnd = i
 				if (i >= src.length) break
 				let line = ''
 				let j = i
@@ -1664,7 +1692,9 @@ class Parser {
 				const test = heredoc.stripTabs ? line.replace(/^\t+/, '') : line
 				i = j
 				if (test === heredoc.delimiter) break
+				bodyEnd = i
 			}
+			heredoc.redirection.body = src.slice(bodyStart, bodyEnd)
 			if (!heredoc.quoted) {
 				const body = src.slice(bodyStart, i)
 				if (/\$[({[]|`/.test(body)) this.heredocBody(body)

package/src/bridge/a2a/mapper.ts

@@ -227,6 +227,8 @@ const MAPPING: {
 			// it whether and when a retry is justified.
 			{
 				checkpointId: e.checkpointId,
+				// A person, not a retry, is what this pause waits for.
+				...(e.handoff ? { handoff: e.handoff } : {}),
 				...(e.failure
 					? {
 							code: e.failure.code,

package/src/bridge/sse/mapper.ts

@@ -297,6 +297,7 @@ const MAPPING: {
 			...(e.failure ? { failure: e.failure } : {}),
 			...(e.providerError ? { provider_error: e.providerError } : {}),
 			...(e.explanation ? { explanation: e.explanation } : {}),
+			...(e.handoff ? { handoff: e.handoff } : {}),
 		}),
 	},
 

package/src/directory/types.ts

@@ -16,6 +16,8 @@ import type { ToolDefinition } from '../types/tool/index.js'
  * those is a `major` waiting to happen on a published type. The layering
  * question — does a convention belong outside the kernel — was answered yes
  * and stands; the shape question had simply never been asked.
+ * Schedules were later answered outside this loader, with a zone per spec and
+ * a claimed occurrence key: see `docs/sdk/schedules.md` (`../schedules/`).
  */
 export type DirectorySlot = 'agent' | 'instructions' | 'tools' | 'skills' | 'agents'
 

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

@@ -69,6 +69,7 @@ export const CODING_AGENT_WORKING_DOCTRINE = `## How you work
 - Before any command that could discard uncommitted work, run \`git status\`. If there are changes there that you did not make, stop and ask rather than stashing, committing or discarding somebody else's work.
 - Commit only when the user asks, on the branch that is checked out. Do not create or switch branches unless the user asks or the project's instructions require it.
 - After a broad \`git add\`, review what was staged before committing; a file whose name looks harmless can still carry a secret.
+- Never change git configuration or other persistent settings without asking: not \`user.name\` or \`user.email\`, hooks, remotes, credential helpers, or any \`git config\` (local or global), nor a shell profile or a tool's own config file. If a commit fails because no identity is set, stop and tell the user the command to set one; do not invent one.
 
 ### Keeping the user informed
 - Before a batch of tool calls, say in one short line what you are about to do and why. When you have been working for a while without saying anything, say in a few words where you are, then continue. One line, not a paragraph; the tool rows on screen already show the details.

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,11 @@ 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.
+export { lexShellCommandLine } 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
@@ -1283,6 +1309,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`.

package/src/public-tools.ts

@@ -107,6 +107,29 @@ export {
 	COMPUTER_USE_TOOL_NAME,
 	createComputerUseTool,
 } 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 +152,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,13 @@ 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,
+	ShellLexOptions,
+	ShellLexResult,
+	ShellRedirection,
+	ShellWord,
+} from './authorization/shell-lexer.js'
 
 export type {
 	DiskSessionStoreConfig,
@@ -629,3 +644,38 @@ 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,
+	ScheduleJobDraft,
+	ScheduleJobPreview,
+	ScheduleJobSummary,
+	ScheduleRuleEffect,
+	ScheduleToolHost,
+	SessionLoop,
+	SessionLoopHost,
+} from './tools/schedules/index.js'

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.ts

@@ -39,6 +39,7 @@ import type {
 	SkillRegistryRef,
 	ToolContext,
 	ToolDispatchOptions,
+	ToolHandoff,
 	ToolRegistryContract,
 	ToolResult,
 } from '../../types/tool/index.js'
@@ -489,6 +490,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 +1449,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 +2014,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 }
+				: {}),
 		}
 	}
 

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. */

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

@@ -0,0 +1,74 @@
+import { GENAI, NAMZU } from '../../../../telemetry/attributes.js'
+import { NamzuError } from '../../../../types/errors/index.js'
+import type { SessionEvent } from '../../../../types/session/index.js'
+import type { ToolCallOutcome } from '../../executor.js'
+import type { IterationContext, PhaseSignal } from './context.js'
+
+/**
+ * A tool asked for a person: stop before the next model call.
+ *
+ * Runs after the batch settled, so every result — the one that asked and
+ * its siblings — is already in the transcript and queued for the session
+ * log. The checkpoint written here is taken from that state, which is what
+ * lets a resume continue exactly as it does after a provider pause: the
+ * next step is a model call that sees the results.
+ *
+ * The first request in the batch speaks for it. Two tools that both need a
+ * person need the same thing from the operator — to come and look — and
+ * one pause answers both.
+ *
+ * In a delegated child the turn fails with the reason instead. Nobody
+ * resumes a child's turn: its parent is waiting on a result, and a failed
+ * child with the reason in it is a result the parent's model can act on.
+ */
+export async function* runHandoffPause(
+	ctx: IterationContext,
+	iterationNum: number,
+	results: readonly ToolCallOutcome[],
+): AsyncGenerator<SessionEvent, PhaseSignal> {
+	const requested = results.find((result) => result.handoff !== undefined)
+	const handoff = requested?.handoff
+	if (!requested || !handoff) return 'continue'
+
+	if (ctx.delegated) {
+		ctx.log.info('A tool in a delegated turn needs a person; the turn fails', {
+			[NAMZU.TURN_ID]: ctx.recorder.turnId,
+			[NAMZU.ITERATION]: iterationNum,
+			[GENAI.TOOL_NAME]: requested.toolName,
+		})
+		throw new NamzuError({
+			code: 'tool_error',
+			message: `${requested.toolName} needs a person: ${handoff.reason}`,
+			details: { toolName: requested.toolName, handoff },
+			retryable: false,
+		})
+	}
+
+	const checkpoint = await ctx.checkpointMgr.create(ctx.recorder, iterationNum)
+	await ctx.emitEvent({
+		type: 'checkpoint_created',
+		turnId: ctx.recorder.turnId,
+		checkpointId: checkpoint.id,
+		iteration: iterationNum,
+	})
+	yield* ctx.drainPending()
+
+	await ctx.emitEvent({
+		type: 'turn_paused',
+		budget: ctx.recorder.budget?.summary(),
+		turnId: ctx.recorder.turnId,
+		checkpointId: checkpoint.id,
+		reason: handoff.reason,
+		handoff,
+	})
+	yield* ctx.drainPending()
+	ctx.recorder.setStopReason('paused')
+	ctx.log.info('Turn paused for a person', {
+		[NAMZU.TURN_ID]: ctx.recorder.turnId,
+		[NAMZU.ITERATION]: iterationNum,
+		[GENAI.TOOL_NAME]: requested.toolName,
+		'namzu.checkpoint.id': checkpoint.id,
+		'namzu.runtime.reason': handoff.reason,
+	})
+	return 'stop'
+}

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

@@ -6,3 +6,4 @@ export type { ToolReviewOutcome } from './tool-review.js'
 export { runIterationCheckpoint } from './checkpoint.js'
 export { runCompactionCheck } from './compaction.js'
 export { runAdvisoryPhase } from './advisory.js'
+export { runHandoffPause } from './handoff.js'