@namzu/sdk 2.0.0 → 3.0.0

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

@@ -23,7 +23,7 @@ const inputSchema = z.object({
 export const ReadFileTool = defineTool({
 	name: 'read',
 	description:
-		'Reads a file and returns its contents with line numbers. Supports readRange ([start,end], 1-indexed inclusive) or offset/limit for large files.',
+		'Reads a file and returns its contents with line numbers. Supports readRange ([start,end], 1-indexed inclusive) or offset/limit for large files. Without a window it returns the first 2000 lines and says so — pass offset/limit to continue.',
 	inputSchema,
 	category: 'filesystem',
 	permissions: ['file_read'],
@@ -57,12 +57,14 @@ export const ReadFileTool = defineTool({
 
 			context.fileReadTracker?.recordRead(input.path)
 
+			const partial = selectedLines.length < lines.length
 			return {
 				success: true,
-				output: numberedLines,
+				output: numberedLines + partialViewNotice(start, selectedLines.length, lines.length),
 				data: {
 					totalLines: lines.length,
 					returnedLines: selectedLines.length,
+					truncated: partial,
 					path: input.path,
 					sandboxed: true,
 				},
@@ -92,12 +94,15 @@ export const ReadFileTool = defineTool({
 
 		context.fileReadTracker?.recordRead(filePath)
 
+		const isPartial = selectedLines.length < lines.length
+
 		return {
 			success: true,
-			output: numberedLines,
+			output: numberedLines + partialViewNotice(start, selectedLines.length, lines.length),
 			data: {
 				totalLines: lines.length,
 				returnedLines: selectedLines.length,
+				truncated: isPartial,
 				path: filePath,
 			},
 		}
@@ -128,6 +133,34 @@ function buildStructuredBinaryGuidance(path: string, format: string, extractor:
 	].join('\n')
 }
 
+/**
+ * Lines returned when the caller specifies no window.
+ *
+ * Chosen to cover the overwhelming majority of source files whole while
+ * bounding the pathological case.
+ */
+const DEFAULT_READ_LINES = 2000
+
+/**
+ * Tell the model, explicitly, when it is looking at a window rather than
+ * the file.
+ *
+ * Without this a truncated read is indistinguishable from a short file, and
+ * the agent reasons about a fragment as if it were the whole thing — the
+ * most expensive silent failure a read tool can have. The notice names the
+ * exact next call rather than describing it.
+ */
+function partialViewNotice(start: number, returned: number, total: number): string {
+	if (returned >= total) return ''
+	const shownTo = start + returned
+	return [
+		'',
+		'',
+		`[PARTIAL view — lines ${start + 1}-${shownTo} of ${total}.`,
+		`Continue with read({ offset: ${shownTo}, limit: N }), or narrow with grep.]`,
+	].join('\n')
+}
+
 function resolveReadWindow(
 	input: z.infer<typeof inputSchema>,
 	totalLines: number,
@@ -139,6 +172,9 @@ function resolveReadWindow(
 		return { start, end }
 	}
 	const start = Math.max(0, input.offset ?? 0)
-	const end = input.limit ? start + input.limit : totalLines
+	// A bare `read({ path })` used to return the entire file, so a 2 MB
+	// lockfile became ~500k tokens in one tool_result. Default to a window
+	// and say so in the output; the model asks for more when it needs it.
+	const end = input.limit ? start + input.limit : Math.min(totalLines, start + DEFAULT_READ_LINES)
 	return { start, end }
 }

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

@@ -1,53 +1,41 @@
-import { access } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { access, mkdir, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
 import { z } from 'zod'
 import type { ToolContext } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
-import { atomicWriteFile } from './atomic-write-file.js'
-import { withFileMutationLock } from './file-mutation-lock.js'
 
 const inputSchema = z
 	.object({
 		path: z
 			.string()
-			.refine((value) => value.trim().length > 0, 'Path must not be empty.')
+			.min(1)
 			.describe(
-				'Relative path to the file to write (e.g. "outputs/report.md"). Must not be empty.',
+				'Relative path to the file to write (e.g. "outputs/report.md"). Required. Must be a non-empty string.',
 			),
 		content: z
 			.string()
+			.optional()
 			.describe(
-				'Complete bounded file body. Use "" only for an intentionally empty file. Keep under 12000 characters. For longer documents, include a deterministic marker such as {{CHUNK_001}} and advance it with exact edit calls.',
+				'Full file body to write. Required (use "" only for an intentionally empty file). The file is fully overwritten — pass the COMPLETE intended content for this bounded chunk, not a diff. Self-budget content under 12000 characters before calling; if the intended body is longer, write a smaller opening section here, then use `edit` with insertLine: "end" to extend the file section by section. Do NOT try to chain multiple `write` calls, since each one overwrites the previous.',
+			),
+		newStr: z
+			.string()
+			.optional()
+			.describe(
+				'Alias for content. Useful for hosts that expose create/write operations as newStr. Self-budget this payload under 12000 characters before calling.',
 			),
 	})
-	.strict()
+	.refine((value) => typeof value.content === 'string' || typeof value.newStr === 'string', {
+		message: 'Either content or newStr is required.',
+	})
 
 type WriteInput = z.infer<typeof inputSchema>
 
-const modelInputSchema: Record<string, unknown> = {
-	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,
-}
-
 export const WriteFileTool = defineTool({
 	name: 'write',
 	description:
-		'Writes a complete bounded file body. Pass exactly path + content. If the file exists, read it first; prefer edit for targeted changes. Self-budget content under 12000 characters. For longer documents, write an opening with a deterministic marker such as {{CHUNK_001}}, then use exact edit calls that advance the marker one chunk at a time. Do not chain write calls because each overwrites the file.',
+		'Writes a file to the local filesystem. Overwrites the existing file at the path if there is one.\n\n- If the file already exists, you must use the `read` tool on it first in this conversation, or this call will fail.\n- Prefer the `edit` tool for modifying existing files — it only sends the diff and preserves the rest of the file byte-for-byte.\n- Use `write` to create a new file or to perform a deliberate full rewrite of a file you have already read.\n- Self-budget content/newStr under 12000 characters before emitting the tool call. For long content, write a smaller opening section, then use `edit` with insertLine: "end" to extend the file section by section. Do not chain multiple `write` calls — each one overwrites the previous.',
 	inputSchema,
-	modelInputSchema,
-	enforceModelInput: true,
-	validationErrorHint: 'Required shape: {"path":"file.md","content":"complete bounded file body"}.',
 	category: 'filesystem',
 	permissions: ['file_write'],
 	readOnly: false,
@@ -55,52 +43,40 @@ export const WriteFileTool = defineTool({
 	concurrencySafe: false,
 
 	async execute(input: WriteInput, context) {
-		const parsed = inputSchema.safeParse(input)
-		if (!parsed.success) {
+		const content = input.content ?? input.newStr ?? ''
+		// Sandbox-aware: route through sandbox.writeFile() when available
+		if (context.sandbox) {
+			const sandboxExists = await sandboxFileExists(context, input.path)
+			if (sandboxExists) {
+				const guard = enforceReadBeforeOverwrite(context, input.path)
+				if (guard) return guard
+			}
+			await context.sandbox.writeFile(input.path, content)
+			context.fileReadTracker?.recordRead(input.path)
 			return {
-				success: false,
-				output: '',
-				error: `Invalid write input: ${parsed.error.issues.map((issue) => issue.message).join('; ')}`,
+				success: true,
+				output: `File written successfully: ${input.path} (${content.length} chars) [sandboxed]`,
+				data: { path: input.path, size: content.length, sandboxed: true },
 			}
 		}
-		const canonicalInput = parsed.data
 
-		const filePath = resolve(context.workingDirectory, canonicalInput.path)
-		const lockKey = `${context.sandbox ? 'sandbox' : 'local'}:${filePath}`
-		return withFileMutationLock(lockKey, async () => {
-			if (context.sandbox) {
-				const sandboxExists = await sandboxFileExists(context, canonicalInput.path)
-				if (sandboxExists) {
-					const guard = enforceReadBeforeOverwrite(context, canonicalInput.path)
-					if (guard) return guard
-				}
-				await context.sandbox.writeFile(canonicalInput.path, canonicalInput.content)
-				context.fileReadTracker?.recordRead(canonicalInput.path)
-				return {
-					success: true as const,
-					output: `File written successfully: ${canonicalInput.path} (${canonicalInput.content.length} chars) [sandboxed]`,
-					data: {
-						path: canonicalInput.path,
-						size: canonicalInput.content.length,
-						sandboxed: true,
-					},
-				}
-			}
+		const filePath = resolve(context.workingDirectory, input.path)
 
-			const localExists = await pathExists(filePath)
-			if (localExists) {
-				const guard = enforceReadBeforeOverwrite(context, filePath)
-				if (guard) return guard
-			}
+		const localExists = await pathExists(filePath)
+		if (localExists) {
+			const guard = enforceReadBeforeOverwrite(context, filePath)
+			if (guard) return guard
+		}
 
-			await atomicWriteFile(filePath, canonicalInput.content)
-			context.fileReadTracker?.recordRead(filePath)
-			return {
-				success: true as const,
-				output: `File written successfully: ${filePath} (${canonicalInput.content.length} chars)`,
-				data: { path: filePath, size: canonicalInput.content.length },
-			}
-		})
+		await mkdir(dirname(filePath), { recursive: true })
+		await writeFile(filePath, content, 'utf-8')
+		context.fileReadTracker?.recordRead(filePath)
+
+		return {
+			success: true,
+			output: `File written successfully: ${filePath} (${content.length} chars)`,
+			data: { path: filePath, size: content.length },
+		}
 	},
 })
 

package/src/tools/coordinator/__tests__/agent.test.ts

@@ -4,7 +4,7 @@
  * - Reports `success: true` only when BOTH the gateway task state and
  *   the underlying `BaseAgentResult.status` say completed.
  * - Reports `success: false` and surfaces `lastError` when either
- *   layer disagrees — the canonical bug Codex caught was that a
+ *   layer disagrees — the canonical bug review caught was that a
  *   failed subagent could be reported as successful when the gateway
  *   forwarded `state: 'completed'` from a manager that did not
  *   propagate the run's `status: 'failed'`.
@@ -152,7 +152,7 @@ describe('buildAgentTool', () => {
 	it("does not accept a taskStore or runId — plan-task lifecycle is the parent's job", () => {
 		// Compile-time pin: AgentToolOptions must NOT include `taskStore`
 		// or `runId`. The Agent tool used to manage a per-call plan task
-		// internally and Codex caught a leak: when the subagent failed,
+		// internally and review caught a leak: when the subagent failed,
 		// the plan task stayed `'in_progress'` forever because
 		// `TaskStatus` has no `'failed'` value to flip to. Drop the
 		// integration entirely; if a host wants to track delegations as

package/src/tools/coordinator/agent.ts

@@ -8,9 +8,7 @@ import { defineTool } from '../defineTool.js'
 import type { TaskLaunchedCallback } from './index.js'
 
 /**
- * Build the canonical Claude Code `Agent` tool — synchronous subagent
- * delegation that mirrors what Claude is trained against in
- * `code.claude.com/docs/en/sub-agents`.
+ * Build the `Agent` tool — synchronous subagent delegation.
  *
  * Semantics: parent calls `Agent({ description, prompt, subagent_type })`,
  * the runtime spawns the chosen subagent with its own context window,
@@ -19,12 +17,14 @@ import type { TaskLaunchedCallback } from './index.js'
  * subagent tool calls are isolated — only the summary surfaces to
  * the parent.
  *
- * This is **NOT** the same shape as the coordinator `create_task`
- * tool that this package ships alongside it. That tool exposes
- * Namzu's task IDs and optional planning integration, while still
- * returning results synchronously. For free agentic alignment,
- * prefer the canonical `Agent` tool; use the coordinator tool when
- * the host needs task tracking.
+ * This is **NOT** the same shape as the legacy `create_task` /
+ * `continue_task` / `cancel_task` trio that this package ships
+ * alongside it: those are non-blocking and use a `<task-notification>`
+ * callback model. The async pattern is useful for hosts that want a
+ * work-queue surface, but it asks the model to track work it cannot
+ * see finish. Prefer the blocking `Agent` tool; keep the legacy
+ * coordinator tools only when you genuinely need fire-and-forget
+ * multi-task fan-out.
  */
 export interface AgentToolOptions {
 	gateway: TaskGateway
@@ -33,6 +33,18 @@ export interface AgentToolOptions {
 	allowedAgentIds: string[]
 
 	onTaskLaunched?: TaskLaunchedCallback
+
+	/**
+	 * Settle the parent run with the subagent's answer instead of looping
+	 * once more to restate it. See {@link ToolDefinition.terminal}.
+	 *
+	 * For a router — an agent whose whole job is to pick a specialist —
+	 * the relay turn is pure overhead at the parent's full context size,
+	 * and it hands the caller the parent's paraphrase rather than the
+	 * specialist's answer. Off by default: an agent that delegates as one
+	 * step of a longer plan needs the loop to continue.
+	 */
+	terminal?: boolean
 }
 
 export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
@@ -62,6 +74,7 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 		readOnly: false,
 		destructive: false,
 		concurrencySafe: true,
+		...(opts.terminal !== undefined ? { terminal: opts.terminal } : {}),
 		async execute({ description, prompt, subagent_type }, context) {
 			// With a single registered subagent the type is optional — default to
 			// it so the model can't trip the "subagent_type required" validation.
@@ -109,7 +122,7 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 			// Treat the subagent as successful only when BOTH agree.
 			// Reporting a failed subagent as successful would silently
 			// hand the parent garbage output and make debugging
-			// impossible, which is what Codex flagged on the first cut.
+			// impossible, which is what review flagged on the first cut.
 			const runStatus = completed.result?.status
 			const succeeded =
 				completed.state === 'completed' && (runStatus === undefined || runStatus === 'completed')

package/src/tools/coordinator/index.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import type { PlanManager } from '../../manager/plan/lifecycle.js'
+import type { PendingAnswers, QuestionParkRecorder } from '../../runtime/query/question-park.js'
 import type { AgentRuntimeContext } from '../../types/agent/base.js'
 import type { TaskGateway } from '../../types/agent/gateway.js'
 import type { ResumeHandler, UserQuestionOption } from '../../types/hitl/index.js'
@@ -45,6 +46,27 @@ export interface CoordinatorToolsOptions {
 	 * runId the park request cannot be addressed.
 	 */
 	resumeHandler?: ResumeHandler
+
+	/**
+	 * Makes a question park durable and visible.
+	 *
+	 * Without it the park exists only as a suspended `await` inside one
+	 * process — nothing on disk says a human owes this run an answer, and a
+	 * remote host cannot observe the question at all. Optional because a
+	 * host driving the tools directly may have no checkpoint store.
+	 */
+	questionParks?: QuestionParkRecorder
+
+	/**
+	 * Answers carried in from a resumed run, keyed by `questionId`.
+	 *
+	 * Consulted BEFORE the park handler: a re-entered `ask_user_question`
+	 * must return the answer that was already given rather than asking
+	 * again. Without it, resuming re-parks a question the user answered —
+	 * and in a headless resume that either deadlocks or auto-answers with
+	 * the no-consent sentinel, discarding the real answer.
+	 */
+	pendingAnswers?: PendingAnswers
 }
 
 const approvePlanStepSchema = z.object({
@@ -93,6 +115,8 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		runId,
 		getPlanManager,
 		resumeHandler,
+		questionParks,
+		pendingAnswers,
 		// `onTaskLaunched` was the entry point for the old
 		// non-blocking + envelope-injection flow. create_task is now
 		// blocking, so the callback is no longer wired here.
@@ -154,16 +178,18 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				prompt,
 				workingDirectory: cwd,
 				runtimeContext: opts.runtimeContext,
+				// Hang the child run off THIS tool's span, so the delegation
+				// shows up inside the turn that asked for it.
+				...(_context.parentSpan ? { parentSpan: _context.parentSpan } : {}),
 			})
 
-			// Industrial-standard Anthropic tool pattern: tool returns
-			// its real result as the tool_result for the dispatching
-			// tool_use. Parallel fan-out happens at the executor layer
-			// — when the supervisor emits N create_task blocks in one
-			// assistant turn, the runtime runs them with Promise.all
-			// and delivers all N tool_results together. No async
-			// envelope injection, no second tool_result for the same
-			// tool_use_id (which Anthropic rejects with 400).
+			// The tool returns its real result as the `tool_result` for the
+			// dispatching `tool_use`. Parallel fan-out happens at the executor
+			// layer: when the supervisor emits N `create_task` blocks in one
+			// assistant turn, the runtime runs them together and delivers all
+			// N `tool_result`s at once. No async envelope injection, and no
+			// second `tool_result` for the same `tool_use_id` — providers
+			// reject a duplicated id outright.
 			const completed = await gateway.waitForTask(handle.taskId)
 			const success = completed.state === 'completed'
 			const resultText =
@@ -227,6 +253,28 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		},
 	})
 
+	const cancelTask = defineTool({
+		name: 'cancel_task',
+		description:
+			'Cancel a running agent task. Only use this with a task_id from a previous create_task.',
+		inputSchema: z.object({
+			task_id: z.string().describe('Agent task ID from a previous create_task'),
+		}),
+		category: 'custom',
+		permissions: [],
+		readOnly: false,
+		destructive: false,
+		concurrencySafe: true,
+		async execute({ task_id }) {
+			gateway.cancelTask(task_id as TaskId)
+			return {
+				success: true,
+				output: `Task ${task_id} cancelled`,
+				data: { task_id },
+			}
+		},
+	})
+
 	const agentTaskList = defineTool({
 		name: 'agent_task_list',
 		description:
@@ -283,17 +331,24 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		},
 	})
 
-	// `continue_task` and model-facing per-task cancellation both
-	// belonged to the old non-blocking worker protocol. With
-	// `create_task` now blocking + tool_result returning the worker's
-	// final output, every worker is terminal by the time a later model
-	// turn learns its task id. The old cancel tool additionally called
-	// a void/no-op gateway method and manufactured "cancelled" even for
-	// a missing id. Host-owned run interruption still uses the gateway
-	// cancellation contract directly; it does not need a model tool.
-	// Keep only the follow-up definition for a future non-default
-	// gateway that deliberately preserves live workers between turns.
+	// `continue_task` was a follow-up channel for a still-alive worker
+	// task. With `create_task` now blocking + tool_result returning
+	// the worker's final output, every worker reaches a terminal
+	// state by the time the supervisor wants to follow up — and the
+	// agent manager rejects `continue` on terminal tasks. The
+	// industrial pattern is to issue a fresh `create_task` that
+	// references the prior worker's output path, so we drop
+	// `continue_task` from the registered surface entirely. The
+	// definition stays in this file for now in case a future
+	// non-default gateway (one that keeps the worker process alive
+	// for follow-ups) wants to re-register it.
 	void continueTask
+	// Per-task cancellation belonged to the old non-blocking worker protocol.
+	// `create_task` blocks and returns the worker output as its tool_result, so
+	// every worker is terminal by the time a later turn learns its id — the tool
+	// could only ever manufacture a "cancelled" for something already done.
+	// Host-owned interruption still uses the gateway contract directly.
+	void cancelTask
 	const tools: ToolDefinition[] = [createTask, agentTaskList]
 
 	if (getPlanManager) {
@@ -454,19 +509,44 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 					...(opt.description !== undefined ? { description: opt.description } : {}),
 				}))
 
-				const decision = await parkHandler({
-					type: 'user_question',
-					runId: parkRunId,
-					checkpointId: `cp_question_${toolUseId}`,
-					question: {
-						questionId: toolUseId,
-						question,
-						...(header !== undefined ? { header } : {}),
-						options: questionOptions,
-						multiSelect,
-						allowFreeText,
-					},
-				})
+				const questionData = {
+					questionId: toolUseId,
+					question,
+					...(header !== undefined ? { header } : {}),
+					options: questionOptions,
+					multiSelect,
+					allowFreeText,
+				}
+
+				// An answer carried in from a resumed run. Checked before the
+				// park, because re-entering this tool is HOW the answer gets
+				// delivered: the batch is re-executed, and without this the
+				// re-execution would ask the user something they already
+				// answered — or, headless, auto-answer with the no-consent
+				// sentinel and throw the real answer away.
+				const carried = pendingAnswers?.take(toolUseId)
+
+				// A real checkpoint, not a synthetic id nothing ever wrote.
+				// Skipped when an answer is already in hand: parking a
+				// question that is answered would leave an outstanding record
+				// for a decision that has been made.
+				const parkedAt =
+					carried === undefined && questionParks ? await questionParks.record(questionData) : null
+
+				const decision =
+					carried ??
+					(await parkHandler({
+						type: 'user_question',
+						runId: parkRunId,
+						checkpointId: parkedAt ?? `cp_question_${toolUseId}`,
+						question: questionData,
+					}))
+
+				// Clear the park once the answer is in, so an approval queue
+				// stops serving a question that has been answered.
+				if (parkedAt !== null && questionParks) {
+					await questionParks.resolve(parkedAt, decision)
+				}
 
 				// The no-answer sentinel (explicitly NOT consent — fixes the
 				// "empty answer reads as approval" ambiguity): used for empty

package/src/tools/defineTool.ts

@@ -20,6 +20,22 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	destructive: boolean | ((input: z.infer<S>) => boolean)
 	concurrencySafe: boolean
 	tier?: string
+	/** Per-execution deadline; see {@link ToolDefinition.timeoutMs}. */
+	timeoutMs?: number
+	/**
+	 * In-loop retry budget for a FAILED execution; see
+	 * {@link ToolDefinition.maxRetries}.
+	 *
+	 * The executor has always read this field, and this builder — the
+	 * sanctioned way to author a tool — had no way to set it, so the
+	 * documented "the tool author opts in, per tool" was reachable only by
+	 * hand-writing the interface.
+	 */
+	maxRetries?: number
+	/** Return shape shown to the model; see {@link ToolDefinition.outputSchema}. */
+	outputSchema?: Record<string, unknown>
+	/** Settle the run with this tool's output; see {@link ToolDefinition.terminal}. */
+	terminal?: boolean
 	execute(input: z.infer<S>, context: ToolContext): Promise<ToolResult>
 }
 
@@ -36,6 +52,10 @@ export function defineTool<S extends z.ZodType>(
 		enforceModelInput: options.enforceModelInput,
 		validationErrorHint: options.validationErrorHint,
 		tier: options.tier,
+		...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+		...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
+		...(options.outputSchema !== undefined ? { outputSchema: options.outputSchema } : {}),
+		...(options.terminal !== undefined ? { terminal: options.terminal } : {}),
 		category: options.category,
 		permissions: options.permissions,
 		isReadOnly: () => options.readOnly,

package/src/tools/glob-match.ts

@@ -0,0 +1,50 @@
+/**
+ * Glob matching for the sandboxed filesystem tools.
+ *
+ * The host path hands its pattern to the runtime's own directory walker;
+ * inside a sandbox there is only a flat listing to filter, so the matching
+ * has to happen here. Written out rather than reached for from the
+ * platform: the runtime's glob matcher is still flagged experimental, and
+ * an SDK that ships into other people's runtimes should not depend on
+ * that.
+ *
+ * The subset is the one the tools document — `**` across separators, `*`
+ * and `?` within one segment. Every other character is escaped, so a
+ * pattern containing regex punctuation matches literally instead of
+ * quietly becoming a different query.
+ */
+
+const NEEDS_ESCAPE = /[.+^${}()|[\]\\]/
+
+export function globToRegExp(pattern: string): RegExp {
+	let out = ''
+	for (let i = 0; i < pattern.length; i++) {
+		const ch = pattern[i] as string
+		if (ch === '*') {
+			if (pattern[i + 1] === '*') {
+				if (pattern[i + 2] === '/') {
+					// `**/` matches zero directories too, so `**/x.ts` finds a
+					// top-level `x.ts` — which is what someone writing it means.
+					out += '(?:.*/)?'
+					i += 2
+				} else {
+					out += '.*'
+					i += 1
+				}
+			} else {
+				out += '[^/]*'
+			}
+			continue
+		}
+		if (ch === '?') {
+			out += '[^/]'
+			continue
+		}
+		out += NEEDS_ESCAPE.test(ch) ? `\\${ch}` : ch
+	}
+	return new RegExp(`^${out}$`)
+}
+
+export function matchesGlob(path: string, pattern: string): boolean {
+	return globToRegExp(pattern).test(path)
+}

package/src/tools/paths.ts

@@ -0,0 +1,44 @@
+import { isAbsolute, relative, resolve } from 'node:path'
+
+/**
+ * Resolve a caller-supplied path against a root, refusing anything that
+ * lands outside it.
+ *
+ * The containment rule existed, in one private function inside the local
+ * sandbox provider, and the filesystem tools never reached it. They called
+ * `resolve(workingDirectory, input.path)` bare — so `path: "../../.."`
+ * resolved to whatever is above the working directory and the tool read it
+ * happily. That holds with no sandbox configured at all, which is the
+ * common case, so the escape did not need a misconfiguration to reach: a
+ * model that asks for a parent directory gets one.
+ *
+ * `relative()` rather than a `startsWith` prefix test: a prefix test says
+ * `/workspace-backup` is inside `/workspace`, and the whole point is to be
+ * exact about the boundary.
+ */
+export function resolveWithin(root: string, candidate: string | undefined): string {
+	if (candidate === undefined || candidate === '') return resolve(root)
+
+	const resolvedRoot = resolve(root)
+	const resolved = resolve(resolvedRoot, candidate)
+	const rel = relative(resolvedRoot, resolved)
+
+	// An absolute `rel` means the two paths share no root at all (a
+	// different drive on Windows); a leading `..` means it climbed out.
+	if (rel.startsWith('..') || isAbsolute(rel)) {
+		throw new Error(
+			`Path escapes the working directory: ${candidate}. Tools may only reach inside ${resolvedRoot}.`,
+		)
+	}
+	return resolved
+}
+
+/** True when `candidate` resolves inside `root`. */
+export function isWithin(root: string, candidate: string): boolean {
+	try {
+		resolveWithin(root, candidate)
+		return true
+	} catch {
+		return false
+	}
+}