@namzu/sdk 51.1.0 → 52.1.0

package/src/runtime/query/review-policy.ts

@@ -228,6 +228,26 @@ export const REQUIRES_APPROVAL_UNATTENDED_REFUSAL =
 export const UNKNOWN_PROGRAM_UNATTENDED_REFUSAL =
 	'Refused: a call in this batch runs a command whose own program name is decided at runtime (a substitution or a variable stands for it), which needs a person to approve it each time, and nobody can be asked in this session. Nothing in this batch ran. Write the program name literally; compute what needs computing in the arguments instead.'
 
+/**
+ * What the model is told when a batch writes a protected path (a git hook, a
+ * shell rc file, editor or tool configuration, the project's `.namzu`
+ * directory) and nobody can be asked.
+ *
+ * Refused in every mode, `auto` included: a write there runs later, outside
+ * the turn, with the operator's rights, so an answer given before the call
+ * existed (a mode, a rule, "approve all") is not an answer about it.
+ */
+export const PROTECTED_PATH_UNATTENDED_REFUSAL =
+	"Refused: a call in this batch writes a protected path (a git hook or config, a shell startup file, editor or tool configuration, or the project's .namzu directory), which needs a person to approve it each time, and nobody can be asked in this session. Nothing in this batch ran. Leave those files alone, or tell the user what change you need so they can make it."
+
+/**
+ * What the model is told when a batch removes something catastrophic (the
+ * root, the home directory, the working directory or a parent of it, a glob
+ * across directories, a target a variable may empty) and nobody can be asked.
+ */
+export const DANGEROUS_REMOVAL_UNATTENDED_REFUSAL =
+	'Refused: a call in this batch removes something this check treats as catastrophic (the file system root, a top-level or home directory, the working directory or a parent of it, a glob across directories, or a target a variable or substitution may leave empty), which needs a person to approve it each time, and nobody can be asked in this session. Nothing in this batch ran. Name the exact directory to remove with a literal path.'
+
 /**
  * What the model is told when a batch would show it the operator's screen for
  * the first time in a session and nobody can be asked.
@@ -250,6 +270,21 @@ export interface ScreenConsentRecord {
 	readonly sessions: Set<string>
 }
 
+/** Whether the call writes a protected path or removes something catastrophic. */
+function reachesAFloor(tc: ToolCallSummary): boolean {
+	return (
+		(tc.escalation?.protectedPaths?.length ?? 0) > 0 ||
+		tc.escalation?.dangerousRemoval !== undefined
+	)
+}
+
+/** The refusal for a batch that reaches a floor and cannot be asked about it. */
+function floorRefusal(toolCalls: readonly ToolCallSummary[]): string {
+	return toolCalls.some((tc) => (tc.escalation?.protectedPaths?.length ?? 0) > 0)
+		? PROTECTED_PATH_UNATTENDED_REFUSAL
+		: DANGEROUS_REMOVAL_UNATTENDED_REFUSAL
+}
+
 /** The batch a person is asked about. */
 export interface ToolReviewRequest {
 	/** Originating session, preserved by createReviewHandler for host attribution. */
@@ -339,6 +374,16 @@ export interface ReviewPolicyOptions {
 	 * `capturesScreen` declaration, read from `registry`; nothing without one.
 	 */
 	readonly capturesScreen?: (name: string, input: unknown) => boolean
+	/**
+	 * The one write `plan` mode lets through: a host that gives plan mode a plan
+	 * file says here which call writes it. In `plan`, a call this accepts is not
+	 * a change — it is neither refused nor asked about — unless a rule asked to
+	 * review it, in which case it is put to the person like a read outside the
+	 * roots. Every other write stays refused. Omitted (the default), `plan`
+	 * refuses every change, as it always has; the option does nothing in any
+	 * other mode.
+	 */
+	readonly planModeWrite?: (call: ToolCallSummary) => boolean
 }
 
 /**
@@ -358,6 +403,23 @@ function isSkillGranted(tc: ToolCallSummary): boolean {
 	)
 }
 
+/**
+ * Whether a `pre_tool_use` hook's `allow` may stand in for a person on this
+ * call. The same bar as a skill's grant, repeated here so that a mark on a
+ * persisted or host-built summary cannot carry more than the kernel gave it.
+ */
+function isHookGranted(tc: ToolCallSummary): boolean {
+	return (
+		tc.hookGrant !== undefined &&
+		tc.hookPermission?.decision !== 'ask' &&
+		!tc.authorization?.explicitReview &&
+		tc.authorization?.decision !== 'deny' &&
+		!tc.isDestructive &&
+		tc.escalation === undefined &&
+		tc.requiresApproval !== true
+	)
+}
+
 /** The handler behind `createReviewPolicy`, for a host that wants only the function. */
 export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHandler {
 	const { prompt, registry } = options
@@ -422,7 +484,16 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 			if (answer.kind === 'approve-all') remembered.all = true
 			answered = answer
 		}
-		if (!batchNeedsReview(request.toolCalls, exempt)) {
+		// The plan file, in `plan`: the one write that is not a change. A rule
+		// that asked for review keeps the call in the batch, so it is asked.
+		const isPlanFileWrite = (tc: ToolCallSummary): boolean =>
+			mode === 'plan' &&
+			options.planModeWrite?.(tc) === true &&
+			tc.authorization?.decision !== 'deny'
+		const reviewable = request.toolCalls.filter(
+			(tc) => !(isPlanFileWrite(tc) && !tc.authorization?.explicitReview),
+		)
+		if (!batchNeedsReview(reviewable, exempt)) {
 			return { action: 'approve_tools' }
 		}
 		// A batch of nothing but non-destructive file edits is the case
@@ -450,7 +521,13 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 		// to do, and the question such a path gets is the same in every mode that
 		// lets reads run. It goes on to that question below; `strict` still
 		// refuses it, since no rule can approve a path outside the roots.
-		if (mode === 'plan' && !onlyReadsOutsideRoots(request.toolCalls, exempt)) {
+		if (
+			mode === 'plan' &&
+			!onlyReadsOutsideRoots(
+				reviewable.filter((tc) => !isPlanFileWrite(tc)),
+				exempt,
+			)
+		) {
 			return { action: 'reject_tools', feedback: PLAN_MODE_REFUSAL }
 		}
 		if (mode === 'strict') return { action: 'reject_tools', feedback: STRICT_MODE_REFUSAL }
@@ -471,6 +548,9 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 				// This opt-in confirms only the sandbox escape. A different call in
 				// the batch, or another boundary on this same call, still needs a
 				// person; the early return must not approve that boundary too.
+				if (request.toolCalls.some(reachesAFloor)) {
+					return { action: 'reject_tools', feedback: floorRefusal(request.toolCalls) }
+				}
 				if (request.toolCalls.some((tc) => (tc.escalation?.outsidePaths?.length ?? 0) > 0)) {
 					return { action: 'reject_tools', feedback: OUTSIDE_ROOTS_UNATTENDED_REFUSAL }
 				}
@@ -495,6 +575,24 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 			if (answer.kind === 'approve-all') remembered.all = true
 			return { action: 'approve_tools', confirmedEscalations: escapes }
 		}
+		// A write to a protected path, or a removal of something catastrophic,
+		// is a question for a person, every time, in every mode that got this
+		// far: `auto` and a remembered "approve all" were answers given before
+		// the call existed. With nobody to ask it is refused, not approved.
+		if (request.toolCalls.some(reachesAFloor)) {
+			if (!prompt) return { action: 'reject_tools', feedback: floorRefusal(request.toolCalls) }
+			const answer = await ask()
+			if (answer.kind === 'reject') {
+				return {
+					action: 'reject_tools',
+					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
+					...(answer.declined ? { declined: answer.declined } : {}),
+				}
+			}
+			// Latches for the ordinary calls that follow, never for the next floor.
+			if (answer.kind === 'approve-all') remembered.all = true
+			return { action: 'approve_tools' }
+		}
 		// A path outside the roots is a question for a person, every time,
 		// like an escape: `auto` and a remembered "approve all" were answers
 		// given about tools, before this path was named, and neither saw it.
@@ -571,15 +669,18 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 					(mode === 'accept-edits' && ACCEPT_EDITS_TOOLS.has(tc.name))
 				),
 		)
+		const skillsHonoured = options.skillGrants !== 'ignore'
 		if (
 			answered === undefined &&
-			options.skillGrants !== 'ignore' &&
 			needsPerson.length > 0 &&
-			needsPerson.every(isSkillGranted)
+			needsPerson.every((tc) => isHookGranted(tc) || (skillsHonoured && isSkillGranted(tc)))
 		) {
+			const byHook = needsPerson.filter(isHookGranted).map((tc) => tc.id)
+			const bySkill = needsPerson.filter((tc) => !isHookGranted(tc)).map((tc) => tc.id)
 			return {
 				action: 'approve_tools',
-				skillGranted: needsPerson.map((tc) => tc.id),
+				...(bySkill.length > 0 ? { skillGranted: bySkill } : {}),
+				...(byHook.length > 0 ? { hookGranted: byHook } : {}),
 			}
 		}
 		const answer = await ask()

package/src/runtime/query/tool-output-budget.ts

@@ -18,6 +18,19 @@ import { digest, spillManifest } from '../../store/evidence/format.js'
  */
 export const DEFAULT_MAX_TOOL_OUTPUT_CHARS = 40_000
 
+/**
+ * Cap on the COMBINED model-visible text of every tool result one assistant
+ * message produced.
+ *
+ * The per-result cap alone lets eight parallel calls put 320,000 characters in
+ * front of the model at once. This is the bound on the whole batch; see
+ * {@link fitResultsToMessageBudget}.
+ */
+export const DEFAULT_MAX_TOOL_OUTPUT_CHARS_PER_MESSAGE = 200_000
+
+/** Size of the preview that stands in for a result replaced to fit the message budget. */
+export const MESSAGE_BUDGET_PREVIEW_CHARS = 2_000
+
 /**
  * Opening of the line that points at a spilled output.
  *
@@ -298,7 +311,10 @@ function spill(
 		writeFileSync(path, bytes, { flag: 'wx', mode: 0o600 })
 		try {
 			const manifest = spillManifest(bytes)
-			writeFileSync(`${path}.manifest.json`, manifest, { flag: 'wx', mode: 0o600 })
+			writeFileSync(`${path}.manifest.json`, manifest, {
+				flag: 'wx',
+				mode: 0o600,
+			})
 			return { path, integrity: digest(manifest) }
 		} catch {
 			onError?.('The full output was retained, but its integrity manifest could not be written.')
@@ -324,3 +340,101 @@ function spill(
 		return undefined
 	}
 }
+
+export interface MessageBudgetItem {
+	readonly toolCallId: string
+	readonly toolName: string
+	readonly output: string
+	/** False for a result that must stay as the tool produced it. */
+	readonly replaceable: boolean
+}
+
+export interface MessageBudgetReplacement {
+	readonly output: string
+	readonly originalLength: number
+	readonly spillPath?: string
+}
+
+export interface FitResultsToMessageBudgetOptions {
+	readonly maxChars: number
+	readonly spillDir?: string | undefined
+	readonly onError?: (message: string) => void
+}
+
+const SPILL_LINE = new RegExp(`^${SPILL_MARKER} .+$`, 'm')
+
+/**
+ * Hold one assistant message's combined tool results under a cap.
+ *
+ * Replaceable results are replaced largest first, each by a short preview that
+ * names where its full text is kept, until the total is within `maxChars`. A
+ * result already spilled keeps the path it was given; one that was not is
+ * spilled now. Results that are not replaceable are left alone and are not
+ * counted, because nothing here could reduce them.
+ *
+ * The caller writes the replacement into the result BEFORE the result reaches
+ * the history. From then on it is just the message's content, so it is the
+ * same on every later request and a prompt-cache prefix over it stays valid;
+ * nothing is decided again on a later turn.
+ *
+ * Returns only the results that changed, keyed by `toolCallId`. Ties keep the
+ * earlier call, so the same batch always yields the same replacements.
+ */
+export function fitResultsToMessageBudget(
+	items: readonly MessageBudgetItem[],
+	opts: FitResultsToMessageBudgetOptions,
+): Map<string, MessageBudgetReplacement> {
+	const replaced = new Map<string, MessageBudgetReplacement>()
+	if (!Number.isFinite(opts.maxChars) || opts.maxChars <= 0) return replaced
+
+	const candidates = items.filter((item) => item.replaceable)
+	let total = candidates.reduce((sum, item) => sum + item.output.length, 0)
+	if (total <= opts.maxChars) return replaced
+
+	const bySize = candidates
+		.map((item, index) => ({ item, index }))
+		.sort((a, b) => b.item.output.length - a.item.output.length || a.index - b.index)
+
+	for (const { item } of bySize) {
+		if (total <= opts.maxChars) break
+		const replacement = previewForMessageBudget(item, opts)
+		if (replacement.output.length >= item.output.length) continue
+		total -= item.output.length - replacement.output.length
+		replaced.set(item.toolCallId, replacement)
+	}
+	return replaced
+}
+
+function previewForMessageBudget(
+	item: MessageBudgetItem,
+	opts: FitResultsToMessageBudgetOptions,
+): MessageBudgetReplacement {
+	const spilledAt = SPILL_LINE.exec(item.output)?.[0]
+	if (spilledAt !== undefined) {
+		const output = [
+			safeHead(item.output, MESSAGE_BUDGET_PREVIEW_CHARS / 2),
+			'',
+			`[... omitted: this message's tool results together were over the ${opts.maxChars.toLocaleString()}-character budget ...]`,
+			spilledAt,
+		].join('\n')
+		return {
+			output,
+			originalLength: item.output.length,
+			spillPath: spilledAt.slice(SPILL_MARKER.length + 1),
+		}
+	}
+	const budgeted = applyToolOutputBudget({
+		toolName: item.toolName,
+		// A distinct name: the spill file is keyed by it and opened exclusively.
+		toolUseId: `${item.toolCallId}:message-budget`,
+		output: item.output,
+		maxChars: MESSAGE_BUDGET_PREVIEW_CHARS,
+		spillDir: opts.spillDir,
+		...(opts.onError ? { onError: opts.onError } : {}),
+	})
+	return {
+		output: budgeted.output,
+		originalLength: item.output.length,
+		...(budgeted.spillPath ? { spillPath: budgeted.spillPath } : {}),
+	}
+}

package/src/runtime/query/tooling.ts

@@ -54,6 +54,7 @@ export interface ToolingBootstrapConfig {
 	maxToolCalls?: number
 	readToolCallBudgetRecords?: () => Promise<readonly SessionRecord[]>
 	maxToolOutputChars?: number
+	maxToolOutputCharsPerMessage?: number
 	/** See `QueryParams.toolResultGuardrails`. Absent installs the shipped default; a registry's own win. */
 	toolResultGuardrails?: readonly import('../../types/guardrail/index.js').ToolResultGuardrailSpec[]
 	retainedToolPreviewChars?: number
@@ -119,6 +120,11 @@ export class ToolingBootstrap {
 				...(config.maxToolOutputChars !== undefined
 					? { maxToolOutputChars: config.maxToolOutputChars }
 					: {}),
+				...(config.maxToolOutputCharsPerMessage !== undefined
+					? {
+							maxToolOutputCharsPerMessage: config.maxToolOutputCharsPerMessage,
+						}
+					: {}),
 				...(config.toolResultGuardrails !== undefined
 					? { toolResultGuardrails: config.toolResultGuardrails }
 					: {}),

package/src/session/paths.ts

@@ -28,7 +28,7 @@ import { uuidv7 } from '../utils/uuidv7.js'
  *     <session-id>.jsonl             the session log (source of truth)
  *     <session-id>/
  *       subagents/<child-id>.jsonl, <child-id>.meta.json, <child-id>/subagents/…
- *       tool-results/  checkpoints/  budgets/  tasks/  feedback/  goals/
+ *       tool-results/  checkpoints/  budgets/  tasks/  plans/  feedback/  goals/
  *       file-history/  lease.json
  * $TMPDIR/namzu-<user>/<slug>/<session-id>/scratchpad/
  * ```
@@ -412,6 +412,16 @@ export class SessionPaths {
 		return join(this.sessionDir(locator), 'tasks')
 	}
 
+	/** The session's plan directory; a host that has a plan mode keeps its one plan file here. */
+	plans(locator: SessionLocator): string {
+		return join(this.sessionDir(locator), 'plans')
+	}
+
+	/** The one file a session's plan mode may write: `<session-id>/plans/plan.md`. */
+	planFile(locator: SessionLocator): string {
+		return join(this.plans(locator), 'plan.md')
+	}
+
 	taskFile(locator: SessionLocator, taskId: TaskId): string {
 		return join(this.tasks(locator), `${checkId(taskId, 'task')}.json`)
 	}

package/src/store/memory/disk.ts

@@ -23,6 +23,7 @@ import { InMemoryMemoryIndex, searchMemoryEntries, selectMemorySearchCandidates
 import {
 	MemoryNameConflictError,
 	assertOptionalMemoryFields,
+	entryPath,
 	isMemoryName,
 	nameHolder,
 	withOptionalFields,
@@ -228,7 +229,7 @@ export class DiskMemoryStore implements ConditionalMemoryStore {
 
 	private contentPath(location: StorageLocation, id: MemoryId): string {
 		assertStorageMemoryId(id, (reason) => invalidContent(id, reason, { field: 'id' }))
-		const path = resolve(location.contentDir, `${id}.json`)
+		const path = resolve(entryPath(location.contentDir, id, '.json'))
 		if (dirname(path) !== location.contentDir) {
 			invalidContent(id, 'resolved path escapes the content directory', { field: 'id' })
 		}

package/src/store/memory/markdown.ts

@@ -38,6 +38,7 @@ import {
 	MemoryContentRejectedError,
 	MemoryNameConflictError,
 	assertOptionalMemoryFields,
+	entryPath,
 	isMemoryName,
 	nameHolder,
 	slugifyMemoryName,
@@ -327,7 +328,7 @@ export class MarkdownMemoryStore implements ConditionalMemoryStore {
 
 	private memoryPath(dir: string, name: string): string {
 		if (!isMemoryName(name)) invalidFile(join(dir, `${name}.md`), 'name is not a memory name')
-		const path = resolve(dir, `${name}.md`)
+		const path = resolve(entryPath(dir, name, '.md'))
 		if (dirname(path) !== dir) invalidFile(path, 'resolved path escapes the memory directory')
 		return path
 	}

package/src/store/memory/naming.ts

@@ -1,3 +1,4 @@
+import { sep } from 'node:path'
 import { NamzuError } from '../../types/errors/index.js'
 import type { MemoryId } from '../../types/ids/index.js'
 import type {
@@ -193,3 +194,15 @@ export function withOptionalFields(
 		...(type !== undefined ? { type } : {}),
 	}
 }
+
+/**
+ * The path of one entry file: `dir`, a separator, `stem`, `extension`, before
+ * the caller resolves it. Written as plain concatenation on purpose. A static
+ * file tracer (the kind standalone-output builds use) evaluates
+ * `path.resolve(dir, `${stem}.ext`)` with an unknown `dir` as a wildcard and
+ * lists every `.ext` file under the repository as a runtime asset; it does not
+ * evaluate string concatenation, so this form leaves it nothing to expand.
+ */
+export function entryPath(dir: string, stem: string, extension: string): string {
+	return dir + sep + stem + extension
+}