@namzu/sdk 44.0.0 → 44.2.0

package/src/manager/agent/lifecycle.ts

@@ -180,6 +180,26 @@ function mergeEnv(
 	return { ...base, ...override }
 }
 
+/**
+ * One `reviewAllowedCalls` that answers `true` when any of `sources` does.
+ *
+ * Review is only ever added along a delegation: a child's own answer joins
+ * its parent's, it never replaces it. Each source is read at every call, so
+ * a parent whose answer changes mid-turn (a mode the operator entered) is
+ * seen by a child already running. The same function twice (a builder that
+ * forwarded the override it was handed) is consulted once. Returns
+ * `undefined` when no source is set, and the one source unwrapped when there
+ * is exactly one.
+ */
+function anyReviewAllowedCalls(
+	...sources: ReadonlyArray<(() => boolean) | undefined>
+): (() => boolean) | undefined {
+	const present = [...new Set(sources.filter((s): s is () => boolean => s !== undefined))]
+	if (present.length === 0) return undefined
+	if (present.length === 1) return present[0]
+	return () => present.some((source) => source() === true)
+}
+
 export class AgentManager {
 	private registry: AgentRegistry
 	private instances: Map<TaskId, AgentTask> = new Map()
@@ -542,6 +562,16 @@ export class AgentManager {
 			const ownDenies = options.toolScope?.deny ?? []
 			const resolvedDenies = [...new Set([...inheritedDenies, ...ownDenies])]
 
+			// The parent's "review even what the rules allow" (plan mode), and
+			// this spawn's own if it names one. OR-ed rather than replaced, for
+			// the same reason the denies above are a union: a descendant may ask
+			// for more review and never for less. The builder's value joins
+			// below, once the builder has run.
+			const inheritedReview = anyReviewAllowedCalls(
+				context.reviewAllowedCalls,
+				options.configOverrides?.reviewAllowedCalls,
+			)
+
 			const childContext: AgentTaskContext = {
 				parentSessionId: context.parentSessionId,
 				parentTurnId: context.parentTurnId,
@@ -557,6 +587,7 @@ export class AgentManager {
 				parentActor: childParentActor,
 				...(resolvedDenies.length > 0 ? { toolDenies: resolvedDenies } : {}),
 				...(context.childStorage ? { childStorage: context.childStorage } : {}),
+				...(inheritedReview ? { reviewAllowedCalls: inheritedReview } : {}),
 			}
 
 			agentTask = Object.assign(queuedTask ?? {}, {
@@ -759,6 +790,21 @@ export class AgentManager {
 				childConfig.toolResultGuardrails = inheritedScreens
 			}
 
+			// Stamped after both branches, beside the screens and for the same
+			// reason: a `configBuilder` cannot forward a field it was never told
+			// about, and the bare-config branch builds its config by hand.
+			//
+			// Without it a child borrowed its parent's review handler and not
+			// the switch that sends rule-allowed and grant-covered batches to
+			// it, so plan mode refused the parent's next change and let the
+			// child's run: a call an approval earlier in the CHILD's turn
+			// covered never reached the handler that knew about plan mode. The
+			// function is carried, not sampled, so a mode entered while the
+			// child runs reaches its next batch. The builder's own value is
+			// kept and OR-ed in: it may add review, never remove the parent's.
+			const effectiveReview = anyReviewAllowedCalls(inheritedReview, childConfig.reviewAllowedCalls)
+			if (effectiveReview) childConfig.reviewAllowedCalls = effectiveReview
+
 			// Lineage is assigned by the spawning manager, not proposed by the
 			// child definition. A fixed configBuilder can ignore its inputs and
 			// configOverrides is caller-authored; neither may turn a child back

package/src/runtime/query/events.ts

@@ -283,6 +283,7 @@ export class EventTranslator {
 						status: task.status,
 						owner: task.owner,
 						...(task.blockedBy.length > 0 ? { blockedBy: task.blockedBy } : {}),
+						...(event.type === 'task.deleted' ? { deleted: true as const } : {}),
 					})
 					break
 				default: {

package/src/runtime/query/index.ts

@@ -739,6 +739,22 @@ export interface QueryParams {
 		current: import('../../types/permission/index.js').PermissionMode
 	}
 
+	/**
+	 * Whether a batch that needs no review still goes to `resumeHandler`.
+	 *
+	 * A batch every call of which an authorization rule allows, or which a
+	 * grant from earlier in the turn covers, runs without asking the handler.
+	 * That is right while the handler would approve it anyway, and wrong under
+	 * a policy stricter than the rules: a read-only mode such as `plan`, which
+	 * refuses a change a rule would let through. Consulted once per batch,
+	 * just before either shortcut; `true` sends the batch to the handler, each
+	 * call carrying the gate's decision in `authorization`. A rule's `deny`
+	 * still refuses a call whatever this returns.
+	 *
+	 * Absent, both shortcuts apply as they always have.
+	 */
+	reviewAllowedCalls?: () => boolean
+
 	/**
 	 * A name for the policy `resumeHandler` implements.
 	 *
@@ -1480,6 +1496,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			// Turn-scoped. An approval is a statement about this turn's work;
 			// carrying one into a later turn would be reuse nobody agreed to.
 			toolGrants: new ToolGrantSet(),
+			...(params.reviewAllowedCalls ? { reviewAllowedCalls: params.reviewAllowedCalls } : {}),
 			// Turn-scoped for the same reason. A repeat count carried into a later
 			// run is a claim about work nobody repeated, and a module-level map
 			// would leak exactly that way.

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

@@ -166,6 +166,8 @@ export interface IterationContext {
 	 * asked about again. Absent on paths that do not review tools.
 	 */
 	readonly toolGrants?: ToolGrantSet
+	/** See `QueryParams.reviewAllowedCalls`. Absent: allowed and granted batches skip review. */
+	readonly reviewAllowedCalls?: () => boolean
 	/**
 	 * Absent when the host opted out with `repeatCallAdvisory: false`. The
 	 * opt-out is the ABSENCE, not a flag read at every call site, so a code

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -226,6 +226,16 @@ export async function* runToolReview(
 	// must not be able to release them.
 	const gateDenied = new Map<string, string>()
 
+	// Sampled once, the first time a shortcut asks, so both shortcuts below
+	// read the same answer for this batch. A policy stricter than the rules
+	// (a read-only mode) sees the batch rather than letting an allowance or a
+	// grant run it past the handler.
+	let reviewAllowedSample: boolean | undefined
+	const reviewAllowed = (): boolean => {
+		reviewAllowedSample ??= ctx.reviewAllowedCalls?.() === true
+		return reviewAllowedSample
+	}
+
 	// The operator's policy runs FIRST, and a grant cannot overrule it.
 	//
 	// The grant short-circuit used to sit above this block and return, so a
@@ -289,7 +299,7 @@ export async function* runToolReview(
 		const allAllowed = gateResults.every((gr) => gr.gateResult.decision === 'allow')
 		const allDenied = gateResults.every((gr) => gr.gateResult.decision === 'deny')
 
-		if (allAllowed) {
+		if (allAllowed && !reviewAllowed()) {
 			ctx.log.debug('Authorization gate: all tool calls pre-approved', {
 				'namzu.tool.names': gateResults.map((gr) => gr.toolCall.name),
 			})
@@ -334,6 +344,7 @@ export async function* runToolReview(
 	// working directory or a run outside the sandbox.
 	if (
 		ctx.toolGrants &&
+		!reviewAllowed() &&
 		gateDenied.size === 0 &&
 		escalated().length === 0 &&
 		toolCallSummaries.every((tc) => ctx.toolGrants?.covers(tc))

package/src/tools/task/create.ts

@@ -4,6 +4,7 @@ import type { ToolDefinition } from '../../types/tool/index.js'
 import { asTaskId } from '../../utils/id.js'
 import { defineTool } from '../defineTool.js'
 import type { TaskToolScope } from './index.js'
+import { presentTaskCreateCall, presentTaskCreateResult } from './present.js'
 
 export function buildTaskCreateTool(
 	taskStore: TaskStore,
@@ -35,6 +36,8 @@ export function buildTaskCreateTool(
 		readOnly: false,
 		destructive: false,
 		concurrencySafe: true,
+		presentCall: presentTaskCreateCall,
+		presentResult: presentTaskCreateResult,
 		async execute({ subject, description, activeForm, owner, blockedBy, metadata }) {
 			const task = await taskStore.create({
 				sessionId: scope.sessionId,
@@ -50,7 +53,7 @@ export function buildTaskCreateTool(
 			return {
 				success: true,
 				output: `Task created: ${task.id} — "${subject}"${owner ? ` [owner: ${owner}]` : ''}`,
-				data: { id: task.id, status: task.status, owner: task.owner },
+				data: { id: task.id, subject: task.subject, status: task.status, owner: task.owner },
 			}
 		},
 	})

package/src/tools/task/list.ts

@@ -4,6 +4,7 @@ import { type TaskStore, isTerminalTaskStatus } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import type { TaskToolScope } from './index.js'
+import { countTasks, presentTaskListCall, presentTaskListResult } from './present.js'
 
 export function buildTaskListTool(
 	taskStore: TaskStore,
@@ -19,6 +20,8 @@ export function buildTaskListTool(
 		readOnly: true,
 		destructive: false,
 		concurrencySafe: true,
+		presentCall: presentTaskListCall,
+		presentResult: presentTaskListResult,
 		async execute() {
 			const all = await taskStore.list({ sessionId: scope.sessionId })
 			// Blockers resolve against every task of the session, shown or not: a
@@ -53,7 +56,7 @@ export function buildTaskListTool(
 				output:
 					tasks.length === 0
 						? 'No planning tasks yet. This list does not report delegated agent status; use agent_task_list when available.'
-						: `${stats.total} tasks: ${stats.completed} completed, ${stats.in_progress} in progress, ${stats.pending} pending.`,
+						: `${countTasks(stats.total)}: ${stats.completed} completed, ${stats.in_progress} in progress, ${stats.pending} pending.`,
 				data: { tasks: summary, stats },
 			}
 		},

package/src/tools/task/present.ts

@@ -0,0 +1,102 @@
+import type { ToolResult } from '../../types/tool/index.js'
+import type { ToolCallView, ToolResultView } from '../../types/tool/presentation.js'
+
+/**
+ * How the task tools read to a person.
+ *
+ * The model-facing output of these tools names task ids, because the model
+ * needs them to call `task_update`. None of that is for the operator: with no
+ * opinion of its own a task call fell through to the generic presenter, which
+ * printed the arguments (`{"id":"01a0…","status":"completed"}`) as the call
+ * row and the model's receipt (`Task 01a0… updated — status: completed`) as
+ * the result. So each tool says what happened in words — `Added task ·
+ * Write the parser` — and a successful receipt adds nothing beneath it.
+ *
+ * Deliberately no ids, no owner and no JSON anywhere in these views. A host
+ * that wants the ids still has the tool result and its `data`.
+ */
+
+const MAX_SUBJECT = 100
+
+function oneLine(value: string): string {
+	const flat = value.replace(/\s+/g, ' ').trim()
+	return flat.length > MAX_SUBJECT ? `${flat.slice(0, MAX_SUBJECT - 1)}…` : flat
+}
+
+function activity(label: string): ToolCallView {
+	return { kind: 'generic', presentation: 'activity', label }
+}
+
+/** A successful receipt: the call row already said it. */
+const HIDDEN_RESULT: ToolResultView = { kind: 'generic', label: '', visibility: 'hidden' }
+
+/** `N task` / `N tasks`. */
+export function countTasks(count: number): string {
+	return `${count} task${count === 1 ? '' : 's'}`
+}
+
+/** What a failed task call says, without the id the model passed. */
+function failure(result: ToolResult, fallback: string): ToolResultView {
+	const text = `${result.error ?? result.output ?? ''}`
+	return {
+		kind: 'generic',
+		label: /not found/i.test(text) ? 'No task has that id' : fallback,
+	}
+}
+
+export function presentTaskCreateCall(input: { readonly subject?: unknown }): ToolCallView {
+	const subject = typeof input.subject === 'string' ? oneLine(input.subject) : ''
+	return activity(subject ? `Add task · ${subject}` : 'Add task')
+}
+
+export function presentTaskCreateResult(_input: unknown, result: ToolResult): ToolResultView {
+	if (!result.success) return failure(result, 'The task was not added')
+	return HIDDEN_RESULT
+}
+
+/** The verb for a `task_update` call, from the status it asks for. */
+export function taskUpdateVerb(status: unknown): string {
+	switch (status) {
+		case 'in_progress':
+			return 'Start task'
+		case 'completed':
+			return 'Complete task'
+		case 'deleted':
+			return 'Remove task'
+		case 'pending':
+			return 'Reopen task'
+		default:
+			return 'Update task'
+	}
+}
+
+export function presentTaskUpdateCall(input: {
+	readonly status?: unknown
+	readonly subject?: unknown
+}): ToolCallView {
+	const verb = taskUpdateVerb(input.status)
+	const subject = typeof input.subject === 'string' ? oneLine(input.subject) : ''
+	return activity(subject ? `${verb} · ${subject}` : verb)
+}
+
+export function presentTaskUpdateResult(_input: unknown, result: ToolResult): ToolResultView {
+	if (!result.success) return failure(result, 'The task was not changed')
+	return HIDDEN_RESULT
+}
+
+export function presentTaskListCall(): ToolCallView {
+	return activity('Check tasks')
+}
+
+export function presentTaskListResult(_input: unknown, result: ToolResult): ToolResultView {
+	if (!result.success) return { kind: 'generic', label: 'The task list could not be read' }
+	const stats = (result.data as { stats?: { total?: unknown; completed?: unknown } } | undefined)
+		?.stats
+	const total = typeof stats?.total === 'number' ? stats.total : undefined
+	const completed = typeof stats?.completed === 'number' ? stats.completed : undefined
+	if (total === undefined || completed === undefined) return HIDDEN_RESULT
+	return {
+		kind: 'generic',
+		label: total === 0 ? 'No tasks yet' : `Tasks · ${completed}/${total} done`,
+	}
+}

package/src/tools/task/update.ts

@@ -3,6 +3,7 @@ import type { TaskStore } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { asTaskId } from '../../utils/id.js'
 import { defineTool } from '../defineTool.js'
+import { presentTaskUpdateCall, presentTaskUpdateResult } from './present.js'
 
 export function buildTaskUpdateTool(taskStore: TaskStore): ToolDefinition {
 	return defineTool({
@@ -34,6 +35,8 @@ export function buildTaskUpdateTool(taskStore: TaskStore): ToolDefinition {
 		readOnly: false,
 		destructive: false,
 		concurrencySafe: true,
+		presentCall: presentTaskUpdateCall,
+		presentResult: presentTaskUpdateResult,
 		async execute({
 			id,
 			subject,
@@ -85,7 +88,12 @@ export function buildTaskUpdateTool(taskStore: TaskStore): ToolDefinition {
 			return {
 				success: true,
 				output: `Task ${id} updated — status: ${updated.status}`,
-				data: { id: updated.id, status: updated.status, owner: updated.owner },
+				data: {
+					id: updated.id,
+					subject: updated.subject,
+					status: updated.status,
+					owner: updated.owner,
+				},
 			}
 		},
 	})

package/src/turn/reporter.ts

@@ -170,7 +170,7 @@ export function createTurnReporter(parentLogger?: Logger): TurnReporter {
 				break
 
 			case 'task_updated':
-				log.info('Task updated', {
+				log.info(event.deleted ? 'Task removed' : 'Task updated', {
 					'namzu.task.subject': event.subject,
 					[NAMZU.TURN_ID]: event.turnId,
 					'namzu.task.id': event.taskId,

package/src/types/agent/base.ts

@@ -293,6 +293,32 @@ export interface BaseAgentConfig {
 	 * host that never wired one is unaffected.
 	 */
 	resumeHandler?: ResumeHandler
+
+	/**
+	 * Whether a batch that needs no review still goes to `resumeHandler`, in
+	 * this agent's turn and in every turn it delegates to. See
+	 * {@link import('../../runtime/query/index.js').QueryParams.reviewAllowedCalls}.
+	 *
+	 * A delegated child borrows its parent's handler, and a handler that
+	 * refuses a change in a read-only mode (`plan`) cannot refuse a batch that
+	 * never reaches it: one a rule allows, or one an approval given earlier in
+	 * the CHILD's turn covers. So `AgentManager` stamps the spawning context's
+	 * function (`AgentTaskContext.reviewAllowedCalls`) onto the child config
+	 * after the builder returns, the same way it stamps the handler.
+	 *
+	 * Passed as a function and read once per batch, so a mode the operator
+	 * enters while a child is already running reaches that child's next batch.
+	 *
+	 * **It only ever adds review.** A value the child config sets itself (from
+	 * its `configBuilder` or `configOverrides`) is kept, and consulted together
+	 * with the inherited one: the child's batch goes to review when EITHER
+	 * says so. A child can ask for more review than its parent; it cannot
+	 * answer `false` over a parent that answers `true`.
+	 *
+	 * Absent, and nothing inherited: rule-allowed and grant-covered batches run
+	 * without asking, as they always have.
+	 */
+	reviewAllowedCalls?: () => boolean
 }
 
 export type RuntimeToolOverrides = Record<string, ToolAvailability | 'disabled'>

package/src/types/agent/task.ts

@@ -142,6 +142,21 @@ export interface AgentTaskContext {
 	 */
 	readonly childStorage?: ChildSessionStorage
 
+	/**
+	 * The parent's `reviewAllowedCalls`, handed to every child it delegates
+	 * to and on to theirs. See `BaseAgentConfig.reviewAllowedCalls`.
+	 *
+	 * The function itself, not a sampled value, so a stricter mode entered
+	 * while a child runs reaches that child's next batch. `AgentManager`
+	 * stamps it onto the child config after the builder runs and carries it
+	 * on the child's own context; a child config that sets its own keeps it,
+	 * and the two are OR-ed, so a descendant can add review and never shed
+	 * it. `SupervisorAgent` sets it from its config; a host that builds its
+	 * own context for a `TaskScheduler` sets it from the same function it
+	 * passes its own `query()`. Absent: children decide from their own config.
+	 */
+	readonly reviewAllowedCalls?: () => boolean
+
 	/** Isolation boundary. Required per session-hierarchy.md §12.1. */
 	tenantId: TenantId
 

package/src/types/session/events.ts

@@ -944,6 +944,14 @@ type CoreSessionEvent =
 			owner?: string
 			/** See `task_created`. Carried on updates because an edge can be added later. */
 			blockedBy?: readonly TaskId[]
+			/**
+			 * The task was removed from the list (`task_update` with status
+			 * `deleted`). `status` and `subject` are what it had when it went.
+			 * Absent on every other update: without it a removal reached a
+			 * reader as an update that changed nothing, so a checklist kept
+			 * drawing the task as open.
+			 */
+			deleted?: true
 	  }
 	| {
 			type: 'plugin_hook_executing'

package/src/utils/log/redact.ts

@@ -2,7 +2,7 @@
 //
 // Runs once, in the pipeline, ahead of sink dispatch — not inside
 // jsonLinesSink, and not inside any other individual sink. A scan that only
-// jsonLinesSink ran would leave prettySink (the one `namzu run` actually
+// jsonLinesSink ran would leave prettySink (the one `namzu exec` actually
 // uses) and every host-supplied sink with no second layer at all, which is
 // the gap a scoped-to-one-sink design would reintroduce: the machine-read
 // path would be the only protected one.

package/src/utils/log/sinks.ts

@@ -19,7 +19,7 @@ export const NOOP_SINK: LogSink = {
 
 /**
  * One JSON object per line — the canonical wire format for the machine-read
- * path (`namzu run-stream`'s stderr). JSON string-escaping neutralises
+ * path (`namzu exec --json`'s stderr). JSON string-escaping neutralises
  * `\n`/`\r` by construction, closing the log-forging surface without a
  * single character-stripping call site, which is bypassable anyway.
  *
@@ -67,7 +67,7 @@ const SEVERITY_LABEL: Record<LogRecord['severityText'], string> = {
 // guarantee yet that either is a constant (that lands with the CI gate in
 // later work) — a remote MCP server that names itself an escape sequence
 // erasing the previous line and printing a fake refusal is a real forging
-// attempt against the terminal `namzu run` writes to today, not a
+// attempt against the terminal `namzu exec` writes to today, not a
 // hypothetical one.
 // biome-ignore lint/suspicious/noControlCharactersInRegex: this pattern IS the control-character filter — the escapes below are ASCII text (`\x00`-`\x1F`, `\x7F`), not raw bytes pasted into the source.
 const CONTROL_BYTE = /[\x00-\x1F\x7F]/g