@namzu/sdk 46.0.0 → 48.0.0

package/src/types/plugin/index.ts

@@ -326,26 +326,41 @@ export function assertPluginHookResult(result: PluginHookResult): asserts result
 	}
 }
 
-export interface PluginHookDefinition {
-	readonly event: PluginHookEvent
-	readonly handler: (context: PluginHookContext) => Promise<PluginHookResult>
-	/**
-	 * Lower runs first. Default 100.
-	 *
-	 * Order was install order, which is neither declared nor stable — it
-	 * depends on when each plugin happened to be installed. That is fine
-	 * for hooks that only observe, and wrong for the ones that decide:
-	 * `executeHooks` SHORT-CIRCUITS on `skip` and `error`, so a hook that
-	 * denies a dangerous command only gets to deny it if it runs before
-	 * whatever else stops the chain. A guard that fires depending on
-	 * installation history is not a guard.
-	 *
-	 * Ties keep registration order, so plugins that never set a priority
-	 * behave exactly as before. Convention: guards below 100, observers
-	 * above.
-	 */
-	readonly priority?: number
-}
+/** Actions the query can interpret for a particular hook event. */
+export type PluginHookResultFor<E extends PluginHookEvent> = E extends 'user_prompt_submit'
+	? Extract<PluginHookResult, { action: 'continue' | 'annotate' | 'skip' | 'error' }>
+	: E extends 'pre_tool_use'
+		? Extract<PluginHookResult, { action: 'continue' | 'skip' | 'modify' | 'error' }>
+		: E extends 'post_tool_use'
+			? Extract<PluginHookResult, { action: 'continue' | 'replace' | 'retry' | 'error' }>
+			: E extends 'turn_interrupt' | 'session_start' | 'session_end'
+				? Extract<PluginHookResult, { action: 'continue' }>
+				: Extract<PluginHookResult, { action: 'continue' | 'error' }>
+
+/** The event and its handler verdict stay correlated, including in hook arrays. */
+export type PluginHookDefinition<E extends PluginHookEvent = PluginHookEvent> =
+	E extends PluginHookEvent
+		? {
+				readonly event: E
+				readonly handler: (context: PluginHookContext) => Promise<PluginHookResultFor<E>>
+				/**
+				 * Lower runs first. Default 100.
+				 *
+				 * Order was install order, which is neither declared nor stable — it
+				 * depends on when each plugin happened to be installed. That is fine
+				 * for hooks that only observe, and wrong for the ones that decide:
+				 * `executeHooks` SHORT-CIRCUITS on `skip` and `error`, so a hook that
+				 * denies a dangerous command only gets to deny it if it runs before
+				 * whatever else stops the chain. A guard that fires depending on
+				 * installation history is not a guard.
+				 *
+				 * Ties keep registration order, so plugins that never set a priority
+				 * behave exactly as before. Convention: guards below 100, observers
+				 * above.
+				 */
+				readonly priority?: number
+			}
+		: never
 
 // ---------------------------------------------------------------------------
 // Plugin MCP server config
@@ -367,6 +382,8 @@ export interface PluginManifest {
 	readonly version: string
 	readonly description: string
 	readonly author?: string
+	/** Plugin-authored request context, present only while this plugin is enabled. */
+	readonly instructions?: string
 	readonly tools?: readonly string[]
 	readonly skills?: readonly string[]
 	readonly hooks?: readonly string[]
@@ -391,6 +408,7 @@ export const PluginManifestSchema = z.object({
 	version: z.string().min(1),
 	description: z.string().min(1),
 	author: z.string().optional(),
+	instructions: z.string().min(1).optional(),
 	tools: z.array(z.string()).max(MAX_TOOLS_PER_PLUGIN).optional(),
 	skills: z.array(z.string()).max(MAX_SKILLS_PER_PLUGIN).optional(),
 	hooks: z.array(z.string()).max(MAX_HOOKS_PER_PLUGIN).optional(),
@@ -419,7 +437,12 @@ export interface PluginDefinition {
 // ---------------------------------------------------------------------------
 
 export type PluginLifecycleEvent =
-	| { type: 'plugin_installed'; pluginId: PluginId; name: string; scope: PluginScope }
+	| {
+			type: 'plugin_installed'
+			pluginId: PluginId
+			name: string
+			scope: PluginScope
+	  }
 	| { type: 'plugin_enabled'; pluginId: PluginId; name: string }
 	| { type: 'plugin_disabled'; pluginId: PluginId; name: string }
 	| { type: 'plugin_uninstalled'; pluginId: PluginId; name: string }

package/src/types/provider/chat.ts

@@ -193,5 +193,10 @@ export interface ChatCompletionResponse {
 		citations?: readonly import('../message/index.js').Citation[]
 	}
 	finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter'
+	/**
+	 * `'context_window'` when a `'length'` finish was the model's context
+	 * window rather than the output token limit; see `StreamChunk.finishDetail`.
+	 */
+	finishDetail?: 'context_window'
 	usage: TokenUsage
 }

package/src/types/provider/config.ts

@@ -38,9 +38,14 @@ export interface MockToolCall {
 	/** Fragment size for the argument JSON; smaller exercises more buffering. */
 	argChunkSize?: number
 	/**
-	 * Omit the block-close signal and stop mid-JSON, reproducing the
-	 * provider cutting a tool call off at `max_tokens`. The consumer should
-	 * mark the call `inputTruncated` rather than crashing on a parse.
+	 * Send only the first half of the arguments, omit the block-close signal
+	 * and finish with `'length'` (unless the turn sets `finishReason`),
+	 * reproducing the provider cutting a tool call off at `max_tokens`. The
+	 * response ends at this call, as an output limit ends it: later calls in
+	 * the turn's `toolCalls` are not streamed. The consumer should mark the
+	 * call `inputTruncated` with a `truncated` `inputError` rather than
+	 * crashing on a parse; under a scripted `finishReason` of `'stop'` or
+	 * `'tool_calls'` it is `malformed` instead.
 	 */
 	truncateArguments?: boolean
 	/**

package/src/types/provider/stream.ts

@@ -29,8 +29,28 @@ export interface StreamChunk {
 		}
 
 		content?: string
+		/**
+		 * Who wrote {@link content}. Absent means the model. `'driver'` marks
+		 * text a driver adds of its own after the model's output, such as a
+		 * list of the sources a hosted search used. It is shown and kept in
+		 * the message like any other text, but it is not output the model
+		 * produced: the turn loop does not read it as the model moving on from
+		 * its last tool call, which would turn a call the output limit cut
+		 * off into a malformed one.
+		 */
+		contentOrigin?: 'driver'
 		/** Identity and phase of this content fragment, when the provider supplies them. */
 		textPart?: Omit<import('../message/index.js').AssistantTextPart, 'text'>
+		/**
+		 * Fragments of tool calls. `index` is what groups them: every fragment
+		 * of one call carries the same index, and no other call in the
+		 * response uses it. The call's `id` and `function.name` may arrive on
+		 * any of its fragments, including after arguments; arguments that
+		 * arrive first are kept for the call at their index. The turn loop gives
+		 * a call whose id never arrives, here or on `toolCallEnd`, an id of its
+		 * own. A second id on an index another call holds is refused, by the
+		 * turn loop and by `collectChatCompletion`.
+		 */
 		toolCalls?: Array<{
 			index: number
 			id?: string
@@ -52,6 +72,12 @@ export interface StreamChunk {
 		 * leave this undefined; the orchestrator infers from
 		 * end-of-stream instead.
 		 *
+		 * `id` fills in the call's id when no fragment carried one. The
+		 * completion always carries the id the call was announced with, and
+		 * follows the announcement: a close with an empty `id` for a call no
+		 * fragment named, or for a call whose name has not arrived, is
+		 * settled when the stream ends instead.
+		 *
 		 * Added 2026-05-01 (ses_001-tool-stream-events A9).
 		 */
 		toolCallEnd?: {
@@ -93,6 +119,19 @@ export interface StreamChunk {
 		citation?: import('../message/index.js').Citation
 	}
 	finishReason?: 'stop' | 'tool_calls' | 'length' | 'content_filter'
+	/**
+	 * Which limit a `'length'` finish reached, when it was not the output
+	 * token limit: `'context_window'` when the response filled the model's
+	 * context window (a stop reason such as `model_context_window_exceeded`
+	 * or `model_length`).
+	 *
+	 * Both stop the output where it stands, so both are `'length'`, and a
+	 * tool call either one cut off is truncated. They differ in what can
+	 * follow: after the output limit the turn loop asks the model to continue
+	 * a reply it cut off mid-text, and after the context window there is no
+	 * room to continue into. Set only with `finishReason: 'length'`.
+	 */
+	finishDetail?: 'context_window'
 	usage?: TokenUsage
 	error?: string
 

package/src/types/sandbox/index.ts

@@ -466,7 +466,7 @@ export interface SandboxDestroyOptions {
  *  - `azureFileShare` — mount an Azure Files SMB share into the
  *    container. Used by managed Azure Container Instances (incl.
  *    Standby Pool) which have no host filesystem to bind from; the
- *    Vandal-side host provisions a per-task share before claim and
+ *    host provisions a per-task share before claim and
  *    the ACI backend translates this variant to ACI's `volume +
  *    azureFile` shape.
  */

package/src/types/session/events.ts

@@ -1096,11 +1096,22 @@ type CoreSessionEvent =
 			toolUseId: ToolUseId
 			input: unknown
 			/**
-			 * True when the provider stream ended before the tool JSON
-			 * arguments closed. `input` stays a sanitized object so public
-			 * consumers never receive internal recovery sentinels.
+			 * True when the streamed arguments could not be read, whether the
+			 * response stopped before they closed or they were not valid JSON;
+			 * {@link inputError} says which. `input` is then `{}`, a sanitized
+			 * object, so public consumers never receive internal recovery
+			 * sentinels.
 			 */
 			inputTruncated?: boolean
+			/** Why the arguments could not be read. Present exactly when `inputTruncated` is. */
+			inputError?: import('../message/index.js').ToolInputError
+			/**
+			 * The arguments as they arrived, when they could not be read: at most
+			 * the first 16 384 characters, with `inputError.length` saying how many
+			 * there were. The whole text stays on the assistant message, as
+			 * `ToolCall.metadata.partialArguments`.
+			 */
+			partialArguments?: string
 	  }
 
 /**

package/src/types/tool/index.ts

@@ -1,5 +1,4 @@
 import type { z } from 'zod'
-import type { Logger } from '../../utils/logger.js'
 import type { CodeNavigationProvider } from '../code-navigation/index.js'
 // Type-only, and circular by design: a tool-result guardrail is described in
 // terms of the tool that produced the result, and the registry that holds
@@ -12,18 +11,27 @@ import type { PermissionMode } from '../permission/index.js'
 import type { Sandbox } from '../sandbox/index.js'
 import type { ToolPresentation } from './presentation.js'
 
-export interface ToolRegistryRef {
-	searchDeferred(query: string): ToolDefinition[]
-	/** Ranked active matches, when this registry supports active-tool discovery. */
-	searchActive?(query: string): ToolDefinition[]
-	activate(names: string[]): void
-	getAvailability(name: string): ToolAvailability
+/**
+ * The read-only slice of a `ToolManager` (`toolsets/manager.ts`) a running
+ * tool's own `execute()` body is given, through {@link ToolContext.toolRegistry}.
+ *
+ * Replaces the old `ToolRegistryRef`, which also carried `activate` (a
+ * mutation) and an optional `searchActive`. Availability is derived, not
+ * mutated (see `ToolManager.availability`), so there is nothing left for a
+ * tool body to activate: a tool that wants to make more of the catalogue
+ * callable returns `ToolResult.reveals` instead, and the manager derives the
+ * effect from that result once it is persisted onto the tool message.
+ */
+export interface ToolsView {
+	has(name: string): boolean
+	availability(name: string): ToolAvailability
+	searchDeferred(query: string, limit?: number): readonly ToolDefinition[]
 }
 
 /**
  * The slice of the skills registry a tool is given.
  *
- * Structural for the reason `ToolRegistryRef` is: this file is imported by
+ * Structural for the reason `ToolsView` is: this file is imported by
  * everything, and naming `SkillRegistry` here would drag the skill loader's
  * filesystem imports into every consumer's type graph.
  */
@@ -98,7 +106,7 @@ export interface SkillRegistryRef {
  * The slice of the background job registry a tool is given.
  *
  * A structural reference rather than the class, for the reason
- * `ToolRegistryRef` exists: this type file is imported by everything, and
+ * `ToolsView` exists: this type file is imported by everything, and
  * naming the implementation here would drag a `node:child_process` module
  * into every consumer's type graph. `owner` is not on this surface at all —
  * the executor binds it to the turn, so a tool cannot start a job that
@@ -400,7 +408,7 @@ export interface ToolContext {
 
 	invocationState?: InvocationState
 
-	toolRegistry?: ToolRegistryRef
+	toolRegistry?: ToolsView
 	/**
 	 * The names this turn may call, if the turn was narrowed.
 	 *
@@ -550,7 +558,7 @@ export interface ToolContext {
 	 * option alone is the host's to write and the kernel's default reaches
 	 * nobody.
 	 *
-	 * The registry's own {@link ToolRegistryConfig.resultGuardrails} WIN when
+	 * The registry's own {@link ToolManagerConfig.resultGuardrails} (`toolsets/manager.ts`) WIN when
 	 * the registry was built with them — including an empty array, which means
 	 * none — because a registry that stated its policy has stated it. These
 	 * apply to a registry that declared none, which is the ordinary case: a
@@ -566,7 +574,7 @@ export interface ToolContext {
 	 * Run another tool through the same dispatch this call came through.
 	 *
 	 * For `run_code`, whose whole purpose is calling tools in a loop. NOT
-	 * added to {@link ToolRegistryRef}: that ref is about discovering and
+	 * added to {@link ToolsView}: that ref is about discovering and
 	 * activating tools, and putting `execute` on it would make "can dispatch"
 	 * a property of holding a registry reference rather than a capability a
 	 * host wired deliberately.
@@ -722,6 +730,20 @@ export interface ToolResult {
 	 * must not lose: what its controls do, where things are, what failed.
 	 */
 	workingState?: readonly import('../../compaction/types.js').WorkingStatePin[]
+	/**
+	 * Names of deferred tool schemas this successful result loads, like
+	 * `search_tools`. This is a discovery receipt, not proof that an external
+	 * connection or capability is ready. Use `readyWhen(toolset, check)` for
+	 * a host-owned prerequisite; search cannot satisfy that check.
+	 *
+	 * Only a name currently `'deferred'` in the manager is loaded, and
+	 * only when it is also inside `ToolContext.allowedTools` when that turn
+	 * is narrowed to an allow-list. Every other name — unknown, already
+	 * active, suspended, or outside the allow-list — is silently ignored:
+	 * this can never throw, resurrect a tool a host marked unready, or
+	 * widen what a narrowed turn may call.
+	 */
+	reveals?: readonly string[]
 	/**
 	 * This result needs a person before the turn can go on — a sign-in page,
 	 * a CAPTCHA, a second factor, anything the model must not try to answer
@@ -779,8 +801,59 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * Concise, model-readable recovery guidance appended when inputSchema
 	 * rejects a call. Use for conditional schemas whose required shapes
 	 * cannot be reconstructed from JSON Schema's top-level `required` list.
+	 *
+	 * Also appended when a call's arguments were malformed, not valid JSON,
+	 * and the tool declares no {@link malformedInputHint}: a model that could
+	 * not write this tool's arguments as JSON needs the same shape.
 	 */
 	validationErrorHint?: string
+	/**
+	 * Concise, model-readable advice appended when a call to this tool was cut
+	 * off before its arguments closed and the call itself has to carry less:
+	 * how this tool takes long input in parts. It follows the size budget the
+	 * model is given (see {@link largeStringArguments}).
+	 *
+	 * That is a cut-off by the stream ending, or by the output limit when the
+	 * call was at least half of the response. When most of the response went
+	 * to what came before the call, the model is told to send less before it
+	 * instead, and this is not appended. Nor after a content filter's stop,
+	 * which sending less does not get past, nor for a malformed call, since
+	 * size does not fix JSON: that is {@link malformedInputHint}.
+	 */
+	truncatedInputHint?: string
+	/**
+	 * Concise, model-readable advice appended when a call to this tool is
+	 * answered as malformed: its arguments were not valid JSON, so the call
+	 * never reached {@link inputSchema}. For example, how to escape a file
+	 * body inside a JSON string. When it is absent,
+	 * {@link validationErrorHint} is appended instead, so a tool that states
+	 * its required shape there need not state it twice; one that declares
+	 * both and wants the shape shown includes it here.
+	 *
+	 * Every unreadable call is malformed except the one the response stopped
+	 * on, when it stopped early: at the output limit (`finishReason:
+	 * 'length'`), at a content filter, or with no finish reason at all. That
+	 * call was cut off, and gets {@link truncatedInputHint} instead. A call
+	 * the model followed with more text, reasoning or another call is
+	 * malformed whatever the finish reason, the output limit included. See
+	 * `ToolInputError`.
+	 */
+	malformedInputHint?: string
+	/**
+	 * The arguments that carry long free-form text — a file body, a
+	 * replacement, a delegated assignment — each with the number of characters
+	 * one call should keep it under, e.g. `{ content: 12_000 }`.
+	 *
+	 * Read only when a call to this tool is cut off before its arguments
+	 * close and the call itself has to carry less (see
+	 * {@link truncatedInputHint} for when that is): the model is told to keep
+	 * these arguments under their budgets, each lowered to half of what
+	 * arrived after an output limit. A tool that declares none is still told,
+	 * after an output limit, to keep its arguments as a whole under half of
+	 * what arrived. Declaring them names the arguments the model should
+	 * shorten, and gives a budget after a stream that ended as well.
+	 */
+	largeStringArguments?: Readonly<Record<string, number>>
 
 	/**
 	 * The shape this tool returns, as JSON Schema, appended to the
@@ -947,6 +1020,52 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 */
 	capturesScreen?(input: TInput): boolean
 
+	/**
+	 * This call always needs a person's approval, whatever the host's rules
+	 * say and whatever mode the turn is running in.
+	 *
+	 * Distinct from {@link isDestructive}, and stronger. A destructive call
+	 * is still let through by a gate `allow` rule (`allow_by_name`,
+	 * `allow_by_category`, …) and by `auto` mode or an unattended turn — the
+	 * rule and the mode both outrank it. This flag cannot be outranked either
+	 * way: it survives an `allow` rule the same way an escalation does (the
+	 * decision is forced back to review before the rule's `allow` ever
+	 * settles anything), and it is asked about, or refused when nobody can
+	 * be asked, in every mode — `auto` and a remembered "approve all"
+	 * included — the same way a sandbox escape or a path outside the turn's
+	 * roots is. No grant, skill grant or `accept-edits` exemption covers it.
+	 * A `deny` rule still wins: this flag can only ADD a review, never open
+	 * one a rule closed.
+	 *
+	 * For a call that is sensitive for a reason other than being
+	 * destructive — it costs money, it leaves an audit trail somewhere else,
+	 * it is policy-sensitive — rather than a tool author reaching for
+	 * `isDestructive` on a call that does not destroy anything, just to get
+	 * the review a host might not otherwise configure. See
+	 * `docs/sdk/review-policy.md`.
+	 *
+	 * Never populated from a connected server's own wire annotations
+	 * (`mcpToolToToolDefinition` does not set it): a server cannot demand,
+	 * or waive, its own review requirement. It is host/plugin-trust-boundary
+	 * metadata, like {@link capturesScreen}.
+	 */
+	requiresApproval?(input: TInput): boolean
+
+	/**
+	 * Free-form, tool-author-declared data for filtering and behaviour
+	 * customization — never a classification the runtime itself reads.
+	 *
+	 * Not sent to the model: unlike {@link outputSchema}, which is shown in
+	 * the description precisely so the model can act on it, this is for a
+	 * host, a capability or a toolset wrapper to read back, with
+	 * `matchesToolSelector` (`tools/roster.ts`) or by hand. A connected
+	 * server's own annotations that have nowhere else to land — its
+	 * `title`, `idempotentHint`, `openWorldHint`, and any `_meta` it
+	 * attached — arrive here (`mcpToolToToolDefinition`); `isReadOnly` and
+	 * `isDestructive` keep the two hints that already have a typed home.
+	 */
+	metadata?: Readonly<Record<string, unknown>>
+
 	/**
 	 * Opt-in ordering boundary in a direct model tool-call batch. Earlier
 	 * calls settle before this call starts; later calls wait for this call
@@ -958,24 +1077,18 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * their external effects have stopped, and does not imply success.
 	 */
 	executionBarrier?: boolean
-
-	/**
-	 * Where this tool came from, when it did not come from here.
-	 *
-	 * Absent means host-defined: this process, code the operator installed,
-	 * no untrusted party in the chain. Present means a connected server
-	 * supplied both the tool and its own description of what the tool does
-	 * — including whether it is read-only, which three separate gates were
-	 * treating as a fact rather than as the hint the wire calls it.
-	 *
-	 * See {@link isTrustedReadOnly}. This field exists so a gate can tell
-	 * the two apart; `isReadOnly` keeps reporting faithfully what the
-	 * server said, because the outbound re-export and the destructive
-	 * label shown to a human both need the server's own answer.
-	 */
-	provenance?: ToolProvenance
 }
 
+/**
+ * A tool's owning source's read-only trust decision, as `screenToolResult`
+ * reads it off a call's `ToolContext`/result plumbing.
+ *
+ * Where a tool once carried this on itself (`ToolDefinition.provenance`,
+ * removed — plan.md v3 §3), it now comes from the `ToolManager`'s
+ * `sourceOf(name)` for the call in progress: a definition cannot claim its
+ * own source, only the toolset that contributed it can. See
+ * `toolsets/types.ts`'s `ToolSourceRef` and `tools/trusted-read-only.ts`.
+ */
 export interface ToolProvenance {
 	/** The connected server this tool came from, named as configured. */
 	readonly server: string
@@ -1006,6 +1119,12 @@ export interface LLMToolSchema {
 	}
 }
 
+/**
+ * `'suspended'` means the owning toolset's host-owned readiness check is
+ * false. Such tools are excluded from discovery and execution even if a
+ * deferred-schema receipt exists. `RuntimeToolOverrides` still does not
+ * implement session-level suspension.
+ */
 export type ToolAvailability = 'deferred' | 'active' | 'suspended'
 
 export type ZodToJsonSchema = (schema: z.ZodType) => Record<string, unknown>
@@ -1023,36 +1142,22 @@ export interface ToolTierConfig {
 	labelInDescription?: boolean
 }
 
-export interface ToolRegistryConfig {
-	logger?: Logger
-	tierConfig?: ToolTierConfig
-	/**
-	 * Screens run against every tool result before anything downstream
-	 * reads it — the output budget, compaction, and the model itself are
-	 * all past this point.
-	 *
-	 * Absent means no screening, which is what shipped before this existed:
-	 * a connected server's text reached the model unexamined. See
-	 * {@link ToolResultGuardrailSpec}.
-	 */
-	resultGuardrails?: readonly ToolResultGuardrailSpec[]
-}
-
 export interface ToolExecutionResult extends ToolResult {
 	permissionDenied?: boolean
 	permissionMessage?: string
 }
 
 /**
- * An input decoded exactly once by its owning tool registry.
+ * An input decoded exactly once by its owning `ToolManager`.
  *
  * `input` is the detached, deeply frozen JSON review projection:
  * authorization, approval UI, probes and audit all inspect this value. The
- * registry privately retains a separate detached copy that
- * {@link ToolRegistryContract.executePrepared} gives the tool. Caller-owned
- * aliases therefore cannot change either side after preparation. A
- * preparation is registry-owned and cannot be executed by a different
- * registry or after that tool registration is replaced.
+ * manager privately retains a separate detached copy that
+ * `ToolManager.executePrepared` (`toolsets/manager.ts`) gives the tool.
+ * Caller-owned aliases therefore cannot change either side after
+ * preparation. A preparation is owned by the manager that made it and
+ * cannot be executed by a different one, or after its tool's definition
+ * changed identity (a live toolset's own update).
  */
 export interface PreparedToolExecution {
 	readonly toolName: string
@@ -1064,62 +1169,6 @@ export type ToolPreparationResult =
 	| { readonly success: true; readonly prepared: PreparedToolExecution }
 	| { readonly success: false; readonly result: ToolExecutionResult }
 
-/**
- * Full tool registry contract — registration, lookup, execution, prompt generation.
- * Concrete implementation: `ToolRegistry` in `registry/tool/execute.ts`.
- */
-export interface ToolRegistryContract {
-	register(id: string, tool: ToolDefinition): void
-	register(tool: ToolDefinition, initialState?: ToolAvailability): void
-	register(tools: ToolDefinition[], initialState?: ToolAvailability): void
-
-	unregister(id: string): boolean
-	clear(): void
-
-	get(name: string): ToolDefinition | undefined
-	getOrThrow(name: string): ToolDefinition
-	has(name: string): boolean
-	getAll(): ToolDefinition[]
-	listIds(): string[]
-	listNames(): string[]
-
-	getAvailability(name: string): ToolAvailability
-	activate(names: string[]): void
-	defer(names: string[]): void
-	suspendAll(): void
-	hasSuspended(): boolean
-	searchDeferred(query: string): ToolDefinition[]
-	/** Ranked active matches, when this registry supports active-tool discovery. */
-	searchActive?(query: string): ToolDefinition[]
-	getCallableTools(toolNames?: string[]): ToolDefinition[]
-
-	/**
-	 * Decode/transform an input once, before authorization or human review.
-	 *
-	 * The returned preparation is opaque registry authority. Implementations
-	 * must not run tool code here. They must detach both the executable value
-	 * and `prepared.input` from caller/schema aliases, and make the latter a
-	 * deeply immutable JSON projection of the exact value retained for
-	 * execution. Unsupported mutable/exotic graphs fail closed.
-	 */
-	prepareExecution(toolName: string, rawInput: unknown): ToolPreparationResult
-
-	/** Execute the exact value retained by `prepareExecution`, without parsing again. */
-	executePrepared(
-		prepared: PreparedToolExecution,
-		context: ToolContext,
-	): Promise<ToolExecutionResult>
-
-	execute(toolName: string, rawInput: unknown, context: ToolContext): Promise<ToolExecutionResult>
-
-	size(): number
-
-	toLLMTools(toolNames?: string[]): LLMToolSchema[]
-	toPromptSection(toolNames?: string[]): string
-	toTierGuidance(): string | null
-	assignTiers(mapping: Record<string, string>): void
-}
-
 export * from './repair.js'
 
 export type {

package/src/types/toolset/index.ts

@@ -1,5 +1,3 @@
-import type { LLMToolSchema, ToolDefinition, ToolPermission } from '../tool/index.js'
-
 export type ToolSourceKind =
 	| 'host_tool'
 	| 'provider_builtin'
@@ -8,8 +6,6 @@ export type ToolSourceKind =
 	| 'plugin'
 	| 'connector'
 
-export type ToolLoadingMode = 'eager' | 'deferred' | 'disabled' | 'suspended'
-
 export interface ToolSource {
 	readonly id: string
 	readonly kind: ToolSourceKind
@@ -21,6 +17,16 @@ export interface ToolSource {
 		readonly url?: string
 		readonly transport?: 'streamable_http' | 'sse' | 'stdio'
 		readonly authorizationRef?: string
+		/**
+		 * The operator marked this connected server's read-only claims
+		 * trustworthy (plan.md §4's `readOnlyHintTrusted` option). Absent or
+		 * `false` means untrusted — an unmarked server's `isReadOnly` claim
+		 * raises the plan-mode bar but never lowers it on its own; see
+		 * `toToolSourceRef` and `tools/trusted-read-only.ts`. One value per
+		 * server, not per tool: every tool an `mcpToolset` contributes for a
+		 * given server carries the same trust decision.
+		 */
+		readonly readOnlyHintTrusted?: boolean
 	}
 	readonly providerTool?: {
 		readonly type: string
@@ -34,46 +40,3 @@ export interface ToolSource {
 	}
 	readonly metadata?: Record<string, unknown>
 }
-
-export interface ToolsetPolicy {
-	readonly enabled?: boolean
-	readonly loading?: ToolLoadingMode
-	readonly preferred?: boolean
-	readonly providerConfig?: Record<string, unknown>
-}
-
-export interface ToolsetDefinition {
-	readonly id: string
-	readonly sourceId: string
-	readonly name: string
-	readonly description?: string
-	readonly defaultPolicy?: ToolsetPolicy
-	readonly metadata?: Record<string, unknown>
-}
-
-export interface ToolCatalogEntry {
-	readonly name: string
-	readonly description: string
-	readonly sourceId: string
-	readonly toolsetId: string
-	readonly policy: ToolsetPolicy
-	readonly definition?: ToolDefinition
-	readonly llmSchema?: LLMToolSchema
-	readonly permissions?: readonly ToolPermission[]
-	readonly category?: ToolDefinition['category']
-	readonly metadata?: Record<string, unknown>
-}
-
-export interface ToolCatalogSearchResult {
-	readonly tool: ToolCatalogEntry
-	readonly source: ToolSource
-	readonly toolset: ToolsetDefinition
-	readonly score: number
-	readonly matched: readonly string[]
-}
-
-export interface ToolCatalogSnapshot {
-	readonly sources: readonly ToolSource[]
-	readonly toolsets: readonly ToolsetDefinition[]
-	readonly tools: readonly ToolCatalogEntry[]
-}