@namzu/sdk 45.1.0 → 48.0.0

package/src/tools/schedules/present.ts

@@ -33,6 +33,8 @@ export function presentScheduleCall(input: {
 		}
 		case 'list':
 			return activity('List scheduled jobs')
+		case 'update':
+			return activity(`Change scheduled job · ${oneLine(input.job)}`)
 		case 'pause':
 			return activity(`Pause scheduled job · ${oneLine(input.job)}`)
 		case 'resume':

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

@@ -7,7 +7,10 @@ import { scanSchedulePrompt } from './prompt-scan.js'
 import type {
 	ScheduleBrowserGrant,
 	ScheduleBrowserSiteLevel,
+	ScheduleJobChanges,
 	ScheduleJobDraft,
+	ScheduleJobSummary,
+	ScheduleJobUpdateProposal,
 	ScheduleToolHost,
 } from './types.js'
 
@@ -15,7 +18,8 @@ export const SCHEDULE_TOOL_NAME = 'schedule'
 
 /**
  * A person reads the whole proposal — the prompt, the rules, the schedule,
- * the credential source — before answering `create`, `resume` or `delete`.
+ * the credential source — before answering `create`, `update`, `resume` or
+ * `delete`.
  * The executor's `DEFAULT_TOOL_TIMEOUT_MS` (two minutes) is sized for a tool
  * call, not a person on the other end of a screen, and would abandon the
  * call out from under them mid-read. `save_skill`
@@ -30,18 +34,43 @@ const BROWSER_PROFILE = /^[a-z0-9][a-z0-9-]{0,62}$/
 
 const inputSchema = z.object({
 	action: z
-		.enum(['create', 'list', 'pause', 'resume', 'delete'])
-		.describe('What to do. create, resume and delete ask the operator first.'),
+		.enum(['create', 'list', 'update', 'pause', 'resume', 'delete'])
+		.describe(
+			'What to do. create, update, resume and delete ask the operator first. To change a job, update it: deleting and creating it again loses its history.',
+		),
 	name: z
 		.string()
 		.regex(/^[a-z0-9][a-z0-9-]{0,62}$/)
 		.optional()
 		.describe('create: job name, lowercase letters, digits and dashes'),
-	prompt: z.string().min(1).max(20_000).optional().describe('create: what the run is asked to do'),
+	kind: z
+		.enum(['agent', 'script', 'script+agent'])
+		.optional()
+		.describe(
+			'create: what the run does. agent (default): the model runs prompt. script: a fixed shell script runs unattended, no model call, no prompt. script+agent: a cheap gate script decides whether to wake the model; wake:false costs nothing. Prefer script/script+agent for a fixed, deterministic check that would otherwise cost tokens for no reason.',
+		),
+	script: z
+		.object({
+			body: z.string().min(1).describe('The exact script text, run verbatim once confirmed'),
+			shell: z.enum(['bash', 'sh']).describe('Which shell reads it; no default'),
+			timeoutMs: z.number().int().positive().optional().describe('The script’s own wall clock'),
+		})
+		.optional()
+		.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}.',
+		),
+	prompt: z
+		.string()
+		.min(1)
+		.max(20_000)
+		.optional()
+		.describe(
+			'create, update: what the model run is asked to do. Required for agent and script+agent; refused for a pure script. For script+agent this is handed to the model only when the wake-gate says wake: true.',
+		),
 	when: z
 		.string()
 		.optional()
-		.describe('create: "every 30m", "0 9 * * 1-5" (cron), "at 2026-09-24 09:00", "in 2h"'),
+		.describe('create, update: "every 30m", "0 9 * * 1-5" (cron), "at 2026-09-24 09:00", "in 2h"'),
 	folder: z
 		.string()
 		.optional()
@@ -90,7 +119,9 @@ const inputSchema = z.object({
 				.describe('Browser access; omit for none'),
 		})
 		.optional()
-		.describe('create: REQUIRED explicit permission set; there is no default'),
+		.describe(
+			'create: REQUIRED explicit permission set; there is no default. A pure script cannot use a browser grant. update: the whole new set, only when the permissions change',
+		),
 	budget: z
 		.object({
 			maxIterations: z
@@ -114,11 +145,13 @@ const inputSchema = z.object({
 				.int()
 				.positive()
 				.optional()
-				.describe('Wall clock of one run, in milliseconds'),
+				.describe('Wall clock of one agent phase, in milliseconds'),
 		})
 		.optional()
-		.describe('Limits of ONE run; omit to use the defaults'),
-	job: z.string().optional().describe('pause/resume/delete: job name'),
+		.describe(
+			'Agent-phase limits; omit to use the defaults. Refused for a pure script; use script.timeoutMs instead.',
+		),
+	job: z.string().optional().describe('update/pause/resume/delete: job name'),
 	allFolders: z.boolean().optional().describe('list: include jobs of other folders (names only)'),
 })
 
@@ -138,6 +171,14 @@ function effectsOf(rule: unknown): string[] {
  * Refuse a network tool beside a shell that runs on the host: a scheduled run
  * that can both read the machine and reach the internet, unattended, is the
  * exfiltration shape, and only the operator can choose it.
+ *
+ * For `runKind: 'script'`/`'script+agent'` the "shell" isn't a rule the model
+ * could reach at some later live call — it's the confirmed script's own
+ * body, which unconditionally runs shell commands whenever it runs at all.
+ * The `bash` rule heuristic below answers a question ("could a live call
+ * reach bash") that isn't the one being asked here, so a script/script+agent
+ * job on the host is treated as reaching a shell outright, whatever its
+ * rules say about `bash`.
  */
 function networkWithHostShell(draft: ScheduleJobDraft): boolean {
 	const rules = draft.permissions.rules ?? {}
@@ -145,6 +186,8 @@ function networkWithHostShell(draft: ScheduleJobDraft): boolean {
 		draft.permissions.browser !== undefined ||
 		NETWORK_TOOLS.some((t) => effectsOf(rules[t]).some((e) => e === 'allow' || e === 'ask'))
 	if (!network) return false
+	const onHost = (draft.permissions.execution ?? 'host') === 'host'
+	if ((draft.runKind ?? 'agent') !== 'agent') return onHost
 	const bashEffects = effectsOf(rules.bash)
 	// The read-only preset denies bash; its rules are expanded by the host,
 	// so the draft carries only its name.
@@ -152,7 +195,7 @@ function networkWithHostShell(draft: ScheduleJobDraft): boolean {
 		bashEffects.length > 0
 			? bashEffects.some((e) => e !== 'deny')
 			: draft.permissions.preset !== 'read-only' && draft.permissions.unmatched !== 'deny'
-	return shellPossible && (draft.permissions.execution ?? 'host') === 'host'
+	return shellPossible && onHost
 }
 
 /**
@@ -208,45 +251,70 @@ function browserGrant(
 	}
 }
 
+/** A proposed permission set as a draft carries it, or why it is refused. */
+function checkPermissions(
+	host: ScheduleToolHost,
+	proposed: NonNullable<Input['permissions']>,
+): { ok: true; permissions: ScheduleJobDraft['permissions'] } | { ok: false; error: string } {
+	if (!proposed.preset && !proposed.rules && !proposed.browser) {
+		return {
+			ok: false,
+			error:
+				'permissions needs a preset, rules or a browser grant; an empty permission set is not a choice.',
+		}
+	}
+	if (!proposed.browser) return { ok: true, permissions: proposed }
+	const grant = browserGrant(host, proposed.browser)
+	if (!grant.ok) return grant
+	return { ok: true, permissions: { ...proposed, browser: grant.grant } }
+}
+
+const NETWORK_WITH_HOST_SHELL =
+	'A scheduled job proposed here cannot combine web or browser access with a shell on the host. Deny bash, use execution "sandbox", or ask the operator to create it with `namzu schedule add`.'
+
 async function create(
 	host: ScheduleToolHost,
 	input: Input,
 	signal: AbortSignal | undefined,
 ): Promise<ToolResult> {
-	const missing = (['name', 'prompt', 'when', 'permissions'] as const).filter(
+	const runKind = input.kind ?? 'agent'
+	const required: string[] = (['name', 'when', 'permissions'] as const).filter(
 		(k) => input[k] === undefined,
 	)
-	if (missing.length > 0) {
+	if (runKind !== 'script' && input.prompt === undefined) required.push('prompt')
+	if (runKind !== 'agent' && input.script === undefined) required.push('script')
+	if (required.length > 0) {
 		return refuse(
-			`create needs ${missing.join(', ')}. permissions is required: propose an explicit set (a preset and/or rules, plus unmatched).`,
+			`create needs ${required.join(', ')}. permissions is required: propose an explicit set (a preset and/or rules, plus unmatched).`,
 		)
 	}
-	const proposed = input.permissions as NonNullable<Input['permissions']>
-	if (!proposed.preset && !proposed.rules && !proposed.browser) {
+	if (runKind === 'agent' && input.script !== undefined) {
+		return refuse('an agent job has no script; omit kind (or set it to agent) to use one')
+	}
+	if (runKind === 'script' && input.prompt !== undefined)
+		return refuse('a pure script job has no prompt; remove prompt')
+	if (runKind === 'script' && input.budget !== undefined) {
 		return refuse(
-			'permissions needs a preset, rules or a browser grant; an empty permission set is not a choice.',
+			'a pure script job has no agent budget; remove budget and use script.timeoutMs for its timeout',
 		)
 	}
-	let permissions: ScheduleJobDraft['permissions'] = proposed
-	if (proposed.browser) {
-		const grant = browserGrant(host, proposed.browser)
-		if (!grant.ok) return refuse(grant.error)
-		permissions = { ...proposed, browser: grant.grant }
-	}
+	if (runKind === 'script' && input.permissions?.browser !== undefined)
+		return refuse('a pure script job cannot use a browser grant; remove permissions.browser')
+	const checked = checkPermissions(host, input.permissions as NonNullable<Input['permissions']>)
+	if (!checked.ok) return refuse(checked.error)
+	const permissions = checked.permissions
 	const draft: ScheduleJobDraft = {
 		name: input.name as string,
-		prompt: input.prompt as string,
 		when: input.when as string,
+		...(runKind !== 'agent' ? { runKind } : {}),
+		...(input.script ? { script: input.script } : {}),
+		...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
 		...(input.folder !== undefined ? { folder: input.folder } : {}),
 		...(input.tz !== undefined ? { tz: input.tz } : {}),
 		permissions,
 		...(input.budget ? { budget: input.budget } : {}),
 	}
-	if (networkWithHostShell(draft)) {
-		return refuse(
-			'A scheduled job proposed here cannot combine web or browser access with a shell on the host. Deny bash, use execution "sandbox", or ask the operator to create it with `namzu schedule add`.',
-		)
-	}
+	if (networkWithHostShell(draft)) return refuse(NETWORK_WITH_HOST_SHELL)
 	let preview: Awaited<ReturnType<ScheduleToolHost['preview']>>
 	try {
 		preview = await host.preview(draft)
@@ -282,7 +350,9 @@ async function create(
 	const said =
 		answer === 'create-paused'
 			? `Job "${created.name}" was created paused. The operator can resume it with /schedule.`
-			: `Job "${created.name}" was created. It runs ${preview.schedule}, with nobody watching; results arrive as a notification and a session.`
+			: runKind === 'script'
+				? `Job "${created.name}" was created. It runs ${preview.schedule}, with nobody watching; results are recorded in its history and may arrive as a notification. It creates no session.`
+				: `Job "${created.name}" was created. It runs ${preview.schedule}, with nobody watching; results arrive as a notification and a session.`
 	return {
 		success: true,
 		output: created.note ? `${said} ${created.note}` : said,
@@ -291,15 +361,141 @@ async function create(
 }
 
 async function list(host: ScheduleToolHost, input: Input): Promise<ToolResult> {
-	const jobs = await host.list({ allFolders: input.allFolders === true })
+	let jobs: readonly ScheduleJobSummary[]
+	try {
+		jobs = await host.list({ allFolders: input.allFolders === true })
+	} catch (error) {
+		return refuse(error instanceof Error ? error.message : String(error))
+	}
 	if (jobs.length === 0) return { success: true, output: 'No scheduled jobs.', data: { jobs: [] } }
 	const lines = jobs.map(
 		(j) =>
-			`${j.name} · ${j.state} · ${j.schedule}${j.nextFireAt ? ` · next ${j.nextFireAt}` : ''}${j.lastStatus ? ` · last ${j.lastStatus}` : ''} · ${j.folder}`,
+			`${j.name} · ${j.state} · ${j.schedule}${j.nextFireAt ? ` · next ${j.nextFireAt}` : ''}${j.lastStatus ? ` · last ${j.lastStatus}` : ''} · ${j.folder}${j.inSessionFolder ? ' (this folder)' : ''}`,
 	)
 	return { success: true, output: lines.join('\n'), data: { jobs } }
 }
 
+/** The fields `update` may change, as the model set them. */
+const CHANGEABLE = [
+	'prompt',
+	'when',
+	'folder',
+	'tz',
+	'permissions',
+	'budget',
+	'kind',
+	'script',
+] as const
+
+async function update(
+	host: ScheduleToolHost,
+	input: Input,
+	signal: AbortSignal | undefined,
+): Promise<ToolResult> {
+	if (!host.previewUpdate || !host.confirmUpdate || !host.update) {
+		return refuse(
+			'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.job) return refuse("update needs job (the job's name) and the fields to change.")
+	if (input.name !== undefined) {
+		return refuse(
+			'update cannot rename a job: name the job to change with job, and leave name out.',
+		)
+	}
+	const given = CHANGEABLE.filter((k) => input[k] !== undefined)
+	if (given.length === 0) {
+		return refuse(`update needs at least one of ${CHANGEABLE.join(', ')} to change.`)
+	}
+	if (input.kind === 'agent' && input.script !== undefined) {
+		return refuse(
+			'update cannot set kind to agent while also giving a script; drop script to make it an agent job, or leave kind unset (or as script/script+agent) to keep one.',
+		)
+	}
+	let permissions: ScheduleJobDraft['permissions'] | undefined
+	if (input.permissions) {
+		const checked = checkPermissions(host, input.permissions)
+		if (!checked.ok) return refuse(checked.error)
+		permissions = checked.permissions
+		// The same guard `create` applies, against whatever THIS call
+		// changes: a kind given here is read too, since a script/script+agent
+		// job is refused this combination even where an agent job is not (no
+		// live turn reviews a script's calls one at a time). A kind changed
+		// with the existing permissions is checked on the effective preview
+		// after the host has applied all changes below.
+		if (
+			networkWithHostShell({
+				name: '',
+				prompt: '',
+				when: '',
+				...(input.kind !== undefined ? { runKind: input.kind } : {}),
+				permissions,
+			})
+		)
+			return refuse(NETWORK_WITH_HOST_SHELL)
+	}
+	const changes: ScheduleJobChanges = {
+		...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
+		...(input.when !== undefined ? { when: input.when } : {}),
+		...(input.folder !== undefined ? { folder: input.folder } : {}),
+		...(input.tz !== undefined ? { tz: input.tz } : {}),
+		...(permissions ? { permissions } : {}),
+		...(input.budget ? { budget: input.budget } : {}),
+		...(input.kind !== undefined ? { runKind: input.kind } : {}),
+		...(input.script !== undefined ? { script: input.script } : {}),
+	}
+	let proposal: ScheduleJobUpdateProposal
+	try {
+		proposal = await host.previewUpdate(input.job, changes)
+	} catch (error) {
+		return refuse(error instanceof Error ? error.message : String(error))
+	}
+	const effectiveKind = input.kind ?? proposal.preview.runKind ?? 'agent'
+	if (
+		(effectiveKind === 'script' || effectiveKind === 'script+agent') &&
+		proposal.preview.execution === 'host' &&
+		(proposal.preview.networkGrantAccess ?? proposal.preview.networkAccess)
+	) {
+		return refuse(NETWORK_WITH_HOST_SHELL)
+	}
+	let confirmed = false
+	try {
+		confirmed = await host.confirmUpdate(
+			{
+				...proposal,
+				promptFindings: scanSchedulePrompt(proposal.preview.prompt),
+				proposedBy: 'model',
+			},
+			signal,
+		)
+	} catch {
+		confirmed = false
+	}
+	// As for `create`: never save on an answer that came after the
+	// operator was no longer being asked.
+	if (signal?.aborted) confirmed = false
+	if (!confirmed) {
+		return {
+			...refuse(
+				`The operator did not confirm the change; "${proposal.preview.name}" was not changed.`,
+			),
+			data: { cancelled: true },
+		}
+	}
+	let saved: Awaited<ReturnType<NonNullable<ScheduleToolHost['update']>>>
+	try {
+		saved = await host.update(proposal.preview)
+	} catch (error) {
+		return refuse(error instanceof Error ? error.message : String(error))
+	}
+	const said = `Job "${saved.name}" was updated in place and keeps its history. It runs ${proposal.preview.schedule}.`
+	return {
+		success: true,
+		output: saved.note ? `${said} ${saved.note}` : said,
+		data: { name: saved.name, updated: true, changes: proposal.changes },
+	}
+}
+
 async function lifecycle(
 	host: ScheduleToolHost,
 	input: Input,
@@ -331,12 +527,13 @@ async function lifecycle(
 }
 
 /**
- * The `schedule` tool: create, list, pause, resume and delete the operator's
- * scheduled jobs from a conversation.
+ * The `schedule` tool: create, list, update, pause, resume and delete the
+ * operator's scheduled jobs from a conversation.
  *
- * Creation, resuming and deleting are confirmed by a person through the host
- * (`ScheduleToolHost.confirm`), on a screen the host draws from its own
- * computation. The model cannot propose that uncovered calls run without
+ * Creation, updating, resuming and deleting are confirmed by a person
+ * through the host (`ScheduleToolHost.confirm`, `confirmUpdate`), on a
+ * screen the host draws from its own computation. An update changes the
+ * job in place, so it keeps its id and its history. The model cannot propose that uncovered calls run without
  * asking, nor web access beside a host shell. Register it only where a person
  * is present to confirm: never in a headless run, a scheduled run or a
  * sub-agent.
@@ -346,7 +543,7 @@ export function buildScheduleTools(host: ScheduleToolHost): ToolDefinition[] {
 		defineTool({
 			name: SCHEDULE_TOOL_NAME,
 			description:
-				"Manage the operator's scheduled jobs: prompts that run later in a folder, with nobody watching, under an explicit permission set. Use it only when the user asks for something to happen on a schedule. create, resume and delete are confirmed by the operator; pause is not. A job needs name, prompt, when and permissions (unmatched: park or deny, plus a preset, rules or a browser grant). Leave every other field (folder, tz, execution, budget, headed) unset unless the user asked for it: the defaults are the operator's, and the confirmation marks each value you chose. Scheduled runs cannot ask questions.",
+				"Manage the operator's scheduled jobs: model prompts or fixed scripts that run later in a folder, with nobody watching, under an explicit permission set. Use it only when the user asks for something to happen on a schedule. create, update, resume and delete are confirmed by the operator; pause is not. A job needs name, when and permissions (unmatched: park or deny, plus a preset, rules or a browser grant). agent and script+agent also need prompt; script and script+agent also need script. A pure script has no prompt, model, agent budget, browser grant or session; set script.timeoutMs to limit it. To change a job, update it with job and only the fields that change; do not delete and recreate it. Leave every other field (folder, tz, execution, budget, headed) unset unless the user asked for it: the defaults are the operator's, and the confirmation marks each value you chose. Scheduled runs cannot ask questions.",
 			inputSchema,
 			category: 'custom',
 			permissions: [],
@@ -358,8 +555,8 @@ export function buildScheduleTools(host: ScheduleToolHost): ToolDefinition[] {
 			concurrencySafe: false,
 			presentCall: presentScheduleCall,
 			presentResult: presentScheduleResult,
-			// A person, not a tool, answers `create`/`resume`/`delete`; see
-			// `OPERATOR_CONFIRM_TIMEOUT_MS`.
+			// A person, not a tool, answers `create`/`update`/`resume`/`delete`;
+			// see `OPERATOR_CONFIRM_TIMEOUT_MS`.
 			timeoutMs: OPERATOR_CONFIRM_TIMEOUT_MS,
 			async execute(input, context: ToolContext) {
 				switch (input.action) {
@@ -367,6 +564,8 @@ export function buildScheduleTools(host: ScheduleToolHost): ToolDefinition[] {
 						return create(host, input, context.abortSignal)
 					case 'list':
 						return list(host, input)
+					case 'update':
+						return update(host, input, context.abortSignal)
 					default:
 						return lifecycle(host, input, input.action, context.abortSignal)
 				}

package/src/tools/schedules/types.ts

@@ -11,10 +11,29 @@
 /** A rule effect, in the vocabulary of the CLI's `[permissions]` table. */
 export type ScheduleRuleEffect = 'allow' | 'ask' | 'deny'
 
-/** What the model proposes. Validated by the tool's schema, then by the host. */
+/**
+ * What the model proposes. Validated by the tool's schema, then by the host.
+ *
+ * `runKind` absent means `'agent'`, unchanged from before this field
+ * existed — every existing host keeps compiling and behaving the same.
+ * `prompt` is optional ONLY because a pure `'script'` draft has none; a
+ * `ScheduleToolHost` that read it as a bare `string` before this field
+ * existed now needs a null check under `strictNullChecks` (see the SDK's
+ * changeset for this release: this is a breaking change to the type, not a
+ * free widening).
+ */
 export interface ScheduleJobDraft {
 	readonly name: string
-	readonly prompt: string
+	/** Required unless `runKind` is `'script'`, whose prompt is unused. */
+	readonly prompt?: string
+	/** Absent: `'agent'`. */
+	readonly runKind?: 'agent' | 'script' | 'script+agent'
+	/** Required when `runKind` is `'script'` or `'script+agent'` (the wake-gate). */
+	readonly script?: {
+		readonly body: string
+		readonly shell: 'bash' | 'sh'
+		readonly timeoutMs?: number
+	}
 	/** Schedule words: `every 30m`, `0 9 * * 1-5`, `at 09:00`, `in 2h`. */
 	readonly when: string
 	/** Folder the job runs in. Absent: the session's working directory. */
@@ -78,7 +97,16 @@ export interface ScheduleJobPreview {
 	readonly folder: string
 	/** True when `folder` is outside the session's working directory and added directories. */
 	readonly outsideSessionRoots: boolean
+	/** Empty for a pure `'script'` job, whose prompt is unused. */
 	readonly prompt: string
+	/** Absent: `'agent'`. */
+	readonly runKind?: 'agent' | 'script' | 'script+agent'
+	/** Present for `runKind: 'script'`/`'script+agent'`: the exact confirmed text. */
+	readonly script?: {
+		readonly body: string
+		readonly shell: 'bash' | 'sh'
+		readonly timeoutMs: number
+	}
 	/** The schedule in words, with its zone. */
 	readonly schedule: string
 	/** The next fire times, ISO-8601 UTC. */
@@ -87,8 +115,11 @@ export interface ScheduleJobPreview {
 	readonly rules: readonly string[]
 	readonly unmatched: 'park' | 'deny' | 'allow'
 	readonly execution: 'host' | 'sandbox'
-	/** A rule lets the run reach the network. */
+	/** The run can reach the network, including through a fixed host script. */
 	readonly networkAccess: boolean
+	/** Web/browser permissions grant network access, separate from a script's own capability. */
+	readonly networkGrantAccess?: boolean
+	/** Effective run limits. A pure script has zero model iterations/tokens and its script timeout. */
 	readonly budget: {
 		readonly maxIterations: number
 		readonly tokenBudget: number
@@ -96,8 +127,8 @@ export interface ScheduleJobPreview {
 	}
 	/** Runs per day at most, times the token budget. Absent for a one-shot. */
 	readonly dailyTokenCeiling?: number
-	/** Provider and model the job is pinned to. */
-	readonly model: string
+	/** Provider and model the agent phase is pinned to. Absent for a pure script job. */
+	readonly model?: string
 	/** Where the run's credential comes from, in words. */
 	readonly credentialSource?: string
 	/** Anything the host wants said in the warning colour. */
@@ -114,6 +145,62 @@ export interface ScheduleJobSummary {
 	readonly lastStatus?: string
 	/** Present only for jobs in the session's own folder. */
 	readonly prompt?: string
+	/**
+	 * True for a job whose folder is the session's own. A host that lists
+	 * other folders' jobs sets it so the model can tell them apart; the tool
+	 * marks such a job `(this folder)`.
+	 */
+	readonly inSessionFolder?: boolean
+}
+
+/**
+ * What the model proposes to change in an existing job. Every field left
+ * out keeps the job's current value. `permissions`, when given, is the whole
+ * new set, with the same limits as a new job's; the host keeps the job's
+ * `execution` when it is not given, and its additional directories.
+ */
+export interface ScheduleJobChanges {
+	readonly prompt?: string
+	readonly when?: string
+	readonly folder?: string
+	readonly tz?: string
+	readonly permissions?: ScheduleJobDraft['permissions']
+	readonly budget?: ScheduleJobDraft['budget']
+	/**
+	 * Changes what kind of run this is. Absent: keeps the job's current kind.
+	 * Moving to `'script'`/`'script+agent'` needs `script`; moving to
+	 * `'agent'` drops whatever script the job had, whether or not one is
+	 * given here — an agent job cannot carry one.
+	 */
+	readonly runKind?: 'agent' | 'script' | 'script+agent'
+	/**
+	 * Replaces the whole script (or, for `'script+agent'`, wake-gate) body,
+	 * shell and timeout — never a partial edit of just one of them. Absent:
+	 * keeps the job's current script. Re-verified fresh against the
+	 * scheduled-run floor and every `deny` rule, the same as a new job's.
+	 */
+	readonly script?: ScheduleJobDraft['script']
+}
+
+/** A proposed change to a job, as the host computed it. */
+export interface ScheduleJobUpdateProposal {
+	/** The job as it would be once changed. Every field is the host's own computation. */
+	readonly preview: ScheduleJobPreview
+	/**
+	 * What differs from the job as it stands (and from edits saved since it
+	 * was last confirmed), one line each: `- ` what goes, `+ ` what comes.
+	 */
+	readonly changes: readonly string[]
+	/** The change touches what a run may do: its rules, `unmatched`, where it runs, its browser grant. */
+	readonly permissionsChange: boolean
+}
+
+/** What the person confirming a change is shown. */
+export interface ScheduleUpdateRequest extends ScheduleJobUpdateProposal {
+	/** The prompt tripwire's findings over `preview.prompt`. */
+	readonly promptFindings: readonly string[]
+	/** Always `model` from this tool. */
+	readonly proposedBy: 'model'
 }
 
 /** What the person answered to a proposed job. */
@@ -157,7 +244,15 @@ export interface ScheduleToolHost {
 		preview: ScheduleJobPreview,
 		options: { readonly paused: boolean },
 	): Promise<{ readonly name: string; readonly note?: string }>
-	/** Jobs, the session folder's in full, other folders' without their prompts. */
+	/**
+	 * Jobs, the session folder's in full, other folders' without their
+	 * prompts. `allFolders: false` lets a host list only the session
+	 * folder's; a host may list every job regardless, marking the session
+	 * folder's with {@link ScheduleJobSummary.inSessionFolder}. The tool says
+	 * "No scheduled jobs." when this returns none, so a host that filters
+	 * says so only for its folder. Throw on an unreadable job store: the tool
+	 * reports the error rather than claiming there are no jobs.
+	 */
 	list(options: { readonly allFolders: boolean }): Promise<readonly ScheduleJobSummary[]>
 	/** A job by name or id prefix, or undefined. */
 	find(job: string): Promise<ScheduleJobSummary | undefined>
@@ -170,6 +265,25 @@ export interface ScheduleToolHost {
 	pause(job: string): Promise<void>
 	resume(job: string): Promise<void>
 	delete(job: string): Promise<void>
+	/**
+	 * Validate a change to `job` (a name or id prefix) and compute what the
+	 * person will be shown. Throws with a message on a refusal. The tool
+	 * offers `update` only when a host has all three of `previewUpdate`,
+	 * `confirmUpdate` and `update`.
+	 */
+	previewUpdate?(job: string, changes: ScheduleJobChanges): Promise<ScheduleJobUpdateProposal>
+	/**
+	 * Ask the person whether to save the change. Anything but `true` — a
+	 * thrown error, a closed screen — changes nothing. See `confirm` on
+	 * `signal`.
+	 */
+	confirmUpdate?(request: ScheduleUpdateRequest, signal?: AbortSignal): Promise<boolean>
+	/**
+	 * Save the change the person confirmed, to the same job: its id and its
+	 * history are kept, and the confirmation is the person's. `note` as for
+	 * `create`.
+	 */
+	update?(preview: ScheduleJobPreview): Promise<{ readonly name: string; readonly note?: string }>
 }
 
 /** A prompt the session re-sends to itself on an interval. */

package/src/tools/trusted-read-only.ts

@@ -1,3 +1,4 @@
+import type { ToolSourceRef } from '../toolsets/types.js'
 import type { ToolDefinition } from '../types/tool/index.js'
 
 /**
@@ -30,23 +31,31 @@ import type { ToolDefinition } from '../types/tool/index.js'
  *    opening its own gate.
  *
  * Trust for the second case comes from the operator, per server, and is
- * recorded on the tool as `provenance.readOnlyHintTrusted`. Never a global
- * switch: one flag meaning "trust annotations" hands every connected
- * server the same reach, which is the hole restated.
+ * carried on the OWNING TOOLSET's source (`ToolSourceRef.readOnlyHintTrusted`,
+ * `toolsets/manager.ts`'s `sourceOf`) rather than stamped onto the tool
+ * itself — `ToolDefinition` has no `provenance` field to read; a definition
+ * cannot claim its own source. Never a global switch: one flag meaning
+ * "trust annotations" hands every connected server the same reach, which is
+ * the hole restated.
  *
  * `isReadOnly` itself is left reporting faithfully what the server said.
- * Provenance and policy are different questions, and collapsing them would
+ * Source and policy are different questions, and collapsing them would
  * corrupt the outbound re-export and the prompt's own destructive label in
  * order to fix a gate.
  */
-export function isTrustedReadOnly(tool: ToolDefinition | undefined, input: unknown): boolean {
+export function isTrustedReadOnly(
+	tool: ToolDefinition | undefined,
+	input: unknown,
+	source?: ToolSourceRef,
+): boolean {
 	if (!tool?.isReadOnly) return false
 
-	// No provenance means the tool is host-defined: it came from this
-	// process, from code the operator installed, and there is no untrusted
-	// party in the chain. Requiring an opt-in for a builtin would break
-	// every read-only exemption for no gain in trust.
-	if (tool.provenance && !tool.provenance.readOnlyHintTrusted) return false
+	// A source that is not `mcp_server` is host-defined: this process, code
+	// the operator installed, no untrusted party in the chain. Requiring an
+	// opt-in for a builtin would break every read-only exemption for no gain
+	// in trust. `source` itself absent (a caller with no manager to ask)
+	// is treated the same way, matching the old "no provenance" default.
+	if (source?.kind === 'mcp_server' && !source.readOnlyHintTrusted) return false
 
 	return tool.isReadOnly(input)
 }