@namzu/sdk 2.0.0 → 3.1.0

package/src/types/tool/index.ts

@@ -14,15 +14,77 @@ export interface ToolRegistryRef {
 /**
  * Tracks which files the agent has read in the current run.
  * Write tool consults this to enforce the "read before overwrite" invariant
- * (Claude Code parity): an existing file must be read first or the write fails.
+ * an existing file must be read first or the write fails.
  * Keys are the resolved path used by the tool — sandbox-relative when a sandbox
  * is active, absolute (`workingDirectory`-resolved) otherwise.
  */
 export interface FileReadTracker {
-	recordRead(key: string): void
+	/**
+	 * `content` lets the tracker fingerprint what was read, which is what
+	 * makes drift detectable later. Optional so a host that only needs the
+	 * read-before-overwrite guard can keep its existing implementation.
+	 */
+	recordRead(key: string, content?: string): void
 	hasRead(key: string): boolean
+	/**
+	 * Fingerprint of the body captured at the last read, when one was.
+	 *
+	 * A file mutation is computed against what the agent READ, and between
+	 * that read and the write the file may have moved under it — a person
+	 * editing in an editor, another process, a second agent. The in-process
+	 * lock cannot see any of those. Comparing this against the body actually
+	 * on disk at mutation time is what turns a silent lost update into a
+	 * refusal the agent can act on by re-reading.
+	 */
+	fingerprint?(key: string): string | undefined
+}
+
+export interface ToolPauseOption {
+	readonly id: string
+	readonly label: string
+	readonly description?: string
+}
+
+export interface ToolPauseRequest {
+	/**
+	 * Names this pause within the call.
+	 *
+	 * A tool call may pause more than once — "which environment", then
+	 * "are you sure" — and the answers have to be told apart. The name is
+	 * what a resume payload is routed by, so it is the author's to choose
+	 * and should describe the decision, not the tool.
+	 */
+	readonly name: string
+	/** The question, in the words the human will read. */
+	readonly prompt: string
+	/** Short topic label, when the surface showing this has room for one. */
+	readonly header?: string
+	readonly options?: readonly ToolPauseOption[]
+	readonly multiSelect?: boolean
+	/** Defaults to true: a human who disagrees with every option can say so. */
+	readonly allowFreeText?: boolean
 }
 
+/**
+ * How a pause ended.
+ *
+ * `unanswered` is deliberately not a variant of `answered` with an empty
+ * selection. A tool that pauses to ask "may I charge this card" and reads
+ * silence as yes is worse than one that never asked, so the absence of an
+ * answer has its own shape and cannot be destructured into consent by
+ * accident.
+ */
+export type ToolPauseOutcome =
+	| {
+			readonly status: 'answered'
+			readonly selectedOptionIds: readonly string[]
+			readonly text?: string
+	  }
+	| { readonly status: 'unanswered'; readonly reason: string }
+	| { readonly status: 'aborted' }
+
+export type RequestToolPause = (request: ToolPauseRequest) => Promise<ToolPauseOutcome>
+
 export interface ToolContext {
 	runId: RunId
 	workingDirectory: string
@@ -51,6 +113,63 @@ export interface ToolContext {
 	 * Optional because not every executor path provides it yet.
 	 */
 	toolUseId?: string
+
+	/**
+	 * Raise a durable pause and wait for a human to resolve it.
+	 *
+	 * The pause machinery is excellent and was reachable from exactly four
+	 * kernel-owned points — the plan gate, the tool-review gate, the
+	 * iteration cadence, and one built-in question tool. A host-authored
+	 * tool had no seam to it, so the operations that most want their own
+	 * confirmation with their own wording (a spend, an outbound post, a
+	 * destructive migration) had to settle for the generic tool-review
+	 * gate or hand-thread a recorder and a resume callback into a private
+	 * builder, which nothing in this type suggested was possible.
+	 *
+	 * The park is a real checkpoint, so a host can see the pause on every
+	 * surface a tool-review park appears on, and the answer routes back by
+	 * name on resume — several tools pausing in one batch each get their
+	 * own, and one tool may pause more than once.
+	 *
+	 * Absent when whatever is driving the tool provides no route to a
+	 * human — a host calling a tool directly, outside a run. A tool must
+	 * treat it as optional and decide what to do without one, and must
+	 * never read an unanswered pause as consent; the outcome says which it
+	 * was, in its own shape, so silence cannot be destructured into a yes.
+	 */
+	requestPause?: RequestToolPause
+
+	/**
+	 * Span to parent this tool's `execute_tool` span to.
+	 *
+	 * OTel's GenAI conventions define a strict hierarchy —
+	 * `invoke_agent` → `chat {model}` → `execute_tool` — and vendor
+	 * dashboards rely on it. `startActiveSpan` cannot supply the parent
+	 * here: the span-owning bodies upstream are async GENERATORS, and a
+	 * generator resumes on its consumer's async context, so the ambient
+	 * context is already gone by the time a tool runs. Passing the parent
+	 * explicitly is the only approach that actually works, and
+	 * `ToolContext` is already threaded to exactly the right place.
+	 */
+	parentSpan?: import('@opentelemetry/api').Span
+
+	/**
+	 * Say how far along you are, for a host rendering a live view.
+	 *
+	 * A tool may run for the full per-tool deadline — two minutes by
+	 * default — and before this it was silent for all of it: a host could
+	 * show that a build had started and then nothing until it finished or
+	 * timed out.
+	 *
+	 * Fire-and-forget and never throws, so a tool can call it freely
+	 * without wrapping it. The model never sees these: progress answers
+	 * "is it still working?", which is a question only a human asks, and
+	 * putting it in the conversation would spend tokens telling the model
+	 * something it cannot act on.
+	 *
+	 * Absent when the executing surface has no event stream to write to.
+	 */
+	report?: (message: string, fraction?: number) => void
 }
 
 export interface ToolResult {
@@ -58,6 +177,31 @@ export interface ToolResult {
 	output: string
 	data?: unknown
 	error?: string
+	/**
+	 * Rich content for the MODEL, when a string cannot carry it — a
+	 * screenshot, a chart, a PDF. `output` stays the text the host and the
+	 * transcript see; when this is set it is what reaches the provider.
+	 *
+	 * Keeping the two separate is deliberate: a host UI wants "screenshot
+	 * (1280x800)", the model wants the pixels, and forcing one channel to
+	 * serve both is what made `computer-use` send megabytes of base64 as
+	 * text.
+	 */
+	content?: import('../message/index.js').ToolResultContent
+
+	/**
+	 * This failure might succeed if tried again — a network blip, a lock
+	 * contention, a rate limit — as opposed to one that never will, like a
+	 * missing file or a rejected argument.
+	 *
+	 * Nothing distinguished the two before, so a transient failure cost a
+	 * full model round trip to retry: the error went back as a
+	 * `tool_result`, the model read it, and decided (or didn't) to call
+	 * again. Only meaningful alongside {@link ToolDefinition.maxRetries};
+	 * a tool that has not opted into retries is never retried no matter
+	 * what it sets here.
+	 */
+	retryable?: boolean
 }
 
 export interface ToolDefinition<TInput = unknown> {
@@ -84,11 +228,84 @@ export interface ToolDefinition<TInput = unknown> {
 	 * cannot be reconstructed from JSON Schema's top-level `required` list.
 	 */
 	validationErrorHint?: string
+
+	/**
+	 * The shape this tool returns, as JSON Schema, appended to the
+	 * description the model sees.
+	 *
+	 * JSON Schema rather than Zod because it is **shown, never validated**:
+	 * namzu does not check a tool's return value against it, so converting
+	 * through Zod would only cost fidelity. Native tools that want one can
+	 * render their Zod type with `renderToolSchema`.
+	 *
+	 * Optional and omitted by default — a tool whose return shape is
+	 * obvious from its description gains nothing from spending prompt on
+	 * it, and every tool schema rides in the cached prefix of every
+	 * request.
+	 */
+	outputSchema?: Record<string, unknown>
 	execute(input: TInput, context: ToolContext): Promise<ToolResult>
 	tier?: string
 	permissions?: ToolPermission[]
 	category?: 'filesystem' | 'shell' | 'network' | 'analysis' | 'custom'
 
+	/**
+	 * Deadline for a single execution, overriding the run-level default.
+	 *
+	 * On expiry the executor stops waiting and returns a model-visible
+	 * error result, so a slow dependency becomes something the agent can
+	 * route around instead of a turn that never comes back. The tool's
+	 * `context.abortSignal` fires at the same moment; a tool that honours
+	 * it also stops doing work, and one that ignores it merely becomes
+	 * detached.
+	 *
+	 * Omit to inherit the executor's default.
+	 */
+	timeoutMs?: number
+
+	/**
+	 * How many times a FAILED execution may be retried in-loop before the
+	 * error is handed to the model.
+	 *
+	 * **Defaults to 0, and that default is load-bearing.** Retrying is only
+	 * safe if the tool is idempotent, and the SDK cannot know that: silently
+	 * re-running a `write_file`, a `git push` or a payment call is worse
+	 * than never retrying at all. The tool author opts in, per tool.
+	 *
+	 * Even then, only failures the tool marked
+	 * {@link ToolResult.retryable} are retried — a missing file is not
+	 * going to appear on the second attempt, and burning the budget on it
+	 * just delays the error the model needs to see.
+	 */
+	maxRetries?: number
+
+	/**
+	 * This tool's output IS the run's answer: settle with it instead of
+	 * asking the model to restate it.
+	 *
+	 * Every delegation path is blocking and returns the worker's final
+	 * text as the dispatching call's result, after which the loop went
+	 * round again — so a router agent, whose entire job is to pick a
+	 * specialist, paid one extra model call per request at the parent's
+	 * full context size, the most expensive call in the run. The relay is
+	 * also LOSSY: the parent paraphrases the worker's answer through its
+	 * own (compacted) context, so what the caller receives is not what the
+	 * worker produced.
+	 *
+	 * Honoured only when the terminal call is the ONLY call in the turn
+	 * and it did not fail. A model that asked for other work in the same
+	 * turn meant to see those results, and ending the run would discard
+	 * answers it requested; that turn takes the ordinary path and the
+	 * reason is logged. A failed terminal call is not an answer either —
+	 * the error goes back to the model, which is the point of returning
+	 * errors to it at all.
+	 *
+	 * Off by default. The generic case is `structured_output`, which the
+	 * runtime has always settled on; this is that rule made available to
+	 * any tool.
+	 */
+	terminal?: boolean
+
 	isReadOnly?(input: TInput): boolean
 	isDestructive?(input: TInput): boolean
 	isConcurrencySafe?(input: TInput): boolean
@@ -173,3 +390,5 @@ export interface ToolRegistryContract {
 	toTierGuidance(): string | null
 	assignTiers(mapping: Record<string, string>): void
 }
+
+export * from './repair.js'

package/src/types/tool/repair.ts

@@ -0,0 +1,54 @@
+import type { ToolCall } from '../message/index.js'
+import type { ToolDefinition } from './index.js'
+
+/**
+ * Why a tool call could not be executed as issued.
+ *
+ * `invalid_json` — the arguments string is not parseable JSON at all,
+ *   typically a truncated stream or an unescaped quote.
+ * `schema_validation` — the JSON parsed but does not satisfy the tool's
+ *   schema: a missing required field, a string where a number belongs.
+ * `unknown_tool` — the model named a tool that is not registered, usually
+ *   a near-miss on a real name.
+ */
+export type ToolCallRepairReason = 'invalid_json' | 'schema_validation' | 'unknown_tool'
+
+export interface ToolCallRepairContext {
+	/** The call as the model issued it, arguments still raw. */
+	readonly toolCall: ToolCall
+	readonly reason: ToolCallRepairReason
+	/** The error the model would otherwise have been shown. */
+	readonly message: string
+	/** The target tool. Absent for `unknown_tool`. */
+	readonly tool?: ToolDefinition
+	/** The tool's JSON Schema, so a repair model has something to aim at. */
+	readonly jsonSchema?: Record<string, unknown>
+	/** Every registered tool name — the useful context for `unknown_tool`. */
+	readonly availableTools: readonly string[]
+}
+
+/**
+ * Fix a tool call the model got wrong, before the error reaches it.
+ *
+ * A malformed call used to cost a full round trip: the error went back as
+ * a `tool_result`, the model read it, and tried again — a second inference
+ * on the entire context to fix a missing brace. A host that can repair the
+ * arguments locally (a cheap model with the schema, or plain string
+ * surgery) turns that into nothing.
+ *
+ * Return the corrected call, or `null` to decline — declining is not a
+ * failure, it just means the original error proceeds to the model as
+ * before. Deliberately narrow: a repair may rewrite the ARGUMENTS and the
+ * tool NAME, and nothing else. It cannot invent a call the model never
+ * made, and it cannot suppress one.
+ */
+export type RepairToolCall = (
+	context: ToolCallRepairContext,
+) => Promise<ToolCallRepair | null> | ToolCallRepair | null
+
+export interface ToolCallRepair {
+	/** Corrected arguments, as a JSON string. */
+	readonly arguments: string
+	/** Corrected tool name. Omit to keep the one the model used. */
+	readonly toolName?: string
+}

package/src/types/toolset/index.ts

@@ -1,6 +1,6 @@
 import type { LLMToolSchema, ToolDefinition, ToolPermission } from '../tool/index.js'
 
-export type ToolCatalogSurface = 'chat' | 'cowork' | 'managed-agent' | 'worker' | 'code'
+export type ToolCatalogSurface = 'chat' | 'supervised' | 'managed-agent' | 'worker' | 'code'
 
 export type ToolSourceKind =
 	| 'host_tool'
@@ -12,8 +12,6 @@ export type ToolSourceKind =
 
 export type ToolLoadingMode = 'eager' | 'deferred' | 'disabled' | 'suspended'
 
-export type ToolPermissionPolicy = 'default' | 'always_allow' | 'always_ask' | 'deny'
-
 export interface ToolSource {
 	readonly id: string
 	readonly kind: ToolSourceKind
@@ -32,7 +30,7 @@ export interface ToolSource {
 		readonly beta?: string
 	}
 	readonly skill?: {
-		readonly type: 'anthropic' | 'custom'
+		readonly type: 'published' | 'custom'
 		readonly skillId: string
 		readonly version?: string
 	}
@@ -43,7 +41,6 @@ export interface ToolsetPolicy {
 	readonly enabled?: boolean
 	readonly loading?: ToolLoadingMode
 	readonly preferred?: boolean
-	readonly permissionPolicy?: ToolPermissionPolicy
 	readonly surfaces?: readonly ToolCatalogSurface[]
 	readonly providerConfig?: Record<string, unknown>
 }
@@ -54,7 +51,6 @@ export interface ToolsetDefinition {
 	readonly name: string
 	readonly description?: string
 	readonly defaultPolicy?: ToolsetPolicy
-	readonly toolPolicies?: Record<string, ToolsetPolicy>
 	readonly metadata?: Record<string, unknown>
 }
 

package/src/utils/__tests__/atomic-write.test.ts

@@ -0,0 +1,108 @@
+import { mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { atomicWriteFile, temporaryPathFor } from '../atomic-write.js'
+
+/**
+ * The rename is what makes the write atomic — a reader sees the old file or
+ * the new one, never a half-written one. The sidecar it renames FROM has to
+ * be private to this write, and in seven places it was a fixed
+ * `${path}.tmp`.
+ *
+ * Two writers of the same record then shared one scratch file: both opened
+ * it, both wrote into it, and the first rename published whatever mixture
+ * had landed while the second renamed a file that was no longer there. That
+ * is the failure atomic writes exist to prevent, reached through the
+ * mechanism meant to prevent it.
+ *
+ * Not hypothetical here: the cross-process park and unpark handoff is a
+ * design where two processes legitimately touch the same records, and it is
+ * the feature these stores exist to serve.
+ */
+
+let dir: string
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), 'namzu-atomic-'))
+})
+
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true })
+})
+
+describe('the sidecar name', () => {
+	it('is different every time', () => {
+		const names = new Set(Array.from({ length: 1000 }, () => temporaryPathFor('/x/record.json')))
+		// A thousand writes in the same millisecond is a batch, not a stress
+		// test — a timestamp alone would collide here.
+		expect(names.size).toBe(1000)
+	})
+
+	it('stays beside the file it will become', () => {
+		expect(temporaryPathFor('/x/record.json').startsWith('/x/record.json.')).toBe(true)
+		// Same directory, so the rename is within one filesystem and stays
+		// atomic rather than degrading to a copy.
+		expect(temporaryPathFor('/x/record.json')).toMatch(/\.tmp$/)
+	})
+
+	it('carries the process id, so two processes cannot pick the same one', () => {
+		expect(temporaryPathFor('/x/record.json')).toContain(`.${process.pid}.`)
+	})
+})
+
+describe('writing', () => {
+	it('publishes the content', async () => {
+		const target = join(dir, 'record.json')
+		await atomicWriteFile(target, '{"a":1}')
+		expect(readFileSync(target, 'utf-8')).toBe('{"a":1}')
+	})
+
+	it('leaves no sidecar behind on success', async () => {
+		await atomicWriteFile(join(dir, 'record.json'), 'x')
+		expect(readdirSync(dir)).toEqual(['record.json'])
+	})
+
+	it('leaves no sidecar behind on failure', async () => {
+		// A directory that does not exist fails the write, not the rename.
+		await expect(atomicWriteFile(join(dir, 'missing', 'record.json'), 'x')).rejects.toThrow()
+		// A leftover sidecar looks like a record to anything scanning the
+		// directory, and the next attempt would not reuse it anyway.
+		expect(readdirSync(dir)).toEqual([])
+	})
+
+	it('does not corrupt a record when two writes race', async () => {
+		const target = join(dir, 'record.json')
+		const first = 'a'.repeat(200_000)
+		const second = 'b'.repeat(200_000)
+
+		await Promise.all([atomicWriteFile(target, first), atomicWriteFile(target, second)])
+
+		// One of them won; neither produced a mixture. With a shared sidecar
+		// this is exactly where the halves interleave.
+		const written = readFileSync(target, 'utf-8')
+		expect([first, second]).toContain(written)
+		expect(readdirSync(dir)).toEqual(['record.json'])
+	})
+
+	it('survives many concurrent writes to the same record', async () => {
+		const target = join(dir, 'record.json')
+		const bodies = Array.from({ length: 25 }, (_, i) => `${i}`.repeat(50_000))
+
+		await Promise.all(bodies.map((body) => atomicWriteFile(target, body)))
+
+		expect(bodies).toContain(readFileSync(target, 'utf-8'))
+		expect(readdirSync(dir)).toEqual(['record.json'])
+	})
+})
+
+describe('a contended rename', () => {
+	it('does not retry a failure that is not contention', async () => {
+		// A missing directory is a permanent condition; retrying it would
+		// turn a clear failure into a delay and then the same failure.
+		const started = Date.now()
+		await expect(atomicWriteFile(join(dir, 'nope', 'record.json'), 'x')).rejects.toThrow()
+		expect(Date.now() - started).toBeLessThan(50)
+	})
+})

package/src/utils/__tests__/shell-compress.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest'
+
+import { compressShellOutputFull } from '../shell-compress.js'
+
+/**
+ * `raw` here is bash stdout, and bash stdout is not something the run
+ * itself typed — a fetched page, a piped response, a file an agent was
+ * told to `cat`, all land in it verbatim. The pass-line detector's opening
+ * alternative used to hunt for a PASS/ok marker with an unbounded
+ * whitespace/bullet run in front of it. On a long line that never produces
+ * that marker, the engine restarts the hunt at every offset in the line,
+ * and this codebase's tool budgets cap payload bytes, not line length —
+ * one crafted line was enough to pin a core testing the regex, and would
+ * have done the same to the process compressing real output.
+ */
+describe('compressShellOutputFull', () => {
+	it('does not hang on a long marker-free line (js/polynomial-redos regression)', () => {
+		// 20 lines is `DEFAULT_MIN_LINES` — below it the function returns the
+		// input untouched and the vulnerable regex is never reached.
+		const poison = ' '.repeat(4000)
+		const raw = [poison, ...Array.from({ length: 19 }, (_, i) => `line ${i}`)].join('\n')
+
+		const start = Date.now()
+		compressShellOutputFull(raw)
+		const elapsedMs = Date.now() - start
+
+		// The vulnerable regex takes ~20s on a line this size; a fixed one
+		// finishes in low single-digit milliseconds. 1s leaves headroom for a
+		// loaded CI box while still failing hard on a regression.
+		expect(elapsedMs).toBeLessThan(1000)
+	})
+
+	it('still recognizes and suppresses repeated PASS markers', () => {
+		// Distinct names, not indices: normalizeLine folds digits to `N`, so
+		// index-numbered lines would collapse into one another in the repeat
+		// pass and the assertion below would be measuring the wrong thing.
+		const names = ['alpha', 'bravo', 'charlie', 'delta', 'echo', 'foxtrot', 'golf', 'hotel']
+		const passLines = names.map((name) => `  ✓ test ${name} PASS `)
+		const raw = [...passLines, ...Array.from({ length: 15 }, (_, i) => `other line ${i}`)].join(
+			'\n',
+		)
+
+		const { text } = compressShellOutputFull(raw, { maxPassLines: 3 })
+
+		expect(text).toContain('passing tests omitted')
+		// Only the configured cap of PASS lines survives verbatim.
+		expect(text.match(/✓ test \w+ PASS/g)?.length).toBe(3)
+	})
+})

package/src/utils/atomic-write.ts

@@ -0,0 +1,85 @@
+import { randomBytes } from 'node:crypto'
+import { rename, unlink, writeFile } from 'node:fs/promises'
+
+/**
+ * Write-then-rename, with a sidecar name no other writer can pick.
+ *
+ * The rename is what makes the write atomic — a reader sees the old file or
+ * the new one, never a half-written one. The sidecar it renames FROM has to
+ * be private to this write, and in six stores it was a fixed
+ * `${path}.tmp`.
+ *
+ * Two writers of the same record then shared one scratch file: both opened
+ * it, both wrote into it, and the first `rename` published whatever mixture
+ * had landed while the second renamed a file that was no longer there. The
+ * result is the failure atomic writes exist to prevent, arrived at through
+ * the mechanism meant to prevent it.
+ *
+ * This is not hypothetical for this SDK. The cross-process park and unpark
+ * handoff — one process suspending a run and another resuming it — is a
+ * design where two processes legitimately touch the same records, and it is
+ * the feature these stores exist to serve. One store already got this
+ * right; the rest inherited the fixed name.
+ *
+ * The suffix carries the pid (distinct per process), a counter (distinct
+ * within a process, including within one millisecond) and a few random
+ * bytes (distinct across hosts sharing a network mount, where a pid can
+ * repeat).
+ */
+
+let counter = 0
+
+export function temporaryPathFor(filePath: string): string {
+	counter = (counter + 1) % Number.MAX_SAFE_INTEGER
+	return `${filePath}.${process.pid}.${counter}.${randomBytes(4).toString('hex')}.tmp`
+}
+
+/**
+ * Publish `content` atomically.
+ *
+ * A failed write removes its own sidecar. Leaving it behind would litter
+ * the store with files that look like records to anything scanning the
+ * directory, and the next attempt would not reuse it anyway.
+ */
+export async function atomicWriteFile(filePath: string, content: string): Promise<void> {
+	const tempPath = temporaryPathFor(filePath)
+	try {
+		await writeFile(tempPath, content, 'utf-8')
+		await renameWithRetry(tempPath, filePath)
+	} catch (err) {
+		await unlink(tempPath).catch(() => undefined)
+		throw err
+	}
+}
+
+/** Transient on Windows while another handle still holds the target. */
+const CONTENDED = new Set(['EPERM', 'EACCES', 'EBUSY'])
+const RENAME_ATTEMPTS = 5
+
+/**
+ * Rename, retrying briefly while the target is contended.
+ *
+ * Replacing an existing file by rename is unconditional on POSIX and not
+ * on Windows, where a concurrent writer holding the target makes the call
+ * fail with `EPERM` — momentarily, for as long as the other rename takes.
+ * Two processes writing the same record is precisely the case this whole
+ * helper exists for, so treating that as a hard failure would hand back an
+ * error for a situation that resolves itself in microseconds.
+ *
+ * Bounded and short on purpose. A genuine permission problem is not
+ * transient, and retrying it forever would turn a clear failure into a
+ * hang; five attempts distinguishes contention from denial without
+ * pretending to fix the latter.
+ */
+async function renameWithRetry(from: string, to: string): Promise<void> {
+	for (let attempt = 1; ; attempt++) {
+		try {
+			await rename(from, to)
+			return
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code ?? ''
+			if (!CONTENDED.has(code) || attempt >= RENAME_ATTEMPTS) throw err
+			await new Promise((resolve) => setTimeout(resolve, attempt))
+		}
+	}
+}

package/src/utils/shell-compress.ts

@@ -1,8 +1,19 @@
 const STACK_FRAME_RE =
 	/^\s+at\s+|^\s+File\s+"[^"]+",\s+line\s+\d+|^\s+at\s+[\w.$]+\(|^\s+\d+:\s+\w|^\s+from\s+\//
 
+// This line is tested against every line of shell output, which is
+// attacker-reachable (e.g. bash stdout can carry bytes the run itself never
+// typed — a fetched file, a piped response). The first alternative used to
+// open with an unbounded `[\s...]+` hunting for a PASS/ok marker that may
+// not exist: on a long run of bullet/whitespace characters with nothing to
+// match, the engine restarts that scan at every offset, and the per-offset
+// scan itself walks the remaining string — quadratic in line length (a
+// single crafted line was enough to hang the process). Capping the run
+// bounds the per-offset work to a constant, so the unavoidable per-offset
+// restart stays linear overall. 40 is generous for the checkmark/indent
+// prefixes real tool output produces; nothing legitimate needs more.
 const PASS_LINE_RE =
-	/[\s✓✔√●∙·►▸▹]+\s*(PASS|pass|ok|OK|✓|✔|√)\s|^\s*(PASS|ok)\s+[\w/.-]+|^ok\s+\d+\s|PASSED\s*$|^---\s*PASS:|^test\s+\S+\s+\.\.\.\s+ok\s*$/
+	/[\s✓✔√●∙·►▸▹]{1,40}(PASS|pass|ok|OK|✓|✔|√)\s|^\s*(PASS|ok)\s+[\w/.-]+|^ok\s+\d+\s|PASSED\s*$|^---\s*PASS:|^test\s+\S+\s+\.\.\.\s+ok\s*$/
 
 const NOISE_RE =
 	/^\s*[\\\/|─━░▓█▒■□◻◼⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⣾⣽⣻⢿⡿⣟⣯⣷]+\s*$|^\s*\d+%\s*[|█▓░]+|^(Downloading|Fetching|Installing|Resolving|Compiling)\b.*\.\.\./

package/src/verification/presets.ts

@@ -7,9 +7,12 @@ import type { VerificationGateConfig } from '../types/verification/index.js'
  * The model: the sandbox is the safety boundary. Anything that
  * stays inside the sandbox auto-approves. Things that try to escape
  * (network reach, shell tricks the dangerous-pattern list catches)
- * fall through to a human review prompt. This mirrors Codex CLI's
- * `workspace-write` + `on-request` default and Claude Code's
- * sandboxed permission mode.
+ * fall through to a human review prompt.
+ *
+ * The boundary is chosen deliberately: it is the one line a tool cannot
+ * blur. "Is this edit risky?" has no stable answer, but "does this leave
+ * the sandbox?" does — so the gate asks the question it can answer, and
+ * asks a human about the rest.
  *
  * What this enables:
  * - `allowReadOnlyTools` — anything `tool.isReadOnly(input)` reports