@namzu/sdk 45.1.0 → 48.0.0

package/src/types/agent/reactive.ts

@@ -1,142 +1,5 @@
-import type { CompactionConfig } from '../../config/runtime.js'
-import type { QueryParams } from '../../runtime/query/index.js'
-import type { SteeringChannel } from '../../runtime/query/steering.js'
-import type { AdvisoryConfig } from '../advisory/index.js'
-import type { AuthorizationGateConfig } from '../authorization/index.js'
-import type { InputGuardrailSpec, OutputGuardrailSpec } from '../guardrail/index.js'
-import type { ResumeHandler } from '../hitl/index.js'
-import type { AgentPersona } from '../persona/index.js'
-import type { LLMProvider } from '../provider/index.js'
-import type { SandboxProvider } from '../sandbox/index.js'
-import type { BeforeStep, PrepareStepChain, StepResult, StopCondition } from '../session/index.js'
-import type { Skill } from '../skills/index.js'
-import type { StructuredOutputConfig } from '../structured-output/index.js'
-import type { ToolRegistryContract } from '../tool/index.js'
-import type { RepairToolCall } from '../tool/repair.js'
-import type { BaseAgentConfig, BaseAgentResult } from './base.js'
-import type { WorkingMemoryProvider } from './working-memory.js'
-
-export interface ReactiveAgentConfig extends BaseAgentConfig {
-	systemPrompt?: string
-	/** Provider-hosted search for this turn; the selected driver must support it. */
-	webSearch?: { mode: 'live' | 'cached' }
-
-	persona?: AgentPersona
-
-	/**
-	 * Channel a host uses to hand guidance to this turn's current turn.
-	 *
-	 * Present here for the same reason it is on `SupervisorAgentConfig`, and
-	 * the reason that file gives twice already: a capability the kernel
-	 * honours in `drainQuery` and not on the surface hosts actually
-	 * construct is a capability nobody can reach. This is the archetype most
-	 * hosts run, and it was the one that could not be steered at all.
-	 */
-	steering?: SteeringChannel
-
-	skills?: Skill[]
-
-	basePrompt?: string
-	provider: LLMProvider
-	tools: ToolRegistryContract
-
-	advisory?: AdvisoryConfig
-
-	/**
-	 * Optional capability-aware deny/allow gate for child tool calls.
-	 * Mirrors the same field on `SupervisorAgentConfig`; when omitted,
-	 * `drainQuery` falls back to its `autoApproveHandler` default
-	 * (every tool call auto-approves, no policy applied). Hosts that
-	 * trust their sandbox should still pass at least
-	 * `{ enabled: true, denyDangerousPatterns: true, ... }` so the
-	 * canonical brick patterns hard-deny instead of executing
-	 * silently.
-	 */
-
-	authorizationGate?: AuthorizationGateConfig
-
-	/**
-	 * Optional ephemeral sandbox provider. When set, drainQuery creates
-	 * a sandbox via `provider.create()` before the iteration loop and
-	 * routes filesystem / shell tool calls through it; on turn end the
-	 * SDK calls `sandbox.destroy()`. Hosts that want a per-task
-	 * container shared across supervisor + every child specialist run
-	 * pass the SAME provider instance to all of them — caching layered
-	 * on top of the provider keeps the underlying container alive.
-	 */
-	sandboxProvider?: SandboxProvider
-	/** See {@link QueryParams.sandboxTeardownTimeoutMs}. */
-	sandboxTeardownTimeoutMs?: number
-	/** See {@link QueryParams.outsideRootAccess}. Default `'refuse'`. */
-	outsideRootAccess?: 'refuse' | 'review'
-	/** See {@link QueryParams.sandboxEscape}. Default `'refuse'`. */
-	sandboxEscape?: 'refuse' | 'review'
-
-	/**
-	 * Optional structured-compaction config. Omitted ⇒ byte-identical run path
-	 * (no `WorkingStateManager`, compaction early-returns). Mirrors the field
-	 * on `SupervisorAgentConfig` so a child specialist can share the
-	 * supervisor's compaction settings.
-	 */
-	compactionConfig?: CompactionConfig
-
-	/**
-	 * Optional neutral working-memory seam — same contract as the field on
-	 * `SupervisorAgentConfig`. Absent ⇒ no block injected. A child specialist
-	 * sharing the supervisor's output dir passes the same provider.
-	 */
-	workingMemoryProvider?: WorkingMemoryProvider
-
-	/**
-	 * Loop-control and resilience seams, forwarded verbatim to `query()`.
-	 *
-	 * These existed on `QueryParams` and stopped there. `ReactiveAgent` is
-	 * the entry point most consumers actually use — it is what
-	 * `AgentManager` spawns and what the estate's own applications call —
-	 * and it forwarded none of them. So a per-tool deadline, a provider
-	 * retry policy, a guardrail, a stop condition: all of it was reachable
-	 * only by dropping down to `query()` and rebuilding the turn wiring by
-	 * hand. Features that a consumer cannot reach are features that do not
-	 * exist for them.
-	 *
-	 * Every field is optional and absent means exactly what it meant
-	 * before, so no existing agent changes behavior.
-	 */
-	resumeHandler?: ResumeHandler
-	retry?: QueryParams['retry']
-	toolTimeoutMs?: number
-	toolRetryBackoff?: QueryParams['toolRetryBackoff']
-	maxToolConcurrency?: number
-	maxToolOutputChars?: number
-	retainedToolPreviewChars?: QueryParams['retainedToolPreviewChars']
-	/**
-	 * Cap on the RICH channel of a single tool result, in base64 characters.
-	 * `0` or absent disables it. Separate from {@link maxToolOutputChars}:
-	 * that one bounds characters the model reads, this one bounds the image
-	 * payload beside them, which no text budget ever touched.
-	 */
-	maxToolContentBytes?: number
-	repairToolCall?: RepairToolCall
-	stopWhen?: StopCondition
-	onStepFinish?: (step: StepResult) => void
-	prepareStep?: PrepareStepChain
-	/**
-	 * Refuse the next model call before it is made. See {@link BeforeStep}.
-	 * A throw fails CLOSED, opposite to `prepareStep` beside it.
-	 */
-	beforeStep?: BeforeStep
-
-	structuredOutput?: StructuredOutputConfig
-	inputGuardrails?: readonly InputGuardrailSpec[]
-	outputGuardrails?: readonly OutputGuardrailSpec[]
-
-	/**
-	 * Span this turn should hang off, when it is a delegated one. Absent for
-	 * a top-level turn, which correctly starts its own root trace.
-	 */
-	parentSpan?: import('@opentelemetry/api').Span
-}
-
-export interface ReactiveAgentResult extends BaseAgentResult {
-	toolCallCount: number
-}
+/** @deprecated Use QueryAgentConfig and QueryAgentResult for the generic query shell. */
+export type {
+	QueryAgentConfig as ReactiveAgentConfig,
+	QueryAgentResult as ReactiveAgentResult,
+} from './query.js'

package/src/types/agent/router.ts

@@ -28,6 +28,7 @@ export interface RouteDefinition {
 	matchPatterns?: string[]
 }
 
+/** @deprecated Configuration for the router example; define application routing as needed. */
 export interface RouterAgentConfig extends BaseAgentConfig {
 	routes: RouteDefinition[]
 	provider: LLMProvider
@@ -37,6 +38,7 @@ export interface RouterAgentConfig extends BaseAgentConfig {
 	maxRoutingRetries?: number
 }
 
+/** @deprecated Result of the router example. */
 export interface RouterAgentResult extends BaseAgentResult {
 	selectedRoute: string
 	routingDecision: RoutingDecision

package/src/types/agent/supervisor.ts

@@ -1,5 +1,6 @@
 import type { CompactionConfig } from '../../config/runtime.js'
 import type { SteeringChannel } from '../../runtime/query/steering.js'
+import type { Toolset } from '../../toolsets/types.js'
 import type { AdvisoryConfig } from '../advisory/index.js'
 import type { AuthorizationGateConfig } from '../authorization/index.js'
 import type { ResumeHandler } from '../hitl/index.js'
@@ -8,13 +9,13 @@ import type { TaskRouterConfig } from '../router/index.js'
 import type { SandboxProvider } from '../sandbox/index.js'
 import type { Skill } from '../skills/index.js'
 import type { StructuredOutputConfig } from '../structured-output/index.js'
-import type { ToolRegistryContract } from '../tool/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { AgentFactoryOptions } from './factory.js'
 import type { AgentManagerContract } from './manager.js'
 import type { SiblingFailurePolicy, TaskScheduler } from './scheduler.js'
 import type { WorkingMemoryProvider } from './working-memory.js'
 
+/** @deprecated Configuration for the supervisor example; hosts own their orchestration. */
 export interface SupervisorAgentConfig extends BaseAgentConfig {
 	provider: LLMProvider
 
@@ -59,7 +60,8 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 */
 	onPlanApproved?: () => Promise<void> | void
 	agentManager?: AgentManagerContract
-	tools?: ToolRegistryContract
+	/** Every tool this turn may see comes from one of these — see `toolsets/types.ts`. */
+	toolsets?: readonly Toolset[]
 
 	systemPrompt: string
 
@@ -234,6 +236,7 @@ export interface AgentTaskResult {
 	taskIndex: number
 }
 
+/** @deprecated Result of the supervisor example. */
 export interface SupervisorAgentResult extends BaseAgentResult {
 	taskResults: AgentTaskResult[]
 	completedTasks: number

package/src/types/authorization/index.ts

@@ -27,6 +27,12 @@ export type AuthorizationRule =
 	| { type: 'allow_by_category'; categories: string[] }
 	| { type: 'allow_by_name'; toolNames: string[] }
 	| { type: 'deny_by_name'; toolNames: string[] }
+	| {
+			/** Match the owning toolset's host-assigned source id, never tool input or MCP metadata. */
+			type: 'by_source'
+			sources: string[]
+			decision: GateDecision
+	  }
 	| {
 			/**
 			 * Match a regular expression against the tool's NAME, the
@@ -115,6 +121,19 @@ export type AuthorizationRule =
 			 */
 			description: string
 			decide: AuthorizationPredicate
+			/**
+			 * The reason for THIS call, when `decide` returned a decision: what
+			 * in the input matched, and where. The gate reports it instead of
+			 * {@link description}. Absent, returning `null` or throwing, the
+			 * gate reports `description`.
+			 *
+			 * A rule that refuses on several grounds and reports one fixed
+			 * sentence leaves the model, and the person reading the refusal,
+			 * to guess which ground it was. A scheduled run's refusal listed
+			 * everything the rule protects when one word of the command had
+			 * matched.
+			 */
+			describe?: (call: AuthorizationPredicateCall) => string | null
 	  }
 
 /** The call an `AuthorizationRule` of type `predicate` is asked about. */
@@ -156,6 +175,11 @@ const DenyByNameSchema = z.object({
 	type: z.literal('deny_by_name'),
 	toolNames: z.array(z.string()),
 })
+const BySourceSchema = z.object({
+	type: z.literal('by_source'),
+	sources: z.array(z.string().min(1)).min(1),
+	decision: z.enum(['allow', 'deny', 'review']),
+})
 const CustomPatternSchema = z.object({
 	type: z.literal('custom_pattern'),
 	pattern: z.string().max(MAX_CUSTOM_PATTERN_LENGTH),
@@ -183,6 +207,14 @@ const PredicateSchema = z.object({
 	decide: z.custom<AuthorizationPredicate>((value) => typeof value === 'function', {
 		message: 'decide must be a function',
 	}),
+	// Named here so the gate's own parse keeps it: zod strips what a schema
+	// does not name.
+	describe: z
+		.custom<(call: AuthorizationPredicateCall) => string | null>(
+			(value) => typeof value === 'function',
+			{ message: 'describe must be a function' },
+		)
+		.optional(),
 })
 
 export const AuthorizationRuleSchema = z.discriminatedUnion('type', [
@@ -191,6 +223,7 @@ export const AuthorizationRuleSchema = z.discriminatedUnion('type', [
 	AllowByCategorySchema,
 	AllowByNameSchema,
 	DenyByNameSchema,
+	BySourceSchema,
 	CustomPatternSchema,
 	ArgumentPatternSchema,
 	AllowByTierSchema,

package/src/types/computer-use/index.ts

@@ -44,10 +44,41 @@ export interface ComputerUseCapabilities {
 	 * model reads the reason once and does not try again.
 	 */
 	readonly unavailableReason?: string
+	/**
+	 * The host implements {@link ComputerUseHost.listWindows} and
+	 * {@link ComputerUseHost.focusWindow}. Absent or false, the tool does not
+	 * offer `list_windows` or `focus_window`, even when the methods exist.
+	 */
+	readonly windows?: boolean
+	/**
+	 * The host implements {@link ComputerUseHost.captureRegion}. Absent or
+	 * false, `zoom` still works: the tool crops a full capture instead, which
+	 * costs one whole-display capture per zoom.
+	 */
+	readonly regionCapture?: boolean
+	/**
+	 * The host implements {@link ComputerUseHost.uiSnapshot} and
+	 * {@link ComputerUseHost.uiAct}: an accessibility tree (Windows UI
+	 * Automation, macOS AX, AT-SPI, or a driver that wraps one) whose
+	 * elements can be acted on by reference instead of by pixel.
+	 *
+	 * @experimental The UI-tree surface is reserved for the host packages that
+	 * implement it; its shape may still change in a minor release.
+	 */
+	readonly uiTree?: boolean
 }
 
 // ---------------------------------------------------------------------------
 // Geometry + screenshot payload
+//
+// Units, once for the whole file: every coordinate and size a host accepts or
+// returns is in PHYSICAL pixels — the pixels of the captured bitmap, not
+// logical points or DPI-scaled units. A 3440x1440 monitor at 150 % scaling is
+// 3440x1440 here. A point a host is asked to act on is relative to the
+// top-left of the display it last captured (the primary display until a host
+// offers display selection); the host adds that display's origin itself.
+// Window and UI-element bounds are the exception and say so: they are in
+// virtual-desktop physical pixels, because a window can span displays.
 // ---------------------------------------------------------------------------
 
 export interface DisplayGeometry {
@@ -56,11 +87,144 @@ export interface DisplayGeometry {
 	readonly scaleFactor: number
 }
 
+/**
+ * The display a capture shows.
+ *
+ * `x`/`y` place it in the virtual desktop (a monitor left of the primary has
+ * a negative `x`); `width`/`height` are its physical size. `scaleFactor` is
+ * physical pixels per logical pixel — 1 at 96 DPI on Windows, 1.5 at 150 %,
+ * 2 on a Retina panel — reported for the host UI and for diagnosis; the tool
+ * never multiplies by it, because every coordinate crossing this interface
+ * is already physical.
+ */
+export interface DisplayInfo {
+	/** Stable for the host's lifetime; what a host would accept to select this display. */
+	readonly id: string
+	readonly x: number
+	readonly y: number
+	readonly width: number
+	readonly height: number
+	readonly scaleFactor: number
+	/** True for the display the operating system calls primary. */
+	readonly primary?: boolean
+}
+
 export interface ScreenshotResult {
 	readonly data: Buffer
 	readonly mimeType: 'image/png'
+	/** Physical pixel width of `data`. */
 	readonly width: number
+	/** Physical pixel height of `data`. */
 	readonly height: number
+	/**
+	 * The display this capture shows. A host should always set it; one written
+	 * before it existed does not, and the tool then assumes a single display at
+	 * the origin whose size is the capture's own, with a scale factor of 1.
+	 */
+	readonly display?: DisplayInfo
+}
+
+/** A rectangle in physical pixels. What its origin is relative to depends on where it appears. */
+export interface Rect {
+	readonly x: number
+	readonly y: number
+	readonly width: number
+	readonly height: number
+}
+
+/** One top-level window, as {@link ComputerUseHost.listWindows} reports it. */
+export interface WindowInfo {
+	/** Opaque and host-defined (an HWND in hex, a CGWindowID, an X11 window id); valid for {@link ComputerUseHost.focusWindow}. */
+	readonly id: string
+	readonly title: string
+	/** Application or process name, e.g. `msedge`, `Teams`, `Code`. */
+	readonly app: string
+	readonly pid: number
+	/** Virtual-desktop physical pixels — not display-relative. */
+	readonly bounds: Rect
+	readonly focused: boolean
+	readonly minimized: boolean
+}
+
+/**
+ * What {@link ComputerUseHost.focusWindow} achieved. Bringing a window to
+ * the front is a request the operating system can refuse (Windows'
+ * foreground lock is the common case), so a host reports the window that is
+ * actually in front afterwards rather than assuming its request held.
+ */
+export interface FocusWindowResult {
+	/** True only when `focusedId` is the requested window. */
+	readonly ok: boolean
+	/** The window in front after the attempt, or null when none could be read. */
+	readonly focusedId: string | null
+}
+
+/**
+ * An action an accessibility element can take by reference.
+ *
+ * @experimental See {@link ComputerUseCapabilities.uiTree}.
+ */
+export type UiElementAction =
+	| 'invoke'
+	| 'focus'
+	| 'set_value'
+	| 'toggle'
+	| 'select'
+	| 'expand'
+	| 'collapse'
+	| 'scroll_into_view'
+
+/**
+ * One accessibility element.
+ *
+ * @experimental See {@link ComputerUseCapabilities.uiTree}.
+ */
+export interface UiElement {
+	/**
+	 * Opaque reference for {@link ComputerUseHost.uiAct}, valid until the
+	 * host's next snapshot. Empty for an element the host cannot act on (a
+	 * label, a group), which is in the tree for what it says.
+	 */
+	readonly ref: string
+	/** Platform role, e.g. `Button`, `Edit`, `ListItem` (UIA ControlType) or `AXButton`. */
+	readonly role: string
+	readonly name: string
+	readonly value?: string
+	/** A platform automation id, when the element has one. */
+	readonly automationId?: string
+	/** Virtual-desktop physical pixels, when the element is on screen. */
+	readonly bounds?: Rect
+	/** Element states such as `focused`, `disabled`, `selected`, `checked`, `expanded`. */
+	readonly states?: readonly string[]
+	readonly actions?: readonly UiElementAction[]
+	readonly children?: readonly UiElement[]
+}
+
+/**
+ * An accessibility tree for one window.
+ *
+ * @experimental See {@link ComputerUseCapabilities.uiTree}.
+ */
+export interface UiSnapshot {
+	readonly windowId?: string
+	/** The window's title, as its application sets it. */
+	readonly title?: string
+	/** The owning application or process name, as in {@link WindowInfo.app}. */
+	readonly app?: string
+	readonly root: UiElement
+	/** True when the host stopped walking the tree before it ended (a size or time bound). */
+	readonly truncated?: boolean
+}
+
+/**
+ * What {@link ComputerUseHost.uiAct} did.
+ *
+ * @experimental See {@link ComputerUseCapabilities.uiTree}.
+ */
+export interface UiActResult {
+	readonly ok: boolean
+	/** Why it did not, in words the model can act on (a stale ref, a disabled element). */
+	readonly detail?: string
 }
 
 export interface Point {
@@ -152,8 +316,46 @@ export interface ComputerUseHost {
 	readonly capabilities: ComputerUseCapabilities
 
 	getDisplayGeometry(): Promise<DisplayGeometry>
+	/**
+	 * Points in `action` are physical pixels relative to the display of the
+	 * most recent capture; a `screenshot` result carries that display in
+	 * {@link ScreenshotResult.display}.
+	 */
 	execute(action: ComputerUseAction): Promise<ComputerUseResult>
 
+	/**
+	 * The visible, titled top-level windows, front to back where the platform
+	 * knows the order. Offered to the model only with
+	 * {@link ComputerUseCapabilities.windows}.
+	 */
+	listWindows?(): Promise<readonly WindowInfo[]>
+	/**
+	 * Bring a window to the front, restoring it when minimized. Offered only
+	 * with {@link ComputerUseCapabilities.windows}.
+	 */
+	focusWindow?(id: string): Promise<FocusWindowResult>
+	/**
+	 * Capture one region of the current display at full physical resolution.
+	 * `rect` is display-relative physical pixels; the result's `width` and
+	 * `height` are the region's. Used by `zoom` when
+	 * {@link ComputerUseCapabilities.regionCapture} is set.
+	 */
+	captureRegion?(rect: Rect): Promise<ScreenshotResult>
+	/**
+	 * The accessibility tree of one window, or of the focused window when
+	 * `windowId` is omitted. Offered only with {@link ComputerUseCapabilities.uiTree}.
+	 *
+	 * @experimental
+	 */
+	uiSnapshot?(windowId?: string): Promise<UiSnapshot>
+	/**
+	 * Act on an element from the latest {@link uiSnapshot}. `value` is the text
+	 * for `set_value`. Offered only with {@link ComputerUseCapabilities.uiTree}.
+	 *
+	 * @experimental
+	 */
+	uiAct?(ref: string, action: UiElementAction, value?: string): Promise<UiActResult>
+
 	initialize?(): Promise<void>
 	dispose?(): Promise<void>
 }

package/src/types/connector/mcp.ts

@@ -276,6 +276,14 @@ export interface MCPToolDefinition {
 	 */
 	outputSchema?: MCPValueJsonSchema
 	annotations?: MCPToolAnnotations
+	/**
+	 * Server-defined data on the tool's own listing entry, carried opaquely:
+	 * this client acts on none of it. `mcpToolToToolDefinition` lands it in
+	 * `ToolDefinition.metadata` alongside the annotations that have no other
+	 * typed home, so a host reading either does not have to reach past this
+	 * client's own parsed shape back to the raw listing.
+	 */
+	_meta?: Record<string, unknown>
 }
 
 /**
@@ -409,6 +417,24 @@ export interface MCPInitializeResult {
 	protocolVersion: string
 	capabilities: MCPServerCapabilities
 	serverInfo: { name: string; version?: string }
+	/**
+	 * The server's own account of how to use it, read off the `initialize`
+	 * response verbatim. Only a legacy handshake carries one — the modern
+	 * era has no `initialize` round trip, so a modern connection's result
+	 * never populates this field (see `completeModernConnection` in
+	 * `client.ts`, which synthesises the rest of this shape from a discover
+	 * result that has no `instructions` concept at all).
+	 *
+	 * This is observability data, not steering: nothing in the SDK folds it
+	 * into an agent's instruction set automatically. It is server-authored,
+	 * remote-party text, and namzu already keeps that class of text out of
+	 * instruction/system position (see `connector/mcp/prompt-adapter.ts`
+	 * and `frameServerResult` in `connector/mcp/adapter.ts`, which frame
+	 * server-supplied prompts and tool results as untrusted data rather
+	 * than instructions). A host may display or log this field; it should
+	 * not read it into a prompt without the same untrusted framing.
+	 */
+	instructions?: string
 }
 
 export type MCPConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error'
@@ -461,6 +487,12 @@ export interface MCPClientState {
 	status: MCPConnectionStatus
 	serverInfo?: { name: string; version?: string }
 	serverCapabilities?: MCPServerCapabilities
+	/**
+	 * The server's `initialize` instructions, captured verbatim. See
+	 * {@link MCPInitializeResult.instructions} — legacy handshakes only,
+	 * observability only, never auto-folded into an agent's instructions.
+	 */
+	serverInstructions?: string
 	connectedAt?: number
 	error?: string
 }

package/src/types/errors/index.ts

@@ -20,6 +20,21 @@ import { ProviderError, classifyProviderError } from '../provider/errors.js'
 export type NamzuErrorCode =
 	/** The turn was set up wrong — missing model, contradictory options. Retrying cannot help. */
 	| 'invalid_config'
+	/**
+	 * A caller's cached prior messages disagree with this session's log. A
+	 * message carrying an id disagrees when the log recorded it under that id
+	 * with different content (`'edited'`) or never recorded that id at all
+	 * (`'foreign'`); `details.messageId` names it. A message with no id
+	 * disagrees when the caller's whole no-id cache does not align as a
+	 * contiguous run ending the log's own fold — the shape a host's cache
+	 * always has when it is exactly the fold plus new messages appended after
+	 * it — yet some of it still matches the fold by value out of place
+	 * (`'unaligned'`; no `messageId`, since none of it carries one). Retrying
+	 * with the same messages cannot help; the host must pass only its new
+	 * messages, or re-read history from the session instead of reusing a
+	 * cached copy.
+	 */
+	| 'stale_cached_history'
 	/** The upstream model call failed. `details.providerCode` narrows it. */
 	| 'provider_error'
 	/** A tool could not be executed or resolved. */

package/src/types/hitl/index.ts

@@ -135,6 +135,19 @@ export interface ToolCallSummary {
 	 * approve it on their own. A `deny` rule still refuses it outright.
 	 */
 	escalation?: ToolCallEscalation
+	/**
+	 * The tool itself declared that this exact call always needs a person's
+	 * approval (`ToolDefinition.requiresApproval`), regardless of the host's
+	 * rules or the turn's mode.
+	 *
+	 * Computed once, when the batch is prepared for review, the same way
+	 * {@link isDestructive} is — so it survives a gate `allow` rule (the
+	 * decision is forced back to `review` before the rule can settle
+	 * anything) and is asked about, or refused unattended, in every mode,
+	 * like {@link escalation}. No grant, skill grant or `accept-edits`
+	 * exemption covers it, and a `deny` rule still wins.
+	 */
+	requiresApproval?: true
 	/**
 	 * Present when a skill loaded earlier in this turn pre-approved this call
 	 * through its `allowed-tools`, and nothing stronger stands in the way.
@@ -165,6 +178,30 @@ export interface ToolCallEscalation {
 	 * `confirmedEscalations`.
 	 */
 	sandboxEscape?: true
+	/**
+	 * Why a command's own program name — where `programPositions` (the SDK's
+	 * shared resolver for where a command line actually execs a program;
+	 * `packages/sdk/src/authorization/program.ts`) says one is actually
+	 * exec'd, after unwrapping any `sudo`/`env`/`nice`/`timeout`/…
+	 * re-exec chain, and independently for each `find -exec` clause — is not
+	 * knowable ahead of running it: the word itself is decided at runtime
+	 * (`$(echo rm) -rf x`, `env $(echo git) push`, `"$HOME"/bin/tool`), an
+	 * option on a wrapper this does not recognise stood in the way, the
+	 * position is inherently unreadable (`eval`/`source`/`.`, an `xargs`
+	 * program that is a shell or a `{}` placeholder), or an earlier command
+	 * set `PATH`, `LD_PRELOAD`, `LD_LIBRARY_PATH`, `BASH_ENV`, `ENV` or `IFS`
+	 * so even a literal name here cannot be trusted to resolve to what its
+	 * text says.
+	 *
+	 * No rule can be trusted to have matched a program whose name never
+	 * appears as such anywhere in the call's own text: `git push.*` does not
+	 * see `$(echo git) push`, and neither `env $(echo git) push` nor
+	 * `timeout 5 $(echo git) push` puts the program right after the wrapper's
+	 * own name. Present only for a tool that declares `commandArgument`.
+	 * Argument-level expansion alone does not set this — only a position
+	 * where a program name is actually decided.
+	 */
+	unknownProgram?: string
 }
 
 export interface ToolModification {
@@ -175,8 +212,28 @@ export interface ToolModification {
 
 export interface UserQuestionOption {
 	id: string
+	/**
+	 * The label as shown and as the answer quotes it. `ask_user_question`
+	 * takes out of it a recommendation marker the model wrote out of habit:
+	 * "(Recommended)" on any option, and "(Önerilen)", "(Empfohlen)", … on
+	 * a recommended option, when every option whose label ends in a
+	 * parenthesised group is recommended, did not end in "(Recommended)", and
+	 * ends in that same one. A group that differs between options, or is left
+	 * before "(Recommended)" ("Cloud (AWS) (Recommended)" → "Cloud (AWS)"),
+	 * is kept. The recommendation is `recommended`, so a host never has to
+	 * parse a label to find it. Apart from surrounding spaces and
+	 * "(Recommended)", an option that is not recommended keeps its label as
+	 * written.
+	 */
 	label: string
 	description?: string
+	/**
+	 * The model recommends this option: it set `recommended: true` on it, or
+	 * left the flag out and ended the label in "(Recommended)". A host marks
+	 * it (a badge, an emphasis) rather than relying on the label to say so.
+	 * Absent, not `false`, on every other option.
+	 */
+	recommended?: boolean
 }
 
 /**