@namzu/sdk 51.1.0 → 52.0.0

package/src/runtime/query/path-escalation.ts

@@ -0,0 +1,204 @@
+/**
+ * What a call writes or removes that no mode may approve in advance.
+ *
+ * Three questions the kernel answers about a prepared call before it runs, all
+ * of them about the call's own arguments and none about the model's intent:
+ *
+ * - does it write a protected path (a git hook, a shell rc file, editor or
+ *   tool configuration, the project's `.namzu` directory)?
+ * - does its shell line remove something catastrophic?
+ * - does its shell line reach a path outside the turn's roots, through a
+ *   command whose operands are paths or through a redirection?
+ *
+ * The first two are floors: they hold in every mode, the way a sandbox escape
+ * does. The third is the existing outside-root boundary, extended from the
+ * file tools' one declared argument to the paths a shell line names.
+ */
+
+import { homedir } from 'node:os'
+import { isAbsolute, relative, resolve } from 'node:path'
+
+import { isProtectedPath } from '../../authorization/protected-paths.js'
+import { dangerousRemoval } from '../../authorization/removal.js'
+import type { ShellDialect } from '../../authorization/shell-lexer.js'
+import { readShellLine, shellPathAccess } from '../../authorization/shell-paths.js'
+import { canonicalize, pathOutsideRoots } from '../../tools/paths.js'
+
+/** What the escalation records carry. */
+export interface PathEscalations {
+	readonly outsidePaths: readonly string[]
+	readonly protectedPaths: readonly string[]
+	readonly dangerousRemoval?: string
+}
+
+export interface PathEscalationContext {
+	/** The working directory first, then the added directories. */
+	readonly roots: readonly string[]
+	/** Whether to report paths outside the roots (`outsideRootAccess: 'review'`, no sandbox). */
+	readonly reviewOutside: boolean
+}
+
+/**
+ * The part of `absolute` that protected names are looked for in.
+ *
+ * Inside a root (the working directory or an added directory) that is the part
+ * below the root, not the whole path: the root is where the turn was put, and
+ * a root that itself sits under a protected name is not a reason to ask about
+ * every file in it. The case that matters is the managed worktree a sub-agent
+ * runs in, `~/.namzu/projects/<slug>/worktrees/<name>`, which lies under
+ * `.namzu` by construction; the reference terminal makes the same exception
+ * for its own worktrees directory. A path in no root is looked at whole.
+ */
+function protectedScope(absolute: string, roots: readonly string[]): string {
+	let best: string | undefined
+	for (const root of roots) {
+		const base = resolve(root)
+		const below = relative(base, absolute)
+		if (below === '' || below.startsWith('..') || isAbsolute(below)) continue
+		if (best === undefined || below.length < best.length) best = below
+	}
+	return best ?? absolute
+}
+
+/** A write is protected when its spelling, or the place a link leads to, is. */
+async function isProtectedWrite(
+	spelled: string,
+	absolute: string,
+	roots: readonly string[],
+): Promise<boolean> {
+	if (isProtectedPath(isAbsolute(spelled) ? protectedScope(absolute, roots) : spelled)) return true
+	if (isProtectedPath(protectedScope(absolute, roots))) return true
+	const real = await canonicalize(absolute)
+	const realRoots = await Promise.all(roots.map((root) => canonicalize(resolve(root))))
+	return isProtectedPath(protectedScope(real, [...roots, ...realRoots]))
+}
+
+/** `{a,b}` with plain comma lists, one level at a time, bounded. */
+export function expandBraces(value: string, limit = 16): string[] {
+	const open = value.indexOf('{')
+	if (open < 0) return [value]
+	let depth = 0
+	let close = -1
+	const commas: number[] = []
+	for (let i = open; i < value.length; i += 1) {
+		const c = value[i]
+		if (c === '{') depth += 1
+		else if (c === '}') {
+			depth -= 1
+			if (depth === 0) {
+				close = i
+				break
+			}
+		} else if (c === ',' && depth === 1) commas.push(i)
+	}
+	if (close < 0 || commas.length === 0) return [value]
+	const head = value.slice(0, open)
+	const tail = value.slice(close + 1)
+	const parts: string[] = []
+	let start = open + 1
+	for (const comma of [...commas, close]) {
+		parts.push(value.slice(start, comma))
+		start = comma + 1
+	}
+	const out: string[] = []
+	for (const part of parts) {
+		for (const rest of expandBraces(head + part + tail, limit)) {
+			out.push(rest)
+			if (out.length >= limit) return out
+		}
+	}
+	return out
+}
+
+/** The path a use names with `~` and `$HOME` read as the home directory, or why it cannot be. */
+function settle(
+	value: string,
+	home: string,
+): { readonly path: string } | { readonly unresolved: true } {
+	if (value === '~') return { path: home }
+	if (value.startsWith('~/')) return { path: resolve(home, value.slice(2)) }
+	if (value.startsWith('~')) return { unresolved: true }
+	const variable = /^\$(?:\{HOME\}|HOME)(?=\/|$)/.exec(value)
+	if (variable !== null) return { path: resolve(home, `.${value.slice(variable[0].length)}`) }
+	if (/[$`]/.test(value)) return { unresolved: true }
+	return { path: value }
+}
+
+/** The part of a glob path before the first segment that holds a glob character. */
+function beforeGlob(path: string): string {
+	const at = path.search(/[*?[]/)
+	if (at < 0) return path
+	const cut = path.lastIndexOf('/', at)
+	return cut <= 0 ? '/' : path.slice(0, cut)
+}
+
+/** A write the file tool's own declared path argument names. */
+export async function declaredWriteEscalation(
+	roots: readonly string[],
+	value: string,
+): Promise<string | undefined> {
+	const [first] = roots
+	if (first === undefined || value === '') return undefined
+	const absolute = resolve(resolve(first), value)
+	return (await isProtectedWrite(value, absolute, roots)) ? absolute : undefined
+}
+
+/** What a shell line reaches. */
+export async function shellEscalations(
+	line: string,
+	dialect: ShellDialect,
+	context: PathEscalationContext,
+): Promise<PathEscalations> {
+	const reading = readShellLine(line, dialect)
+	const access = shellPathAccess(reading)
+	const [cwd, ...added] = context.roots
+	const outside = new Set<string>()
+	const protectedPaths = new Set<string>()
+	const home = homedir()
+	if (cwd !== undefined) {
+		for (const use of access.uses) {
+			for (const spelled of expandBraces(use.path)) {
+				const settled = settle(spelled, home)
+				const unresolved = use.unresolved || 'unresolved' in settled
+				const base = 'path' in settled ? settled.path : spelled
+				const absolute = isAbsolute(base) ? resolve(base) : resolve(cwd, base)
+				if (use.access === 'write' && (await isProtectedWrite(spelled, absolute, context.roots))) {
+					protectedPaths.add(absolute)
+				}
+				if (!context.reviewOutside) continue
+				if (unresolved) {
+					// A write whose target is decided at runtime cannot be checked; a
+					// read of one is left, as the reference leaves it.
+					if (use.access === 'write') outside.add(spelled)
+					continue
+				}
+				if (
+					access.changesDirectory &&
+					use.access === 'write' &&
+					!isAbsolute(base) &&
+					!spelled.startsWith('~')
+				) {
+					// A `cd` earlier in the line moves a relative target somewhere the
+					// roots cannot be compared with.
+					outside.add(spelled)
+					continue
+				}
+				const reached = await pathOutsideRoots(context.roots, beforeGlob(absolute))
+				if (reached !== undefined) outside.add(reached)
+			}
+		}
+	}
+	const removal =
+		cwd === undefined
+			? undefined
+			: dangerousRemoval(reading, access.changesDirectory, {
+					cwd,
+					additionalDirectories: added,
+					home,
+				})
+	return {
+		outsidePaths: [...outside],
+		protectedPaths: [...protectedPaths],
+		...(removal !== undefined ? { dangerousRemoval: removal } : {}),
+	}
+}

package/src/runtime/query/plugin-hooks.ts

@@ -27,6 +27,14 @@ export function applyLifecycleHookResults(
 				if (result.text.trim().length > 0) annotations.push(result.text.trim())
 				continue
 			case 'skip':
+				// `turn_end`, `subagent_stop` and `pre_compact` answer with `skip`
+				// to keep the turn going or to cancel a pass. The sites that can act
+				// on that read the results themselves; a site that cannot (the
+				// final `turn_end` of a turn that already ended) has nothing to
+				// refuse and carries on.
+				if (event === 'turn_end' || event === 'subagent_stop' || event === 'pre_compact') {
+					continue
+				}
 				// The one lifecycle event with a verdict: a hook may refuse the
 				// prompt before the model sees it, and the turn ends there.
 				if (event === 'user_prompt_submit') {

package/src/runtime/query/reminders.ts

@@ -0,0 +1,45 @@
+import type { SessionId, TurnId } from '../../types/ids/index.js'
+import type { Message } from '../../types/message/index.js'
+
+/**
+ * What a reminder source is told when the kernel asks it for hidden reminders.
+ */
+export interface ReminderContext {
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	/** The model request about to be made; 1 for the first of the turn. */
+	readonly iteration: number
+	/**
+	 * The conversation as it stands, reminders included. Read-only: a source
+	 * derives its cadence from this (how many assistant turns since it last
+	 * spoke), so a resumed or compacted conversation needs no counter of its own.
+	 */
+	readonly messages: readonly Message[]
+}
+
+/**
+ * A host's hidden reminders for the next model request.
+ *
+ * The kernel calls it once at the start of every model request of a turn
+ * (never the closing one) and appends each returned text to the conversation
+ * as a user-role message with provenance `{ type: 'runtime-context', kind:
+ * 'reminder' }`. The message is part of the durable history, so it is not
+ * operator input, never counts as the latest user request, and is not shown as
+ * something the operator typed. The channel is opt-in
+ * (`QueryParams.reminders`): a turn without a source behaves as before.
+ *
+ * A source that throws is treated as having nothing to say; a reminder is
+ * context, and a fault in one must not end a turn.
+ */
+export type ReminderSource = (
+	context: ReminderContext,
+) => readonly string[] | undefined | Promise<readonly string[] | undefined>
+
+/** Whether a message is a reminder the kernel appended for a {@link ReminderSource}. */
+export function isReminderMessage(message: Message): boolean {
+	return (
+		message.role === 'user' &&
+		message.source?.type === 'runtime-context' &&
+		message.source.kind === 'reminder'
+	)
+}

package/src/runtime/query/resume-pending.ts

@@ -517,6 +517,24 @@ export async function applyPendingResume(
 				reason: "the turn's review approved this call, answered across a restart",
 			})
 		}
+		for (const path of call.escalation?.protectedPaths ?? []) {
+			await recorder.recordAudit({
+				what: { action: 'protected_path_write', tool: call.name, resource: path },
+				outcome: 'approved',
+				reason: "the turn's review approved this call, answered across a restart",
+			})
+		}
+		if (call.escalation?.dangerousRemoval !== undefined) {
+			await recorder.recordAudit({
+				what: {
+					action: 'dangerous_removal',
+					tool: call.name,
+					resource: call.escalation.dangerousRemoval,
+				},
+				outcome: 'approved',
+				reason: "the turn's review approved this call, answered across a restart",
+			})
+		}
 	}
 
 	// The parked assistant message is already in the log: it goes back into
@@ -562,6 +580,15 @@ export function escalationRefusal(
 	for (const path of escalation.outsidePaths ?? []) {
 		if (!shown?.outsidePaths?.includes(path)) return refusal
 	}
+	for (const path of escalation.protectedPaths ?? []) {
+		if (!shown?.protectedPaths?.includes(path)) return refusal
+	}
+	if (
+		escalation.dangerousRemoval !== undefined &&
+		shown?.dangerousRemoval !== escalation.dangerousRemoval
+	) {
+		return refusal
+	}
 	if (escalation.sandboxEscape && (!shown?.sandboxEscape || !confirmed?.includes(id))) {
 		return 'Refused after resume: running this command outside the sandbox needs a person to confirm it for this call, and the durable approval did not.'
 	}

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' })
 		}