@namzu/sdk 52.3.0 → 52.5.0

package/src/tools/builtins/monitor.ts

@@ -6,6 +6,17 @@ import {
 	MONITOR_TIMEOUT_MIN_MS,
 	formatMonitorDuration,
 } from '../../runtime/jobs/monitor-stream.js'
+import {
+	WEBSOCKET_PROTOCOLS_MAX,
+	WebSocketRefusedError,
+	type WebSocketVetOptions,
+	vetWebSocketTarget,
+	webSocketHostname,
+	webSocketProtocolsProblem,
+	webSocketSandboxRefusal,
+	webSocketUrlProblem,
+} from '../../runtime/jobs/websocket-source.js'
+import type { MonitorWebSocketTarget } from '../../types/tool/index.js'
 import {
 	bashToolDialect,
 	hostCommandShell,
@@ -38,42 +49,82 @@ import {
  * read the command the way they read `bash`'s, and it is never read-only. It
  * has no way out of the sandbox: a watch that outlives one approved call must
  * not run outside the boundary that call was approved under.
+ *
+ * A source can also be a WebSocket (`ws`), for services that push their events
+ * and offer no command that prints them. That one is a different thing to
+ * approve: it is not a shell line, it opens a connection FROM THE HOST to an
+ * address the model chose, and it does so outside any sandbox. So it is read
+ * by no command rule, it is always reviewed, a sandbox that blocks the network
+ * refuses it, and the address is checked and pinned (see
+ * `runtime/jobs/websocket-source.ts`). Untrusted frames reach the model the way
+ * a command's lines do: through the monitor event path, in its untrusted frame.
  */
 
-const inputSchema = z.object({
-	description: z
-		.string()
-		.min(1)
-		.max(200)
-		.describe(
-			'What you are watching, in a few specific words. It is shown with every event ("Monitor event: <description>"), so make it identify this watch among several: "errors in deploy log", not "monitor".',
-		),
-	command: z
+const webSocketInput = z.object({
+	url: z
 		.string()
-		.min(1)
-		// Same rewrite as `bash`, for the same reason: the rules read the line a
-		// shell will run.
-		.transform((command) =>
-			isWindowsBash(hostCommandShell()) ? rewriteWindowsNullRedirect(command) : command,
-		)
-		.describe(
-			'The shell command to watch. Each line it prints to stdout becomes an event. It runs until it ends or the timeout; it must not need stdin.',
-		),
-	timeout_ms: z
-		.preprocess(
-			(v) => (typeof v === 'string' ? Number(v) : v),
-			z
-				.number()
-				.int()
-				.min(MONITOR_TIMEOUT_MIN_MS)
-				.max(MONITOR_TIMEOUT_MAX_MS)
-				.default(MONITOR_TIMEOUT_DEFAULT_MS),
-		)
+		.superRefine((value, ctx) => {
+			const problem = webSocketUrlProblem(value)
+			if (problem !== undefined) ctx.addIssue({ code: z.ZodIssueCode.custom, message: problem })
+		})
 		.describe(
-			`How long to watch, in milliseconds. Default ${MONITOR_TIMEOUT_DEFAULT_MS}. The host caps it (30 minutes by default; shorter in a single-shot run), and a larger value is lowered to that cap without an error; the result states the time actually granted.`,
+			'The ws:// or wss:// URL to connect to. A query string is kept; credentials in it are refused.',
 		),
+	protocols: z
+		.array(z.string())
+		.max(WEBSOCKET_PROTOCOLS_MAX)
+		.superRefine((value, ctx) => {
+			const problem = webSocketProtocolsProblem(value)
+			if (problem !== undefined) ctx.addIssue({ code: z.ZodIssueCode.custom, message: problem })
+		})
+		.optional()
+		.describe('Subprotocol names to offer, when the service asks for one.'),
 })
 
+const inputSchema = z
+	.object({
+		description: z
+			.string()
+			.min(1)
+			.max(200)
+			.describe(
+				'What you are watching, in a few specific words. It is shown with every event ("Monitor event: <description>"), so make it identify this watch among several: "errors in deploy log", not "monitor".',
+			),
+		command: z
+			.string()
+			.min(1)
+			// Same rewrite as `bash`, for the same reason: the rules read the line a
+			// shell will run.
+			.transform((command) =>
+				isWindowsBash(hostCommandShell()) ? rewriteWindowsNullRedirect(command) : command,
+			)
+			.optional()
+			.describe(
+				'The shell command to watch. Each line it prints to stdout becomes an event. It runs until it ends or the timeout; it must not need stdin. Give this or ws, not both.',
+			),
+		ws: webSocketInput
+			.optional()
+			.describe(
+				'Watch a WebSocket instead of a command: each line of each text frame the server sends becomes an event. Give this or command, not both.',
+			),
+		timeout_ms: z
+			.preprocess(
+				(v) => (typeof v === 'string' ? Number(v) : v),
+				z
+					.number()
+					.int()
+					.min(MONITOR_TIMEOUT_MIN_MS)
+					.max(MONITOR_TIMEOUT_MAX_MS)
+					.default(MONITOR_TIMEOUT_DEFAULT_MS),
+			)
+			.describe(
+				`How long to watch, in milliseconds. Default ${MONITOR_TIMEOUT_DEFAULT_MS}. The host caps it (30 minutes by default; shorter in a single-shot run), and a larger value is lowered to that cap without an error; the result states the time actually granted.`,
+			),
+	})
+	.refine((input) => (input.command === undefined) !== (input.ws === undefined), {
+		message: 'Give exactly one of command and ws.',
+	})
+
 type MonitorInput = z.infer<typeof inputSchema>
 
 export const MONITOR_TOOL_NAME = 'monitor'
@@ -88,109 +139,231 @@ export const MONITOR_CANNOT_DETACH =
 	'monitor is unavailable: this sandbox cannot start a detached process, and the watch will not be run on the host to get around it. Run the command in the foreground with bash, with a timeout.'
 
 const MONITOR_DESCRIPTION =
-	'Starts a command and tells you about each line it prints to stdout, as it prints it, while you keep working. Lines that arrive within 200 ms come together as one event. Use it to watch a log, a test or deploy run, a status endpoint — anything where you must react to something happening INSIDE a long-running command. For ONE notification when something finishes, do not use this: run bash with run_in_background and wait_for_job. Every stage of a pipe must flush per line or events arrive late or never (grep --line-buffered, awk with fflush(), sed -u; `head` cannot). Make the filter match failure as well as success (crash, Traceback, Error, FAILED, Killed…): silence from a monitor is not success. Poll a remote API no faster than every 30 seconds. stderr is not an event; read it with job. A monitor that prints too much is stopped, so filter at the source. It expires after the timeout (default 5 minutes, at most 30) and you get one notice; start it again if you still need it. Stop one early with job {"action":"kill","id":"<id>"}.'
-
-export const MonitorTool = defineTool({
-	name: MONITOR_TOOL_NAME,
-	description: MONITOR_DESCRIPTION,
-	inputSchema,
-	category: 'shell',
-	// Bash's, because it IS a shell command: the gate reads the line, splits
-	// chains, and applies the operator's rules to each part.
-	commandArgument: 'command',
-	commandDialect: bashToolDialect,
-	permissions: ['shell_execute'],
-	readOnly: false,
-	destructive: (input: MonitorInput) => isDangerousCommand(input.command),
-	// Starting a monitor registers a job against the owner's cap and its id
-	// is then named in later calls; two at once could race the cap, as they
-	// can for a background `bash`.
-	concurrencySafe: false,
-
-	presentCall(input) {
-		if (typeof input.command !== 'string') return undefined
-		return {
-			kind: 'generic',
-			label: `Monitor · ${typeof input.description === 'string' ? input.description : input.command}`,
-			facts: { kind: 'command', command: input.command, background: true },
-		}
-	},
-
-	async execute(input, context) {
-		if (isDangerousCommand(input.command)) {
-			return {
-				success: false,
-				output: '',
-				error: `Dangerous command blocked: "${input.command}"`,
-				facts: { kind: 'failure', reason: 'blocked', subject: MONITOR_TOOL_NAME },
+	'Starts a command and tells you about each line it prints to stdout, as it prints it, while you keep working. Lines that arrive within 200 ms come together as one event. Use it to watch a log, a test or deploy run, a status endpoint — anything where you must react to something happening INSIDE a long-running command. For ONE notification when something finishes, do not use this: run bash with run_in_background and wait_for_job. Every stage of a pipe must flush per line or events arrive late or never (grep --line-buffered, awk with fflush(), sed -u; `head` cannot). Make the filter match failure as well as success (crash, Traceback, Error, FAILED, Killed…): silence from a monitor is not success. Poll a remote API no faster than every 30 seconds. stderr is not an event; read it with job. A monitor that prints too much is stopped, so filter at the source. It expires after the timeout (default 5 minutes, at most 30) and you get one notice; start it again if you still need it. Stop one early with job {"action":"kill","id":"<id>"}. ' +
+	'To watch a service that PUSHES events (a CI or log stream, a change feed) give ws instead of command: { "url": "wss://…", "protocols": [...] }. Each line of each text frame becomes an event, binary frames are only counted, and the watch ends when the server closes the connection. Use it for a push stream, not for request and response. It connects from this machine, so private and local addresses are refused, and you are asked before it connects.'
+
+/** What a host can tune about the WebSocket source; for tests only, see {@link WebSocketVetOptions}. */
+export interface MonitorToolOptions {
+	readonly webSocket?: WebSocketVetOptions
+	/**
+	 * How to turn web access on, in the host's own words, appended to the
+	 * refusal a WebSocket call gets while it is off. The SDK cannot name a
+	 * switch it does not own (a CLI config key, a desktop setting), and a
+	 * refusal that only says "off" leaves the operator guessing. One short
+	 * sentence; it is shown to the model and the operator as written.
+	 */
+	readonly webAccessHint?: string
+}
+
+/** The text that says a WebSocket watch was refused because the host has web access off. */
+export const MONITOR_WEBSOCKET_WEB_OFF =
+	"WebSocket monitors follow the host's web access setting, and web access is switched off here, so no connection was opened. Watch the service with a command (for example curl or websocat through monitor) if the operator allows it."
+
+const MONITOR_WEBSOCKET_NOT_SUPPORTED =
+	'This host cannot start a WebSocket monitor, so no connection was opened. Watch the service with a command through monitor if the operator allows it.'
+
+/**
+ * The tool, built once with defaults for a host and again by a test that needs
+ * to reach a server on this machine. The options belong to whoever builds the
+ * tool; nothing a model sends can set them.
+ */
+export function createMonitorTool(options: MonitorToolOptions = {}) {
+	return defineTool({
+		name: MONITOR_TOOL_NAME,
+		description: MONITOR_DESCRIPTION,
+		inputSchema,
+		category: 'shell',
+		// Bash's, because it IS a shell command: the gate reads the line, splits
+		// chains, and applies the operator's rules to each part. A WebSocket call
+		// 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
+		// it changes no decision for a command; it says what the tool may do.
+		permissions: ['shell_execute', 'network_access'],
+		readOnly: false,
+		destructive: (input: MonitorInput) =>
+			input.command !== undefined && isDangerousCommand(input.command),
+		// A WebSocket call is the one input-aware seam the gate offers that no
+		// allow rule or mode outranks: it connects from the host, outside any
+		// sandbox, to an address the model chose. `category: 'shell'` is what the
+		// sandboxed-shell preset auto-approves, and moving the whole tool to
+		// `network` would start asking about commands that were never a question;
+		// this asks only about the connection. It is stronger than "review where
+		// the mode reviews non-read-only calls": `auto` mode and an unattended
+		// turn are asked too (or refuse when nobody can be asked), which is the
+		// point for a connection that leaves the boundary those modes rely on.
+		requiresApproval: (input: MonitorInput) => input.ws !== undefined,
+		// Starting a monitor registers a job against the owner's cap and its id
+		// is then named in later calls; two at once could race the cap, as they
+		// can for a background `bash`.
+		concurrencySafe: false,
+
+		presentCall(input) {
+			const label = typeof input.description === 'string' ? input.description : undefined
+			if (input.ws !== undefined && typeof input.ws === 'object') {
+				const ws = input.ws as { url?: unknown; protocols?: unknown }
+				if (typeof ws.url !== 'string') return undefined
+				const protocols =
+					Array.isArray(ws.protocols) && ws.protocols.length > 0
+						? ` (subprotocols: ${ws.protocols.join(', ')})`
+						: ''
+				// What will happen, said plainly, because this is what a person
+				// approves: no command line stands in for it.
+				return {
+					kind: 'generic',
+					label: `Monitor${label ? ` · ${label}` : ''} · WebSocket ${ws.url}${protocols}`,
+				}
 			}
-		}
-		if (backgroundTasksDisabled()) {
+			if (typeof input.command !== 'string') return undefined
 			return {
-				success: false,
-				output: '',
-				error: `Background jobs are switched off here (${DISABLE_BACKGROUND_TASKS_ENV}), and a monitor is one. Check in the foreground with bash instead.`,
+				kind: 'generic',
+				label: `Monitor · ${label ?? input.command}`,
+				facts: { kind: 'command', command: input.command, background: true },
 			}
-		}
-		// Same rule as background bash: the executor withholds the registry from
-		// a sandbox that cannot start a detached process, and this check is for
-		// the direct caller who hands both.
-		if (context.sandbox && context.sandbox.spawnDetached === undefined) {
-			return { success: false, output: '', error: MONITOR_CANNOT_DETACH }
-		}
-		const jobs = context.backgroundJobs
-		if (!jobs) {
-			return {
-				success: false,
-				output: '',
-				error:
-					'monitor was requested, but this host provides no background job registry. Run the command in the foreground with bash, with a timeout.',
+		},
+
+		async execute(input, context) {
+			if (input.command !== undefined && isDangerousCommand(input.command)) {
+				return {
+					success: false,
+					output: '',
+					error: `Dangerous command blocked: "${input.command}"`,
+					facts: { kind: 'failure', reason: 'blocked', subject: MONITOR_TOOL_NAME },
+				}
 			}
-		}
-		if (!jobs.startMonitor) {
-			return {
-				success: false,
-				output: '',
-				error:
-					'This host cannot deliver monitor events, so no watch was started. Use bash with run_in_background and wait_for_job to be told when a command finishes.',
+			if (backgroundTasksDisabled()) {
+				return {
+					success: false,
+					output: '',
+					error: `Background jobs are switched off here (${DISABLE_BACKGROUND_TASKS_ENV}), and a monitor is one. Check in the foreground with bash instead.`,
+				}
+			}
+			// What is checked about a connection is checked before anything that
+			// speaks of commands, so a refusal names its own cause.
+			let webSocket: MonitorWebSocketTarget | undefined
+			if (input.ws !== undefined) {
+				// The operator's switch for reaching the web at all. A host that has
+				// not given this turn a web capability has not decided to let the
+				// model open connections, and a WebSocket is one.
+				if (context.web?.fetch === undefined) {
+					return {
+						success: false,
+						output: '',
+						error: options.webAccessHint
+							? `${MONITOR_WEBSOCKET_WEB_OFF} ${options.webAccessHint}`
+							: MONITOR_WEBSOCKET_WEB_OFF,
+					}
+				}
+				const hostname = webSocketHostname(input.ws.url)
+				const sandboxRefusal = webSocketSandboxRefusal(context.sandbox, hostname)
+				if (sandboxRefusal !== undefined) {
+					return { success: false, output: '', error: sandboxRefusal }
+				}
+				try {
+					const addresses = await vetWebSocketTarget(input.ws.url, options.webSocket)
+					webSocket = {
+						url: input.ws.url,
+						...(input.ws.protocols ? { protocols: input.ws.protocols } : {}),
+						addresses,
+					}
+				} catch (err) {
+					if (err instanceof WebSocketRefusedError) {
+						return { success: false, output: '', error: err.message }
+					}
+					throw err
+				}
+			} else if (context.sandbox && context.sandbox.spawnDetached === undefined) {
+				// Same rule as background bash: the executor withholds the registry
+				// from a sandbox that cannot start a detached process, and this check
+				// is for the direct caller who hands both.
+				return { success: false, output: '', error: MONITOR_CANNOT_DETACH }
 			}
-		}
-
-		try {
-			const { job, timeoutMs } = jobs.startMonitor({
-				command: input.command,
-				description: input.description,
-				timeoutMs: input.timeout_ms,
-				workingDirectory: context.workingDirectory,
-			})
-			// `startMonitor` returns before the process exists, and a spawn that
-			// fails reports a tick later; wait for that one event so "started" is
-			// never said of a watch that could not start.
-			const startup = await jobs.awaitStarted?.(job.id)
-			if (startup?.error !== undefined) {
+			const jobs = context.backgroundJobs
+			if (!jobs) {
 				return {
 					success: false,
 					output: '',
-					error: `${startup.error} (monitor ${job.id} did not run).`,
-					data: { jobId: job.id, monitor: true, startFailed: true },
+					error:
+						'monitor was requested, but this host provides no background job registry. Run the command in the foreground with bash, with a timeout.',
 				}
 			}
-			return {
-				success: true,
-				output: `Monitor started (job ${job.id}, expires in ${formatMonitorDuration(timeoutMs)} unless the command ends first; you get one notice at expiry — start it again if you still need the watch). Each line the command prints to stdout reaches you as an event while you keep working; do not poll or sleep. Stop it with job {"action":"kill","id":"${job.id}"}. An event may arrive while you are waiting for the user — it is not their reply.`,
-				data: { jobId: job.id, monitor: true, timeoutMs },
-				facts: { kind: 'command', command: input.command, background: true },
+			if (webSocket !== undefined && !jobs.startWebSocketMonitor) {
+				return {
+					success: false,
+					output: '',
+					error: MONITOR_WEBSOCKET_NOT_SUPPORTED,
+				}
 			}
-		} catch (err) {
-			// The per-owner cap, most likely; naming the limit is actionable.
-			return {
-				success: false,
-				output: '',
-				error: err instanceof Error ? err.message : String(err),
+			if (webSocket === undefined && !jobs.startMonitor) {
+				return {
+					success: false,
+					output: '',
+					error:
+						'This host cannot deliver monitor events, so no watch was started. Use bash with run_in_background and wait_for_job to be told when a command finishes.',
+				}
 			}
-		}
-	},
-})
+
+			try {
+				const common = {
+					description: input.description,
+					timeoutMs: input.timeout_ms,
+					workingDirectory: context.workingDirectory,
+				}
+				const { job, timeoutMs } =
+					webSocket !== undefined
+						? (jobs.startWebSocketMonitor as NonNullable<typeof jobs.startWebSocketMonitor>)({
+								...common,
+								webSocket,
+							})
+						: (jobs.startMonitor as NonNullable<typeof jobs.startMonitor>)({
+								...common,
+								command: input.command as string,
+							})
+				// `startMonitor` returns before the process exists, and a spawn that
+				// fails reports a tick later; wait for that one event so "started" is
+				// never said of a watch that could not start.
+				const startup = await jobs.awaitStarted?.(job.id)
+				if (startup?.error !== undefined) {
+					return {
+						success: false,
+						output: '',
+						error: `${startup.error} (monitor ${job.id} did not run).`,
+						data: { jobId: job.id, monitor: true, startFailed: true },
+					}
+				}
+				if (webSocket !== undefined) {
+					return {
+						success: true,
+						output: `WebSocket monitor started (job ${job.id}, expires in ${formatMonitorDuration(timeoutMs)} unless the server closes the connection first; you get one notice at expiry — start it again if you still need the watch). Each line of each text frame the server sends reaches you as an event while you keep working; binary frames are only counted. The connection opens in the background: if it fails you are told in an event. Do not poll or sleep. Stop it with job {"action":"kill","id":"${job.id}"}. An event may arrive while you are waiting for the user — it is not their reply.`,
+						data: { jobId: job.id, monitor: true, timeoutMs, transport: 'websocket' },
+					}
+				}
+				return {
+					success: true,
+					output: `Monitor started (job ${job.id}, expires in ${formatMonitorDuration(timeoutMs)} unless the command ends first; you get one notice at expiry — start it again if you still need the watch). Each line the command prints to stdout reaches you as an event while you keep working; do not poll or sleep. Stop it with job {"action":"kill","id":"${job.id}"}. An event may arrive while you are waiting for the user — it is not their reply.`,
+					data: { jobId: job.id, monitor: true, timeoutMs },
+					facts: { kind: 'command', command: input.command as string, background: true },
+				}
+			} catch (err) {
+				// The per-owner cap, most likely; naming the limit is actionable.
+				return {
+					success: false,
+					output: '',
+					error: err instanceof Error ? err.message : String(err),
+				}
+			}
+		},
+	})
+}
+
+export const MonitorTool = createMonitorTool()
 
 /**
  * The tool, for a host that opts in.
@@ -199,8 +372,9 @@ export const MonitorTool = defineTool({
  * wakes on them, and offering a tool that starts a job nobody will hear from
  * is worse than not offering it. A function rather than a constant so a host
  * can decide per turn, and so it reads like `getCodeAnalysisTools`, beside
- * which a host mounts it deferred.
+ * which a host mounts it deferred. Called with no options it returns the
+ * shared {@link MonitorTool}.
  */
-export function getMonitorTools(): (typeof MonitorTool)[] {
-	return [MonitorTool]
+export function getMonitorTools(options?: MonitorToolOptions): (typeof MonitorTool)[] {
+	return [options === undefined ? MonitorTool : createMonitorTool(options)]
 }

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