@namzu/sdk 45.1.0 → 48.0.0

package/src/authorization/shell-lexer.ts

@@ -70,6 +70,14 @@ export interface ShellWord {
 	readonly expands: boolean
 	/** True when any part of the word was quoted or escaped. */
 	readonly quoted: boolean
+	/**
+	 * True when the word reads a `$(…)` or backtick substitution. Read by
+	 * `redirectionTarget()`: an unquoted substitution used as a `<`/`>`
+	 * redirection target can run twice (measured, bash 5.2.21 and 5.3.15,
+	 * for a `${var:-…}`-style default value that turns out ambiguous), so
+	 * such a target is opaque rather than trusted to run once.
+	 */
+	readonly substitutes: boolean
 }
 
 /** A redirection: `2>&1`, `> file`, `<<EOF` and the rest. */
@@ -145,15 +153,53 @@ export interface ShellLexResult {
  * payload is decoded as bash reads it; for `dash` and friends the bash reading
  * is a close approximation, and the line is only as exact as that.
  */
-export const NESTED_SHELLS: ReadonlySet<string> = new Set([
-	'sh',
-	'bash',
-	'zsh',
-	'dash',
-	'ksh',
-	'ash',
-	'mksh',
-])
+export const NESTED_SHELLS: ReadonlySet<string> = PLAIN_SHELL_NAMES
+
+/** What {@link nestedShellCommand} found: the payload the lexer reads, or why it could not. */
+export type NestedShellCommand =
+	| {
+			/** The shell's basename, one of {@link NESTED_SHELLS}. */
+			readonly shell: string
+			/** The `-c` argument, read as a command line of its own. */
+			readonly payload: ShellWord
+	  }
+	| {
+			/** Why the lexer calls the line opaque instead (`nested shell option` …). */
+			readonly opaque: string
+	  }
+
+/**
+ * Whether the lexer reads a simple command's payload as a command line of
+ * its own: `words` are the command's words without its leading assignments.
+ * The command must, after unwrapping a chain of re-exec wrappers this
+ * recognises (`sudo`, `env`, `nice`, `timeout`, … — {@link unwrapReexecChain}
+ * in `reexec-wrapper.ts`, shared with `program.ts` so the two can never
+ * quietly disagree about where one ends), start a shell in
+ * {@link NESTED_SHELLS} by basename, exactly as written (`bash`, `/bin/sh`;
+ * not `bash.exe`, `BASH` or `fish`), or `busybox`/`toybox` running one, with
+ * `-c` among its options (clustered short forms included, `-ec`, `-lc`); the
+ * payload is the first argument that is not an option. `null` when it reads
+ * no payload — including when a wrapper consumed the whole line (`chroot
+ * /mnt` alone) or hit an option it does not recognise, in which case the
+ * whole line is opaque instead (below), not silently read as unremarkable.
+ *
+ * A host deciding on {@link lexShellCommandLine}'s reading uses this to know
+ * which text that reading already includes. Every other text a program runs
+ * as code — `powershell -c '…'`, `fish -c '…'`, `bash.exe -c '…'`, a script
+ * — is not in it.
+ */
+export function nestedShellCommand(words: readonly ShellWord[]): NestedShellCommand | null {
+	if (words.length === 0) return null
+	const chained = unwrapReexecChain(words)
+	if ('unknown' in chained) return { opaque: chained.unknown }
+	if ('none' in chained) return null
+	const invocation = shellInvocation(chained.rest)
+	if (invocation === null) return null
+	const found = shellDashC(invocation.rest)
+	if ('unknown' in found) return { opaque: found.unknown }
+	if ('none' in found) return null
+	return { shell: invocation.shell, payload: found.payload }
+}
 
 /** How many `bash -c` payloads deep the lexer follows before it gives up. */
 const MAX_SHELL_DEPTH = 4
@@ -161,6 +207,13 @@ const MAX_SHELL_DEPTH = 4
 const MAX_NESTING = 100
 
 import type { ShellDialect } from '../types/tool/index.js'
+import {
+	PLAIN_SHELL_NAMES,
+	REEXEC_WRAPPER_NAMES,
+	shellDashC,
+	shellInvocation,
+	unwrapReexecChain,
+} from './reexec-wrapper.js'
 
 export type { ShellDialect }
 
@@ -390,6 +443,14 @@ class WordBuilder {
 	quoted = false
 	/** A brace expansion, which POSIX shells do not perform. */
 	brace = false
+	/**
+	 * A `$(…)` or backtick substitution read in this word. Brace expansion
+	 * happens on the word's raw text BEFORE any expansion runs, so `{a,b}`
+	 * beside one duplicates it — `$(cmd){a,b}` runs `cmd` once per brace
+	 * alternative, not once — which the recursive read below does not
+	 * model; `brace && substitutes` together are opaque instead of trusted.
+	 */
+	substitutes = false
 	/** Unquoted `{` seen, and whether a `,` or `..` followed it: brace expansion. */
 	private braceOpen = false
 	private braceSeparator = false
@@ -435,6 +496,12 @@ class WordBuilder {
 		this.value += text
 		this.empty = false
 	}
+
+	/** A `$(…)` or backtick substitution, kept as written. */
+	substitution(text: string): void {
+		this.substitutes = true
+		this.expansion(text)
+	}
 }
 
 // ---------------------------------------------------------------------------
@@ -1138,6 +1205,21 @@ class Parser {
 			// Ubuntu ship).
 			this.context.opaque('quoted or expanding target of >& or <&')
 		}
+		if (
+			['<', '>', '<>', '>>', '>|'].includes(operator.op) &&
+			!target.word.quoted &&
+			target.word.substitutes
+		) {
+			// A `<`/`>`-family target must be exactly one word; when it is not
+			// (empty, or several), bash reports "ambiguous redirect" — and for
+			// a `${var:-…}`-style default value, running that check evaluates
+			// the substitution in it a SECOND time (measured, bash 5.2.21 and
+			// 5.3.15: `<${a:-$(a)}` and `>${a:-$(a)}` both run `a` twice, a
+			// bare `<$(a)` or `<a$(a)` only once). Whether the default branch
+			// even runs depends on whether the variable is set at runtime, so
+			// this is opaque rather than trusted to run once.
+			this.context.opaque('unquoted substitution in a redirection target')
+		}
 		const redirection: { -readonly [K in keyof ShellRedirection]: ShellRedirection[K] } = {
 			operator: operator.op,
 			...(operator.fd !== undefined ? { fd: operator.fd } : {}),
@@ -1178,8 +1260,8 @@ class Parser {
 			name !== 'shopt' &&
 			name !== 'enable' &&
 			name !== 'set' &&
-			name !== 'busybox' &&
-			!NESTED_SHELLS.has(name)
+			!NESTED_SHELLS.has(name) &&
+			!REEXEC_WRAPPER_NAMES.has(name)
 		)
 			return
 		const words = command.words.slice(command.assignments)
@@ -1202,55 +1284,17 @@ class Parser {
 			}
 			return
 		}
-		if (name === 'busybox' && words[1] !== undefined && !words[1].expands) {
-			if (NESTED_SHELLS.has(basename(words[1].value))) this.nestedShell(words.slice(1))
+		const nested = nestedShellCommand(words)
+		if (nested === null) return
+		if ('opaque' in nested) {
+			this.context.opaque(nested.opaque)
 			return
 		}
-		if (!NESTED_SHELLS.has(name)) return
-		this.nestedShell(words)
+		this.nestedShell(nested.shell, nested.payload)
 	}
 
-	/**
-	 * `bash [options] -c payload [name args…]`: the payload is the first
-	 * non-option argument once `-c` has been seen among the options.
-	 */
-	private nestedShell(words: readonly ShellWord[]): void {
-		const shell = basename(words[0]?.value ?? '')
-		let command = false
-		let payload: ShellWord | undefined
-		for (let i = 1; i < words.length; i += 1) {
-			const word = words[i] as ShellWord
-			if (word.expands) {
-				this.context.opaque('nested shell option')
-				return
-			}
-			const value = word.value
-			if (value === '--' || value === '-') {
-				payload = words[i + 1]
-				break
-			}
-			if (value.startsWith('--')) {
-				if (value === '--rcfile' || value === '--init-file') i += 1
-				continue
-			}
-			if (/^[-+][A-Za-z]+$/.test(value)) {
-				if (value.startsWith('-') && value.includes('c')) command = true
-				// `-o name`, `-O name`: the option takes the next word.
-				if (/[oO]$/.test(value)) i += 1
-				continue
-			}
-			payload = word
-			break
-		}
-		if (!command) return
-		if (payload === undefined) {
-			this.context.opaque('nested shell without a command')
-			return
-		}
-		if (payload.expands) {
-			this.context.opaque('nested shell command is expanded at runtime')
-			return
-		}
+	/** Read the payload of `bash -c payload` as a command line of its own. */
+	private nestedShell(shell: string, payload: ShellWord): void {
 		if (this.depth + 1 >= MAX_SHELL_DEPTH) {
 			this.context.opaque('nested shells too deep')
 			return
@@ -1426,7 +1470,7 @@ class Parser {
 					kind: 'word',
 					start,
 					end: start + 1,
-					word: { text: '-', value: '-', expands: false, quoted: false },
+					word: { text: '-', value: '-', expands: false, quoted: false, substitutes: false },
 					reservedOk: false,
 				}
 			}
@@ -1814,11 +1858,19 @@ class Parser {
 		}
 		this.pos = i
 		if (builder.brace) this.bashOnly('brace expansion')
+		// Brace expansion runs on the word's raw text before any substitution
+		// does, so `$(cmd){a,b}` duplicates `$(cmd)` into two copies that
+		// each run `cmd` — the commands pushed while reading this word are
+		// not the one-time account the recursive read otherwise gives.
+		if (builder.brace && builder.substitutes) {
+			this.context.opaque('command substitution duplicated by brace expansion')
+		}
 		const word: ShellWord = {
 			text: src.slice(start, i),
 			value: builder.value,
 			expands: builder.expands,
 			quoted: builder.quoted,
+			substitutes: builder.substitutes,
 		}
 		// A descriptor before a redirection operator: `2>`, `{fd}>`.
 		const next = src[i]
@@ -1991,7 +2043,7 @@ class Parser {
 				builder.expansion(src.slice(at, end))
 				return end
 			}
-			const end = this.parameterBraces(n + 1, inDouble)
+			const end = this.parameterBraces(n + 1, inDouble, builder)
 			builder.expansion(src.slice(at, end))
 			return end
 		}
@@ -2005,7 +2057,18 @@ class Parser {
 					return end
 				}
 			}
-			this.context.opaque('command substitution')
+			// `$(…)`'s body is read as a command list of its own, the same
+			// way `nestedShell()` reads a `bash -c` payload: each command
+			// found inside it is pushed to the shared `context.commands`
+			// (marked `origin: 'substitution'`), checked by the same deny
+			// rules, instead of the containing line being called opaque
+			// outright. Finding the matching `)` requires the parse to
+			// succeed — a `)` inside a quoted string or a `case` pattern is
+			// not it — so a substitution that does not parse throws all the
+			// way to `lexShellCommandLine`'s own catch, which is the only
+			// sound way to be wrong about its extent, and marks the whole
+			// line opaque (`internal error`) exactly as any other
+			// unmodeled construct does.
 			const inner = new Parser(
 				src,
 				n + 1,
@@ -2015,7 +2078,7 @@ class Parser {
 				this.nestingNow + 1,
 			)
 			const end = inner.substitution()
-			builder.expansion(src.slice(at, end))
+			builder.substitution(src.slice(at, end))
 			return end
 		}
 		if (next === '[') {
@@ -2084,7 +2147,7 @@ class Parser {
 	 * (indirection, a subscript or offset evaluated as arithmetic, a
 	 * transformation) is opaque.
 	 */
-	private parameterBraces(from: number, inDouble: boolean): number {
+	private parameterBraces(from: number, inDouble: boolean, builder: WordBuilder): number {
 		const src = this.src
 		let i = from
 		const scratch = new WordBuilder()
@@ -2134,6 +2197,11 @@ class Parser {
 		const content = src.slice(from, i).replace(/\\\n/g, '')
 		if (!SAFE_PARAMETER.test(content)) this.context.opaque('parameter expansion')
 		else if (!POSIX_PARAMETER.test(content)) this.bashOnly('parameter expansion')
+		// A substitution inside the default-value expression (`${a:-$(cmd)}`)
+		// is read into a scratch builder discarded above; propagate whether
+		// it happened onto the enclosing word, which is what the caller's
+		// own brace-expansion check reads.
+		if (scratch.substitutes) builder.substitutes = true
 		return i + 1
 	}
 
@@ -2268,8 +2336,12 @@ class Parser {
 			body += char
 			i += 1
 		}
-		this.context.opaque('command substitution')
-		builder.expansion(src.slice(at, i + 1))
+		// Backtick's extent is found lexically, above — unlike `$(…)`, its
+		// boundary does not depend on the body parsing as commands. So a
+		// body that fails to parse is caught here, the same way a `bash -c`
+		// payload's own failure is (`nestedShell()`): the rest of the LINE
+		// is still read, only this substitution's own commands are unknown.
+		builder.substitution(src.slice(at, i + 1))
 		this.context.rescan(body.length)
 		this.inherit(body)
 		const inner = new Parser(body, 0, this.context, 'substitution', this.depth, this.nestingNow + 1)
@@ -2277,6 +2349,7 @@ class Parser {
 			inner.program()
 		} catch (error) {
 			if (!(error instanceof Stop)) throw error
+			this.context.opaque(`command substitution: ${error.reason}`)
 		}
 		return i + 1
 	}

package/src/bridge/sse/mapper.ts

@@ -572,6 +572,12 @@ const MAPPING: {
 		transform: (e) => ({
 			tool_use_id: e.toolUseId,
 			input: e.input,
+			// Arguments that could not be read: that they were not, why, and
+			// what arrived. Dropped here before, so a wire client saw `{}` as
+			// the call's input with nothing to say it was not the model's.
+			...(e.inputTruncated ? { input_truncated: true } : {}),
+			...(e.inputError ? { input_error: e.inputError } : {}),
+			...(e.partialArguments !== undefined ? { partial_arguments: e.partialArguments } : {}),
 		}),
 	},
 }

package/src/capabilities/index.ts

@@ -0,0 +1,157 @@
+import { PromptContributionRegistry } from '../prompt/contributions.js'
+import type { PromptContribution } from '../prompt/contributions.js'
+import type { Toolset } from '../toolsets/types.js'
+import type { InputGuardrailSpec, OutputGuardrailSpec } from '../types/guardrail/index.js'
+import type { ProjectId, SessionId, TenantId, TopicId } from '../types/ids/index.js'
+import type { Message } from '../types/message/index.js'
+import type { ReasoningEffort, ThinkingConfig } from '../types/provider/index.js'
+
+export interface CapabilityModelSettings {
+	readonly temperature?: number
+	readonly thinking?: ThinkingConfig
+	readonly effort?: ReasoningEffort
+}
+
+/** Host-authored behavior assembled for one agent invocation. */
+export interface Capability {
+	/** Stable across invocations; duplicate ids are refused. */
+	readonly id: string
+	readonly instructions?: string
+	readonly toolsets?: readonly Toolset[]
+	readonly promptContributions?: readonly PromptContribution[]
+	readonly inputGuardrails?: readonly InputGuardrailSpec[]
+	readonly outputGuardrails?: readonly OutputGuardrailSpec[]
+	/** Later capabilities override earlier ones; explicit run options win. */
+	readonly modelSettings?: CapabilityModelSettings
+}
+
+export interface CapabilityRunContext {
+	readonly workingDirectory: string
+	readonly model: string
+	readonly prompt: string | readonly Message[]
+	readonly sessionId: SessionId
+	readonly topicId: TopicId
+	readonly projectId: ProjectId
+	readonly tenantId: TenantId
+	readonly signal?: AbortSignal
+}
+
+/** A factory receives a fresh context on every invocation, including repeated session turns. */
+export interface DynamicCapability {
+	readonly id: string
+	readonly forRun: (context: CapabilityRunContext) => Capability | null | Promise<Capability | null>
+}
+
+export type AgentCapability = Capability | DynamicCapability
+
+function assertCapabilityId(id: string): void {
+	if (typeof id !== 'string' || id.trim() !== id || id.length === 0) {
+		throw new Error('Capability id must be a nonempty, trimmed string.')
+	}
+}
+
+/** Snapshot a reusable host declaration. Toolsets retain their own source ownership. */
+export function defineCapability(value: Capability): Capability {
+	assertCapabilityId(value.id)
+	return Object.freeze({
+		...value,
+		...(value.toolsets ? { toolsets: Object.freeze([...value.toolsets]) } : {}),
+		...(value.promptContributions
+			? { promptContributions: Object.freeze([...value.promptContributions]) }
+			: {}),
+		...(value.inputGuardrails
+			? { inputGuardrails: Object.freeze([...value.inputGuardrails]) }
+			: {}),
+		...(value.outputGuardrails
+			? { outputGuardrails: Object.freeze([...value.outputGuardrails]) }
+			: {}),
+		...(value.modelSettings ? { modelSettings: Object.freeze({ ...value.modelSettings }) } : {}),
+	})
+}
+
+/** Make the factory's stable identity explicit before it sees a run. */
+export function dynamicCapability(
+	id: string,
+	forRun: DynamicCapability['forRun'],
+): DynamicCapability {
+	assertCapabilityId(id)
+	return Object.freeze({ id, forRun })
+}
+
+export interface ResolvedCapabilities {
+	readonly toolsets: readonly Toolset[]
+	readonly promptContributions: PromptContributionRegistry
+	readonly modelSettings: CapabilityModelSettings
+	readonly inputGuardrails: readonly InputGuardrailSpec[]
+	readonly outputGuardrails: readonly OutputGuardrailSpec[]
+}
+
+async function resolveForRun(
+	entry: DynamicCapability,
+	context: CapabilityRunContext,
+): Promise<Capability | null> {
+	if (!context.signal) return await entry.forRun(context)
+	const signal = context.signal
+	return await new Promise<Capability | null>((resolve, reject) => {
+		const onAbort = () => {
+			signal.removeEventListener('abort', onAbort)
+			reject(signal.reason)
+		}
+		signal.addEventListener('abort', onAbort, { once: true })
+		if (signal.aborted) {
+			onAbort()
+			return
+		}
+		Promise.resolve()
+			.then(() => entry.forRun(context))
+			.then(resolve, reject)
+			.finally(() => signal.removeEventListener('abort', onAbort))
+	})
+}
+
+/** Resolve each factory exactly once, in declaration order, before the first model call. */
+export async function resolveCapabilities(
+	capabilities: readonly AgentCapability[],
+	context: CapabilityRunContext,
+): Promise<ResolvedCapabilities> {
+	const seen = new Set<string>()
+	const toolsets: Toolset[] = []
+	const promptContributions = new PromptContributionRegistry()
+	const inputGuardrails: InputGuardrailSpec[] = []
+	const outputGuardrails: OutputGuardrailSpec[] = []
+	let modelSettings: CapabilityModelSettings = {}
+
+	for (const entry of capabilities) {
+		context.signal?.throwIfAborted()
+		assertCapabilityId(entry.id)
+		if (seen.has(entry.id)) throw new Error(`Capability "${entry.id}" is declared twice.`)
+		seen.add(entry.id)
+
+		const resolved = 'forRun' in entry ? await resolveForRun(entry, context) : entry
+		context.signal?.throwIfAborted()
+		if (resolved === null) continue
+		if (!resolved) throw new Error(`Capability "${entry.id}" returned no declaration.`)
+		if (resolved.id !== entry.id) {
+			throw new Error(
+				`Capability "${entry.id}" returned id "${resolved.id}"; a run factory must keep its declared id.`,
+			)
+		}
+		const capability = defineCapability(resolved)
+		toolsets.push(...(capability.toolsets ?? []))
+		if (capability.instructions?.trim()) {
+			const instructions = capability.instructions
+			promptContributions.register({
+				id: `capability:${capability.id}:instructions`,
+				placement: 'dynamic',
+				render: () => instructions,
+			})
+		}
+		for (const contribution of capability.promptContributions ?? []) {
+			promptContributions.register(contribution)
+		}
+		inputGuardrails.push(...(capability.inputGuardrails ?? []))
+		outputGuardrails.push(...(capability.outputGuardrails ?? []))
+		modelSettings = { ...modelSettings, ...capability.modelSettings }
+	}
+	return { toolsets, promptContributions, modelSettings, inputGuardrails, outputGuardrails }
+}

package/src/config/registry.ts

@@ -1,5 +1,6 @@
 import type { ZodType, ZodTypeDef } from 'zod'
 
+import { RegistryCollisionError } from '../registry/collision.js'
 import { type ConfigOverrideStore, InMemoryConfigOverrideStore } from '../store/config/index.js'
 import { type Logger, resolveLogger } from '../utils/logger.js'
 
@@ -49,9 +50,11 @@ export interface ConfigScope<T> {
 	watch(listener: (next: T, previous: T) => void): () => void
 }
 
-export class ConfigNamespaceCollisionError extends Error {
+export class ConfigNamespaceCollisionError extends RegistryCollisionError {
 	constructor(readonly namespace: string) {
 		super(
+			'ConfigRegistry',
+			namespace,
 			`Configuration namespace "${namespace}" is already registered. Two owners of one namespace means whichever registered second silently decides the schema, so this refuses instead.`,
 		)
 		this.name = 'ConfigNamespaceCollisionError'

package/src/connector/index.ts

@@ -6,10 +6,13 @@ export { ScopedConnectorRegistry } from '../registry/connector/scoped.js'
 export { ConnectorManager } from '../manager/connector/lifecycle.js'
 export type { ConnectorManagerConfig } from '../manager/connector/lifecycle.js'
 
-export { TenantConnectorManager } from '../manager/connector/tenant.js'
+export { TenantCollisionError, TenantConnectorManager } from '../manager/connector/tenant.js'
 export type { TenantConnectorManagerConfig } from '../manager/connector/tenant.js'
 
-export { EnvironmentConnectorManager } from '../manager/connector/environment.js'
+export {
+	EnvironmentCollisionError,
+	EnvironmentConnectorManager,
+} from '../manager/connector/environment.js'
 export type {
 	EnvironmentConnectorSetup,
 	EnvironmentConnectorManagerConfig,
@@ -73,6 +76,8 @@ export {
 	mcpJsonSchemaToZod,
 	mcpPromptToToolDefinition,
 	mcpToolResultToToolResult,
+	mcpToolset,
+	mcpToolsetName,
 	mcpToolToToolDefinition,
 	renderPromptMessages,
 	resolveMcpEra,
@@ -102,4 +107,6 @@ export type {
 	MCPToolDrift,
 	MCPToolPolicy,
 	MCPToolPolicyDecision,
+	MCPToolsetOptions,
+	MCPToolsets,
 } from './mcp/index.js'

package/src/connector/mcp/adapter.ts

@@ -469,10 +469,48 @@ export function mcpToolToToolDefinition(
 	 * never lowers it. See `isTrustedReadOnly`.
 	 */
 	readOnlyHintTrusted = false,
+	/**
+	 * In-loop retry budget for every tool this server contributes. Unset
+	 * (the default) keeps today's behaviour byte-for-byte: `maxRetries`
+	 * absent on the returned `ToolDefinition`, so the executor's own
+	 * default (0) applies.
+	 *
+	 * Even with this set, a failure is only retried if `execute` also
+	 * marked it {@link ToolResult.retryable}, which below is true only for
+	 * the two outcomes this adapter already knows never reached the
+	 * server's side effect (`mcp_tool_input_required`,
+	 * `mcp_tool_missing_client_capability`) — never for
+	 * `mcp_tool_outcome_unknown` or a raw transport error, where whether
+	 * the call landed is exactly what is not known.
+	 */
+	maxRetries?: number,
 ): ToolDefinition {
 	const inputSchema = mcpJsonSchemaToZod(tool.inputSchema)
 	const toolName = `mcp_${serverName}_${tool.name}`
 
+	// Everything the server's own annotations carry that `isReadOnly`/
+	// `isDestructive` do not already have a typed home for — `title`,
+	// `idempotentHint`, `openWorldHint` — plus any `_meta` on the listing
+	// entry itself. Never sent back to the model (ToolDefinition.metadata is
+	// wire-excluded); a host, capability or toolset wrapper reads it with
+	// `matchesToolSelector` or by hand.
+	const mcpMetadata: Record<string, unknown> = {}
+	if (tool.annotations?.title !== undefined) mcpMetadata.title = tool.annotations.title
+	if (tool.annotations?.idempotentHint !== undefined) {
+		mcpMetadata.idempotentHint = tool.annotations.idempotentHint
+	}
+	if (tool.annotations?.openWorldHint !== undefined) {
+		mcpMetadata.openWorldHint = tool.annotations.openWorldHint
+	}
+	if (tool._meta !== undefined) mcpMetadata._meta = tool._meta
+	// Advisory only, NOT a security boundary: the gate that actually decides
+	// (`isTrustedReadOnly`, `tools/trusted-read-only.ts`) reads the OWNING
+	// TOOLSET's source (`ToolManager.sourceOf`), which whoever wraps this
+	// definition sets — `plugin/lifecycle.ts` or `mcpToolset`. Kept here too so a definition inspected on its
+	// own (a probe, a test, `matchesToolSelector`) can still see what the
+	// caller passed, now that `ToolDefinition.provenance` is gone.
+	mcpMetadata.readOnlyHintTrusted = readOnlyHintTrusted
+
 	return {
 		name: toolName,
 		description: tool.description
@@ -488,14 +526,21 @@ export function mcpToolToToolDefinition(
 			: {}),
 		category: 'network',
 		permissions: ['network_access'],
+		...(maxRetries === undefined ? {} : { maxRetries }),
 		// Reports what the SERVER said, faithfully. The outbound re-export
 		// and the destructive label a human is shown both need the server's
-		// own answer; whether a gate may act on it is decided separately, by
-		// `isTrustedReadOnly` reading `provenance` below.
+		// own answer; whether a gate may act on it is decided separately,
+		// from the OWNING TOOLSET's source (`ToolManager.sourceOf`,
+		// `toolsets/manager.ts`) — a definition cannot claim its own source,
+		// so `readOnlyHintTrusted` is carried only as advisory metadata here.
+		// See `tools/trusted-read-only.ts`. Whoever wraps this definition into a
+		// toolset (`plugin/lifecycle.ts` or `mcpToolset`)
+		// gives it `source.kind: 'mcp_server'`, `source.mcpServer.name:
+		// serverName` and this same `readOnlyHintTrusted`.
 		isReadOnly: () => tool.annotations?.readOnlyHint ?? false,
 		isDestructive: () => tool.annotations?.destructiveHint ?? false,
 		isConcurrencySafe: () => true,
-		provenance: { server: serverName, readOnlyHintTrusted },
+		...(Object.keys(mcpMetadata).length > 0 ? { metadata: mcpMetadata } : {}),
 
 		async execute(input: unknown, context: ToolContext): Promise<ToolResult> {
 			try {
@@ -533,6 +578,12 @@ export function mcpToolToToolDefinition(
 							success: false,
 							output: '',
 							error: `MCP tool "${tool.name}" on server "${serverName}" asked for input this client has no way to supply${requested.length > 0 ? ` (${requested.join(', ')})` : ''}.`,
+							// No side effect is known to have happened (see the
+							// comment above), so a retry — of this tool, or a
+							// different approach entirely — is safe. Only
+							// meaningful when the definition also opted into
+							// `maxRetries`; see this function's parameter.
+							retryable: true,
 							data: {
 								code: 'mcp_tool_input_required',
 								server: serverName,
@@ -555,6 +606,10 @@ export function mcpToolToToolDefinition(
 							success: false,
 							output: '',
 							error: `MCP tool "${tool.name}" on server "${serverName}" requires client capabilities this client did not declare${requiredCapabilities.length > 0 ? ` (${requiredCapabilities.join(', ')})` : ''}.`,
+							// The server refused before running the tool, so
+							// nothing ran; safe to retry the same way
+							// `mcp_tool_input_required` above is.
+							retryable: true,
 							data: {
 								code: 'mcp_tool_missing_client_capability',
 								server: serverName,