@namzu/sdk 62.6.1 → 62.7.0

package/src/sandbox/glob-segment.ts

@@ -7,22 +7,24 @@
  */
 
 // Written for the `u` flag, which every compiled expression carries.
-const POSIX_CLASSES: Record<string, string> = {
-	alnum: '\\p{L}\\p{Nl}\\p{Nd}',
-	alpha: '\\p{L}\\p{Nl}',
-	ascii: '\\x00-\\x7f',
-	blank: '\\p{Zs}\\t',
-	cntrl: '\\p{Cc}',
-	digit: '\\p{Nd}',
-	graph: '\\x21-\\x7e',
-	lower: '\\p{Ll}',
-	print: '\\x20-\\x7e',
-	punct: '\\p{P}\\p{S}',
-	space: '\\s',
-	upper: '\\p{Lu}',
-	word: '\\p{L}\\p{Nl}\\p{Nd}_',
-	xdigit: '0-9a-fA-F',
-}
+const POSIX_CLASSES: ReadonlyMap<string, string> = new Map(
+	Object.entries({
+		alnum: '\\p{L}\\p{Nl}\\p{Nd}',
+		alpha: '\\p{L}\\p{Nl}',
+		ascii: '\\x00-\\x7f',
+		blank: '\\p{Zs}\\t',
+		cntrl: '\\p{Cc}',
+		digit: '\\p{Nd}',
+		graph: '\\x21-\\x7e',
+		lower: '\\p{Ll}',
+		print: '\\x20-\\x7e',
+		punct: '\\p{P}\\p{S}',
+		space: '\\s',
+		upper: '\\p{Lu}',
+		word: '\\p{L}\\p{Nl}\\p{Nd}_',
+		xdigit: '0-9a-fA-F',
+	}),
+)
 
 export interface CompiledSegment {
 	/** Set when the segment has no magic: the exact name it matches. */
@@ -31,6 +33,23 @@ export interface CompiledSegment {
 	source: string
 }
 
+/**
+ * The longest segment, in UTF-16 code units, that `compileSegment` accepts. A
+ * file name is at most 255 bytes on the file systems Namzu runs on, so a
+ * pattern for one name beyond four times that is never legitimate, while
+ * compiling a segment costs time in proportion to the square of its length.
+ */
+export const MAX_GLOB_SEGMENT_LENGTH = 1024
+
+/** How much of an over-long pattern an error message shows, in code points. */
+const PREVIEW_LENGTH = 60
+
+/** The first `PREVIEW_LENGTH` code points of `text`, never cutting a surrogate pair. */
+const preview = (text: string) =>
+	Array.from(text.slice(0, PREVIEW_LENGTH * 2))
+		.slice(0, PREVIEW_LENGTH)
+		.join('')
+
 /**
  * Raised for a segment that repeats a group (`*( )` or `+( )`) which could match
  * the same text more than one way. Such a group backtracks exponentially on a
@@ -38,14 +57,17 @@ export interface CompiledSegment {
  */
 export class GlobTooComplexError extends Error {
 	readonly segment: string
-	constructor(segment: string, reason: 'ambiguous' | 'stretch' = 'ambiguous') {
+	constructor(segment: string, reason: 'ambiguous' | 'stretch' | 'length' = 'ambiguous') {
 		super(
-			reason === 'stretch'
-				? `The pattern '${segment}' has more than three wildcards that can stretch; split it across folders or use fewer *.`
-				: `The pattern '${segment}' repeats a group that can match the same text more than one way; use ** or {a,b} instead.`,
+			reason === 'length'
+				? `The pattern '${preview(segment)}...' is too long (${segment.length} characters; at most ${MAX_GLOB_SEGMENT_LENGTH} between slashes); shorten it or split it across folders.`
+				: reason === 'stretch'
+					? `The pattern '${segment}' has more than three wildcards that can stretch; split it across folders or use fewer *.`
+					: `The pattern '${segment}' repeats a group that can match the same text more than one way; use ** or {a,b} instead.`,
 		)
 		this.name = 'GlobTooComplexError'
-		this.segment = segment
+		// An over-long pattern is not kept whole: the error may be logged.
+		this.segment = reason === 'length' ? preview(segment) : segment
 	}
 }
 
@@ -85,7 +107,7 @@ function classEnd(text: string, start: number): number {
 		if (ch === '\\') index += 1
 		else if (ch === '[' && text[index + 1] === ':') {
 			const end = text.indexOf(':]', index + 2)
-			if (end > 0 && POSIX_CLASSES[text.slice(index + 2, end)]) index = end + 1
+			if (end > 0 && POSIX_CLASSES.has(text.slice(index + 2, end))) index = end + 1
 		} else if (ch === ']') return index
 	}
 	return -1
@@ -134,8 +156,9 @@ function classSource(body: string): string {
 		if (ch === '[' && body[index + 1] === ':') {
 			const end = body.indexOf(':]', index + 2)
 			const name = end > 0 ? body.slice(index + 2, end) : ''
-			if (POSIX_CLASSES[name]) {
-				out += POSIX_CLASSES[name]
+			const members = POSIX_CLASSES.get(name)
+			if (members !== undefined) {
+				out += members
 				index = end + 1
 				continue
 			}
@@ -268,6 +291,7 @@ function isOneGroup(text: string): boolean {
  * segment that itself begins with a literal `.` can.
  */
 export function compileSegment(segment: string, dot: boolean): CompiledSegment {
+	if (segment.length > MAX_GLOB_SEGMENT_LENGTH) throw new GlobTooComplexError(segment, 'length')
 	const guard = dot ? '' : '(?!\\.)'
 	let parsed: Parsed
 	try {

package/src/store/session-log/index.ts

@@ -61,6 +61,13 @@ export {
 	withMessageId,
 } from './fold.js'
 export { type TornTailRepair, repairRecordDraft } from './heal.js'
+export {
+	foldChildOutcomes,
+	foldTurnOutcomes,
+	parseTurnOutcome,
+	readOutcomeProgress,
+	readTurnOutcome,
+} from './turn-outcome.js'
 export {
 	type ReleaseHeldSessionLeasesOptions,
 	type ReleaseHeldSessionLeasesResult,

package/src/store/session-log/turn-outcome.ts

@@ -0,0 +1,84 @@
+import type { CheckpointId, SessionId, TurnId } from '../../types/ids/index.js'
+import { type TurnOutcome, TurnOutcomeSchema } from '../../types/session/outcome.js'
+import type { SessionRecord } from '../../types/session/records.js'
+import type { SessionLog } from './core.js'
+
+/**
+ * Reading the turn's outcome record back out of the session log.
+ *
+ * It lives in three records of its own (`turn_outcome_recorded`,
+ * `child_outcome_recorded`, `outcome_progress_written`), each flagged
+ * `ignorable`, and never in a field of an older record: a release that
+ * validates `turn_completed`, `child_session_ended` or the checkpoint strictly
+ * reads a log that has them and loses only the outcome. The fold of messages
+ * does not look at them. A body that does not parse as a `TurnOutcome` reads
+ * as no outcome, never as a guess.
+ */
+
+/** `value` as a {@link TurnOutcome}, or `undefined` when it is not one. */
+export function parseTurnOutcome(value: unknown): TurnOutcome | undefined {
+	const parsed = TurnOutcomeSchema.safeParse(value)
+	return parsed.success ? parsed.data : undefined
+}
+
+/**
+ * The outcome of each turn that recorded one, from records in log order. A
+ * turn that recorded none is absent, so a caller never reads `unchanged` into
+ * a turn nobody measured.
+ */
+export function foldTurnOutcomes(records: Iterable<SessionRecord>): Map<TurnId, TurnOutcome> {
+	const outcomes = new Map<TurnId, TurnOutcome>()
+	for (const record of records) {
+		if (record.type !== 'turn_outcome_recorded') continue
+		const outcome = parseTurnOutcome(record.outcome)
+		if (outcome) outcomes.set(record.turnId, outcome)
+		else outcomes.delete(record.turnId)
+	}
+	return outcomes
+}
+
+/** The outcome `turnId` recorded, or `undefined`. */
+export async function readTurnOutcome(
+	log: SessionLog,
+	turnId: TurnId,
+): Promise<TurnOutcome | undefined> {
+	let found: TurnOutcome | undefined
+	for await (const { record } of log.read({ mode: 'tolerant' })) {
+		if (record.type !== 'turn_outcome_recorded' || record.turnId !== turnId) continue
+		found = parseTurnOutcome(record.outcome)
+	}
+	return found
+}
+
+/**
+ * The outcome a child's settled turn recorded in the parent's log, by child
+ * session id. A child with no record is absent.
+ */
+export function foldChildOutcomes(records: Iterable<SessionRecord>): Map<SessionId, TurnOutcome> {
+	const outcomes = new Map<SessionId, TurnOutcome>()
+	for (const record of records) {
+		if (record.type !== 'child_outcome_recorded') continue
+		const outcome = parseTurnOutcome(record.outcome)
+		if (outcome) outcomes.set(record.childSessionId, outcome)
+		else outcomes.delete(record.childSessionId)
+	}
+	return outcomes
+}
+
+/**
+ * What the outcome record had gathered when `checkpointId` was written, or
+ * `undefined` when no progress record names it (a checkpoint written before
+ * the record existed, or by a release that does not write it).
+ */
+export async function readOutcomeProgress(
+	log: SessionLog,
+	checkpointId: CheckpointId,
+): Promise<Readonly<Record<string, unknown>> | undefined> {
+	let found: Readonly<Record<string, unknown>> | undefined
+	for await (const { record } of log.read({ mode: 'tolerant' })) {
+		if (record.type === 'outcome_progress_written' && record.checkpointId === checkpointId) {
+			found = record.progress
+		}
+	}
+	return found
+}

package/src/tools/builtins/bash.ts

@@ -537,7 +537,7 @@ export const SANDBOX_ESCAPE_NOT_APPROVED =
 	'dangerously_disable_sandbox was not approved for this call, so the command did not run. Leaving the sandbox needs the user to confirm it each time, and this turn either cannot ask or does not allow it. Run the command inside the sandbox, or tell the user what it needs and let them run it.'
 
 const BASH_DESCRIPTION =
-	'Executes a command line using the execution shell disclosed in the system context and returns stdout/stderr output. The working directory persists between calls, but shell state does not. Command timeout is configurable. The `command` parameter is required, so every call carries one. Long file content goes through `write`, not a heredoc, so it cannot hit the output token limit mid-stream.'
+	'Executes a command line using the execution shell disclosed in the system context and returns stdout/stderr output. The working directory persists between calls, but shell state does not. Command timeout is configurable. Read and search with `read`, `grep` and `glob`, not shell loops: a file read through the shell earns no read credit, so its next edit is refused once. Run a check on its own, not piped: its output is already trimmed, and a pipe hides the exit status.'
 
 const BashToolBase = defineTool({
 	name: 'bash',

package/src/tools/builtins/edit-apply.ts

@@ -40,7 +40,7 @@ export type NormalizedEditInput =
 export function normalizeEditInput(
 	input: EditInput,
 ): { success: true; operations: NormalizedEditInput[] } | { success: false; error: string } {
-	if (input.edits !== undefined) {
+	if (input.edits !== undefined && input.edits.length > 0) {
 		return {
 			success: true,
 			operations: input.edits.map((edit) => ({
@@ -197,11 +197,15 @@ function applyOne(
 	if (!content.includes(oldString)) {
 		const resolved = resolveOldString(content, oldString)
 		if (resolved === null) {
+			const near = nearLine(content, oldString)
 			return {
 				success: false,
 				reason: 'text_not_found',
-				error:
-					'old_string/oldStr not found in file. Make sure the string matches exactly, including whitespace and indentation.',
+				error: `old_string/oldStr not found in file. Make sure the string matches exactly, including whitespace and indentation. ${
+					near === undefined
+						? 'Read the lines you mean to change again and copy them as they are.'
+						: `A line that matches its first line apart from spacing is at line ${near}; read around it again and copy it as it is.`
+				}`,
 			}
 		}
 		newString = reconcileNewString(oldString, resolved, newString)
@@ -235,7 +239,7 @@ function applyOne(
 		return {
 			success: false,
 			reason: 'not_unique',
-			error: `old_string/oldStr is not unique — found at lines ${lineNumber} and ${secondLine}. Provide more surrounding context to make it unique, or use replace_all: true.`,
+			error: `old_string/oldStr is not unique — found at lines ${lineNumber} and ${secondLine}. Provide more surrounding context to make it unique, or use replace_all: true. Read around those lines again to choose context that is only in one of them.`,
 		}
 	}
 
@@ -247,6 +251,24 @@ function applyOne(
 	}
 }
 
+const NEAR_LINE_MIN_CHARS = 8
+
+/** The line of `content` that matches the first non-blank line of `needle` apart from spacing, 1-based. */
+function nearLine(content: string, needle: string): number | undefined {
+	const squash = (text: string) => text.replace(/\s+/g, ' ').trim()
+	const first = needle
+		.split('\n')
+		.map(squash)
+		.find((line) => line !== '')
+	// A bare brace or paren is on many lines; naming the first one would point at the wrong place.
+	if (first === undefined || first.length < NEAR_LINE_MIN_CHARS) return undefined
+	const lines = content.split('\n')
+	for (let i = 0; i < lines.length; i++) {
+		if (squash(lines[i] ?? '') === first) return i + 1
+	}
+	return undefined
+}
+
 function applyLineInsert(
 	content: string,
 	input: Extract<NormalizedEditInput, { operation: 'insert' }>,

package/src/tools/builtins/edit.ts

@@ -22,8 +22,91 @@ import {
 import { withFileMutationLock } from './file-mutation-lock.js'
 import { jsonStringEscapes } from './json-string-hint.js'
 import { lineDiff } from './line-diff.js'
+import { notebookRefusal } from './notebook-guard.js'
 import { staleBeforeReview } from './stale-before-review.js'
 
+type RawEditInput = {
+	path: string
+	old_string?: string
+	oldStr?: string
+	new_string?: string
+	newStr?: string
+	insertLine?: number | string
+	replace_all?: boolean
+	edits?: { old_string: string; new_string: string; replace_all?: boolean }[]
+}
+
+const ONE_SHAPE_EACH =
+	'Single edit: {"path":"file.md","old_string":"exact unique text","new_string":"replacement text"}\nSeveral edits: {"path":"file.md","edits":[{"old_string":"a","new_string":"b"},{"old_string":"c","new_string":"d"}]}'
+
+const hasTopLevelEdit = (value: RawEditInput): boolean =>
+	value.old_string !== undefined ||
+	value.oldStr !== undefined ||
+	value.new_string !== undefined ||
+	value.newStr !== undefined ||
+	value.insertLine !== undefined
+
+/**
+ * A top-level edit that is exactly the one entry of a one-entry batch: the same
+ * call said twice, not two intentions. Anything else (a different text, a
+ * longer list, an insertion) is a real conflict and stays refused.
+ */
+function restatesTheBatch(value: RawEditInput): boolean {
+	const entries = value.edits
+	if (entries === undefined || entries.length !== 1 || value.insertLine !== undefined) return false
+	const [entry] = entries
+	return (
+		entry !== undefined &&
+		(value.old_string ?? value.oldStr) === entry.old_string &&
+		(value.new_string ?? value.newStr) === entry.new_string &&
+		(value.replace_all ?? false) === (entry.replace_all ?? false)
+	)
+}
+
+/**
+ * Which of the two shapes this call is, and what to say when it is neither.
+ *
+ * An empty `edits` beside a top-level edit, and a one-entry `edits` that restates
+ * the top-level edit, are the single edit: the intent is not in doubt and nothing
+ * is dropped. A batch beside a DIFFERENT top-level edit stays refused, because
+ * any precedence would silently drop an edit somebody believes was made.
+ */
+function checkEditShape(value: RawEditInput): string | undefined {
+	const batch = value.edits !== undefined && value.edits.length > 0
+	const top = hasTopLevelEdit(value)
+	if (value.edits !== undefined && !batch && !top) {
+		return `\`edits\` is an empty list, so there is nothing to change. Send exactly one of these, and leave out the field you are not using:\n${ONE_SHAPE_EACH}`
+	}
+	if (batch && top && !restatesTheBatch(value)) {
+		return `This call has both an \`edits\` list and a different top-level edit, and only one can be applied. Send exactly one of these, and leave out the field you are not using:\n${ONE_SHAPE_EACH}`
+	}
+	if (batch) return undefined
+	if (typeof value.new_string !== 'string' && typeof value.newStr !== 'string') {
+		return 'Either new_string or newStr is required.'
+	}
+	if (
+		value.insertLine === undefined &&
+		typeof value.old_string !== 'string' &&
+		typeof value.oldStr !== 'string'
+	) {
+		return 'Either old_string/oldStr or insertLine is required.'
+	}
+	return undefined
+}
+
+/**
+ * The input every later stage sees: one shape, with the redundant half gone. The
+ * review card, the classifier, the dry run and the apply step all read this, so
+ * none of them meets `edits: []` or a restated edit.
+ */
+function canonicalEditInput(value: RawEditInput): RawEditInput {
+	if (value.edits === undefined) return value
+	const { edits, ...rest } = value
+	if (edits.length === 0) return rest
+	const { old_string, oldStr, new_string, newStr, insertLine, ...kept } = rest
+	return { ...kept, edits }
+}
+
 /**
  * Two schemas, on purpose.
  *
@@ -106,48 +189,23 @@ const inputSchema = z
 					})
 					.strict(),
 			)
-			.min(1)
+			// No `.min(1)`: a model that fills every optional field of a flat object
+			// sends `edits: []` next to a single top-level edit, and that is the
+			// single edit, not an error. An empty list with nothing beside it is
+			// refused by `checkEditShape` below, in a sentence that says what to send.
 			.optional()
 			.describe(
-				'Several replacements in one file, applied in order and committed together. Nothing is written unless every one applies.',
+				'Several replacements in one file, applied in order and committed together. Nothing is written unless every one applies. Leave out when sending a single old_string/new_string.',
 			),
 	})
 	.strict()
-	.refine(
-		(value) =>
-			value.edits !== undefined ||
-			typeof value.new_string === 'string' ||
-			typeof value.newStr === 'string',
-		{ message: 'Either new_string or newStr is required.' },
-	)
-	.refine(
-		(value) =>
-			value.edits !== undefined ||
-			value.insertLine !== undefined ||
-			typeof value.old_string === 'string' ||
-			typeof value.oldStr === 'string',
-		{ message: 'Either old_string/oldStr or insertLine is required.' },
-	)
-	// Refused rather than resolved. A call carrying both an `edits` list and a
-	// top-level replacement is two different intentions in one object, and any
-	// precedence this code picked would be a guess about which the model meant
-	// — silently dropping the other. There is no reading of that which is safe:
-	// the dropped half is an edit somebody believes was made.
-	.refine(
-		(value) =>
-			value.edits === undefined ||
-			(value.old_string === undefined &&
-				value.oldStr === undefined &&
-				value.new_string === undefined &&
-				value.newStr === undefined &&
-				value.insertLine === undefined),
-		{
-			message:
-				'Use either `edits` or a single top-level edit, not both. Move the top-level old_string/new_string into the edits list.',
-		},
-	)
+	.superRefine((value, ctx) => {
+		const problem = checkEditShape(value)
+		if (problem) ctx.addIssue({ code: 'custom', message: problem })
+	})
+	.transform(canonicalEditInput)
 
-export type EditInput = z.infer<typeof inputSchema>
+export type EditInput = z.output<typeof inputSchema>
 
 /**
  * What an `edit` call WOULD produce for a file body, without touching any file.
@@ -184,7 +242,10 @@ export function dryRunEdit(
 		}
 	}
 	const result = applyEdit(content, normalized.operations)
-	return result.success ? { success: true, content: result.content } : result
+	if (!result.success) return result
+	const notebook = notebookRefusal(parsed.data.path, result.content, content)
+	if (notebook) return { success: false, error: notebook }
+	return { success: true, content: result.content }
 }
 
 /**
@@ -205,7 +266,7 @@ const modelInputSchema: Record<string, unknown> = {
 		old_string: {
 			type: 'string',
 			description:
-				'Exact unique text from the file, without read-tool line-number prefixes. Must not be empty.',
+				'For a single change: exact unique text from the file, without read-tool line-number prefixes. Must not be empty. Do not send together with edits.',
 		},
 		new_string: {
 			type: 'string',
@@ -282,7 +343,7 @@ const modelInputSchema: Record<string, unknown> = {
 				additionalProperties: false,
 			},
 			description:
-				'Several replacements in one file, applied in order and committed together. Nothing is written unless every one applies. Use this instead of several edit calls when the changes only make sense together.',
+				'For SEVERAL changes to one file: a non-empty list, applied in order and committed together. Nothing is written unless every one applies. Leave this field out entirely when you send old_string/new_string; never send an empty list.',
 		},
 	},
 	// `old_string` is deliberately NOT required, and this is the fix.
@@ -437,7 +498,7 @@ function refusedEdit(result: EditApplyFailure, path: string) {
 export const EditTool = defineTool({
 	name: 'edit',
 	description:
-		'Makes targeted edits to a file using exact string find-and-replace or line insertion. To change an existing file, use `edit`: `write` overwrites the whole body and discards earlier work on partial failure, while `edit` keeps the rest of the file byte-for-byte intact and is recoverable: if a single edit fails (old_string/oldStr ambiguous, broader restructuring needed), follow up with another `edit` instead of re-emitting the entire file via `write`. The old_string/oldStr must be unique in the file unless replace_all is true. For insertions, pass insertLine plus new_string/newStr; use insertLine: "end" to extend a file at the end. Keep new_string/newStr under 12000 characters, because a longer payload can be cut off mid-call and fail; use repeated bounded edits for long sections. Preserves file formatting and indentation. To make several changes to one file that only make sense together, send them as `edits`: a list of {old_string, new_string} applied in order and committed as one write — if any of them does not apply, nothing is written and the reply names which one, so the file is never left half-changed.',
+		'Makes targeted edits to a file using exact string find-and-replace or line insertion. To change an existing file, use `edit`: `write` overwrites the whole body and discards earlier work on partial failure, while `edit` keeps the rest of the file byte-for-byte intact and is recoverable: if a single edit fails (old_string/oldStr ambiguous, broader restructuring needed), follow up with another `edit` instead of re-emitting the entire file via `write`. The old_string/oldStr must be unique in the file unless replace_all is true. For insertions, pass insertLine plus new_string/newStr; use insertLine: "end" to extend a file at the end. Keep new_string/newStr under 12000 characters, because a longer payload can be cut off mid-call and fail; use repeated bounded edits for long sections. Preserves file formatting and indentation. To make several changes to one file that only make sense together, send them as `edits` (and then no top-level old_string/new_string; for a single change leave `edits` out): a list of {old_string, new_string} applied in order and committed as one write — if any of them does not apply, nothing is written and the reply names which one, so the file is never left half-changed. An edit that would leave a `.ipynb` file as invalid notebook JSON is refused and the file is unchanged.',
 	inputSchema,
 	modelInputSchema,
 	enforceModelInput: true,
@@ -458,7 +519,7 @@ export const EditTool = defineTool({
 	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) {
+		if (input.edits !== undefined && input.edits.length > 0) {
 			const shown = input.edits.slice(0, 5).map((e) => describeChange(e.old_string, e.new_string))
 			const more =
 				input.edits.length > shown.length ? `; ${input.edits.length - shown.length} more` : ''
@@ -570,6 +631,8 @@ export const EditTool = defineTool({
 				if (!admitted.success) return admitted
 				const result = admitted.result
 				if (!result.success) return refusedEdit(result, parsed.data.path)
+				const notebook = notebookRefusal(parsed.data.path, result.content, content)
+				if (notebook) return { success: false as const, output: '', error: notebook }
 
 				await context.sandbox.writeFile(parsed.data.path, result.content)
 				recordEditedContent(context, parsed.data.path, result.content)
@@ -593,6 +656,8 @@ export const EditTool = defineTool({
 			if (!admitted.success) return admitted
 			const result = admitted.result
 			if (!result.success) return refusedEdit(result, hostPath)
+			const notebook = notebookRefusal(hostPath, result.content, content)
+			if (notebook) return { success: false as const, output: '', error: notebook }
 
 			// Temp file, fsync, rename — a reader sees the old body or the new
 			// one, never a half-written one. A plain `writeFile` that fails

package/src/tools/builtins/glob.ts

@@ -68,7 +68,7 @@ function relativePattern(pattern: string, root: string, sandboxed: boolean): str
 export const GlobTool = defineTool({
 	name: 'glob',
 	description:
-		'Finds regular files by glob pattern in a bounded search. "*" searches one directory; use "**" explicitly for recursive discovery. Skips files that .gitignore and .ignore rules exclude unless include_ignored is set, and files the read rules of the session deny. Returns at most 500 paths and says when a result is limited or a search stopped early. Does not follow symlinks.',
+		'Finds regular files by glob pattern in a bounded search. "*" searches one directory; use "**" explicitly for recursive discovery. Skips files that .gitignore and .ignore rules exclude unless include_ignored is set, and files the read rules of the session deny. Returns at most 500 paths and says when a result is limited or a search stopped early. Does not follow symlinks. To search inside files, use grep.',
 	inputSchema,
 	category: 'filesystem',
 	// Declared so a path outside the turn's roots can be reviewed before the

package/src/tools/builtins/grep.ts

@@ -211,7 +211,7 @@ function isBinaryContent(buffer: Buffer): boolean {
 export const GrepTool = defineTool({
 	name: 'grep',
 	description:
-		'Searches file contents using a regular expression. By default returns the paths of matching files, newest first; output_mode "content" returns matching lines with file paths, line numbers and optional context lines, and "count" returns the number of matching lines per file. Set multiline for a pattern that spans lines and type (js, py, rust, ...) to search one kind of file. In content mode, before_context and after_context override symmetric context_lines; only_matching returns matched substrings without context. Results are paged: head_limit (default 250, 0 for none) and offset. A line over 500 characters is replaced by a notice. Searches hidden files unless include_hidden is false. Skips files that .gitignore and .ignore rules exclude unless include_ignored is set, and files the read rules of the session deny. Says when a result is limited or a search stopped early. Skips binary files, files over 5 MB, and symlinks. Choose the narrowest relevant directory.',
+		'Searches file contents using a regular expression. By default returns the paths of matching files, newest first; output_mode "content" returns matching lines with file paths, line numbers and optional context lines, and "count" returns the number of matching lines per file. Set multiline for a pattern that spans lines and type (js, py, rust, ...) to search one kind of file. In content mode, before_context and after_context override symmetric context_lines; only_matching returns matched substrings without context. Results are paged: head_limit (default 250, 0 for none) and offset. A line over 500 characters is replaced by a notice. Searches hidden files unless include_hidden is false. Skips files that .gitignore and .ignore rules exclude unless include_ignored is set, and files the read rules of the session deny. Says when a result is limited or a search stopped early. Skips binary files, files over 5 MB, and symlinks. Choose the narrowest relevant directory. To find files by name, use glob.',
 	inputSchema,
 	category: 'analysis',
 	// Declared so a path outside the turn's roots can be reviewed before the

package/src/tools/builtins/notebook-guard.ts

@@ -0,0 +1,76 @@
+/**
+ * A notebook is JSON with a fixed shape. `edit` and `write` treat every file
+ * as text, so a model can leave an `.ipynb` that no notebook program opens.
+ * This check runs on the body about to be written, never on the file on disk,
+ * so a refusal leaves the file untouched.
+ */
+
+const CELL_TYPES = new Set(['code', 'markdown', 'raw'])
+
+export function isNotebookPath(path: string): boolean {
+	return path.toLowerCase().endsWith('.ipynb')
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function shapeProblem(parsed: unknown): string | undefined {
+	if (!isRecord(parsed)) return 'the top level must be a JSON object'
+	if (typeof parsed.nbformat !== 'number') return 'it needs a numeric "nbformat"'
+	if (!isRecord(parsed.metadata)) return 'it needs a "metadata" object'
+	// Formats before 4 keep their cells inside "worksheets" and name a code cell's text "input".
+	// Those files are valid and still open, so only the envelope is checked for them.
+	if (parsed.nbformat < 4) {
+		return Array.isArray(parsed.worksheets) ? undefined : 'it needs a "worksheets" list'
+	}
+	if (!Array.isArray(parsed.cells)) return 'it needs a "cells" list'
+	for (const [index, cell] of parsed.cells.entries()) {
+		if (!isRecord(cell)) return `cell ${index} must be an object`
+		if (typeof cell.cell_type !== 'string' || !CELL_TYPES.has(cell.cell_type)) {
+			return `cell ${index} needs a "cell_type" of code, markdown or raw`
+		}
+		const source = cell.source
+		const sourceOk =
+			typeof source === 'string' ||
+			(Array.isArray(source) && source.every((line) => typeof line === 'string'))
+		if (!sourceOk) return `cell ${index} needs a "source" that is a string or a list of strings`
+	}
+	return undefined
+}
+
+/** Why a notebook body would not open, or `undefined` when it would. */
+function bodyProblem(content: string): string | undefined {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(content)
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error)
+		return `it is not valid JSON (${reason})`
+	}
+	return shapeProblem(parsed)
+}
+
+/**
+ * Returns a plain refusal for a notebook body that would no longer open, or
+ * `undefined` when the body is fine or the path is not a notebook.
+ *
+ * `before` is the file's current body, when the caller has it. A notebook that
+ * was already broken cannot be mended one string at a time, because every
+ * partial repair still leaves a file that does not open; without saying so the
+ * refusal would tell the model to keep a structure the file never had, and it
+ * would try the same edit again.
+ */
+export function notebookRefusal(
+	path: string,
+	content: string,
+	before?: string,
+): string | undefined {
+	if (!isNotebookPath(path)) return undefined
+	const problem = bodyProblem(content)
+	if (problem === undefined) return undefined
+	if (before !== undefined && bodyProblem(before) !== undefined) {
+		return `Not written: ${path} is a notebook that already does not open, and after this change it still would not because ${problem}. Repair it in one change that leaves a whole valid notebook, or replace the file with a write of the corrected notebook. The file is unchanged.`
+	}
+	return `Not written: ${path} is a notebook, and after this change it would no longer open because ${problem}. Change only text inside a cell and keep the notebook's structure (its cells, nbformat and metadata, with the surrounding quotes, commas and brackets), then try again. The file is unchanged.`
+}

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

@@ -80,8 +80,12 @@ export function renderNumberedRead(content: string, input: ReadWindowRequest): R
 	}
 	const selected = lines.slice(start, Math.min(end, lineCount))
 	const numbered = selected.map((line, i) => `${start + i + 1}\t${line}`).join('\n')
+	// Only a cut the cap imposed is the model's to be warned about: a window it
+	// asked for is what it got.
+	const asked = (input.readRange?.length ?? 0) >= 2 || Boolean(input.limit)
+	const capCut = !asked
 	return {
-		output: numbered + partialViewNotice(start, selected.length, lineCount),
+		output: numbered + partialViewNotice(start, selected.length, lineCount, capCut),
 		totalLines: lineCount,
 		returnedLines: selected.length,
 		partial: selected.length < lineCount,
@@ -97,9 +101,15 @@ export function renderNumberedRead(content: string, input: ReadWindowRequest): R
  * 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 {
+function partialViewNotice(
+	start: number,
+	returned: number,
+	total: number,
+	capCut: boolean,
+): string {
 	if (returned >= total) return ''
 	const shownTo = start + returned
+	if (!capCut) return `\n\n[Lines ${start + 1}-${shownTo} of ${total}, as asked.]`
 	return [
 		'',
 		'',