@namzu/sdk 57.1.0 → 58.1.0

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

@@ -34,6 +34,8 @@ export interface PathEscalations {
 export interface PathEscalationContext {
 	/** The working directory first, then the added directories. */
 	readonly roots: readonly string[]
+	/** Actual shell start directory; roots remain the original authorization boundary. */
+	readonly cwd?: string
 	/** Whether to report paths outside the roots (`outsideRootAccess: 'review'`, no sandbox). */
 	readonly reviewOutside: boolean
 }
@@ -150,7 +152,7 @@ export async function shellEscalations(
 ): Promise<PathEscalations> {
 	const reading = readShellLine(line, dialect)
 	const access = shellPathAccess(reading)
-	const [cwd, ...added] = context.roots
+	const cwd = context.cwd ?? context.roots[0]
 	const outside = new Set<string>()
 	const protectedPaths = new Set<string>()
 	const home = homedir()
@@ -222,14 +224,18 @@ export async function shellEscalations(
 			}
 		}
 	}
-	const removal =
-		cwd === undefined
+	const removalAt = (directory: string | undefined) =>
+		directory === undefined
 			? undefined
 			: dangerousRemoval(reading, access.changesDirectory, {
-					cwd,
-					additionalDirectories: added,
+					cwd: directory,
+					additionalDirectories: context.roots,
 					home,
 				})
+	// Moving into an added directory must not make removal of the original
+	// working directory cease to be catastrophic. Keep both conservative floors.
+	const removal =
+		removalAt(cwd) ?? (cwd !== context.roots[0] ? removalAt(context.roots[0]) : undefined)
 	return {
 		outsidePaths: [...outside],
 		protectedPaths: [...protectedPaths],

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

@@ -19,9 +19,9 @@ export function applyLifecycleHookResults(
 			case 'continue':
 				continue
 			case 'annotate':
-				if (event !== 'user_prompt_submit') {
+				if (event !== 'user_prompt_submit' && event !== 'subagent_start') {
 					throw new Error(
-						`Plugin hook ${event} returned 'annotate', which only user_prompt_submit accepts`,
+						`Plugin hook ${event} returned 'annotate', which only user_prompt_submit and subagent_start accept`,
 					)
 				}
 				if (result.text.trim().length > 0) annotations.push(result.text.trim())

package/src/runtime/query/prepare-turn.ts

@@ -89,6 +89,8 @@ export interface PreparedTurn {
 	readonly approvalPolicy: SessionApprovalPolicy
 	readonly eventTranslator: EventTranslator
 	readonly executeUserInterruptHooks: (terminalError: unknown) => Promise<void>
+	/** Tell `turn_failure` hooks the root turn failed; never throws, never fires for a cancellation. */
+	readonly executeTurnFailureHooks: (terminalError: unknown) => Promise<void>
 	/**
 	 * Repair reports this turn owes its log.
 	 *
@@ -823,6 +825,36 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 			}
 		}
 
+		const executeTurnFailureHooks = async (terminalError: unknown): Promise<void> => {
+			// A cancellation is the operator's own act, a child's failure reaches its
+			// parent as a tool result, and the turn is already failed: this is a
+			// notice, so nothing it does may change how the turn settles.
+			if (
+				!params.pluginManager ||
+				params.parentSessionId !== undefined ||
+				ctx.abortController.signal.aborted ||
+				isCallerAbortError(terminalError, ctx.abortController.signal)
+			) {
+				return
+			}
+			try {
+				await params.pluginManager.executeHooks(
+					'turn_failure',
+					{
+						sessionId: ctx.sessionId,
+						turnId: ctx.turnId,
+						error: toErrorMessage(terminalError),
+					},
+					eventTranslator.emitEvent,
+				)
+			} catch (error) {
+				ctx.log.error('Turn failure hooks did not settle cleanly', {
+					[NAMZU.TURN_ID]: ctx.turnId,
+					...errorAttributes(error),
+				})
+			}
+		}
+
 		return {
 			turnConfig,
 			budget,
@@ -836,6 +868,7 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 			approvalPolicy,
 			eventTranslator,
 			executeUserInterruptHooks,
+			executeTurnFailureHooks,
 			pendingHistoryRepairs,
 			initialMessages,
 			historyIds,

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

@@ -28,6 +28,8 @@ import {
 	readShellLine,
 	shellPathAccess,
 } from '../../authorization/shell-paths.js'
+import { effectiveBashWorkingDirectory } from '../../tools/builtins/bash-cwd.js'
+import { BashTool } from '../../tools/builtins/bash.js'
 import { isTrustedReadOnly } from '../../tools/trusted-read-only.js'
 import type { ToolManager } from '../../toolsets/manager.js'
 import type {
@@ -83,10 +85,11 @@ export type ReviewMode =
 	 *
 	 * Where `auto` approves what remains after the questions a person must
 	 * answer (a path outside the roots, a program nobody can name, a protected
-	 * write), `bypass` also approves those. It still asks, or refuses when
+	 * write), `bypass` approves outside paths and unknown programs but not protected
+	 * writes. It still asks, or refuses when
 	 * nobody can be asked: a `deny` rule (the gate refuses before this is
 	 * reached), an `ask` rule or a hook that asked for a person, a catastrophic
-	 * removal, a tool's own `requiresApproval`, a sandbox escape, and a call
+	 * removal, a protected write, a tool's own `requiresApproval`, a sandbox escape, and a call
 	 * whose safety checks did not finish. The dangerous-pattern floor refuses in
 	 * the gate, unchanged. With nobody to ask, whatever would have been asked is
 	 * refused.
@@ -571,14 +574,15 @@ function isPermissive(mode: ReviewMode): boolean {
 
 /**
  * Whether the call is one of the few no mode may settle in advance: a rule or
- * hook asked for a person, a sandbox escape, a catastrophic removal, a check
- * that did not finish, or a tool that always needs approval. The dangerous
+ * hook asked for a person, a sandbox escape, a protected write, a catastrophic
+ * removal, a check that did not finish, or a tool that always needs approval. The dangerous
  * pattern floor and `deny` rules are not here: the gate refuses those first.
  */
 function isBypassImmune(tc: ToolCallSummary): boolean {
 	return (
 		tc.authorization?.askRule === true ||
 		tc.escalation?.sandboxEscape === true ||
+		(tc.escalation?.protectedPaths?.length ?? 0) > 0 ||
 		tc.escalation?.dangerousRemoval !== undefined ||
 		tc.escalation?.unfinishedCheck !== undefined ||
 		tc.requiresApproval === true
@@ -593,6 +597,9 @@ function immuneRefusal(
 	if (!escapeConfirmed && toolCalls.some((tc) => tc.escalation?.sandboxEscape === true)) {
 		return SANDBOX_ESCAPE_UNATTENDED_REFUSAL
 	}
+	if (toolCalls.some((tc) => (tc.escalation?.protectedPaths?.length ?? 0) > 0)) {
+		return PROTECTED_PATH_UNATTENDED_REFUSAL
+	}
 	if (toolCalls.some((tc) => tc.escalation?.dangerousRemoval !== undefined)) {
 		return DANGEROUS_REMOVAL_UNATTENDED_REFUSAL
 	}
@@ -879,7 +886,10 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 	 * path, a path in a variable, a program nobody can name or a `sed` script
 	 * that can run something is not that.
 	 */
-	const shellFileCommandsInRoots = async (tc: ToolCallSummary): Promise<boolean> => {
+	const shellFileCommandsInRoots = async (
+		tc: ToolCallSummary,
+		sessionId?: string,
+	): Promise<boolean> => {
 		const rootList = rootsNow()
 		if (rootList.length === 0) return false
 		if (
@@ -906,23 +916,39 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 			if (invocation.program === 'sed' && !sedOnlyEdits(invocation.args)) return false
 		}
 		if (shellPathAccess(reading).uses.some((use) => use.unresolved)) return false
-		const found = await shellEscalations(line, dialect, { roots: rootList, reviewOutside: true })
-		return (
-			found.outsidePaths.length === 0 &&
-			found.protectedPaths.length === 0 &&
-			found.dangerousRemoval === undefined
+		const cwd =
+			tool.execute === BashTool.execute && rootList[0] !== undefined
+				? effectiveBashWorkingDirectory(sessionId, rootList[0])
+				: undefined
+		const found = await shellEscalations(line, dialect, {
+			roots: rootList,
+			...(cwd !== undefined ? { cwd } : {}),
+			reviewOutside: true,
+		})
+		// A standalone review request carries no sandbox attribution. Retain the
+		// original-root reading too: missing execution metadata can only ask more,
+		// never approve a call the old reading would have sent to a person.
+		const baseline =
+			cwd !== undefined && cwd !== rootList[0]
+				? await shellEscalations(line, dialect, { roots: rootList, reviewOutside: true })
+				: found
+		return [found, baseline].every(
+			(reading) =>
+				reading.outsidePaths.length === 0 &&
+				reading.protectedPaths.length === 0 &&
+				reading.dangerousRemoval === undefined,
 		)
 	}
 
 	/** What `accept-edits` approves without asking: edits, exempt reads and file commands inside the roots. */
-	const acceptEditsAllows = async (tc: ToolCallSummary): Promise<boolean> =>
+	const acceptEditsAllows = async (tc: ToolCallSummary, sessionId?: string): Promise<boolean> =>
 		!tc.authorization?.explicitReview &&
 		tc.escalation === undefined &&
 		!tc.isDestructive &&
 		tc.requiresApproval !== true &&
 		(ACCEPT_EDITS_TOOLS.has(tc.name) ||
 			exempt(tc.name, tc.input) ||
-			(await shellFileCommandsInRoots(tc)))
+			(await shellFileCommandsInRoots(tc, sessionId)))
 
 	/**
 	 * Whether a rule's `allow` is one the classifier should not defer to: the
@@ -944,7 +970,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 	}
 
 	/** Whether `classify` decides this call without the classifier: it would not be asked, or is plainly safe. */
-	const neverSent = async (tc: ToolCallSummary): Promise<boolean> => {
+	const neverSent = async (tc: ToolCallSummary, sessionId?: string): Promise<boolean> => {
 		if (tc.authorization?.decision === 'allow' && !allowRuleTooWide(tc)) return true
 		// A name on the safe list is safe for what it does in the session; a read of
 		// /etc/shadow is still a read of /etc/shadow, and a person's own ask is
@@ -965,7 +991,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 		) {
 			return true
 		}
-		return acceptEditsAllows(tc)
+		return acceptEditsAllows(tc, sessionId)
 	}
 
 	return async (request, context?: ResumeContext): Promise<HITLResumeDecision> => {
@@ -1043,7 +1069,10 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 					request.toolCalls.map((tc) =>
 						// The mode covers a write although the flag is set; the classifier
 						// still judges one, so only this branch lifts the flag.
-						acceptEditsAllows(isFileWrite(tc.name) ? { ...tc, isDestructive: false } : tc),
+						acceptEditsAllows(
+							isFileWrite(tc.name) ? { ...tc, isDestructive: false } : tc,
+							request.sessionId,
+						),
 					),
 				)
 			).every(Boolean)
@@ -1093,7 +1122,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 				const transcript = context?.transcript() ?? []
 				for (const tc of live) {
 					// The questions a person must answer are asked of a person, never of a model.
-					if (isBypassImmune(tc) || (await neverSent(tc))) continue
+					if (isBypassImmune(tc) || (await neverSent(tc, request.sessionId))) continue
 					const decision = await classifier.review({
 						call: tc,
 						transcript,

package/src/session/retention/archive.ts

@@ -223,7 +223,7 @@ export class ArchivalManager {
 
 		// 6. Dispose the workspace (idempotent — driver contract tolerates
 		//    already-disposed refs; a missing ref is a no-op).
-		if (workspace && sub.workspaceRetention !== 'retain') {
+		if (workspace && sub.workspaceRetention === undefined) {
 			try {
 				const driver = this.deps.workspaceRegistry.get(workspace.meta.backend)
 				await driver.dispose(workspace)

package/src/session/workspace/driver.ts

@@ -47,6 +47,12 @@ export interface WorkspaceInspection {
 	exists: boolean
 	currentRef: string
 	isDirty: boolean
+	/**
+	 * Whether the workspace moved off the commit it started on. Absent when the
+	 * backend cannot tell; a caller deciding whether to keep it treats absent
+	 * as `true`.
+	 */
+	hasNewCommits?: boolean
 }
 
 /**

package/src/session/workspace/git-worktree.ts

@@ -147,11 +147,19 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 			})
 		}
 
+		// The commit the checkout starts on, so a later look can tell a child that
+		// committed from one that did not. Left out when it cannot be read: a ref
+		// without it is always treated as changed.
+		const baseCommit = await this.exec('git', ['-C', worktreePath, 'rev-parse', 'HEAD'])
+			.then((r) => r.stdout.trim() || undefined)
+			.catch(() => undefined)
+
 		const meta: GitWorktreeBackendMeta = {
 			backend: 'git-worktree',
 			repoRoot,
 			branch,
 			worktreePath,
+			...(baseCommit ? { baseCommit } : {}),
 		}
 
 		this.log.info('git-worktree created', {
@@ -202,6 +210,25 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 				[NAMZU.SESSION_ID]: ref.id,
 				'namzu.session.path': owned.worktreePath,
 			})
+			// A branch still on its starting commit holds nothing, so it goes with
+			// its checkout. Compare and delete under Git's ref lock: a branch that
+			// advanced after the worktree listing must keep its new commits.
+			if (owned.baseCommit !== undefined && registered.head === owned.baseCommit) {
+				await this.exec('git', [
+					'-C',
+					owned.repoRoot,
+					'update-ref',
+					'--no-deref',
+					'-d',
+					`refs/heads/${owned.branch}`,
+					owned.baseCommit,
+				]).catch((cause) =>
+					this.log.warn('git-worktree branch left behind', {
+						'namzu.session.branch': owned.branch,
+						'namzu.session.cause': cause instanceof Error ? cause.message : String(cause),
+					}),
+				)
+			}
 		} catch (cause) {
 			// Two concurrent disposals can both observe the entry before one wins.
 			// Re-read after failure and accept only repository evidence that the
@@ -282,10 +309,13 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 			throw new WorkspaceBackendError({ op: 'inspect:status', kind: this.kind, cause })
 		}
 
+		const baseCommit = owned.baseCommit
 		return {
 			exists: true,
 			currentRef: entry.branch ?? entry.head ?? ref.meta.branch,
 			isDirty: statusStdout.trim().length > 0,
+			// Unknown (no recorded start, or HEAD unreadable) reads as "has commits".
+			hasNewCommits: baseCommit === undefined || entry.head !== baseCommit,
 		}
 	}
 
@@ -329,6 +359,7 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 				repoRoot,
 				branch,
 				worktreePath,
+				...(ref.meta.baseCommit ? { baseCommit: ref.meta.baseCommit } : {}),
 			}
 		} catch (cause) {
 			throw new WorkspaceBackendError({ op: `${op}:ownership`, kind: this.kind, cause })

package/src/skills/index.ts

@@ -1,2 +1,7 @@
-export { SKILL_FRONTMATTER_KEYS, loadSkill, discoverSkills } from './loader.js'
+export {
+	SKILL_FRONTMATTER_KEYS,
+	SKILL_FRONTMATTER_TOLERATED_KEYS,
+	loadSkill,
+	discoverSkills,
+} from './loader.js'
 export { SkillCollisionError, SkillRegistry, resolveSkillChain } from './registry.js'

package/src/skills/loader.ts

@@ -1,5 +1,6 @@
 import { readFile, readdir, stat } from 'node:fs/promises'
 import { basename, join } from 'node:path'
+import type { ReasoningEffort } from '../types/provider/chat.js'
 import type {
 	Skill,
 	SkillDisclosureLevel,
@@ -31,8 +32,28 @@ export const SKILL_FRONTMATTER_KEYS: readonly string[] = Object.freeze([
 	'invocation',
 	'disable-model-invocation',
 	'metadata',
+	'when_to_use',
+	'context',
+	'agent',
+	'model',
+	'effort',
+	'background',
 ])
 
+/**
+ * The keys added after other tools' skills already used them. A value in one
+ * that this reader cannot take (`when_to_use: >-`, `model: [a, b]`) leaves the
+ * key absent instead of refusing the skill.
+ */
+export const SKILL_FRONTMATTER_TOLERATED_KEYS: readonly string[] = [
+	'when_to_use',
+	'context',
+	'agent',
+	'model',
+	'effort',
+	'background',
+]
+
 const READS_SKILL_KEY = (key: string): boolean => SKILL_FRONTMATTER_KEYS.includes(key)
 
 /**
@@ -44,6 +65,7 @@ const READS_SKILL_KEY = (key: string): boolean => SKILL_FRONTMATTER_KEYS.include
 export const SKILL_FRONTMATTER_OPTIONS = {
 	lists: ['allowed-tools'],
 	readsKey: READS_SKILL_KEY,
+	tolerates: (key: string): boolean => SKILL_FRONTMATTER_TOLERATED_KEYS.includes(key),
 } as const
 
 /**
@@ -161,6 +183,27 @@ function toSkillMetadata(parsed: ParsedFrontmatter, dirPath: string): SkillMetad
 		}
 	}
 
+	// The fields that shape how the skill RUNS are read leniently, the other
+	// way round from the access fields above: a value this loader does not
+	// understand (`effort: 5000`, `context: sideways`) leaves the skill at its
+	// plain behaviour rather than refusing a skill written for another agent.
+	const whenToUse = scalarAt(values, 'when_to_use')?.trim()
+	if (whenToUse) skillMetadata.whenToUse = whenToUse
+
+	if (scalarAt(values, 'context') === 'fork') skillMetadata.context = 'fork'
+	const agent = scalarAt(values, 'agent')?.trim()
+	if (agent) skillMetadata.agent = agent
+	const model = scalarAt(values, 'model')?.trim()
+	if (model && model.toLowerCase() !== 'inherit') skillMetadata.model = model
+	const effort = scalarAt(values, 'effort')?.trim().toLowerCase()
+	if (effort && (REASONING_EFFORTS as readonly string[]).includes(effort)) {
+		skillMetadata.effort = effort as ReasoningEffort
+	}
+	const background = scalarAt(values, 'background')
+	if (background === 'true' || background === 'false') {
+		skillMetadata.background = background === 'true'
+	}
+
 	const extra = mappingAt(values, 'metadata')
 	if (extra && Object.keys(extra).length > 0) {
 		skillMetadata.metadata = { ...extra }
@@ -169,6 +212,17 @@ function toSkillMetadata(parsed: ParsedFrontmatter, dirPath: string): SkillMetad
 	return skillMetadata
 }
 
+const REASONING_EFFORTS: readonly ReasoningEffort[] = [
+	'none',
+	'minimal',
+	'low',
+	'medium',
+	'high',
+	'xhigh',
+	'max',
+	'ultra',
+]
+
 const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
 
 function validateSkillName(name: string, dirPath: string): void {

package/src/skills/registry.ts

@@ -1,11 +1,12 @@
 import { stat } from 'node:fs/promises'
 import { join } from 'node:path'
 import { RegistryCollisionError } from '../registry/collision.js'
-import type {
-	Skill,
-	SkillChain,
-	SkillDisclosureLevel,
-	SkillLoadResult,
+import {
+	type Skill,
+	type SkillChain,
+	type SkillDisclosureLevel,
+	type SkillLoadResult,
+	skillModelDescription,
 } from '../types/skills/index.js'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import { type Logger, resolveLogger } from '../utils/logger.js'
@@ -273,7 +274,7 @@ export class SkillRegistry {
 			const skill = loaded.skill
 			entries.push({
 				registeredName,
-				description: skill.metadata.description,
+				description: skillModelDescription(skill.metadata),
 				location: join(skill.dirPath, SKILL_FILENAME),
 				directory: skill.dirPath,
 				...(skill.metadata.allowedTools === undefined

package/src/tools/builtins/bash-cwd.ts

@@ -0,0 +1,156 @@
+/**
+ * The directory a `bash` call starts in, carried from one call to the next.
+ *
+ * A model that runs `cd packages/app` expects the next call to be there; shell
+ * state (variables, functions, aliases) does not carry over, but the directory
+ * does. After a foreground command the shell writes its physical directory to a
+ * private file, and the next call of the same session starts there.
+ *
+ * Two limits keep this from widening what a command can reach. The new
+ * directory has to lie inside the turn's roots (the working directory, the
+ * directories added for the session, any path this call was approved for); a
+ * command that leaves them is put back at the session's working directory and
+ * the result says so. And a directory that no longer exists is dropped without
+ * ceremony. Nothing here applies to a sandboxed command or to Windows shells,
+ * whose paths a host process cannot use as they are printed.
+ */
+
+import { randomUUID } from 'node:crypto'
+import { statSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { type CommandShell, hostCommandShell } from '../command-shell.js'
+import { pathOutsideRoots, toolRoots } from '../paths.js'
+import { readBoundedFile } from './bounded-file-read.js'
+
+interface Carried {
+	/** The working directory the session started with; the fallback. */
+	readonly base: string
+	cwd: string
+}
+
+/** Sessions remembered; the oldest is forgotten first. */
+const MAX_SESSIONS = 256
+const carried = new Map<string, Carried>()
+
+/** The notice appended to a result when the command left the allowed directories. */
+export function cwdResetNotice(base: string): string {
+	return `Shell cwd was reset to ${base}`
+}
+
+/** Single-quote `text` for a POSIX shell. */
+function shellQuote(text: string): string {
+	return `'${text.replace(/'/g, `'\\''`)}'`
+}
+
+/**
+ * Runs `command` unchanged and records the directory it ended in. The exit
+ * status is the command's own. A command that ends the shell itself (`exit`)
+ * records nothing, so the directory stays as it was.
+ */
+export function withCwdCapture(command: string, file: string): string {
+	return `eval ${shellQuote(command)}\n__namzu_status=$?\npwd -P >| ${shellQuote(file)} 2>/dev/null\nexit $__namzu_status`
+}
+
+export function newCwdFile(): string {
+	return join(tmpdir(), `namzu-cwd-${randomUUID()}`)
+}
+
+/** Where this session's next foreground call starts. Synchronous: the spawn must not wait on it. */
+export function startingDirectory(sessionId: string, base: string): string {
+	const entry = carried.get(sessionId)
+	if (entry === undefined) return base
+	if (entry.base !== base) {
+		carried.delete(sessionId)
+		return base
+	}
+	try {
+		if (statSync(entry.cwd).isDirectory()) return entry.cwd
+	} catch {
+		// Removed or unreadable: start again from the base.
+	}
+	entry.cwd = base
+	return base
+}
+
+/**
+ * The cwd used by bash execution and host authorization. Hosts must resolve it
+ * for each call, not cache the session's initial directory. Sandboxed commands
+ * (including sandbox escapes) and Windows never use the carried POSIX cwd.
+ */
+export function effectiveBashWorkingDirectory(
+	sessionId: string | undefined,
+	workingDirectory: string,
+	options: {
+		sandboxed?: boolean
+		shell?: Pick<CommandShell, 'path' | 'windows'>
+	} = {},
+): string {
+	const shell = options.shell ?? hostCommandShell()
+	if (options.sandboxed || sessionId === undefined || shell.windows || shell.path === undefined)
+		return workingDirectory
+	return startingDirectory(sessionId, workingDirectory)
+}
+
+/**
+ * Reads what the finished command recorded and keeps it for the next call.
+ * Returns the notice to append when the directory was outside the roots.
+ */
+export async function recordDirectory(
+	sessionId: string,
+	file: string,
+	context: Parameters<typeof toolRoots>[0],
+): Promise<string | undefined> {
+	let reported: string
+	try {
+		reported = (await readBoundedFile(file, 64 * 1024)).toString('utf8').trim()
+	} catch {
+		return undefined
+	} finally {
+		await rm(file, { force: true })
+	}
+	if (reported === '') return undefined
+	const base = context.workingDirectory
+	const outside = await pathOutsideRoots(toolRoots(context), reported)
+	const next = outside === undefined ? reported : base
+	carried.delete(sessionId)
+	if (next !== base) {
+		carried.set(sessionId, { base, cwd: next })
+		if (carried.size > MAX_SESSIONS) {
+			const oldest = carried.keys().next().value
+			if (oldest !== undefined) carried.delete(oldest)
+		}
+	}
+	return outside === undefined ? undefined : cwdResetNotice(base)
+}
+
+/** For tests: forget every session. */
+export function forgetCarriedDirectories(): void {
+	carried.clear()
+}
+
+// Enumerable symbol crosses the executor's context copies, never the model's
+// JSON input. No public ToolContext field or caller-authored cwd is trusted.
+const REVIEWED_CWD = Symbol('namzu.bash.reviewed-cwd')
+
+export function pinBashWorkingDirectory(context: object, cwd: string): void {
+	Object.defineProperty(context, REVIEWED_CWD, { value: cwd, enumerable: true, configurable: true })
+}
+
+export function bashWorkingDirectoryForExecution(context: {
+	sessionId?: string
+	workingDirectory: string
+	sandbox?: unknown
+}): string {
+	const current = effectiveBashWorkingDirectory(context.sessionId, context.workingDirectory, {
+		sandboxed: context.sandbox !== undefined,
+	})
+	const reviewed = (context as { [REVIEWED_CWD]?: string })[REVIEWED_CWD]
+	if (reviewed !== undefined && current !== reviewed)
+		throw new Error(
+			'Shell working directory changed after this call was reviewed. Nothing ran. Retry the call so its paths can be checked in the current directory.',
+		)
+	return reviewed ?? current
+}