@namzu/sdk 52.4.0 → 52.6.0

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

@@ -0,0 +1,274 @@
+/**
+ * Flexible `old_string` matching for the edit tool.
+ *
+ * When an exact match of `old_string` against the file fails, a handful of
+ * near-misses are not the model being wrong about the text, only about one
+ * invisible or interchangeable detail: a curly quote where the file has a
+ * straight one, or a `\uXXXX` escape where the file has the character itself
+ * (or the reverse). This module recovers the real span the model meant, and
+ * carries the same transformation across to `new_string` so the replacement
+ * stays consistent with what it replaced.
+ *
+ * The strategies and their order are a faithful port of the reference client's
+ * file-edit resolver (the `lje`/`b`/`_`/`L`/`k`/`R`/`C`/`cDs`/`ipt`/`H`/`Q`/`N`
+ * functions in its shipped bundle), so an edit that lands there lands here:
+ *
+ *   1. exact
+ *   2. curly vs straight quotes, both directions
+ *   3. `\uXXXX` escape in `old_string`, character in the file
+ *   4. character in `old_string`, `\uXXXX` escape in the file
+ *
+ * The reference also expands a map of its own prompt delimiters (`<fnr>` →
+ * `<function_results>`, `\n\nH:` → `\n\nHuman:`, …). That is deliberately NOT
+ * ported: those tokens are artifacts of that client's own transcript format,
+ * not a mismatch a Namzu model produces against a real source file.
+ *
+ * Pure by construction, like `edit-apply`: every function here is from strings
+ * to strings, with no filesystem access.
+ */
+
+const LEFT_SINGLE_QUOTE = '‘'
+const RIGHT_SINGLE_QUOTE = '’'
+const LEFT_DOUBLE_QUOTE = '“'
+const RIGHT_DOUBLE_QUOTE = '”'
+
+/** `old_string` carries a `\uXXXX` escape the file may hold as a character. */
+const HAS_UNICODE_ESCAPE = /\\u[0-9a-fA-F]{4}/
+/** `old_string` carries a non-ASCII character the file may hold as an escape. */
+const HAS_NON_ASCII = /[\u0080-￿]/
+
+/** Curly quotes to straight. Length-preserving: one character for one. */
+function straightenQuotes(text: string): string {
+	return text
+		.replaceAll(LEFT_SINGLE_QUOTE, "'")
+		.replaceAll(RIGHT_SINGLE_QUOTE, "'")
+		.replaceAll(LEFT_DOUBLE_QUOTE, '"')
+		.replaceAll(RIGHT_DOUBLE_QUOTE, '"')
+}
+
+/**
+ * Replace each `\uXXXX` escape with its character, leaving an escaped
+ * backslash (`\\`) untouched so `\\u0041` stays the five characters it is
+ * rather than becoming a stray `A`.
+ */
+function decodeUnicodeEscapes(text: string): string {
+	return text.replace(/(\\\\)|\\u([0-9a-fA-F]{4})/g, (whole, backslashes, hex) =>
+		backslashes !== undefined ? whole : String.fromCharCode(Number.parseInt(hex, 16)),
+	)
+}
+
+/** The length `text` would have if every non-ASCII character were a `\uXXXX`. */
+function escapedLength(text: string): number {
+	let nonAscii = 0
+	for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) >= 128) nonAscii++
+	return text.length + 5 * nonAscii
+}
+
+/** Consecutive backslashes immediately before index `at`. */
+function trailingBackslashes(text: string, at: number): number {
+	let count = 0
+	while (text[at - 1 - count] === '\\') count++
+	return count
+}
+
+/** Escape a literal string so it matches itself inside a `RegExp`. */
+function escapeRegExp(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * A pattern that matches `model` where every non-ASCII character appears as its
+ * `\uXXXX` escape (case-insensitive in the hex letters) and every ASCII
+ * character appears literally. Used to find, in a file written with escapes,
+ * the span a model wrote with the characters themselves.
+ */
+function buildEscapeTolerantPattern(model: string): string {
+	let pattern = ''
+	for (let i = 0; i < model.length; i++) {
+		const code = model.charCodeAt(i)
+		if (code >= 128) {
+			pattern += '\\\\u'
+			for (const digit of code.toString(16).padStart(4, '0'))
+				pattern += digit >= 'a' ? `[${digit}${digit.toUpperCase()}]` : digit
+		} else {
+			// biome-ignore lint/style/noNonNullAssertion: index < length
+			pattern += escapeRegExp(model[i]!)
+		}
+	}
+	return pattern
+}
+
+/**
+ * Find, in `file`, the escaped form of `model` — where `model` is written with
+ * real non-ASCII characters and `file` holds them as `\uXXXX`. Returns the
+ * matched (escaped) substring, or null when there is no such span, when the
+ * pattern would be ambiguous, or when a matched `\u` is itself escaped by an
+ * odd run of backslashes (a literal `\u`, not an escape).
+ */
+function findEscapedForm(model: string, file: string): string | null {
+	// A model ending in an odd number of backslashes cannot be the clean prefix
+	// of an escape sequence; bail rather than build a pattern that misreads it.
+	if (trailingBackslashes(model, model.length) % 2 === 1) return null
+
+	// Offsets, within the escaped match, whose backslash parity must be checked
+	// so a literal `\u` in the file is not mistaken for an escape.
+	const sensitiveOffsets: number[] = model[0] === '\\' ? [0] : []
+	let offset = 0
+	for (let i = 0; i < model.length; i++) {
+		if (model.charCodeAt(i) >= 128) {
+			sensitiveOffsets.push(offset)
+			offset += 6
+		} else {
+			offset += 1
+		}
+	}
+
+	let regex: RegExp
+	try {
+		regex = new RegExp(buildEscapeTolerantPattern(model), 'g')
+	} catch {
+		return null
+	}
+	for (let match = regex.exec(file); match !== null; match = regex.exec(file)) {
+		const at = match.index
+		if (sensitiveOffsets.every((o) => trailingBackslashes(file, at + o) % 2 === 0)) {
+			return file.indexOf(match[0]) === at ? match[0] : null
+		}
+		regex.lastIndex = at + 1
+	}
+	return null
+}
+
+/**
+ * The span of `content` that `oldString` refers to, recovering it across a
+ * quote- or escape-only difference, or null when nothing matches even then.
+ *
+ * The returned string is a real substring of `content` (or its escaped form),
+ * so the caller can run the ordinary uniqueness check and splice against it.
+ */
+export function resolveOldString(content: string, oldString: string): string | null {
+	if (content.includes(oldString)) return oldString
+
+	const straight = straightenQuotes(oldString)
+	const quoteIndex = straightenQuotes(content).indexOf(straight)
+	if (quoteIndex !== -1) return content.substring(quoteIndex, quoteIndex + oldString.length)
+
+	if (HAS_UNICODE_ESCAPE.test(oldString)) {
+		const decoded = decodeUnicodeEscapes(oldString)
+		if (decoded !== oldString && content.includes(decoded)) return decoded
+	}
+
+	if (HAS_NON_ASCII.test(oldString)) {
+		if (escapedLength(oldString) > content.length || !content.includes('\\u')) return null
+		return findEscapedForm(oldString, content)
+	}
+
+	return null
+}
+
+/** Is `char` at `index` opening a quote (preceded by a boundary) rather than closing one? */
+function isOpeningPosition(chars: readonly string[], index: number): boolean {
+	if (index === 0) return true
+	const before = chars[index - 1]
+	return (
+		before === ' ' ||
+		before === '\t' ||
+		before === '\n' ||
+		before === '\r' ||
+		before === '(' ||
+		before === '[' ||
+		before === '{' ||
+		before === '—' ||
+		before === '–'
+	)
+}
+
+/** Apply curly double quotes to `text`, choosing opening vs closing by context. */
+function curlifyDoubleQuotes(text: string): string {
+	const chars = [...text]
+	return chars
+		.map((char, index) =>
+			char === '"'
+				? isOpeningPosition(chars, index)
+					? LEFT_DOUBLE_QUOTE
+					: RIGHT_DOUBLE_QUOTE
+				: char,
+		)
+		.join('')
+}
+
+/** Apply curly single quotes to `text`; an apostrophe between letters is always closing. */
+function curlifySingleQuotes(text: string): string {
+	const chars = [...text]
+	return chars
+		.map((char, index) => {
+			if (char !== "'") return char
+			const before = index > 0 ? chars[index - 1] : undefined
+			const after = index < chars.length - 1 ? chars[index + 1] : undefined
+			const betweenLetters =
+				before !== undefined && /\p{L}/u.test(before) && after !== undefined && /\p{L}/u.test(after)
+			if (betweenLetters) return RIGHT_SINGLE_QUOTE
+			return isOpeningPosition(chars, index) ? LEFT_SINGLE_QUOTE : RIGHT_SINGLE_QUOTE
+		})
+		.join('')
+}
+
+/**
+ * Carry the transformation that matched `oldString` across to `newString`, so
+ * the replacement matches the span it lands in rather than the literal the
+ * model typed.
+ *
+ * `resolved` is what {@link resolveOldString} returned — equal to `oldString`
+ * for an exact match (then `newString` is returned unchanged), and otherwise
+ * the real span, which tells us which strategy fired.
+ */
+export function reconcileNewString(oldString: string, resolved: string, newString: string): string {
+	if (resolved === oldString) return newString
+
+	// character in old, escape in file: re-escape new's non-ASCII to the file's
+	// hex spelling, matching the letter-case the file used.
+	if (
+		HAS_NON_ASCII.test(oldString) &&
+		escapedLength(oldString) === resolved.length &&
+		findEscapedForm(oldString, resolved) !== null
+	) {
+		const perChar = new Map<number, string>()
+		let upper = 0
+		let lower = 0
+		for (let oldIndex = 0, resolvedIndex = 0; oldIndex < oldString.length; oldIndex++) {
+			const code = oldString.charCodeAt(oldIndex)
+			if (code >= 128) {
+				const hex = resolved.slice(resolvedIndex + 2, resolvedIndex + 6)
+				perChar.set(code, hex)
+				for (const digit of hex)
+					if (digit >= 'a' && digit <= 'f') lower++
+					else if (digit >= 'A' && digit <= 'F') upper++
+				resolvedIndex += 6
+			} else {
+				resolvedIndex += 1
+			}
+		}
+		return newString.replace(/[\u0080-￿]/g, (char) => {
+			const code = char.charCodeAt(0)
+			const known = perChar.get(code)
+			if (known !== undefined) return `\\u${known}`
+			const hex = code.toString(16).padStart(4, '0')
+			return `\\u${upper > lower ? hex.toUpperCase() : hex}`
+		})
+	}
+
+	// escape in old, character in file: decode new's escapes to match.
+	if (HAS_UNICODE_ESCAPE.test(oldString) && decodeUnicodeEscapes(oldString) === resolved) {
+		return decodeUnicodeEscapes(newString)
+	}
+
+	// quote difference: re-apply the file's curly quotes to new, by kind.
+	const hasCurlyDouble =
+		resolved.includes(LEFT_DOUBLE_QUOTE) || resolved.includes(RIGHT_DOUBLE_QUOTE)
+	const hasCurlySingle =
+		resolved.includes(LEFT_SINGLE_QUOTE) || resolved.includes(RIGHT_SINGLE_QUOTE)
+	let reconciled = newString
+	if (hasCurlyDouble) reconciled = curlifyDoubleQuotes(reconciled)
+	if (hasCurlySingle) reconciled = curlifySingleQuotes(reconciled)
+	return reconciled
+}

package/src/tools/builtins/edit.ts

@@ -5,6 +5,7 @@ import type { ToolContext, ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
+import { clip, describeChange } from './classifier-input.js'
 import { fingerprintContent, staleFileError, unreadFileError } from './content-fingerprint.js'
 import { type NormalizedEditInput, applyEdit, normalizeEditInput } from './edit-apply.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
@@ -393,6 +394,18 @@ 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',
+	// The classifier judges which file changes and in what way, in a line.
+	classifierInput: (input: EditInput) => {
+		if (input.edits !== undefined) {
+			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` : ''
+			return clip(`${input.path}: ${input.edits.length} edits: ${shown.join('; ')}${more}`, 1500)
+		}
+		const removed = input.old_string ?? input.oldStr
+		const added = input.new_string ?? input.newStr
+		return clip(`${input.path}: ${describeChange(removed, added)}`, 1500)
+	},
 	permissions: ['file_write'],
 	readOnly: false,
 	destructive: false,

package/src/tools/builtins/monitor.ts

@@ -178,6 +178,10 @@ export function createMonitorTool(options: MonitorToolOptions = {}) {
 		// has no `command`, so a rule written for commands has nothing to match
 		// and cannot allow it; `requiresApproval` below is what asks.
 		commandArgument: 'command',
+		classifierInput: (input: MonitorInput) =>
+			input.command !== undefined
+				? `[long-running watch] ${input.command}`
+				: `[long-running WebSocket watch] ${JSON.stringify(input.ws)}`,
 		commandDialect: bashToolDialect,
 		// `network_access` too: a WebSocket call reaches the network. The gate
 		// reads a tool's `category`, not this list, to route a call, so declaring

package/src/tools/builtins/web.ts

@@ -11,6 +11,7 @@ import {
 import { WebFetchRefusedError } from '../../connector/web/types.js'
 import type { ToolContext } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
+import { clip } from './classifier-input.js'
 
 /**
  * The two web tools, and the reason they are one file.
@@ -151,6 +152,8 @@ export const WebFetchTool = defineTool({
 	// preset — handing outbound reach to runs whose sandbox was never asked
 	// to confine the network.
 	category: 'network',
+	// The classifier judges the address and what is asked of it.
+	classifierInput: (input) => `${clip(input.url, 1000)}: ${clip(input.prompt, 300)}`,
 	permissions: ['network_access'],
 	// Reads a page and changes nothing HERE. That is not the same as
 	// harmless — a GET can still act on a remote system — which is why the

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

@@ -6,6 +6,7 @@ import type { ToolFacts } from '../../types/tool/presentation.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
+import { clip } from './classifier-input.js'
 import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
 import { fileWriteResult } from './file-write-result.js'
@@ -93,6 +94,11 @@ 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',
+	// The classifier judges where a file is written and how much, not the body.
+	classifierInput: (input: WriteInput) => {
+		const body = input.content ?? input.newStr ?? ''
+		return `${input.path}: writes ${body.length} characters, starting ${JSON.stringify(clip(body, 300))}`
+	},
 	permissions: ['file_write'],
 	readOnly: false,
 	destructive: true,

package/src/tools/defineTool.ts

@@ -33,6 +33,8 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	capturesScreen?: boolean | ((input: z.infer<S>) => boolean)
 	/** Whether this exact call always needs a person's approval; see {@link ToolDefinition.requiresApproval}. */
 	requiresApproval?: boolean | ((input: z.infer<S>) => boolean)
+	/** What the auto-mode classifier is shown of this call; see {@link ToolDefinition.classifierInput}. */
+	classifierInput?: (input: z.infer<S>) => string
 	/** Free-form filtering data, never sent to the model; see {@link ToolDefinition.metadata}. */
 	metadata?: Readonly<Record<string, unknown>>
 	/** Batch ordering boundary; see {@link ToolDefinition.executionBarrier}. */
@@ -186,6 +188,7 @@ export function defineTool<S extends z.ZodType>(
 							: () => options.requiresApproval as boolean,
 				}
 			: {}),
+		...(options.classifierInput !== undefined ? { classifierInput: options.classifierInput } : {}),
 		...(options.metadata !== undefined ? { metadata: options.metadata } : {}),
 
 		async execute(input: TInput, context: ToolContext): Promise<ToolResult> {

package/src/types/acp/index.ts

@@ -43,6 +43,13 @@ export interface AcpInitializeResult {
 	readonly promptAttachments?: boolean
 	/** True only when this host applies captured effort and review settings per prompt. */
 	readonly promptOptions?: boolean
+	/**
+	 * The review modes beyond the original five (`prompt`, `plan`,
+	 * `accept-edits`, `auto`, `strict`) that this host applies per prompt:
+	 * `bypass` and `classify`, when it supports them. Absent: it accepts only
+	 * the original five, and refuses the others before a turn starts.
+	 */
+	readonly promptPermissionModes?: readonly ('bypass' | 'classify')[]
 	/** Optional, explicitly installed Namzu host methods; core ACP peers can ignore them. */
 	readonly extensions?: readonly string[]
 	readonly protocolVersion: number

package/src/types/code-analysis/index.ts

@@ -119,6 +119,14 @@ export interface AnalysisFunction {
 	readonly id: number
 	/** `null` for an anonymous function with nothing to infer a name from. */
 	readonly name: string | null
+	/**
+	 * `name` qualified by what holds it, when it is a member: `Svc.init` for a
+	 * method of the class `Svc` (a class expression assigned to a variable takes
+	 * the variable's name), `obj.run` for a method of an object literal assigned
+	 * to `obj`. Absent for a function that is not a member. `functionSource`
+	 * accepts either spelling.
+	 */
+	readonly qualifiedName?: string
 	readonly kind: AnalysisFunctionKind
 	/** Absolute path. */
 	readonly path: string
@@ -136,6 +144,17 @@ export interface AnalysisSourceSlice {
 	readonly chars: number
 	/** `true` when `text` is shorter than `chars` because of the size cap. */
 	readonly truncated: boolean
+	/**
+	 * Present when the cut was made around a position rather than at the end:
+	 * `text` is the function's first `headerChars` characters, a marker for
+	 * what was left out, then the file's own characters `from` to `to`, which
+	 * contain the position asked about. `from` and `to` are offsets into the file.
+	 */
+	readonly window?: {
+		readonly headerChars: number
+		readonly from: number
+		readonly to: number
+	}
 }
 
 export interface IndexRequest extends AnalysisCallOptions {
@@ -222,6 +241,11 @@ export interface EnclosingFunctionRequest extends AnalysisCallOptions {
 export interface AnalysisEnclosingFunction {
 	/** `null` when the position is not inside any function — a real answer. */
 	readonly function: AnalysisFunction | null
+	/**
+	 * When `function` is `null` because the position is in a class body outside
+	 * every method (a field initializer, a `static {}` block): that class.
+	 */
+	readonly inClass?: string
 	/** The function's parents, innermost first. */
 	readonly parents: readonly AnalysisFunction[]
 	readonly source?: AnalysisSourceSlice
@@ -235,6 +259,11 @@ export interface FunctionSourceRequest extends AnalysisPaging {
 	readonly path?: string
 	readonly name?: string
 	readonly maxChars?: number
+	/**
+	 * A position in the function. When the source is longer than `maxChars`, the
+	 * slice is cut around it instead of at the end, and always contains it.
+	 */
+	readonly around?: { readonly line: number; readonly column?: number }
 }
 
 export interface AnalysisFunctionSource {
@@ -245,7 +274,11 @@ export interface AnalysisFunctionSource {
 
 export interface CallersOfRequest extends AnalysisPaging {
 	readonly root: string
-	/** The callee text: `foo`, `obj.foo`, `this.foo`. */
+	/**
+	 * The callee text: `foo`, `obj.foo`, `this.foo`. A method's qualified name
+	 * (`Svc.init`, as `functionSource` shows it) finds `this.init()` inside
+	 * `Svc` as a resolved call, and every other `<expr>.init()` as `text-only`.
+	 */
 	readonly name: string
 	/**
 	 * `file` looks in `path` only and is the default, because a callee matched
@@ -266,8 +299,19 @@ export interface AnalysisCallSite {
 	readonly line: number
 	readonly column: number
 	readonly callee: string
-	readonly kind: 'call' | 'new'
+	/**
+	 * `call-via` is `f.call(…)`, `f.apply(…)` or `f.bind(…)` of the callee (a
+	 * use, not necessarily a call); `tagged` is a tagged template.
+	 */
+	readonly kind: 'call' | 'new' | 'call-via' | 'tagged'
 	readonly argumentCount: number
+	/**
+	 * Only when the request named a method by its qualified name: `resolved`
+	 * for `this.m()` inside the class that declares it and for the qualified
+	 * text itself, `text-only` for any other receiver, which may be an
+	 * unrelated method of the same name.
+	 */
+	readonly resolution?: 'resolved' | 'text-only'
 	/** The function the call sits in; absent at the top level of a file. */
 	readonly caller?: AnalysisFunction
 	/** See {@link AnalysisLiteralHit.stale}. */
@@ -290,7 +334,11 @@ export type AnalysisModuleEdge =
 	  }
 	| {
 			readonly direction: 'export'
-			readonly kind: 'named' | 'default' | 'reexport' | 'star'
+			/**
+			 * `type` is a type-only export, `commonjs` is `module.exports` or
+			 * `exports.x`, `assign` is `export =`.
+			 */
+			readonly kind: 'named' | 'default' | 'reexport' | 'star' | 'type' | 'commonjs' | 'assign'
 			readonly name: string
 			readonly source?: string
 			readonly line: number

package/src/types/hitl/index.ts

@@ -1,5 +1,6 @@
 import type { CostInfo, TokenUsage } from '../common/index.js'
 import type { CheckpointId, PlanId, SessionId, TurnId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
 
 export type { CheckpointId }
 
@@ -139,7 +140,28 @@ export type HITLDecisionRequest =
 			question: UserQuestionData
 	  }
 
-export type ResumeHandler = (request: HITLDecisionRequest) => Promise<HITLResumeDecision>
+/**
+ * What the turn offers a resume handler besides the request, in memory only.
+ *
+ * Kept out of {@link HITLDecisionRequest} on purpose: the request is written
+ * to the session log when a decision takes long, and a transcript does not
+ * belong there. A handler that does not need it ignores the argument; one that
+ * wraps another passes it on.
+ */
+export interface ResumeContext {
+	/**
+	 * The conversation as it stands now, the batch under review included.
+	 * Read on demand; the array is the turn's own, so a caller must not change it.
+	 */
+	readonly transcript: () => readonly Message[]
+	/** The turn's cancellation signal, when it has one. */
+	readonly signal?: AbortSignal
+}
+
+export type ResumeHandler = (
+	request: HITLDecisionRequest,
+	context?: ResumeContext,
+) => Promise<HITLResumeDecision>
 
 export interface ToolCallSummary {
 	id: string
@@ -158,6 +180,24 @@ export interface ToolCallSummary {
 		reason?: string
 		/** A matching rule requested review; read-only exemptions must not bypass it. */
 		explicitReview?: true
+		/**
+		 * A rule written to ask a person (a `review` rule), or a hook that asked
+		 * for one, requested this review. Unlike {@link explicitReview} it is not
+		 * set when an `allow` rule was demoted to review because the call reaches
+		 * past its boundary. `bypass` and `classify` keep this question for a
+		 * person; they answer the demoted kind themselves.
+		 */
+		askRule?: true
+		/**
+		 * How wide the `allow` rule that settled this call is. `tool` means the
+		 * rule names the whole tool, a category, a tier or a source, or its
+		 * pattern matches every input; `pattern` means it matches some inputs
+		 * only. Present only when `decision` is `allow` and a rule (not the
+		 * read-only allowance) decided it. The `classify` review mode reads it:
+		 * a whole-tool allow for a shell tool would let the classifier never
+		 * see a command.
+		 */
+		allowScope?: 'tool' | 'pattern'
 	}
 	/**
 	 * What this call reaches beyond the turn's ordinary boundary, as the
@@ -278,6 +318,14 @@ export interface ToolCallEscalation {
 	 * tool that declares `commandArgument`.
 	 */
 	dangerousRemoval?: string
+	/**
+	 * Why the kernel could not finish looking at this call: the check that
+	 * finds the escalations above threw, so none of them is known to be
+	 * absent. Treated as the most serious escalation there is, because the
+	 * safety checks did not run: a person is asked in every mode, `bypass`
+	 * and `classify` included, and it is refused when nobody can be asked.
+	 */
+	unfinishedCheck?: string
 }
 
 export interface ToolModification {

package/src/types/tool/index.ts

@@ -1178,6 +1178,23 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 */
 	requiresApproval?(input: TInput): boolean
 
+	/**
+	 * What the auto-mode safety classifier is shown of this call.
+	 *
+	 * The classifier (`createAutoReviewClassifier`, review mode `classify`)
+	 * reads a compact transcript, not raw tool arguments: a tool knows which
+	 * part of its own input says what the call DOES. A shell tool returns the
+	 * command, a file tool the path and a short summary of the change, a fetch
+	 * the address. The string should be short and carry no content the model
+	 * could not already be trusted with; the runtime caps its length.
+	 *
+	 * Absent, the classifier is shown the input as compact JSON. A tool whose
+	 * input is large or opaque (a file body, a binary payload) should declare
+	 * this so the classifier judges the action rather than the bulk. Never
+	 * called with a tool RESULT: results are untrusted and are not shown.
+	 */
+	classifierInput?(input: TInput): string
+
 	/**
 	 * Free-form, tool-author-declared data for filtering and behaviour
 	 * customization — never a classification the runtime itself reads.