@namzu/sdk 62.11.0 → 62.13.0

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

package/src/types/connector/mcp.ts

@@ -416,6 +416,12 @@ export interface MCPClientCapabilities {
 	 * only. The client sets it, a caller passing it by hand gets no handler.
 	 */
 	elicitation?: Record<string, never>
+	/**
+	 * Extensions beyond the core protocol, by identifier (2026-07-28). The
+	 * client adds `io.modelcontextprotocol/tasks` itself when the server
+	 * advertises it and {@link MCPClientConfig.tasks} is not `false`.
+	 */
+	extensions?: Record<string, Record<string, unknown>>
 	experimental?: Record<string, unknown>
 }
 
@@ -424,6 +430,8 @@ export interface MCPServerCapabilities {
 	resources?: { subscribe?: boolean; listChanged?: boolean }
 	prompts?: { listChanged?: boolean }
 	logging?: Record<string, never>
+	/** Extensions the server offers, by identifier (2026-07-28 `server/discover`). */
+	extensions?: Record<string, Record<string, unknown>>
 	experimental?: Record<string, unknown>
 }
 
@@ -500,6 +508,16 @@ export interface MCPClientConfig {
 	transportFactory?: () => MCPTransport
 	capabilities?: MCPClientCapabilities
 	clientInfo?: { name: string; version: string }
+	/**
+	 * Take part in the tasks extension (2026-07-28). Default `true`.
+	 *
+	 * When the server advertises `io.modelcontextprotocol/tasks`, the client
+	 * declares it on each request, and a `tools/call` the server turns into a
+	 * task is waited on until it ends: `callTool()` resolves with the task's
+	 * result exactly as if the server had answered at once. `false` declares
+	 * nothing, so a server never returns a task to this client.
+	 */
+	tasks?: boolean
 	/**
 	 * Answer a server's `elicitation/create` (form mode) by asking the person.
 	 *

package/src/types/goal/index.ts

@@ -3,6 +3,13 @@ import type { GoalId, SessionId, TenantId } from '../ids/index.js'
 /** Durable lifecycle of one same-session completion goal. */
 export type GoalPhase = 'active' | 'paused' | 'blocked' | 'complete'
 
+/**
+ * Who says a goal is done. `model`: the model's own report ends the goal, as it
+ * always has. `record`: the kernel reads the record of the work done for the
+ * goal first, and the goal ends only as that record allows.
+ */
+export type GoalConfirmedBy = 'model' | 'record'
+
 /** Machine-routable and human-readable reason that a goal stopped. */
 export interface GoalBlockReason {
 	/** Stable lower-kebab-case policy code. */
@@ -33,6 +40,12 @@ export interface SessionGoal extends GoalRef {
 	readonly maxGoalRounds: number
 	/** Durable admissions, not a claim that the provider began or completed. */
 	readonly roundsAdmitted: number
+	/**
+	 * What this goal was created to be confirmed by. Absent means the host's own
+	 * setting decides, which is the case for every goal created before this
+	 * field existed.
+	 */
+	readonly confirmedBy?: GoalConfirmedBy
 	/** Present exactly while {@link phase} is `blocked`. */
 	readonly blockedReason?: GoalBlockReason
 	readonly createdAt: number

package/src/types/session/config.ts

@@ -106,6 +106,14 @@ export interface TurnConfig {
 	 * Off when absent, so an embedding host sees no change.
 	 */
 	completionAudit?: boolean
+	/**
+	 * Let the model hand the task back to a person (`hand_back_task`) instead of
+	 * forcing a result it cannot honestly reach. On: the tool is offered, a short
+	 * paragraph of guidance joins the static system prompt, and a call to the tool
+	 * ends the turn with nothing else run (`Turn.handedBack`). Off or absent: the
+	 * tool is absent and the prompt is byte for byte what it was.
+	 */
+	handBack?: boolean
 	/**
 	 * How many times in a row `turn_end` / `subagent_stop` hooks may refuse to
 	 * let the turn end (answer `skip`) before the turn stops honouring them. At

package/src/types/session/hand-back.ts

@@ -0,0 +1,31 @@
+/**
+ * A turn the model handed back to a person (`docs/sdk/hand-back.md`).
+ *
+ * The model calls `hand_back_task` when the task cannot be finished as
+ * specified and the honest thing is to stop and say so. The turn ends there:
+ * no further model call, nothing else runs. The fact is kept beside the
+ * turn's outcome verdict, not inside it: a turn can have changed files and
+ * still have been handed back.
+ */
+
+/** Why the model stopped; a small closed set so a script can branch on it. */
+export type HandBackKind =
+	/** The request conflicts with itself, or with the checks that decide whether it is done. */
+	| 'conflict'
+	/** Something needed is missing or not allowed: an input, a file, a credential, a permission. */
+	| 'missing'
+	/** A decision is needed that belongs to a person. */
+	| 'decision'
+
+export const HAND_BACK_KINDS: readonly HandBackKind[] = ['conflict', 'missing', 'decision']
+
+/** What the model said when it handed the task back. The words are the model's. */
+export interface HandBack {
+	readonly kind: HandBackKind
+	/** What blocks it. */
+	readonly blocker: string
+	/** What it tried. */
+	readonly tried: string
+	/** What a person has to decide or provide. */
+	readonly needed: string
+}

package/src/types/session/outcome.ts

@@ -74,6 +74,35 @@ export interface TurnOutcome {
 	readonly checksTotal?: number
 }
 
+/** What a plain claim in an answer was about. */
+export type AnswerClaimKind = 'tests' | 'build' | 'lint' | 'typecheck' | 'checks'
+
+/** What the turn's record held that the claim did not match. */
+export type AnswerClaimRecord =
+	/** A check's latest run failed. */
+	| 'check-failed'
+	/** Files changed and no check ran. */
+	| 'unchecked'
+	/** Files changed and no check established a pass, or its result could not be read. */
+	| 'unreadable'
+
+/**
+ * An answer said a check passed and the same turn's record says otherwise.
+ *
+ * Recorded, not acted on: the model is not told and nothing blocks. See
+ * `compareAnswerToOutcome`.
+ */
+export interface AnswerClaimMismatch {
+	readonly claim: AnswerClaimKind
+	/** The claim in the kernel's words, for example `the tests pass`. */
+	readonly said: string
+	/** The clause of the answer it was found in, whitespace folded and clipped. */
+	readonly quote: string
+	readonly record: AnswerClaimRecord
+	/** What the record holds, in the kernel's words, for example `pnpm test failed`. */
+	readonly recordSays: string
+}
+
 /** Host hooks for the turn's outcome record. */
 export interface TurnOutcomeConfig {
 	/**
@@ -88,6 +117,19 @@ export interface TurnOutcomeConfig {
 	readonly isCheck?: (command: string) => boolean
 	/** Deadline per detector call. A detector that is late is `null`. Default 3000. */
 	readonly detectTimeoutMs?: number
+	/**
+	 * Asked when the model has finished its answer with no tool call left and
+	 * the turn would end. `read` gives the turn's record as it stands, with the
+	 * workspace compared once; it is not computed unless called. A returned
+	 * sentence goes to the model as a runtime note and the turn goes on; nothing
+	 * returned lets the turn end. A turn that is being stopped by a limit, a
+	 * cancellation or a forced final answer is not asked, so a limit always wins
+	 * over this hook. At most 16 notes are honoured in one turn. A hook that
+	 * throws is read as nothing returned.
+	 */
+	readonly beforeEnd?: (
+		read: () => Promise<TurnOutcome | undefined>,
+	) => string | undefined | Promise<string | undefined>
 }
 
 /** Bounds on a recorded outcome. */

package/src/types/session/turn.ts

@@ -11,7 +11,8 @@ import type {
 import type { Message } from '../message/index.js'
 import type { ProviderErrorInfo } from '../provider/index.js'
 import type { TurnConfig } from './config.js'
-import type { TurnOutcome } from './outcome.js'
+import type { HandBack } from './hand-back.js'
+import type { AnswerClaimMismatch, TurnOutcome } from './outcome.js'
 import type { StepResult } from './step.js'
 import type { StopReason } from './stop-reason.js'
 
@@ -166,6 +167,21 @@ export interface LiveTurnSettlement extends TurnSettlement {
 	 * did not keep the record.
 	 */
 	readonly outcome?: TurnOutcome
+	/**
+	 * A plain claim in the answer that this turn's outcome record contradicts.
+	 * Shadow only: the model is not told and nothing blocks. In memory only,
+	 * like {@link LiveTurnSettlement.outcome}; the session log does not keep it.
+	 * Absent when the answer made no such claim, which is the usual case.
+	 */
+	readonly claimMismatch?: AnswerClaimMismatch
+	/**
+	 * The model handed the task back to a person (`hand_back_task`) and the turn
+	 * ended there. A fact beside {@link LiveTurnSettlement.outcome}, not a field of
+	 * it: a turn can have changed files and been handed back. In memory only; the
+	 * session log keeps no record of it, since the call and its words are already in
+	 * the saved conversation and a reopened one reads them from there.
+	 */
+	readonly handedBack?: HandBack
 }
 
 /** Metadata of one turn: who ran it, with what, and where it sits in the session tree. */
@@ -235,6 +251,8 @@ export interface Turn {
 	abandonedJobIds?: readonly string[]
 	/** What the turn changed and what checked it; see {@link LiveTurnSettlement.outcome}. */
 	outcome?: TurnOutcome
+	/** Set when the model handed the task back; see {@link LiveTurnSettlement.handedBack}. */
+	handedBack?: HandBack
 	/** Present on a child session's turn. */
 	parentSessionId?: SessionId
 	/** Present on a child session's turn. */