@namzu/sdk 56.0.1 → 56.1.0

package/src/tools/builtins/edit.ts

@@ -17,6 +17,7 @@ import {
 import { withFileMutationLock } from './file-mutation-lock.js'
 import { jsonStringEscapes } from './json-string-hint.js'
 import { lineDiff } from './line-diff.js'
+import { staleBeforeReview } from './stale-before-review.js'
 
 /**
  * Two schemas, on purpose.
@@ -351,11 +352,13 @@ type EditAdmission =
  * 1. A file the session never read is refused. The model is about to rewrite
  *    text it has not seen, which is the commonest source of a wrong patch. A
  *    host that supplies no tracker has no ledger to ask and is not refused.
- * 2. A file that moved since the read is refused UNLESS every operation is a
- *    text replacement that still applies to the current body — uniquely,
- *    unless `replace_all` was asked for. A formatter run between the read and
- *    the edit then costs nothing. An insertion by line number is never
- *    recovered: the line it named may now be a different line.
+ * 2. A file that moved since the read is refused, whatever the operations are.
+ *    There is no recovery: a replacement that "still applies" to the moved body
+ *    can apply somewhere the model never meant (the read said `a = 1`, the file
+ *    now says `a = 100`, and the replacement of `a = 1` by `a = 2` lands inside
+ *    the new number and writes `a = 200`). Only the body the model read can
+ *    show where its text belongs, and the ledger keeps a fingerprint of it, not
+ *    the body. The refusal tells the model to read the file again.
  */
 function admitAgainstRead(
 	context: ToolContext,
@@ -373,19 +376,16 @@ function admitAgainstRead(
 		}
 	}
 	const seen = tracker?.fingerprint?.(key)
-	const applied = applyEdit(content, operations)
 	if (seen !== undefined && seen !== fingerprintContent(content)) {
-		const recoverable = applied.success && operations.every((o) => o.operation === 'replace')
-		if (!recoverable) {
-			recordDrift(context, key)
-			return {
-				success: false,
-				output: '',
-				error: staleFileError(key),
-				facts: { kind: 'failure', reason: 'changed_on_disk', subject: key },
-			}
+		recordDrift(context, key)
+		return {
+			success: false,
+			output: '',
+			error: staleFileError(key),
+			facts: { kind: 'failure', reason: 'changed_on_disk', subject: key },
 		}
 	}
+	const applied = applyEdit(content, operations)
 	return { success: true, result: applied }
 }
 
@@ -444,6 +444,9 @@ export const EditTool = defineTool({
 	// Declared so a path outside the turn's roots can be reviewed before the
 	// call runs, rather than refused after. See `ToolDefinition.pathArgument`.
 	pathArgument: 'path',
+	// A file that moved since the read is refused whatever the replacement is,
+	// so the person is not asked to approve one that cannot run.
+	refuseBeforeReview: (input: EditInput, context) => staleBeforeReview(context, input.path, 'edit'),
 	// The classifier judges which file changes and in what way, in a line.
 	classifierInput: (input: EditInput) => {
 		if (input.edits !== undefined) {

package/src/tools/builtins/stale-before-review.ts

@@ -0,0 +1,45 @@
+import { readFile } from 'node:fs/promises'
+
+import type { ToolContext } from '../../types/tool/index.js'
+import type { ToolFacts } from '../../types/tool/presentation.js'
+import { resolveWithinAnyReal, toolRoots } from '../paths.js'
+import { movedSinceRead, staleFileError } from './content-fingerprint.js'
+
+/**
+ * The refusal a file mutation would give for a file that moved on disk since
+ * the session read it, asked before a person is.
+ *
+ * `edit` and `write` refuse such a call when they run. By then the person has
+ * already been shown a change and said yes to it, so the answer is asked here
+ * too, ahead of the review. It looks at the same body the tool will (the host
+ * file, or the sandbox's) and says nothing when it cannot tell: a path that is
+ * missing or outside the roots, an unreadable file, or a session that never
+ * read the path. Those keep their own answers at run time.
+ */
+export async function staleBeforeReview(
+	context: ToolContext,
+	path: string,
+	operation: 'edit' | 'write',
+): Promise<{ readonly error: string; readonly facts: ToolFacts } | undefined> {
+	const tracker = context.fileReadTracker
+	if (!tracker) return undefined
+	let key: string
+	let current: string
+	try {
+		if (context.sandbox) {
+			key = path
+			current = (await context.sandbox.readFile(path)).toString('utf-8')
+		} else {
+			key = await resolveWithinAnyReal(toolRoots(context), path)
+			current = await readFile(key, 'utf-8')
+		}
+	} catch {
+		return undefined
+	}
+	if (!movedSinceRead(tracker, key, current)) return undefined
+	tracker.recordDriftObserved?.(key)
+	return {
+		error: staleFileError(key, operation),
+		facts: { kind: 'failure', reason: 'changed_on_disk', subject: key },
+	}
+}

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

@@ -11,6 +11,7 @@ import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
 import { fileWriteResult } from './file-write-result.js'
 import { jsonStringEscapes } from './json-string-hint.js'
+import { staleBeforeReview } from './stale-before-review.js'
 
 const inputSchema = z
 	.object({
@@ -94,6 +95,10 @@ export const WriteFileTool = defineTool({
 	// Declared so a path outside the turn's roots can be reviewed before the
 	// call runs, rather than refused after. See `ToolDefinition.pathArgument`.
 	pathArgument: 'path',
+	// An overwrite of a file that moved since the read is refused when it runs,
+	// so the person is not asked to approve one that cannot.
+	refuseBeforeReview: (input: WriteInput, context) =>
+		staleBeforeReview(context, input.path, 'write'),
 	// The classifier judges where a file is written and how much, not the body.
 	classifierInput: (input: WriteInput) => {
 		const body = input.content ?? input.newStr ?? ''

package/src/tools/defineTool.ts

@@ -83,6 +83,8 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	commandDialect?: ToolDefinition['commandDialect']
 	/** The argument holding a filesystem path; see {@link ToolDefinition.pathArgument}. */
 	pathArgument?: string
+	/** A refusal known before any reviewer is asked; see {@link ToolDefinition.refuseBeforeReview}. */
+	refuseBeforeReview?: ToolDefinition<z.infer<S>>['refuseBeforeReview']
 	/** The argument holding a canonical URL; see {@link ToolDefinition.urlArgument}. */
 	urlArgument?: string
 	/** The argument asking to leave the sandbox; see {@link ToolDefinition.sandboxEscapeArgument}. */
@@ -146,6 +148,7 @@ export function defineTool<S extends z.ZodType>(
 		...(options.commandArgument !== undefined ? { commandArgument: options.commandArgument } : {}),
 		...(options.commandDialect !== undefined ? { commandDialect: options.commandDialect } : {}),
 		...(options.pathArgument !== undefined ? { pathArgument: options.pathArgument } : {}),
+		...(options.refuseBeforeReview ? { refuseBeforeReview: options.refuseBeforeReview } : {}),
 		...(options.urlArgument !== undefined ? { urlArgument: options.urlArgument } : {}),
 		...(options.sandboxEscapeArgument !== undefined
 			? { sandboxEscapeArgument: options.sandboxEscapeArgument }

package/src/types/tool/index.ts

@@ -1050,6 +1050,24 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * the safe direction to be wrong in.
 	 */
 	pathArgument?: string
+	/**
+	 * A refusal that needs no person's answer: the call cannot run as it stands,
+	 * and the tool can already tell.
+	 *
+	 * Asked once the arguments are valid and BEFORE the call is put to a
+	 * reviewer, so a person is never asked to approve a change that would be
+	 * refused the moment they said yes. A file tool answers here when the file
+	 * moved on disk after the session read it. Returning `undefined` means no
+	 * objection; the call goes on to review and `execute`, which keep their own
+	 * checks, since the state may move again in between. A hook that throws is
+	 * read as no objection too.
+	 */
+	refuseBeforeReview?(
+		input: TInput,
+		context: ToolContext,
+	): Promise<
+		{ readonly error: string; readonly facts?: import('./presentation.js').ToolFacts } | undefined
+	>
 	/**
 	 * The argument that holds an absolute URL the tool has already
 	 * canonicalised in its input schema — one spelling, no whitespace.