@namzu/sdk 62.12.0 → 62.13.0

package/src/tools/goal/confirmation.ts

@@ -0,0 +1,375 @@
+import type { SessionGoalStore } from '../../store/goal/index.js'
+import { StaleGoalError } from '../../store/goal/index.js'
+import type { GoalConfirmedBy, GoalRoundAuthority, SessionGoal } from '../../types/goal/index.js'
+import type { HandBack } from '../../types/session/hand-back.js'
+import type { TurnOutcome } from '../../types/session/outcome.js'
+import { showCommand } from '../coordinator/outcome-record.js'
+import { handBackKindSentence, handBackReason } from '../hand-back/index.js'
+
+/**
+ * Ending a goal by the record of the work.
+ *
+ * Today the model's own report ends a goal. With `confirmedBy: 'record'` the
+ * kernel first reads the record it keeps of the work (`Turn.outcome`, built
+ * from what the tool calls did and never from what the model says) and the
+ * goal ends only as that record allows. There is no judge model and no model
+ * call beyond the turns themselves: the decision is a pure function over what
+ * the model reported, the record and the count of refusals so far.
+ */
+
+/**
+ * Times the record may send a goal back to the model before the goal ends as
+ * not confirmed. Three: a first refusal normally costs one fix and one rerun of
+ * the check, a second covers a fix that did not hold, a third a check that
+ * needed a second look; past that the model is looping, and every further
+ * refusal costs a model call that has stopped moving the work. The limit is
+ * per goal and a host can set its own.
+ */
+export const DEFAULT_GOAL_REFUSALS = 3
+
+/** The `reasonCode` that makes a `complete` report say that no check exists to run. */
+export const NO_CHECK_REASON_CODE = 'no-check-available'
+
+/** How a goal ended once the record had been read. */
+export type GoalEnding =
+	/** A check passed and nothing changed after it. */
+	| 'confirmed'
+	/** The model said it was done; the record cannot confirm or contradict it. */
+	| 'stated-not-checked'
+	/** The record disagrees and the model could not or would not put it right. */
+	| 'not-confirmed'
+
+/** What the model reported. */
+export type GoalStatement =
+	/** The goal is met. */
+	| 'met'
+	/** The goal is met, and no check exists to run. */
+	| 'no-check'
+	/** The goal is not met: the model could not make the check pass. */
+	| 'could-not'
+
+export type GoalDecision =
+	| { readonly kind: 'end'; readonly ending: GoalEnding; readonly sentence: string }
+	| { readonly kind: 'refuse'; readonly sentence: string; readonly note: string }
+
+export interface GoalDecisionInput {
+	readonly statement: GoalStatement
+	/** The record of the turn the report was made in; `undefined` when none was kept. */
+	readonly record: TurnOutcome | undefined
+	/** Refusals already given to this goal. */
+	readonly refusals: number
+	/** Most refusals this goal may be given. */
+	readonly maxRefusals: number
+	/**
+	 * An earlier round of this same goal changed files. Never makes a goal
+	 * confirmed; it only keeps a round that changed nothing and ran nothing from
+	 * being read as proof that nothing needed checking.
+	 */
+	readonly earlierRoundsChanged?: boolean
+}
+
+/** The record in plain words, without a lead and without a final stop. */
+export function recordSentence(record: TurnOutcome | undefined): string {
+	if (record === undefined) return 'there is no record of this work'
+	const named = (command: string | undefined): string =>
+		command === undefined ? 'a check' : (showCommand(command) ?? 'a command')
+	const passedCheck = [...record.checks].reverse().find((check) => check.result === 'passed')
+	switch (record.verdict) {
+		case 'checked':
+			return `${named(passedCheck?.command)} passed and nothing changed after it`
+		case 'unchanged':
+			return passedCheck
+				? `${named(passedCheck.command)} passed and nothing changed`
+				: 'nothing changed and no check ran'
+		case 'stale':
+			return 'files changed after the last passing check'
+		case 'failing': {
+			const failed = record.checks.filter((check) => check.result === 'failed')
+			const more = failed.length > 1 ? ` (and ${failed.length - 1} more)` : ''
+			return `${named(failed[0]?.command)} failed${more}`
+		}
+		case 'unchecked':
+			return 'files changed and no check ran'
+		case 'inconclusive': {
+			const masked = record.checks.find((check) => check.result === 'masked')
+			if (masked) {
+				const how = /(?<!\|)\|(?!\|)/.test(masked.command) ? 'the pipe' : 'the command line'
+				return `${named(masked.command)} ran, but ${how} hides whether it passed`
+			}
+			const unsettled = record.checks.find((check) => check.result === 'unsettled')
+			if (unsettled) return `${named(unsettled.command)} ran, but its result was not seen`
+			return 'files changed and no check gave a result that could be read'
+		}
+		case 'unknown':
+			return 'a command ran that may have changed files, and nothing could tell whether it did'
+	}
+}
+
+const HOW_TO_SAY_SO =
+	'To say so, call update_goal with status "blocked" and the reason if the check cannot be made to pass, or with status "complete", reasonCode "no-check-available" and the reason if no check exists here.'
+
+function refusalNote(record: TurnOutcome | undefined, earlierChanged: boolean): string {
+	switch (record?.verdict) {
+		case 'failing':
+			return `The record says ${recordSentence(record)}. Fix what it reports and run it again, or say plainly that you could not make it pass. ${HOW_TO_SAY_SO}`
+		case 'stale':
+			return `The record says ${recordSentence(record)}. Run the check again, or say plainly that you could not. ${HOW_TO_SAY_SO}`
+		case 'unchecked':
+			return `The record says ${recordSentence(record)}. Run the project's check on the files as they are now, or say plainly that no check can be run here. ${HOW_TO_SAY_SO}`
+		case 'inconclusive':
+			return `The record says ${recordSentence(record)}. Run the check again on its own so that its result can be read, or say plainly that you could not. ${HOW_TO_SAY_SO}`
+		default:
+			return earlierChanged
+				? `The record of this round says ${recordSentence(record)}, and an earlier round of this goal changed files. Run the project's check on the files as they are now, or say plainly that you could not. ${HOW_TO_SAY_SO}`
+				: `The record says ${recordSentence(record)}. Run the check, or say plainly that you could not. ${HOW_TO_SAY_SO}`
+	}
+}
+
+/**
+ * What to do with the model's report of a goal, given the record.
+ *
+ * - The model says it could not: the goal ends `not-confirmed`; it is never
+ *   pushed again.
+ * - The model says no check exists: `stated-not-checked`, unless the record
+ *   holds a failing or stale check (`not-confirmed`) or a passing one
+ *   (`confirmed`).
+ * - The model says it is met: a passing check with nothing changed after it is
+ *   `confirmed`; a failing check, files changed after the last pass, files
+ *   changed and no check, or a check whose result could not be read are refused
+ *   while refusals remain and `not-confirmed` once they do not; nothing
+ *   changed, a command that may have changed files (`unknown`) or no record at
+ *   all is `stated-not-checked`. `unknown` is not refused on purpose: the
+ *   record keeps it for the whole turn, so no later check could clear it and a
+ *   refusal would only cost calls until the bound.
+ */
+export function decideGoalConfirmation(input: GoalDecisionInput): GoalDecision {
+	const { statement, record, refusals, maxRefusals } = input
+	const sentence = recordSentence(record)
+	if (statement === 'could-not') return { kind: 'end', ending: 'not-confirmed', sentence }
+
+	const verdict = record?.verdict
+	if (verdict === 'checked') return { kind: 'end', ending: 'confirmed', sentence }
+	if (
+		verdict === 'unchanged' &&
+		record?.checks.some((check) => check.result === 'passed' && check.fresh !== false)
+	) {
+		return { kind: 'end', ending: 'confirmed', sentence }
+	}
+
+	const contradicted = verdict === 'failing' || verdict === 'stale'
+	if (statement === 'no-check') {
+		return contradicted
+			? { kind: 'end', ending: 'not-confirmed', sentence }
+			: { kind: 'end', ending: 'stated-not-checked', sentence }
+	}
+
+	const earlierChanged = input.earlierRoundsChanged === true
+	const refusable =
+		contradicted ||
+		verdict === 'unchecked' ||
+		verdict === 'inconclusive' ||
+		(verdict === 'unchanged' && earlierChanged)
+	if (!refusable) return { kind: 'end', ending: 'stated-not-checked', sentence }
+	if (refusals >= Math.max(0, maxRefusals)) {
+		return { kind: 'end', ending: 'not-confirmed', sentence }
+	}
+	return { kind: 'refuse', sentence, note: refusalNote(record, earlierChanged) }
+}
+
+/** How a goal ended, for the line a person reads and for a machine reading the result. */
+export interface GoalEndingReport {
+	readonly goalId: string
+	readonly ending: GoalEnding
+	/** The record in plain words, as {@link recordSentence} writes it. */
+	readonly sentence: string
+	/** How many times the record sent this goal back before it ended. */
+	readonly refusals: number
+	/**
+	 * Set when the goal ended because the model handed the task back to a person
+	 * (`hand_back_task`). The ending is `not-confirmed` and `sentence` is the
+	 * kernel's sentence for the kind; the model's own words are in the hand-back.
+	 */
+	readonly handedBack?: HandBack
+}
+
+/** The closing line of a goal: which of the three endings it was and, always, what the record held. */
+export function describeGoalEnding(
+	report: Pick<GoalEndingReport, 'ending' | 'sentence' | 'handedBack'>,
+): string {
+	if (report.handedBack) {
+		return `Goal not confirmed: the model handed the task back to a person (${report.sentence}).`
+	}
+	switch (report.ending) {
+		case 'confirmed':
+			return `Goal confirmed by the record: ${report.sentence}.`
+		case 'stated-not-checked':
+			return `Goal stated, not checked: the record cannot confirm it (${report.sentence}).`
+		case 'not-confirmed':
+			return `Goal not confirmed: the record says ${report.sentence}.`
+	}
+}
+
+export interface GoalConfirmationOptions {
+	readonly store: SessionGoalStore
+	/** The same resolver the goal tools use: the authority of the turn, or none. */
+	readonly resolveAuthority: (turnId: string) => GoalRoundAuthority | null | undefined
+	/** What a goal that did not choose is confirmed by. Default `model`, the behaviour before this existed. */
+	readonly defaultConfirmedBy?: GoalConfirmedBy
+	/** Refusals a goal may be given. Default {@link DEFAULT_GOAL_REFUSALS}. */
+	readonly maxRefusals?: number
+}
+
+interface Claim {
+	readonly statement: GoalStatement
+	readonly reason?: string
+}
+
+/**
+ * Holds, for one session, what the model reported this turn, how many times a
+ * goal was sent back, and whether an earlier round of it changed files. All of
+ * it lives in memory: a restart begins the count again, which is the cautious
+ * side of the bound only in that the model gets its refusals again.
+ */
+export class GoalConfirmation {
+	private readonly claims = new Map<string, Claim>()
+	private readonly refusals = new Map<string, number>()
+	private readonly changed = new Set<string>()
+	private readonly endings = new Map<string, GoalEndingReport>()
+
+	constructor(private readonly options: GoalConfirmationOptions) {}
+
+	/** What decides this goal: its own choice, else the host's setting, else the model. */
+	confirmedByFor(goal: Pick<SessionGoal, 'confirmedBy'>): GoalConfirmedBy {
+		return goal.confirmedBy ?? this.options.defaultConfirmedBy ?? 'model'
+	}
+
+	get maxRefusals(): number {
+		return this.options.maxRefusals ?? DEFAULT_GOAL_REFUSALS
+	}
+
+	/** Refusals given to a goal so far. */
+	refusalsFor(goalId: string): number {
+		return this.refusals.get(goalId) ?? 0
+	}
+
+	/**
+	 * The model reported on the goal in the round now running; the record is read
+	 * when it finishes its answer. Held by goal, because only one round of a goal
+	 * runs at a time and a round that ends without an answer leaves the goal
+	 * active: the next report replaces this one.
+	 */
+	claim(goalId: string, statement: GoalStatement, reason?: string): void {
+		this.claims.set(goalId, { statement, ...(reason !== undefined ? { reason } : {}) })
+	}
+
+	/** The ending the turn's goal came to, once; `undefined` when it did not end here. */
+	takeEnding(turnId: string): GoalEndingReport | undefined {
+		const ending = this.endings.get(turnId)
+		this.endings.delete(turnId)
+		return ending
+	}
+
+	/**
+	 * The model handed this round's task back to a person: the goal, when this
+	 * turn is a round of an active one, ends as not confirmed and is left blocked
+	 * with the reason, whatever it was confirmed by. Nothing for any other turn.
+	 */
+	async handBack(turnId: string, handBack: HandBack): Promise<GoalEndingReport | undefined> {
+		const authority = this.options.resolveAuthority(turnId)
+		if (!authority) return undefined
+		const goal = await this.options.store.getGoal(authority.sessionId, authority.tenantId)
+		if (!goal || goal.id !== authority.id || goal.phase !== 'active') return undefined
+		const ref = { id: authority.id, revision: authority.revision }
+		try {
+			await this.options.store.blockGoal(authority.sessionId, authority.tenantId, ref, {
+				code: 'handed-back-to-a-person',
+				message: handBackReason(handBack),
+			})
+		} catch (error) {
+			if (error instanceof StaleGoalError) return undefined
+			throw error
+		}
+		const report: GoalEndingReport = {
+			goalId: goal.id,
+			ending: 'not-confirmed',
+			sentence: handBackKindSentence(handBack.kind),
+			refusals: this.refusalsFor(goal.id),
+			handedBack: handBack,
+		}
+		this.claims.delete(goal.id)
+		this.refusals.delete(goal.id)
+		this.changed.delete(goal.id)
+		return report
+	}
+
+	/** Drop a report that was never answered for, when its round ends without the turn finishing an answer. */
+	forget(goalId: string): void {
+		this.claims.delete(goalId)
+	}
+
+	/**
+	 * For `TurnConfig.outcome.beforeEnd`: the note that sends the model back to
+	 * the work, or `undefined` when the turn may end. A turn that is not a round
+	 * of a goal confirmed by the record is never touched.
+	 */
+	beforeEnd(
+		turnId: string,
+	): (read: () => Promise<TurnOutcome | undefined>) => Promise<string | undefined> {
+		return async (read) => {
+			const authority = this.options.resolveAuthority(turnId)
+			if (!authority) return undefined
+			const goal = await this.options.store.getGoal(authority.sessionId, authority.tenantId)
+			if (!goal || goal.id !== authority.id || goal.phase !== 'active') return undefined
+			if (this.confirmedByFor(goal) !== 'record') return undefined
+
+			const record = await read()
+			const claim = this.claims.get(goal.id)
+			this.claims.delete(goal.id)
+			const changedHere = (record?.changes.total ?? 0) > 0 || record?.changes.outsideKnownTools
+			if (!claim) {
+				if (changedHere) this.changed.add(goal.id)
+				return undefined
+			}
+
+			const decision = decideGoalConfirmation({
+				statement: claim.statement,
+				record,
+				refusals: this.refusalsFor(goal.id),
+				maxRefusals: this.maxRefusals,
+				earlierRoundsChanged: this.changed.has(goal.id),
+			})
+			if (changedHere) this.changed.add(goal.id)
+			if (decision.kind === 'refuse') {
+				this.refusals.set(goal.id, this.refusalsFor(goal.id) + 1)
+				return decision.note
+			}
+
+			const ref = { id: authority.id, revision: authority.revision }
+			try {
+				if (decision.ending === 'not-confirmed') {
+					const said = claim.reason ? ` The model said: ${claim.reason}` : ''
+					await this.options.store.blockGoal(authority.sessionId, authority.tenantId, ref, {
+						code: 'not-confirmed-by-record',
+						message: `The record says ${decision.sentence}.${said}`,
+					})
+				} else {
+					await this.options.store.completeGoal(authority.sessionId, authority.tenantId, ref)
+				}
+			} catch (error) {
+				// The person changed the goal while the model was answering; what they
+				// did stands, and nothing is said about an ending that did not happen.
+				if (error instanceof StaleGoalError) return undefined
+				throw error
+			}
+			this.endings.set(turnId, {
+				goalId: goal.id,
+				ending: decision.ending,
+				sentence: decision.sentence,
+				refusals: this.refusalsFor(goal.id),
+			})
+			this.refusals.delete(goal.id)
+			this.changed.delete(goal.id)
+			return undefined
+		}
+	}
+}

package/src/tools/goal/index.ts

@@ -5,6 +5,7 @@ import type { GoalRoundAuthority, SessionGoal } from '../../types/goal/index.js'
 import type { TurnId } from '../../types/ids/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
+import { type GoalConfirmation, NO_CHECK_REASON_CODE } from './confirmation.js'
 
 export const SESSION_GOAL_TOOL_NAMES = ['get_goal', 'update_goal'] as const
 export const MIN_GOAL_BLOCK_ROUND = 3
@@ -58,6 +59,7 @@ function authorityFor(
 export function buildSessionGoalTools(
 	store: SessionGoalStore,
 	resolveAuthority: ResolveGoalRoundAuthority,
+	options: { readonly confirmation?: GoalConfirmation } = {},
 ): ToolDefinition[] {
 	const getGoal = defineTool({
 		name: 'get_goal',
@@ -106,8 +108,42 @@ export function buildSessionGoalTools(
 		concurrencySafe: false,
 		async execute({ status, reasonCode, reason }, context) {
 			const authority = authorityFor(resolveAuthority, context.turnId)
-			await currentGoal(store, authority)
+			const current = await currentGoal(store, authority)
 			const ref = { id: authority.id, revision: authority.revision }
+			const confirmation = options.confirmation
+			if (confirmation && confirmation.confirmedByFor(current) === 'record') {
+				// The report is held until the model finishes its answer; the kernel then
+				// reads the record of the work and the goal ends as the record allows.
+				if (status === 'complete') {
+					confirmation.claim(
+						authority.id,
+						reasonCode === NO_CHECK_REASON_CODE ? 'no-check' : 'met',
+						reason,
+					)
+					return {
+						success: true,
+						output:
+							'Completion reported. This goal is confirmed by the record: when you finish your answer the kernel reads the record of the work done, and the goal ends as that record allows. Give your final answer now.',
+					}
+				}
+				if (
+					authority.round < MIN_GOAL_BLOCK_ROUND &&
+					confirmation.refusalsFor(authority.id) === 0
+				) {
+					throw new Error(
+						`A goal cannot be marked blocked before admitted round ${MIN_GOAL_BLOCK_ROUND}, unless the record has already sent it back once; this is round ${authority.round}.`,
+					)
+				}
+				if (!reasonCode || !reason) {
+					throw new TypeError('Blocked goal updates require reasonCode and reason.')
+				}
+				confirmation.claim(authority.id, 'could-not', reason)
+				return {
+					success: true,
+					output:
+						'Reported as not met. The goal ends as not confirmed when you finish your answer, and the record of the work is shown with your reason. Give your final answer now.',
+				}
+			}
 			if (status === 'complete') {
 				const goal = await store.completeGoal(authority.sessionId, authority.tenantId, ref)
 				return { success: true, output: 'Goal marked complete.', data: goal }

package/src/tools/hand-back/index.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod'
+
+import type { HandBack, HandBackKind } from '../../types/session/hand-back.js'
+import type { ToolDefinition } from '../../types/tool/index.js'
+import { defineTool } from '../defineTool.js'
+
+/** The name the model calls. */
+export const HAND_BACK_TOOL_NAME = 'hand_back_task'
+
+/** Each of the three sentences is cut to this many characters when it is kept. */
+export const HAND_BACK_MAX_CHARS = 800
+
+/** What the model is told when the setting is on. One place, added to the static prompt. */
+export const HAND_BACK_GUIDANCE = `## Handing a task back
+If the task cannot be done as specified, call \`${HAND_BACK_TOOL_NAME}\` instead of forcing a result: it ends the turn and tells a person what blocks you, what you tried and what they must decide or provide. Never weaken, skip, delete or special-case a check to make it pass; if the request and its checks cannot both hold, hand it back. Hand back only what you could not finish.`
+
+/**
+ * What the tool answers when the hand-back was accepted. A saved conversation
+ * holds this receipt beside the call, so a reader can tell an accepted call
+ * (the turn ended there) from one that was refused.
+ */
+export const HAND_BACK_RECEIPT = 'Handed back to a person.'
+
+/** The id of the prompt contribution that carries {@link HAND_BACK_GUIDANCE}. */
+export const HAND_BACK_GUIDANCE_CONTRIBUTION_ID = 'namzu.hand-back'
+
+const text = z.string().trim().min(1)
+
+export const HandBackInputSchema = z.object({
+	kind: z
+		.enum(['conflict', 'missing', 'decision'])
+		.describe(
+			'conflict: request and checks disagree. missing: something needed is missing or not allowed. decision: the person must decide.',
+		),
+	blocker: text.describe('What blocks you.'),
+	tried: text.describe('What you tried.'),
+	needed: text.describe('What a person has to decide or provide.'),
+})
+
+/** Control, invisible-format and bidirectional code points: none of them is text a person reads. */
+const UNSHOWN: readonly (readonly [number, number])[] = [
+	[0x0000, 0x001f],
+	[0x007f, 0x009f],
+	[0x00ad, 0x00ad],
+	[0x061c, 0x061c],
+	[0x180e, 0x180e],
+	[0x200b, 0x200f],
+	[0x2028, 0x202e],
+	[0x2060, 0x206f],
+	[0xfeff, 0xfeff],
+	[0xfff9, 0xfffb],
+]
+
+/** Whitespace-like controls become a space; every other unshown code point is dropped. */
+const cleaned = (value: string): string => {
+	let out = ''
+	for (const ch of value) {
+		const code = ch.codePointAt(0) ?? 0
+		if (code === 0x09 || code === 0x0a || code === 0x0d) out += ' '
+		else if (!UNSHOWN.some(([lo, hi]) => code >= lo && code <= hi)) out += ch
+	}
+	return out
+}
+
+const clip = (value: string): string => {
+	const flat = cleaned(value).replace(/\s+/g, ' ').trim()
+	return flat.length > HAND_BACK_MAX_CHARS ? `${flat.slice(0, HAND_BACK_MAX_CHARS - 1)}…` : flat
+}
+
+/**
+ * The hand-back a tool call's input holds, or `undefined` when it is not one.
+ * Never throws; text is stripped of control and bidirectional characters, whitespace-folded and clipped.
+ */
+export function parseHandBack(input: unknown): HandBack | undefined {
+	let value = input
+	if (typeof value === 'string') {
+		try {
+			value = JSON.parse(value)
+		} catch {
+			return undefined
+		}
+	}
+	const parsed = HandBackInputSchema.safeParse(value)
+	if (!parsed.success) return undefined
+	const { kind, blocker, tried, needed } = parsed.data
+	return { kind, blocker: clip(blocker), tried: clip(tried), needed: clip(needed) }
+}
+
+const KIND_SENTENCE: Record<HandBackKind, string> = {
+	conflict: 'the request conflicts with itself or with its checks',
+	missing: 'something needed is missing or not allowed',
+	decision: 'a decision is needed that belongs to a person',
+}
+
+/** The kernel's own sentence for a kind; the model's words are never part of it. */
+export function handBackKindSentence(kind: HandBackKind): string {
+	return KIND_SENTENCE[kind] ?? KIND_SENTENCE.decision
+}
+
+/** The closing line in the kernel's words: `The model handed the task back: <kind>.` */
+export function describeHandBack(handBack: HandBack): string {
+	return `The model handed the task back to a person: ${handBackKindSentence(handBack.kind)}.`
+}
+
+/**
+ * The model's three sentences, labelled as the model's, one per line. The
+ * labels are the kernel's; every value after a label is the model's own text.
+ */
+export function handBackModelLines(handBack: HandBack): readonly string[] {
+	return [
+		`The model says it is blocked by: ${handBack.blocker}`,
+		`It tried: ${handBack.tried}`,
+		`It needs a person to: ${handBack.needed}`,
+	]
+}
+
+/** The one-line reason a goal or a scheduled run records. */
+export function handBackReason(handBack: HandBack): string {
+	return `${describeHandBack(handBack).replace(/\.$/, '')}. The model said: ${handBack.blocker}`
+}
+
+/** What a refused sibling call is told in the step that handed the task back. */
+export const HAND_BACK_SIBLING_REFUSAL = `Not run: this step handed the task back to a person with ${HAND_BACK_TOOL_NAME}, and the turn ends there.`
+
+/** The tool. Offered only when `TurnConfig.handBack` is on. */
+export function buildHandBackTool(): ToolDefinition {
+	return defineTool({
+		name: HAND_BACK_TOOL_NAME,
+		description:
+			'Hand the task back to a person when it cannot be done as specified. Ends the turn: nothing else runs after it.',
+		inputSchema: HandBackInputSchema,
+		category: 'custom',
+		permissions: [],
+		readOnly: true,
+		destructive: false,
+		concurrencySafe: false,
+		async execute(input) {
+			const handBack = parseHandBack(input)
+			if (!handBack)
+				throw new TypeError(
+					'The hand-back needs a kind, a blocker, what was tried and what is needed.',
+				)
+			return {
+				success: true,
+				output: `${HAND_BACK_RECEIPT} The turn ends now; nothing more will run and no further answer is needed.`,
+				data: handBack,
+			}
+		},
+	})
+}

package/src/tools/schedules/schedule-tool.ts

@@ -65,6 +65,12 @@ const inputSchema = z.object({
 		.describe(
 			'create: required when kind is script or script+agent. For script+agent this is the wake-gate: its stdout must be exactly one JSON line, {"wake": boolean, "context": string}.',
 		),
+	gate: z
+		.unknown()
+		.optional()
+		.describe(
+			'Never set this. A gate is a command that runs unattended before every run, so only the operator can set or change one (namzu schedule add/edit --gate, or the job file). Giving it refuses the call. A job that already has a gate keeps it when you update the job.',
+		),
 	prompt: z
 		.string()
 		.min(1)
@@ -177,6 +183,9 @@ const inputSchema = z.object({
 
 type Input = z.infer<typeof inputSchema>
 
+const GATE_REFUSAL =
+	'This tool cannot set or change a gate. A gate is a command that runs unattended before every run of the job, so it must come from the person: they set it with `namzu schedule add --gate` or `namzu schedule edit --gate`, or in the job’s file. Leave gate out; a job that already has one keeps it when you update the job.'
+
 function refuse(error: string): ToolResult {
 	return { success: false, output: '', error }
 }
@@ -297,6 +306,7 @@ async function create(
 	input: Input,
 	signal: AbortSignal | undefined,
 ): Promise<ToolResult> {
+	if (input.gate !== undefined) return refuse(GATE_REFUSAL)
 	const runKind = input.kind ?? 'agent'
 	const required: string[] = (['name', 'when', 'permissions'] as const).filter(
 		(k) => input[k] === undefined,
@@ -427,6 +437,7 @@ async function update(
 			'This host cannot change a scheduled job. Ask the operator to change it themselves; do not delete and create it again, which loses its history.',
 		)
 	}
+	if (input.gate !== undefined) return refuse(GATE_REFUSAL)
 	if (!input.job) return refuse("update needs job (the job's name) and the fields to change.")
 	if (input.name !== undefined) {
 		return refuse(
@@ -496,6 +507,13 @@ async function update(
 	) {
 		return refuse(NETWORK_WITH_HOST_SHELL)
 	}
+	if (
+		proposal.preview.gate !== undefined &&
+		proposal.preview.execution === 'host' &&
+		(proposal.preview.networkGrantAccess ?? proposal.preview.networkAccess)
+	) {
+		return refuse(NETWORK_WITH_HOST_SHELL)
+	}
 	let confirmed = false
 	try {
 		confirmed = await host.confirmUpdate(
@@ -587,7 +605,7 @@ export function buildScheduleTools(host: ScheduleToolHost): ToolDefinition[] {
 		defineTool({
 			name: SCHEDULE_TOOL_NAME,
 			description:
-				'Manage durable jobs that run later, including while Namzu is closed when its scheduler is installed. For repetition in this open conversation while the TUI is open, use session_loop (/loop); a loop is not a background service. Use schedule only when the user asks for durable scheduled work. create, update, resume and delete ask the operator; pause does not. A job needs name, when and explicit permissions. agent and script+agent need prompt; script and script+agent need script. For a pure script, use permissions {rules:{},unmatched:\'deny\'} without a preset unless you intend deny rules: read-only denies bash and blocks every script. A pure script has no prompt, model, agent budget, browser grant or run session; set script.timeoutMs to limit it. A pure script may opt into script.report:\'json-v1\': one JSON stdout line says quiet or changed with a summary and optional scheduler-owned nextState. For a project-free pure script set workspace:\'none\' and omit folder; its private scheduler workspace is not a sandbox, and its shell still has host authority. For project work, use the actual existing project folder; home, root and NAMZU_HOME are invalid. Do not create a visible folder merely to satisfy validation. The requesting conversation can receive important results separately from the run workspace. To change a job, update it with job and only the fields that change; do not delete and recreate it. Leave tz, execution, budget and headed unset unless requested: defaults are the operator\'s. Scheduled runs cannot ask questions. Example, a weekday-morning agent job: {"action":"create","name":"daily-report","kind":"agent","when":"0 9 * * 1-5","prompt":"Summarise yesterday\'s changes","permissions":{"preset":"read-only","unmatched":"deny"}}.',
+				'Manage durable jobs that run later, including while Namzu is closed when its scheduler is installed. For repetition in this open conversation while the TUI is open, use session_loop (/loop); a loop is not a background service. Use schedule only when the user asks for durable scheduled work. create, update, resume and delete ask the operator; pause does not. A job needs name, when and explicit permissions. agent and script+agent need prompt; script and script+agent need script. For a pure script, use permissions {rules:{},unmatched:\'deny\'} without a preset unless you intend deny rules: read-only denies bash and blocks every script. A pure script has no prompt, model, agent budget, browser grant or run session; set script.timeoutMs to limit it. A pure script may opt into script.report:\'json-v1\': one JSON stdout line says quiet or changed with a summary and optional scheduler-owned nextState. For a project-free pure script set workspace:\'none\' and omit folder; its private scheduler workspace is not a sandbox, and its shell still has host authority. For project work, use the actual existing project folder; home, root and NAMZU_HOME are invalid. Do not create a visible folder merely to satisfy validation. The requesting conversation can receive important results separately from the run workspace. To change a job, update it with job and only the fields that change; do not delete and recreate it. A gate (a command the operator runs before every run to decide whether to wake the model) is the operator\'s alone: this tool cannot set or change one, and a job that has one keeps it. Leave tz, execution, budget and headed unset unless requested: defaults are the operator\'s. Scheduled runs cannot ask questions. Example, a weekday-morning agent job: {"action":"create","name":"daily-report","kind":"agent","when":"0 9 * * 1-5","prompt":"Summarise yesterday\'s changes","permissions":{"preset":"read-only","unmatched":"deny"}}.',
 			inputSchema,
 			category: 'custom',
 			permissions: [],

package/src/tools/schedules/types.ts

@@ -125,6 +125,16 @@ export interface ScheduleJobPreview {
 		readonly timeoutMs: number
 		readonly report?: 'json-v1'
 	}
+	/**
+	 * Present when the job has a gate: the exact command the operator wrote,
+	 * run before every run, which decides whether the model is called. Shown so
+	 * a change to the job is confirmed knowing it. The tool never sets one.
+	 */
+	readonly gate?: {
+		readonly command: string
+		readonly shell: 'bash' | 'sh'
+		readonly timeoutMs: number
+	}
 	/** The schedule in words, with its zone. */
 	readonly schedule: string
 	/** Whether a completed run sends a Namzu desktop notice; absent for older hosts. */