@namzu/sdk 3.2.0 → 4.0.0

package/src/tools/builtins/__tests__/edit-insert-reachable.test.ts

@@ -0,0 +1,166 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import type { ToolContext } from '../../../types/tool/index.js'
+import { EditTool } from '../edit.js'
+import { WriteFileTool } from '../write-file.js'
+
+/**
+ * The tool's description ordered an idiom its own schema forbade.
+ *
+ * `edit`'s description says "For insertions, pass insertLine … use
+ * insertLine: 'end' to extend a file at the end". `modelInputSchema` listed
+ * only path/old_string/new_string/replace_all with
+ * `additionalProperties: false`, and `enforceModelInput: true` — so under
+ * constrained decoding the append idiom the prompt recommends was the one
+ * idiom a model could not emit.
+ *
+ * A consuming host measured the consequence over 7 days on one tenant: 94 of
+ * 159 tool failures were `edit` rejecting an `insertLine` the model had
+ * guessed a spelling for. That number is theirs and not reproducible here;
+ * the contradiction below is reproducible and is what these pin.
+ */
+
+let dirs: string[] = []
+
+afterEach(async () => {
+	await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })))
+	dirs = []
+})
+
+async function workdir(): Promise<string> {
+	const dir = await mkdtemp(join(tmpdir(), 'namzu-edit-insert-'))
+	dirs.push(dir)
+	return dir
+}
+
+const ctx = (workingDirectory: string): ToolContext =>
+	({
+		runId: 'run_e',
+		workingDirectory,
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => undefined,
+	}) as unknown as ToolContext
+
+const schema = () =>
+	(EditTool as unknown as { modelInputSchema: Record<string, unknown> }).modelInputSchema
+
+describe('the model can emit the idiom the description recommends', () => {
+	it('advertises insertLine at all', () => {
+		const props = schema().properties as Record<string, unknown>
+
+		expect(props.insertLine).toBeDefined()
+	})
+
+	it('keeps the closed shape, so an invented field is still refused', () => {
+		expect(schema().additionalProperties).toBe(false)
+	})
+
+	it('does not require old_string, which an insert cannot supply', () => {
+		// Requiring it is what made the append idiom unexpressible: an insert
+		// has no text to match.
+		expect(schema().required).not.toContain('old_string')
+	})
+
+	it('still requires the two fields every operation needs', () => {
+		expect(schema().required).toEqual(expect.arrayContaining(['path', 'new_string']))
+	})
+
+	it('admits only "end" as a string, so a synonym cannot be generated', () => {
+		const insert = (schema().properties as Record<string, { oneOf?: unknown[] }>).insertLine
+
+		// The schema is where the synonym problem is solved for a provider that
+		// constrains: `"EOF"` is not emittable because `"end"` is the only
+		// string the union admits.
+		expect(insert?.oneOf).toEqual([{ type: 'integer', minimum: 0 }, { const: 'end' }])
+	})
+})
+
+describe('an insert actually works end to end', () => {
+	it('appends with insertLine "end"', async () => {
+		const dir = await workdir()
+		await writeFile(join(dir, 'a.md'), 'first\n', 'utf-8')
+
+		const result = await EditTool.execute(
+			{ path: 'a.md', insertLine: 'end', new_string: 'second', replace_all: false },
+			ctx(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(await readFile(join(dir, 'a.md'), 'utf-8')).toContain('second')
+	})
+
+	it('inserts after a numbered line', async () => {
+		const dir = await workdir()
+		await writeFile(join(dir, 'a.md'), 'one\ntwo\n', 'utf-8')
+
+		await EditTool.execute(
+			{ path: 'a.md', insertLine: 1, new_string: 'inserted', replace_all: false },
+			ctx(dir),
+		)
+
+		const lines = (await readFile(join(dir, 'a.md'), 'utf-8')).split('\n')
+		expect(lines[1]).toBe('inserted')
+	})
+})
+
+describe('a synonym for the end of the file is accepted, not charged for', () => {
+	it.each(['EOF', 'append', 'last', 'End_Of_File'])('accepts %s', async (spelling) => {
+		const dir = await workdir()
+		await writeFile(join(dir, 'a.md'), 'first\n', 'utf-8')
+
+		const result = await EditTool.execute(
+			{ path: 'a.md', insertLine: spelling, new_string: 'second', replace_all: false },
+			ctx(dir),
+		)
+
+		// Liberal here and strict in the schema, which is the right way round.
+		// None of these is ambiguous; refusing one costs a full model round
+		// trip to be told a synonym.
+		expect(result.success).toBe(true)
+	})
+
+	it('still refuses something that is not a line and not the end', async () => {
+		const dir = await workdir()
+		await writeFile(join(dir, 'a.md'), 'first\n', 'utf-8')
+
+		const result = await EditTool.execute(
+			{ path: 'a.md', insertLine: 'somewhere in the middle', new_string: 'x', replace_all: false },
+			ctx(dir),
+		)
+
+		expect(result.success).toBe(false)
+		// The rejection names what was received, so the retry is informed.
+		expect(result.error).toContain('somewhere in the middle')
+	})
+
+	it('still refuses a negative line', async () => {
+		const dir = await workdir()
+		await writeFile(join(dir, 'a.md'), 'first\n', 'utf-8')
+
+		const result = await EditTool.execute(
+			{ path: 'a.md', insertLine: -3, new_string: 'x', replace_all: false },
+			ctx(dir),
+		)
+
+		expect(result.success).toBe(false)
+	})
+})
+
+describe('the two mutating tools agree on what a path is', () => {
+	it('write refuses a whitespace-only path, as edit already did', async () => {
+		const dir = await workdir()
+
+		const w = await WriteFileTool.execute({ path: '   ', content: 'x' }, ctx(dir))
+		const e = await EditTool.execute(
+			{ path: '   ', old_string: 'a', new_string: 'b', replace_all: false },
+			ctx(dir),
+		)
+
+		expect(w.success).toBe(false)
+		expect(e.success).toBe(false)
+	})
+})

package/src/tools/builtins/__tests__/edit.test.ts

@@ -19,7 +19,7 @@ function makeContext(workingDirectory: string): ToolContext {
 }
 
 describe('EditTool', () => {
-	it('publishes one closed canonical replacement contract', () => {
+	it('publishes one closed contract covering both operations', () => {
 		const schema = EditTool.modelInputSchema
 		expect(schema).toEqual({
 			type: 'object',
@@ -38,12 +38,20 @@ describe('EditTool', () => {
 					description:
 						'Exact replacement text. May be empty to delete old_string. Keep under 12000 characters.',
 				},
+				insertLine: {
+					oneOf: [{ type: 'integer', minimum: 0 }, { const: 'end' }],
+					description:
+						'Insert instead of replacing. The new_string goes after this 1-indexed line; 0 inserts before the first line; "end" appends. Omit for a find-and-replace.',
+				},
 				replace_all: {
 					type: 'boolean',
 					description: 'Replace every occurrence instead of requiring one unique match.',
 				},
 			},
-			required: ['path', 'old_string', 'new_string'],
+			//  left out on purpose: an insert has no text to match,
+			// and requiring it is what made the append idiom the tool's own
+			// description recommends unexpressible under constrained decoding.
+			required: ['path', 'new_string'],
 			additionalProperties: false,
 		})
 

package/src/tools/builtins/__tests__/write-file.test.ts

@@ -27,6 +27,86 @@ function makeContext(workingDirectory: string, tracker?: FileReadTracker): ToolC
 	}
 }
 
+/**
+ * The published contract, pinned exactly.
+ *
+ * This was dropped when the tool gained `newStr`, and dropping it is what let
+ * the two contracts drift apart silently. They are deliberately NOT the same
+ * contract, and that is the thing worth recording: a host driving `execute`
+ * directly may pass `newStr`, and a model may not — because a model given two
+ * names for the body has to choose, and choosing is what produces the
+ * half-filled calls the closed model schema exists to prevent. Nothing said
+ * that out loud once the test asserting it was rewritten to assert the
+ * opposite.
+ */
+describe('WriteFileTool — the published contract', () => {
+	it('publishes one closed path + content shape to the model', () => {
+		expect(WriteFileTool.modelInputSchema).toEqual({
+			type: 'object',
+			properties: {
+				path: {
+					type: 'string',
+					description: 'Relative path to the file to write. Must not be empty.',
+				},
+				content: {
+					type: 'string',
+					description:
+						'Complete file body. Use "" only for an intentionally empty file. Keep under 12000 characters.',
+				},
+			},
+			required: ['path', 'content'],
+			additionalProperties: false,
+		})
+		expect(WriteFileTool.enforceModelInput).toBe(true)
+	})
+
+	it('keeps newStr off the model surface while accepting it from a host', () => {
+		const modelProperties = WriteFileTool.modelInputSchema?.properties as Record<string, unknown>
+		expect(Object.keys(modelProperties)).not.toContain('newStr')
+
+		// The execution schema is the wider one, on purpose.
+		expect(WriteFileTool.inputSchema.safeParse({ path: 'doc.md', newStr: 'body' }).success).toBe(
+			true,
+		)
+	})
+
+	it('requires a body under one name or the other', () => {
+		expect(WriteFileTool.inputSchema.safeParse({ path: 'doc.md' }).success).toBe(false)
+		// An empty string is a body — an intentionally empty file is legal.
+		expect(WriteFileTool.inputSchema.safeParse({ path: 'doc.md', content: '' }).success).toBe(true)
+	})
+
+	it('refuses a whitespace-only path but not a path with edge whitespace', async () => {
+		expect(WriteFileTool.inputSchema.safeParse({ path: '   ', content: 'body' }).success).toBe(
+			false,
+		)
+
+		// The refusal above must not over-reach: ' fresh.txt ' is a legal name
+		// on every filesystem this runs on, and trimming it would write to a
+		// different file than the caller asked for.
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))
+		const result = await WriteFileTool.execute(
+			{ path: ' fresh.txt ', content: 'hello' },
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(join(dir, ' fresh.txt '), 'utf-8')).toBe('hello')
+	})
+
+	it('rejects an undeclared field even when execute is called directly', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))
+
+		const result = await WriteFileTool.execute(
+			{ path: 'fresh.txt', content: 'hello', append: true } as never,
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('Invalid write input')
+	})
+})
+
 describe('WriteFileTool — read-before-overwrite invariant', () => {
 	it('writes a new file without requiring a prior read', async () => {
 		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))

package/src/tools/builtins/edit.ts

@@ -1,7 +1,8 @@
 import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
+
 import { z } from 'zod'
 import { defineTool } from '../defineTool.js'
+import { resolveWithinReal } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
 import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
@@ -99,12 +100,40 @@ const modelInputSchema: Record<string, unknown> = {
 			description:
 				'Exact replacement text. May be empty to delete old_string. Keep under 12000 characters.',
 		},
+		insertLine: {
+			// The union the execution schema already accepts, stated so a
+			// constrained decoder can emit it. Declaring it as `oneOf` of an
+			// integer and the literal `"end"` also makes the synonym problem
+			// structurally impossible: `"EOF"`, `"append"` and `"last"` are
+			// not emittable, because `"end"` is the only string the schema
+			// admits.
+			oneOf: [{ type: 'integer', minimum: 0 }, { const: 'end' }],
+			description:
+				'Insert instead of replacing. The new_string goes after this 1-indexed line; 0 inserts before the first line; "end" appends. Omit for a find-and-replace.',
+		},
 		replace_all: {
 			type: 'boolean',
 			description: 'Replace every occurrence instead of requiring one unique match.',
 		},
 	},
-	required: ['path', 'old_string', 'new_string'],
+	// `old_string` is deliberately NOT required, and this is the fix.
+	//
+	// The tool's own description tells the model to append with `insertLine`,
+	// and this schema forbade the field while `enforceModelInput` was on — so
+	// the idiom the prompt ordered was the one idiom a constrained model could
+	// not express. Requiring `old_string` reintroduces that, since an insert
+	// has no text to match.
+	//
+	// Which of `old_string` / `insertLine` is present is decided by the two
+	// refinements on the execution schema, which already exist and name what
+	// is missing. That is a deliberate choice over a top-level `oneOf`: strict
+	// structured-output modes are least surprising with a flat object, and a
+	// discriminated union at the root is the construct most likely to be
+	// rejected or quietly ignored by a provider. The cost is that an
+	// incomplete call is now expressible and caught at execution rather than
+	// at generation — paid knowingly, because the alternative is that a
+	// working capability stays unreachable.
+	required: ['path', 'new_string'],
 	additionalProperties: false,
 }
 
@@ -130,7 +159,7 @@ export const EditTool = defineTool({
 	modelInputSchema,
 	enforceModelInput: true,
 	validationErrorHint:
-		'Required shape: {"path":"file.md","old_string":"exact unique text","new_string":"replacement text"}. Optional: "replace_all": true.',
+		'Two shapes. Replace: {"path":"file.md","old_string":"exact unique text","new_string":"replacement text"} (optional "replace_all": true). Insert: {"path":"file.md","insertLine":"end","new_string":"text to add"} where insertLine is a non-negative line number or "end". Exactly one of old_string or insertLine.',
 	category: 'filesystem',
 	permissions: ['file_write'],
 	readOnly: false,
@@ -165,14 +194,20 @@ export const EditTool = defineTool({
 			}
 		}
 
-		const filePath = resolve(context.workingDirectory, parsed.data.path)
+		// Host-side containment, on the host branch only. The sandbox has its
+		// own root and its own resolver; canonicalizing a sandbox-relative
+		// path against the HOST filesystem asks a question about the wrong
+		// machine, and answers it with whatever happens to exist there.
+		const filePath = context.sandbox
+			? undefined
+			: await resolveWithinReal(context.workingDirectory, parsed.data.path)
 		// Read-modify-write is not atomic on its own: two edits to the same
 		// path interleave their reads, and the second write lands on content
 		// the first had already replaced — so one edit vanishes and the loser
 		// reports "old_string not found", blaming the model for a race. The
 		// key spans both branches because sandbox and local are distinct
 		// files even when the path string matches.
-		const lockKey = `${context.sandbox ? 'sandbox' : 'local'}:${filePath}`
+		const lockKey = context.sandbox ? `sandbox:${parsed.data.path}` : `local:${filePath as string}`
 
 		return withFileMutationLock(lockKey, async () => {
 			if (context.sandbox) {
@@ -190,7 +225,8 @@ export const EditTool = defineTool({
 				}
 			}
 
-			const content = await readFile(filePath, 'utf-8')
+			const hostPath = filePath as string
+			const content = await readFile(hostPath, 'utf-8')
 
 			const result = applyEdit(content, normalized.operation)
 			if (!result.success) {
@@ -213,9 +249,9 @@ export const EditTool = defineTool({
 				// changed elsewhere in the file, and refusing there would
 				// reject safe edits every time anyone touched an unrelated
 				// line.
-				const seen = context.fileReadTracker?.fingerprint?.(filePath)
+				const seen = context.fileReadTracker?.fingerprint?.(hostPath)
 				if (seen !== undefined && seen !== fingerprintContent(content)) {
-					return { success: false as const, output: '', error: staleFileError(filePath) }
+					return { success: false as const, output: '', error: staleFileError(hostPath) }
 				}
 				return { success: false as const, output: '', error: result.error }
 			}
@@ -223,15 +259,15 @@ export const EditTool = defineTool({
 			// Temp file, fsync, rename — a reader sees the old body or the new
 			// one, never a half-written one. A plain `writeFile` that fails
 			// partway leaves the user's source truncated.
-			await atomicWriteFile(filePath, result.content)
+			await atomicWriteFile(hostPath, result.content)
 			// This runtime is now the last writer, so the next edit in the same
 			// turn compares against what we just wrote rather than the read
 			// before it.
-			context.fileReadTracker?.recordRead(filePath, result.content)
+			context.fileReadTracker?.recordRead(hostPath, result.content)
 			return {
 				success: true as const,
-				output: `Edited ${filePath}: ${result.replacements} replacement(s)`,
-				data: { path: filePath, replacements: result.replacements },
+				output: `Edited ${hostPath}: ${result.replacements} replacement(s)`,
+				data: { path: hostPath, replacements: result.replacements },
 			}
 		})
 	},
@@ -274,16 +310,35 @@ function normalizeEditInput(
 	}
 }
 
+/**
+ * Spellings of "the end of the file" a model reaches for.
+ *
+ * Liberal here and strict in the schema, which is the right way round: the
+ * schema makes `"end"` the only emittable string for a provider that
+ * constrains, and this catches the rest for one that does not. None of these
+ * is ambiguous — accepting them is not guessing at intent, it is declining to
+ * spend a round trip on a synonym.
+ */
+const END_ALIASES = new Set(['end', 'eof', 'append', 'last', 'end_of_file', 'end-of-file'])
+
 function normalizeInsertLine(
 	value: string | number,
 ): { success: true; value: number | 'end' } | { success: false; error: string } {
 	if (typeof value === 'string') {
-		if (value.trim().toLowerCase() === 'end') return { success: true, value: 'end' }
+		const normalized = value.trim().toLowerCase()
+		// `"end"` is the only spelling the model-facing schema admits, so a
+		// constrained decoder cannot produce anything else. These aliases are
+		// for the providers that do not constrain: a model reading "appends to
+		// the file" reaches for the word it knows, and every one of these says
+		// the same unambiguous thing. Refusing them bought strictness and cost
+		// a full model round trip per occurrence — measured by a consuming host
+		// as the single largest source of tool-call waste in its runs.
+		if (END_ALIASES.has(normalized)) return { success: true, value: 'end' }
 		const parsed = Number(value)
 		if (Number.isInteger(parsed) && parsed >= 0) return { success: true, value: parsed }
 		return {
 			success: false,
-			error: 'insertLine must be a non-negative line number or "end".',
+			error: `insertLine must be a non-negative line number or "end" (also accepted: ${[...END_ALIASES].filter((a) => a !== 'end').join(', ')}). Received ${JSON.stringify(value)}.`,
 		}
 	}
 	return { success: true, value }

package/src/tools/builtins/ls.ts

@@ -1,8 +1,11 @@
 import { readdir, stat } from 'node:fs/promises'
 import { join, relative } from 'node:path'
 import { z } from 'zod'
+import type { Sandbox } from '../../types/sandbox/index.js'
+import type { ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithin } from '../paths.js'
+import { joinPosix, relativePosix, resolveWithinPosix } from '../posix-path.js'
 
 const inputSchema = z.object({
 	path: z.string().default('.').describe('Directory path to list. Defaults to working directory.'),
@@ -105,6 +108,101 @@ async function listRecursive(
 	}
 }
 
+/**
+ * Enumerate inside the sandbox.
+ *
+ * This tool read the HOST filesystem through `node:fs` and referenced
+ * `context.sandbox` nowhere, so with a container or microVM backend wired in
+ * it enumerated the host — in the one builtin whose entire job is telling the
+ * model what exists. `glob` carried the identical defect, was fixed, and its
+ * fix notes that "every sibling builtin already remembers this branch". This
+ * was the sibling that did not, which is why the claim needed checking rather
+ * than reading.
+ *
+ * Worse than a leak on its own: the paths it returned were host-relative,
+ * while `read`, `grep` and `glob` all resolve INSIDE the sandbox. So every
+ * ls-to-read handoff either failed or opened a different file than the one
+ * listed. This returns the sandbox-relative coordinates the others speak.
+ *
+ * `listFiles` reports files, not directories — every backend implements it as
+ * a recursive file walk — so directories are derived from the paths. A
+ * directory holding nothing is therefore invisible here, which is a real
+ * difference from the host branch and the honest cost of having one
+ * enumeration primitive rather than one per backend.
+ */
+async function listInSandbox(
+	input: { path: string; all: boolean; recursive: boolean; max_depth: number },
+	sandbox: Sandbox,
+): Promise<ToolResult> {
+	const root = resolveWithinPosix(sandbox.rootDir, input.path)
+	const entries = await sandbox.listFiles(root)
+
+	// Relative to the LISTED directory, in the sandbox's own coordinates.
+	const relativePaths: { segments: string[]; size: number }[] = []
+	for (const entry of entries) {
+		const rel = relativePosix(root, joinPosix(root, entry.path))
+		if (!rel || rel.startsWith('..')) continue
+		const segments = rel.split('/').filter(Boolean)
+		if (segments.length === 0) continue
+		if (!input.all && segments.some((s) => s.startsWith('.'))) continue
+		relativePaths.push({ segments, size: entry.size })
+	}
+
+	if (!input.recursive) {
+		// One level: a single segment is a file, more than one means the
+		// first segment is a directory.
+		const files = new Map<string, number>()
+		const dirs = new Set<string>()
+		for (const { segments, size } of relativePaths) {
+			const head = segments[0] as string
+			if (segments.length === 1) files.set(head, size)
+			else dirs.add(head)
+		}
+
+		const lines = [
+			...[...dirs].sort().map((name) => `${name}/`),
+			...[...files.entries()]
+				.sort(([a], [b]) => a.localeCompare(b))
+				.map(([name, size]) => `${name}\t${formatSize(size)}`),
+		]
+
+		return {
+			success: true,
+			output: lines.length > 0 ? lines.join('\n') : '(empty directory)',
+			data: { count: lines.length, sandboxed: true },
+		}
+	}
+
+	const seenDirs = new Set<string>()
+	const lines: string[] = []
+	let count = 0
+	for (const { segments, size } of relativePaths.sort((a, b) =>
+		a.segments.join('/').localeCompare(b.segments.join('/')),
+	)) {
+		if (segments.length > input.max_depth) continue
+		// Emit each parent directory once, before anything inside it.
+		for (let depth = 1; depth < segments.length; depth++) {
+			const dir = segments.slice(0, depth).join('/')
+			if (seenDirs.has(dir)) continue
+			seenDirs.add(dir)
+			if (count >= MAX_ENTRIES) break
+			lines.push(`./${dir}/`)
+			count++
+		}
+		if (count >= MAX_ENTRIES) break
+		lines.push(`./${segments.join('/')} (${formatSize(size)})`)
+		count++
+	}
+
+	const truncated = count >= MAX_ENTRIES ? `\n(truncated at ${MAX_ENTRIES} entries)` : ''
+
+	return {
+		success: true,
+		output: lines.length > 0 ? lines.join('\n') + truncated : '(empty directory)',
+		data: { count, truncated: count >= MAX_ENTRIES, sandboxed: true },
+	}
+}
+
 export const LsTool = defineTool({
 	name: 'ls',
 	description:
@@ -117,6 +215,10 @@ export const LsTool = defineTool({
 	concurrencySafe: true,
 
 	async execute(input, context) {
+		if (context.sandbox) {
+			return await listInSandbox(input, context.sandbox)
+		}
+
 		// Contained, not merely resolved — see `resolveWithin`.
 		const targetPath = resolveWithin(context.workingDirectory, input.path)
 

package/src/tools/builtins/read-file.ts

@@ -1,7 +1,8 @@
 import { readFile } from 'node:fs/promises'
-import { extname, resolve } from 'node:path'
+import { extname } from 'node:path'
 import { z } from 'zod'
 import { defineTool } from '../defineTool.js'
+import { resolveWithinReal } from '../paths.js'
 
 const inputSchema = z.object({
 	path: z.string().describe('Path to the file to read (absolute or relative)'),
@@ -74,7 +75,7 @@ export const ReadFileTool = defineTool({
 			}
 		}
 
-		const filePath = resolve(context.workingDirectory, input.path)
+		const filePath = await resolveWithinReal(context.workingDirectory, input.path)
 		const buffer = await readFile(filePath)
 		const binaryGuidance = describeStructuredBinaryRead(filePath, buffer)
 		if (binaryGuidance) {

package/src/tools/builtins/write-file.ts

@@ -1,8 +1,9 @@
 import { access, mkdir } from 'node:fs/promises'
-import { dirname, resolve } from 'node:path'
+import { dirname } from 'node:path'
 import { z } from 'zod'
 import type { ToolContext } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
+import { resolveWithinReal } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
 
@@ -11,6 +12,12 @@ const inputSchema = z
 		path: z
 			.string()
 			.min(1)
+			// `.min(1)` alone admits `"   "`, which resolves to the working
+			// directory itself and turns a write into a directory-write error
+			// nobody can read. `edit` has refused this since it was written;
+			// the two tools disagreeing on the same input is the kind of gap a
+			// model finds and a reviewer does not.
+			.refine((value) => value.trim().length > 0, 'Path must not be empty.')
 			.describe(
 				'Relative path to the file to write (e.g. "outputs/report.md"). Required. Must be a non-empty string.',
 			),
@@ -87,11 +94,17 @@ export const WriteFileTool = defineTool({
 		}
 		const valid = parsed.data
 		const content = valid.content ?? valid.newStr ?? ''
-		const filePath = resolve(context.workingDirectory, valid.path)
+		// Host-side containment, on the host branch only. The sandbox has its
+		// own root and its own resolver; canonicalizing a sandbox-relative
+		// path against the HOST filesystem asks a question about the wrong
+		// machine and answers it with whatever happens to exist there.
+		const filePath = context.sandbox
+			? undefined
+			: await resolveWithinReal(context.workingDirectory, valid.path)
 		// The exists-check and the write are a check-then-act pair. Unlocked,
 		// two writers both see "absent", both skip the read-before-overwrite
 		// guard, and the second silently discards the first.
-		const lockKey = `${context.sandbox ? 'sandbox' : 'local'}:${filePath}`
+		const lockKey = context.sandbox ? `sandbox:${valid.path}` : `local:${filePath as string}`
 
 		return withFileMutationLock(lockKey, async () => {
 			if (context.sandbox) {
@@ -109,23 +122,24 @@ export const WriteFileTool = defineTool({
 				}
 			}
 
-			const localExists = await pathExists(filePath)
+			const hostPath = filePath as string
+			const localExists = await pathExists(hostPath)
 			if (localExists) {
-				const guard = enforceReadBeforeOverwrite(context, filePath)
+				const guard = enforceReadBeforeOverwrite(context, hostPath)
 				if (guard) return guard
 			}
 
-			await mkdir(dirname(filePath), { recursive: true })
+			await mkdir(dirname(hostPath), { recursive: true })
 			// Temp file, fsync, rename. A plain write that fails partway
 			// leaves the destination truncated — and this tool overwrites a
 			// whole file, so the truncation is the user's previous work.
-			await atomicWriteFile(filePath, content)
-			context.fileReadTracker?.recordRead(filePath)
+			await atomicWriteFile(hostPath, content)
+			context.fileReadTracker?.recordRead(hostPath)
 
 			return {
 				success: true as const,
-				output: `File written successfully: ${filePath} (${content.length} chars)`,
-				data: { path: filePath, size: content.length },
+				output: `File written successfully: ${hostPath} (${content.length} chars)`,
+				data: { path: hostPath, size: content.length },
 			}
 		})
 	},
@@ -144,9 +158,9 @@ function enforceReadBeforeOverwrite(
 	}
 }
 
-async function pathExists(filePath: string): Promise<boolean> {
+async function pathExists(hostPath: string): Promise<boolean> {
 	try {
-		await access(filePath)
+		await access(hostPath)
 		return true
 	} catch {
 		return false