@namzu/sdk 1.4.0 → 2.0.0

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

@@ -1,10 +1,11 @@
-import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
-import { zodToJsonSchema } from 'zod-to-json-schema'
 import { ToolRegistry } from '../../../registry/tool/execute.js'
+import type { Sandbox } from '../../../types/sandbox/index.js'
 import type { ToolContext } from '../../../types/tool/index.js'
+import { atomicWriteFile } from '../atomic-write-file.js'
 import { EditTool } from '../edit.js'
 
 function makeContext(workingDirectory: string): ToolContext {
@@ -18,12 +19,75 @@ function makeContext(workingDirectory: string): ToolContext {
 }
 
 describe('EditTool', () => {
-	it('accepts oldStr/newStr aliases for string replacement', async () => {
+	it('publishes one closed canonical replacement contract', () => {
+		const schema = EditTool.modelInputSchema
+		expect(schema).toEqual({
+			type: 'object',
+			properties: {
+				path: {
+					type: 'string',
+					description: 'Path to the file to edit. Must not be empty.',
+				},
+				old_string: {
+					type: 'string',
+					description:
+						'Exact unique text from the file, without read-tool line-number prefixes. Must not be empty.',
+				},
+				new_string: {
+					type: 'string',
+					description:
+						'Exact replacement text. May be empty to delete old_string. Keep under 12000 characters.',
+				},
+				replace_all: {
+					type: 'boolean',
+					description: 'Replace every occurrence instead of requiring one unique match.',
+				},
+			},
+			required: ['path', 'old_string', 'new_string'],
+			additionalProperties: false,
+		})
+
+		expect(
+			EditTool.inputSchema.safeParse({
+				path: 'doc.md',
+				old_string: 'old',
+				new_string: 'new',
+				replace_all: true,
+			}).success,
+		).toBe(true)
+
+		for (const legacy of [
+			{ path: 'doc.md', oldStr: 'old', newStr: 'new' },
+			{ path: 'doc.md', insertLine: 'end', new_string: 'append' },
+			{
+				path: 'doc.md',
+				old_string: 'old',
+				new_string: 'new',
+				newStr: 'legacy',
+			},
+		]) {
+			expect(EditTool.inputSchema.safeParse(legacy).success, JSON.stringify(legacy)).toBe(false)
+		}
+		expect(
+			EditTool.inputSchema.safeParse({
+				path: '   ',
+				old_string: 'old',
+				new_string: 'new',
+			}).success,
+		).toBe(false)
+	})
+
+	it('replaces one exact unique string', async () => {
 		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
 		writeFileSync(join(dir, 'doc.md'), 'alpha\nbeta\n')
 
 		const result = await EditTool.execute(
-			{ path: 'doc.md', oldStr: 'beta', newStr: 'gamma', replace_all: false },
+			{
+				path: 'doc.md',
+				old_string: 'beta',
+				new_string: 'gamma',
+				replace_all: false,
+			},
 			makeContext(dir),
 		)
 
@@ -31,25 +95,36 @@ describe('EditTool', () => {
 		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\ngamma\n')
 	})
 
-	it('inserts content after a 1-indexed line number', async () => {
+	it('validates a path without rewriting edge whitespace', async () => {
 		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
-		writeFileSync(join(dir, 'doc.md'), 'alpha\nbeta\n')
+		writeFileSync(join(dir, ' doc.md '), 'alpha\n')
 
 		const result = await EditTool.execute(
-			{ path: 'doc.md', insertLine: 1, newStr: 'inserted', replace_all: false },
+			{
+				path: ' doc.md ',
+				old_string: 'alpha',
+				new_string: 'beta',
+				replace_all: false,
+			},
 			makeContext(dir),
 		)
 
 		expect(result.success).toBe(true)
-		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\ninserted\nbeta\n')
+		expect(readFileSync(join(dir, ' doc.md '), 'utf-8')).toBe('beta\n')
+		expect(existsSync(join(dir, 'doc.md'))).toBe(false)
 	})
 
-	it('inserts content at the end with insertLine=end', async () => {
+	it('allows deletion with an empty new_string', async () => {
 		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
-		writeFileSync(join(dir, 'doc.md'), 'alpha\n')
+		writeFileSync(join(dir, 'doc.md'), 'alpha\nremove me\nomega\n')
 
 		const result = await EditTool.execute(
-			{ path: 'doc.md', insertLine: 'end', newStr: 'omega', replace_all: false },
+			{
+				path: 'doc.md',
+				old_string: 'remove me\n',
+				new_string: '',
+				replace_all: false,
+			},
 			makeContext(dir),
 		)
 
@@ -57,77 +132,186 @@ describe('EditTool', () => {
 		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\nomega\n')
 	})
 
-	it('publishes only the insertLine values the executor can apply', () => {
-		for (const insertLine of ['## Progress', null, '', '1', -1]) {
-			const parsed = EditTool.inputSchema.safeParse({
+	it('replaces every exact occurrence only when replace_all is true', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha alpha alpha')
+
+		const result = await EditTool.execute(
+			{
 				path: 'doc.md',
-				insertLine,
-				newStr: 'inserted',
-			})
-			expect(parsed.success, JSON.stringify(insertLine)).toBe(false)
-		}
+				old_string: 'alpha',
+				new_string: 'beta',
+				replace_all: true,
+			},
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(result.data).toMatchObject({ replacements: 3 })
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('beta beta beta')
+	})
+
+	it('refuses ambiguous exact matches instead of guessing', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\nalpha\n')
 
-		for (const insertLine of [0, 1, 'end']) {
-			const parsed = EditTool.inputSchema.safeParse({
+		const result = await EditTool.execute(
+			{
 				path: 'doc.md',
-				insertLine,
-				newStr: 'inserted',
-			})
-			expect(parsed.success, JSON.stringify(insertLine)).toBe(true)
-		}
+				old_string: 'alpha',
+				new_string: 'beta',
+				replace_all: false,
+			},
+			makeContext(dir),
+		)
 
-		const json = zodToJsonSchema(EditTool.inputSchema, {
-			target: 'jsonSchema7',
-			$refStrategy: 'none',
-		}) as {
-			properties?: {
-				insertLine?: {
-					anyOf?: Record<string, unknown>[]
-				}
-			}
-		}
-		expect(json.properties?.insertLine?.anyOf).toEqual([
-			{ type: 'integer', minimum: 0 },
-			{ type: 'string', const: 'end' },
-		])
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('old_string is not unique')
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\nalpha\n')
 	})
 
-	it('refuses invalid insertLine values even when a caller bypasses the schema', async () => {
-		for (const insertLine of ['## Progress', null, '', '1']) {
-			const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
-			writeFileSync(join(dir, 'doc.md'), 'alpha\nbeta\n')
-
-			const result = await EditTool.execute(
-				{
-					path: 'doc.md',
-					insertLine,
-					newStr: 'inserted',
-					replace_all: false,
-				} as never,
-				makeContext(dir),
-			)
-
-			expect(result.success, JSON.stringify(insertLine)).toBe(false)
-			expect(result.error).toBe('insertLine must be a non-negative line number or "end".')
-			expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\nbeta\n')
+	it('normalizes consistent CRLF/LF boundaries without fuzzy matching', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\r\nbeta\r\nomega\r\n')
+
+		const result = await EditTool.execute(
+			{
+				path: 'doc.md',
+				old_string: 'alpha\nbeta',
+				new_string: 'gamma\ndelta',
+				replace_all: false,
+			},
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('gamma\r\ndelta\r\nomega\r\n')
+	})
+
+	it('rejects legacy and extra fields even when execute is called directly', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\n')
+
+		for (const input of [
+			{ path: 'doc.md', oldStr: 'alpha', newStr: 'beta' },
+			{
+				path: 'doc.md',
+				old_string: 'alpha',
+				new_string: 'beta',
+				insertLine: 'end',
+			},
+		]) {
+			const result = await EditTool.execute(input as never, makeContext(dir))
+			expect(result.success, JSON.stringify(input)).toBe(false)
+			expect(result.error).toContain('Invalid edit input')
 		}
+
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\n')
 	})
 
-	it('returns complete recovery shapes when path is missing and insertLine is invalid', async () => {
+	it('returns one canonical recovery shape after registry validation fails', async () => {
 		const registry = new ToolRegistry()
 		registry.register(EditTool)
 
 		const result = await registry.execute(
 			'edit',
-			{ insertLine: '## Progress' },
+			{ insertLine: '"end"', newStr: 'content' },
 			makeContext('/tmp'),
 		)
 
 		expect(result.success).toBe(false)
 		expect(result.error).toContain('Validation failed for "edit":')
-		expect(result.error).toContain('insertLine: Invalid input')
-		expect(result.error).toContain('Required: path: string — Path to the file to edit.')
-		expect(result.error).toContain('{"path":"file.md","insertLine":"end","new_string":"text"}')
-		expect(result.error).toContain('{"path":"file.md","old_string":"old","new_string":"new"}')
+		expect(result.error).toContain('Required: path: string')
+		expect(result.error).toContain(
+			'{"path":"file.md","old_string":"exact unique text","new_string":"replacement text"}',
+		)
+		expect(result.error).not.toContain('Accepted shapes')
+	})
+
+	it('serializes independent EditTool read-modify-write cycles for one sandbox path', async () => {
+		let body = Buffer.from('alpha')
+		let reads = 0
+		let writes = 0
+		let releaseFirstWrite = () => {}
+		let markFirstWriteStarted = () => {}
+		const firstWriteStarted = new Promise<void>((resolve) => {
+			markFirstWriteStarted = resolve
+		})
+		const firstWriteGate = new Promise<void>((resolve) => {
+			releaseFirstWrite = resolve
+		})
+		const sandbox = {
+			id: 'sbx_edit_lock',
+			status: 'ready',
+			rootDir: '/workspace',
+			environment: 'basic',
+			async readFile() {
+				reads += 1
+				return Buffer.from(body)
+			},
+			async writeFile(_path: string, content: string | Buffer) {
+				writes += 1
+				if (writes === 1) {
+					markFirstWriteStarted()
+					await firstWriteGate
+				}
+				body = Buffer.isBuffer(content) ? Buffer.from(content) : Buffer.from(content)
+			},
+			async exec() {
+				throw new Error('not used')
+			},
+			async listFiles() {
+				return []
+			},
+			async destroy() {},
+		} as Sandbox
+		const firstContext = { ...makeContext('/workspace'), sandbox }
+		const secondContext = { ...makeContext('/workspace'), sandbox }
+
+		const first = EditTool.execute(
+			{
+				path: 'doc.md',
+				old_string: 'alpha',
+				new_string: 'beta',
+				replace_all: false,
+			},
+			firstContext,
+		)
+		await firstWriteStarted
+		const second = EditTool.execute(
+			{
+				path: 'doc.md',
+				old_string: 'beta',
+				new_string: 'gamma',
+				replace_all: false,
+			},
+			secondContext,
+		)
+		await Promise.resolve()
+		expect(reads).toBe(1)
+
+		releaseFirstWrite()
+		const results = await Promise.all([first, second])
+		expect(results.every((result) => result.success)).toBe(true)
+		expect(reads).toBe(2)
+		expect(writes).toBe(2)
+		expect(body.toString('utf-8')).toBe('gamma')
+	})
+
+	it('leaves the original intact when an atomic local write fails before commit', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-atomic-write-'))
+		const filePath = join(dir, 'doc.md')
+		writeFileSync(filePath, 'original')
+
+		await expect(
+			atomicWriteFile(filePath, 'replacement', {
+				beforeCommit: async () => {
+					throw new Error('injected pre-commit failure')
+				},
+			}),
+		).rejects.toThrow('injected pre-commit failure')
+
+		expect(readFileSync(filePath, 'utf-8')).toBe('original')
+		expect(readdirSync(dir).filter((entry) => entry.includes('.namzu-'))).toEqual([])
 	})
 })

package/src/tools/builtins/__tests__/payload-budget.test.ts

@@ -17,8 +17,8 @@ describe('filesystem tool payload budgeting', () => {
 		expect(() =>
 			EditTool.inputSchema.parse({
 				path: 'outputs/long.md',
-				oldStr: '{{SECTION}}',
-				newStr: oversized,
+				old_string: '{{SECTION}}',
+				new_string: oversized,
 				replace_all: false,
 			}),
 		).not.toThrow()
@@ -31,7 +31,7 @@ describe('filesystem tool payload budgeting', () => {
 		expect(names).not.toContain('append')
 	})
 
-	it('assembles long documents with bounded write plus edit insert chunks', async () => {
+	it('assembles replay-safe long documents by advancing an exact marker', async () => {
 		const dir = mkdtempSync(join(tmpdir(), 'namzu-long-doc-'))
 		const ctx: ToolContext = {
 			runId: 'run_test' as ToolContext['runId'],
@@ -40,12 +40,12 @@ describe('filesystem tool payload budgeting', () => {
 			env: {},
 			log: () => {},
 		}
-		const opening = '# Long document regression\n\n{{BODY}}\n'
+		const opening = '# Long document regression\n\n{{CHUNK_001}}\n'
 		const chunks = Array.from({ length: 6 }, (_, sectionIndex) => {
 			const lines = Array.from({ length: 45 }, (_, lineIndex) => {
 				const section = sectionIndex + 1
 				const line = lineIndex + 1
-				return `Section ${section}.${line}: this bounded paragraph proves long-form output grows through edit insertions rather than one oversized JSON tool argument.`
+				return `Section ${section}.${line}: this bounded paragraph proves long-form output grows through exact marker edits rather than one oversized JSON tool argument.`
 			})
 			const chunk = [`## Section ${sectionIndex + 1}`, ...lines, ''].join('\n')
 			expect(chunk.length).toBeLessThan(12_000)
@@ -58,32 +58,52 @@ describe('filesystem tool payload budgeting', () => {
 		)
 		expect(writeResult.success).toBe(true)
 
-		const firstEdit = await EditTool.execute(
-			{
-				path: 'outputs/regression-long-document.md',
-				oldStr: '{{BODY}}',
-				newStr: chunks[0],
-				replace_all: false,
-			},
-			ctx,
-		)
-		expect(firstEdit.success).toBe(true)
-
-		for (const chunk of chunks.slice(1)) {
+		for (const [index, chunk] of chunks.entries()) {
+			const currentMarker = `{{CHUNK_${String(index + 1).padStart(3, '0')}}}`
+			const nextMarker = `{{CHUNK_${String(index + 2).padStart(3, '0')}}}`
 			const result = await EditTool.execute(
 				{
 					path: 'outputs/regression-long-document.md',
-					insertLine: 'end',
-					newStr: chunk,
+					old_string: currentMarker,
+					new_string: `${chunk}\n${nextMarker}`,
 					replace_all: false,
 				},
 				ctx,
 			)
 			expect(result.success).toBe(true)
+
+			if (index === 0) {
+				const beforeReplay = readFileSync(join(dir, 'outputs/regression-long-document.md'), 'utf-8')
+				const replay = await EditTool.execute(
+					{
+						path: 'outputs/regression-long-document.md',
+						old_string: currentMarker,
+						new_string: `${chunk}\n${nextMarker}`,
+						replace_all: false,
+					},
+					ctx,
+				)
+				expect(replay.success).toBe(false)
+				expect(readFileSync(join(dir, 'outputs/regression-long-document.md'), 'utf-8')).toBe(
+					beforeReplay,
+				)
+			}
 		}
 
+		const finalMarker = `{{CHUNK_${String(chunks.length + 1).padStart(3, '0')}}}`
+		const finalize = await EditTool.execute(
+			{
+				path: 'outputs/regression-long-document.md',
+				old_string: finalMarker,
+				new_string: '',
+				replace_all: false,
+			},
+			ctx,
+		)
+		expect(finalize.success).toBe(true)
+
 		const final = readFileSync(join(dir, 'outputs/regression-long-document.md'), 'utf-8')
-		expect(final).not.toContain('{{BODY}}')
+		expect(final).not.toContain('{{CHUNK_')
 		expect(final.split('\n').length).toBeGreaterThan(250)
 		expect(final).toContain('## Section 1')
 		expect(final).toContain('## Section 6')

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

@@ -8,10 +8,10 @@ import { WriteFileTool } from '../write-file.js'
 function makeTracker(): FileReadTracker & { keys(): string[] } {
 	const set = new Set<string>()
 	return {
-		recordRead: (k) => {
-			set.add(k)
+		recordRead: (key) => {
+			set.add(key)
 		},
-		hasRead: (k) => set.has(k),
+		hasRead: (key) => set.has(key),
 		keys: () => Array.from(set),
 	}
 }
@@ -27,7 +27,33 @@ function makeContext(workingDirectory: string, tracker?: FileReadTracker): ToolC
 	}
 }
 
-describe('WriteFileTool — read-before-overwrite invariant', () => {
+describe('WriteFileTool — canonical contract and read-before-overwrite invariant', () => {
+	it('publishes one closed path + content contract', () => {
+		expect(WriteFileTool.modelInputSchema).toEqual({
+			type: 'object',
+			properties: {
+				path: {
+					type: 'string',
+					description: 'Non-empty path to the file to write.',
+				},
+				content: {
+					type: 'string',
+					description:
+						'Complete bounded file body. May be empty only for an intentionally empty file.',
+				},
+			},
+			required: ['path', 'content'],
+			additionalProperties: false,
+		})
+		expect(WriteFileTool.inputSchema.safeParse({ path: 'doc.md', content: '' }).success).toBe(true)
+		expect(WriteFileTool.inputSchema.safeParse({ path: 'doc.md', newStr: 'legacy' }).success).toBe(
+			false,
+		)
+		expect(WriteFileTool.inputSchema.safeParse({ path: '   ', content: 'body' }).success).toBe(
+			false,
+		)
+	})
+
 	it('writes a new file without requiring a prior read', async () => {
 		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))
 		const tracker = makeTracker()
@@ -40,15 +66,28 @@ describe('WriteFileTool — read-before-overwrite invariant', () => {
 		expect(tracker.hasRead(join(dir, 'fresh.txt'))).toBe(true)
 	})
 
-	it('accepts newStr as the canonical create/write content alias', async () => {
+	it('preserves edge whitespace in a valid path', async () => {
 		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))
-		const tracker = makeTracker()
-		const ctx = makeContext(dir, tracker)
 
-		const result = await WriteFileTool.execute({ path: 'fresh.txt', newStr: 'hello' }, ctx)
+		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')
+		expect(readFileSync(join(dir, ' fresh.txt '), 'utf-8')).toBe('hello')
+	})
+
+	it('rejects legacy content aliases even when execute is called directly', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))
+
+		const result = await WriteFileTool.execute(
+			{ path: 'fresh.txt', newStr: 'legacy' } as never,
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('Invalid write input')
 	})
 
 	it('refuses to overwrite an existing file the agent has not read', async () => {
@@ -84,14 +123,14 @@ describe('WriteFileTool — read-before-overwrite invariant', () => {
 		expect(readFileSync(filePath, 'utf-8')).toBe('replaced')
 	})
 
-	it('falls back to legacy behaviour when no fileReadTracker is provided (back-compat)', async () => {
+	it('preserves existing hosts without a file read tracker', async () => {
 		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))
-		writeFileSync(join(dir, 'legacy.txt'), 'before')
+		writeFileSync(join(dir, 'existing.txt'), 'before')
 		const ctx = makeContext(dir)
 
-		const result = await WriteFileTool.execute({ path: 'legacy.txt', content: 'after' }, ctx)
+		const result = await WriteFileTool.execute({ path: 'existing.txt', content: 'after' }, ctx)
 
 		expect(result.success).toBe(true)
-		expect(readFileSync(join(dir, 'legacy.txt'), 'utf-8')).toBe('after')
+		expect(readFileSync(join(dir, 'existing.txt'), 'utf-8')).toBe('after')
 	})
 })

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

@@ -0,0 +1,58 @@
+import { randomUUID } from 'node:crypto'
+import { type FileHandle, mkdir, open, rename, stat, unlink } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+
+interface AtomicWriteHooks {
+	/** Internal fault-injection seam; production callers never pass this. */
+	beforeCommit?: () => Promise<void>
+}
+
+/**
+ * Commit a complete file body without exposing a truncated destination.
+ *
+ * The temp file lives beside the destination so rename stays on one
+ * filesystem. A failed pre-commit write leaves the original untouched.
+ */
+export async function atomicWriteFile(
+	filePath: string,
+	content: string,
+	hooks: AtomicWriteHooks = {},
+): Promise<void> {
+	const directory = dirname(filePath)
+	await mkdir(directory, { recursive: true })
+
+	const existingMode = await stat(filePath)
+		.then((value) => value.mode)
+		.catch(() => undefined)
+	const tempPath = join(
+		directory,
+		`.${basename(filePath)}.namzu-${process.pid}-${randomUUID()}.tmp`,
+	)
+	let handle: FileHandle | undefined
+	let committed = false
+
+	try {
+		handle = await open(tempPath, 'wx', existingMode ?? 0o666)
+		await handle.writeFile(content, 'utf-8')
+		await handle.sync()
+		await handle.close()
+		handle = undefined
+		await hooks.beforeCommit?.()
+		await rename(tempPath, filePath)
+		committed = true
+		await syncDirectory(directory)
+	} finally {
+		await handle?.close().catch(() => undefined)
+		if (!committed) await unlink(tempPath).catch(() => undefined)
+	}
+}
+
+async function syncDirectory(directory: string): Promise<void> {
+	let handle: FileHandle | undefined
+	try {
+		handle = await open(directory, 'r')
+		await handle.sync()
+	} finally {
+		await handle?.close().catch(() => undefined)
+	}
+}

package/src/tools/builtins/bash.ts

@@ -22,7 +22,7 @@ const inputSchema = z.object({
 		.string()
 		.min(1)
 		.describe(
-			'The bash command to execute. Required, non-empty. Single command per call (use `&&` / `;` chaining for compound commands). Avoid heredocs that span more than a few hundred bytes — large content should be created with `write`, then extended with `edit` insertLine: "end", not piped into bash.',
+			'The bash command to execute. Required, non-empty. Single command per call (use `&&` / `;` chaining for compound commands). Avoid heredocs that span more than a few hundred bytes — create large content with bounded write plus exact marker-advancing edit calls instead.',
 		),
 	timeout: z
 		.preprocess(
@@ -41,7 +41,7 @@ function isDangerousCommand(command: string): boolean {
 export const BashTool = defineTool({
 	name: 'bash',
 	description:
-		'Executes a bash command and returns stdout/stderr output. Command timeout is configurable. The `command` parameter is required — never call this tool with empty arguments. For very long content (e.g. building a large file), prefer `write` for the opening and `edit` with insertLine: "end" for follow-up chunks over a heredoc to avoid hitting the output token limit mid-stream.',
+		'Executes a bash command and returns stdout/stderr output. Command timeout is configurable. The `command` parameter is required — never call this tool with empty arguments. For very long content, prefer a bounded write with a deterministic marker followed by exact marker-advancing edit calls over a heredoc.',
 	inputSchema,
 	category: 'shell',
 	permissions: ['shell_execute'],