@matatbread/matbot-core 0.4.19 → 0.4.21

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.19",
+  "version": "0.4.21",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@matatbread/matbot-plugin-api": "^0.4.19"
+    "@matatbread/matbot-plugin-api": "^0.4.21"
   },
   "devDependencies": {
     "typescript": "^6.0.3"

package/src/assemble.ts

@@ -69,8 +69,6 @@ export interface AssembleOptions {
   providers:        ProviderRegistryImpl;
   gate:             HostGate;
   defaultSettings?: ReadonlyMap<string, Readonly<Record<string, unknown>>> | undefined;
-  /** Registry values present from boot, which an unregister reverts to rather than deleting. */
-  seed?:            Partial<MatbotServices>;
   builtinTools?:    Tool[];
   /** Resolve one `${NAME}` reference; the browser prompts for a missing secret. Defaults to the vault. */
   resolveSecret?(ref: string, vault: Vault): Promise<string>;
@@ -183,6 +181,9 @@ export function assembleMachine(opts: AssembleOptions): AssembledMachine {
   // registers its own (forwarding to its parent) over it — and unloading that reverts to refusing, which
   // is the honest answer for a job with no channel. Late-bound, as `services` is built below. It writes
   // through the shared runner, the one writer of the sessions in `services.sessions`.
+  // Not a host-supplied set: an embedder with a service of its own registers it on the returned
+  // `services` before `loaded()`, which is the same moment and one mechanism rather than two. A `seed`
+  // option existed for the node `FunctionRunner`, and went with it when that became a plugin.
   const seed: Partial<MatbotServices> = {
     MediaStore:      fileStore,
     SessionAppender: createSessionAppender({
@@ -191,15 +192,21 @@ export function assembleMachine(opts: AssembleOptions): AssembledMachine {
       notifier:   () => services.Notifier,
       isSubAgent: () => services.isSubAgent(),
     }),
-    ...opts.seed,
   };
   const serviceRegistry = new Map<string, unknown>(Object.entries(seed));
-  // The validator lookup is late-bound and read per call: one is registered by a plugin long after the
-  // builtins are seeded, and may be unloaded again. It wraps the executor, so every door — the runner,
-  // `POST /tools/:name`, `invokeTool` — is covered by one wrapper rather than a hook on the model's path.
-  const tools = new ToolRegistryImpl(opts.builtinTools, notifier,
-    () => serviceRegistry.get('ToolCallValidator') as ToolInputValidator | undefined);
+  // Validation wraps the executor, so every door — the runner, `POST /tools/:name`, `invokeTool` — is
+  // covered by one wrapper. It asks the `validate` hooks per call: validators arrive long after the
+  // builtins are seeded, and may be unloaded again.
   const hooks = new HookRegistry();
+  // The `ToolCallValidator` service is its predecessor, still honoured: consulted as one more hook, so a
+  // validator registered there is combined with the rest by the same rule. Host-owned (no `pluginName`),
+  // so no plugin's unload removes it; the key is read per call.
+  hooks.register({
+    on: 'validate',
+    handler: ctx => (serviceRegistry.get('ToolCallValidator') as ToolInputValidator | undefined)?.validateToolCall(ctx.tool, ctx.parameters),
+  });
+  const tools = new ToolRegistryImpl(opts.builtinTools, notifier,
+    (tool, parameters, signal) => hooks.runValidate({ tool, parameters, signal }));
   const systemContext = new SystemContextRegistryImpl();
 
   // The installation's permission policy. Deliberately NOT behind a forwardingProxy: the documented way

package/src/config/loader.ts

@@ -21,12 +21,6 @@ export interface MatbotConfig {
    * config rather than data. A stored value always wins; `delete` reverts to the default here.
    */
   defaultSettings?:  ReadonlyMap<string, Readonly<Record<string, unknown>>>;
-  /**
-   * Longest a `tool_function` body may run synchronously — without awaiting — before it is stopped
-   * (`function_timeout_ms`). Absent ⇒ the host's default. `0` ⇒ no limit at all, for testing: bodies run
-   * directly, and a loop that never awaits freezes the process.
-   */
-  functionTimeoutMs?: number;
 }
 
 function asString(v: YamlValue | undefined, label: string): string {
@@ -144,17 +138,6 @@ export function parseConfig(
     }
   }
 
-  const functionTimeoutRaw = doc['function_timeout_ms'];
-  let functionTimeoutMs: number | undefined;
-  if (functionTimeoutRaw !== undefined && functionTimeoutRaw !== null) {
-    functionTimeoutMs = asNumber(functionTimeoutRaw, 'function_timeout_ms');
-    // Refused rather than clamped, like maxRounds: a negative or fractional limit is a typo, and `0` already
-    // means something of its own.
-    if (!Number.isInteger(functionTimeoutMs) || functionTimeoutMs < 0) {
-      throw new Error(`Config: "function_timeout_ms" must be a non-negative integer (milliseconds; 0 removes the limit), got ${functionTimeoutMs}`);
-    }
-  }
-
   const prompt           = typeof doc['prompt']            === 'string' ? doc['prompt']            : undefined;
   const ephemeral        = doc['ephemeral'] === true ? true : undefined;
   const defaultProvider  = typeof doc['default_provider'] === 'string' ? doc['default_provider']  : undefined;
@@ -168,7 +151,6 @@ export function parseConfig(
     ...(defaultProvider  !== undefined ? { defaultProvider  } : {}),
     ...(principal        !== undefined ? { principal        } : {}),
     ...(defaultSettings.size > 0       ? { defaultSettings  } : {}),
-    ...(functionTimeoutMs !== undefined ? { functionTimeoutMs } : {}),
   };
 }
 

package/src/index.ts

@@ -18,12 +18,12 @@ export type {
   MissingSecretError, IncompatibleRuntimeError, NotAPluginError, PromptCancelledError, ReadOnlyError,
   MediaRejectedError, InvalidSecretNameError, MatbotErrorKind,
 } from '@matatbread/matbot-plugin-api';
-export { applyCreateSecret, assertStorableKey, unreferenceableKey, REFERENCEABLE_KEY_RULE } from '@matatbread/matbot-plugin-api';
+export { applyResolve, applyCreateSecret, assertStorableKey, unreferenceableKey, REFERENCEABLE_KEY_RULE } from '@matatbread/matbot-plugin-api';
 // The `provider update` patch policy, alongside the vault's: written once in plugin-api so the hosts
 // that apply one cannot differ on what a patch MEANS, and re-exported here so an app needs no direct
 // plugin-api dependency to get it.
-export { applyProviderPatch, patchedFields } from '@matatbread/matbot-plugin-api';
-export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind, SessionAppendKind, FUNCTION_TIMEOUT } from '@matatbread/matbot-plugin-api';
+export { applyProviderPatch, movedCredentialKeys, patchedFields, checkProviderModel, modelListed, closestIds } from '@matatbread/matbot-plugin-api';
+export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind, SessionAppendKind, FUNCTION_TIMEOUT, permitted, refused, refusalMessage } from '@matatbread/matbot-plugin-api';
 // The canonical `type: 'confirm'` answers. Same reason as the patch policy above: an app implementing a
 // PromptFn (or a test standing one in) has to speak them, and must not hard-code the rendered label.
 export { CONFIRM_YES, CONFIRM_NO } from '@matatbread/matbot-plugin-api';

package/src/registry.ts

@@ -20,7 +20,8 @@ const state = {
   toolRegistry:    undefined as ToolRegistry | undefined,
   frontendPlugins:  new Map<string, FrontendInfo>(),  // pluginName → info, written by services.registerFrontend()
   serviceKeys:     new Map<string, string[]>(),  // pluginName → MatbotMachine keys it registered
-  hookPlugins:        new Set<string>(),         // plugins that registered at least one hook
+  serviceLayers:   new Map<string, { owner: string; value: unknown }[]>(),  // key → plugin registrations, oldest first
+  hookPlugins:       new Set<string>(),         // plugins that registered at least one hook
   systemContextPlugins: new Set<string>(),       // plugins that registered a system-context contributor
   lifecycles:      new Map<string, AbortController>(),  // pluginName → "this plugin is loaded" signal, aborted on unload
   failedPlugins:   [] as FailedPlugin[],         // plugins the loader skipped, keyed by specifier (last failure wins)
@@ -60,7 +61,7 @@ async function resolveToolCollision(
 ): Promise<boolean> {
   const owner = existingOwner !== undefined ? `"${existingOwner}"` : 'a built-in';
   const label = `Tool \`"${toolName}"\` is already registered by **${owner}**. Overwrite it with the one from **"${incomingOwner}"**?`;
-  const allowed = await (services.PermissionGate ?? askPermissionGate).decide({
+  const decision = await (services.PermissionGate ?? askPermissionGate).decide({
     gate:     'tools.overwrite',
     subject:  toolName,
     // The incoming OWNER rides in the label rather than in a field of its own: a single `subject`
@@ -73,9 +74,10 @@ async function resolveToolCollision(
   // changed hands" is exactly the report this line answers. A policy that overwrites after ASKING
   // needs no warning — the user just saw the question.
   if (prompt === undefined) {
-    console.warn(`[matbot] ${label} — non-interactive, ${allowed ? 'overwriting' : 'keeping the existing tool'}.`);
+    console.warn(`[matbot] ${label} — non-interactive (${decision.source}), `
+      + `${decision.allowed ? 'overwriting' : 'keeping the existing tool'}.`);
   }
-  return allowed;
+  return decision.allowed;
 }
 
 // ── Version check ─────────────────────────────────────────────────────────────
@@ -121,6 +123,8 @@ export function registerPlugin(plugin: MatbotPlugin): void {
 
 // ── Resolution ────────────────────────────────────────────────────────────────
 
+const adapterLoads = new Map<string, Promise<MatbotPlugin>>();
+
 export function tryResolveProviderFactory(module: string): ProviderAdapterFactory | undefined {
   return state.providers.get(module);
 }
@@ -155,9 +159,18 @@ export async function instantiateProvider(services: MatbotRuntime, config: Provi
 
   // Not loaded yet — force-load the adapter module on demand (a runtime-contributed profile, or a disabled
   // pre-scan). Warn and return null rather than throw, so one unusable profile can't abort a turn. The next
-  // resolution hits the fast path above via specifier→name, so this loads at most once per adapter module.
+  // resolution hits the fast path above via specifier→name, so this loads at most once per adapter module —
+  // once SETTLED. Calls that arrive while the load is in flight share it: each starting its own lost to
+  // the first on "already registered", and boot is exactly when they arrive together (a skills reindex
+  // analyses every skill at once, all through one provider whose module `plugins:` does not list).
+  const loadKey = name ?? config.module;
+  let loading = adapterLoads.get(loadKey);
+  if (loading === undefined) {
+    loading = services.loadPlugin(config.module).finally(() => adapterLoads.delete(loadKey));
+    adapterLoads.set(loadKey, loading);
+  }
   try {
-    const plugin = await services.loadPlugin(config.module);
+    const plugin = await loading;
     if (plugin.provider === undefined) {
       console.warn(`[matbot] provider "${config.name}": module "${config.module}" loaded but registered no adapter.`);
       return null;
@@ -214,10 +227,46 @@ export function getRegisteredServiceKeys(pluginName: string): readonly string[]
  * register() that would normally record the key. Recording it makes the boot-opened backend unload-equal
  * to a runtime register(): unloadPlugin() then calls unregister() for it, reverting to the host base.
  */
-export function recordServiceKey(pluginName: string, key: string): void {
+export function recordServiceKey(pluginName: string, key: string, value?: unknown): void {
   const keys = state.serviceKeys.get(pluginName) ?? [];
   if (!keys.includes(key)) keys.push(key);
   state.serviceKeys.set(pluginName, keys);
+  // Out of band means it was in place before anything the loader registered, so it goes underneath.
+  const layers = state.serviceLayers.get(key) ?? [];
+  if (value !== undefined && !layers.some(l => l.owner === pluginName)) state.serviceLayers.set(key, [{ owner: pluginName, value }, ...layers]);
+}
+
+// A displaced StorageBackend is closed by the swap, so there is nothing beneath to reinstate.
+const CLOSED_WHEN_DISPLACED = new Set(['StorageBackend']);
+
+function pushServiceLayer(owner: string, key: string, value: unknown): void {
+  const layers = (state.serviceLayers.get(key) ?? []).filter(l => l.owner !== owner);
+  layers.push({ owner, value });
+  state.serviceLayers.set(key, layers);
+}
+
+/**
+ * Withdraw one plugin's registration of `key`. The registry holds one value per key, so this used to
+ * be a plain `unregister`, which removed whatever was CURRENT — not necessarily this plugin's. Where
+ * plugins stack on a key (a validator or gate that captures the one it displaces and delegates to it),
+ * unloading the one underneath took the one on top with it, and unloading the one on top reverted past
+ * the one it had displaced. Now: withdrawing the current registration reinstates the one it displaced,
+ * withdrawing a displaced one changes nothing visible, and only the last one out reverts to the host.
+ */
+function releaseServiceLayer(services: MatbotMachine, owner: string, key: string): void {
+  const layers = state.serviceLayers.get(key) ?? [];
+  const idx    = layers.findIndex(l => l.owner === owner);
+  if (idx === -1) { services.unregister(key); return; }
+  const wasCurrent = idx === layers.length - 1;
+  layers.splice(idx, 1);
+  if (wasCurrent && CLOSED_WHEN_DISPLACED.has(key)) layers.length = 0;
+  if (layers.length === 0) state.serviceLayers.delete(key);
+  if (!wasCurrent) return;
+  const beneath = layers[layers.length - 1];
+  if (beneath === undefined) { services.unregister(key); return; }
+  // The base register applies its value synchronously, before its returned promise settles.
+  void services.register(key as never, beneath.value as never).catch((e: unknown) =>
+    console.error(`[matbot] Could not reinstate "${key}" from "${beneath.owner}":`, e instanceof Error ? e.message : e));
 }
 
 /** Plugins that registered at least one hook in setup(). */
@@ -352,6 +401,7 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
       resolve:       (name: string) => services.tools.resolve(name),
       list:          ()             => services.tools.list(),
       removeByPlugin:(name: string) => services.tools.removeByPlugin(name),
+      validate:      async (name: string, parameters: unknown) => services.tools.validate?.(name, parameters),
     },
     hooks: {
       register(hook: Hook) {
@@ -375,6 +425,12 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
     async register(key, svc) {
       await services.register(key, svc);
       recordServiceKey(plugin.name, key as string);
+      pushServiceLayer(plugin.name, key as string, svc);
+    },
+    unregister(key: string) {
+      releaseServiceLayer(services, plugin.name, key);
+      const keys = state.serviceKeys.get(plugin.name);
+      if (keys !== undefined) state.serviceKeys.set(plugin.name, keys.filter(k => k !== key));
     },
     registerFrontend(info) {
       state.frontendPlugins.set(plugin.name, info);
@@ -404,7 +460,7 @@ export async function unloadPlugin(pluginName: string, services: MatbotMachine):
   state.lifecycles.delete(pluginName);
 
   for (const key of state.serviceKeys.get(pluginName) ?? []) {
-    services.unregister(key);
+    releaseServiceLayer(services, pluginName, key);
   }
   state.serviceKeys.delete(pluginName);
   state.hookPlugins.delete(pluginName);

package/src/runner.ts

@@ -192,6 +192,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
     async createSecret() { throw new Error('No vault configured'); },
     async writeSecret()  { throw new Error('No vault configured'); },
     hasKey() { return false; },
+    async readSecret() { return undefined; },
     async resolve(ref: string) { return ref; },
     scrub(text: string) { return text; },
   };
@@ -449,6 +450,9 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
           case 'thinking':
             yield { type: 'thinking', delta: ev.delta, traceId };
             break;
+          case 'progress':
+            yield { type: 'progress', pct: ev.pct, ...(ev.message !== undefined ? { message: ev.message } : {}), traceId };
+            break;
           case 'thinking-block':
             assistantParts.push({ type: 'thinking', thinking: ev.thinking, signature: ev.signature });
             break;
@@ -668,7 +672,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
         // default, so a gate handed it could never tell "no human is reachable" from "a human answered
         // with the default" — and would get the fallback back one layer too late to reason about.
         // `ToolContext.prompt` keeps the stand-in exactly as before; only the gate sees the truth.
-        ...bindGate(opts.permissionGate, tc.name, opts.prompt),
+        ...bindGate(opts.permissionGate, tool, opts.prompt, opts.toolRegistry ?? { resolve: n => tools.get(n) ?? null }),
         ...(opts.workdir     !== undefined ? { workdir:     opts.workdir     } : {}),
         ...(opts.configPath  !== undefined ? { configPath:  opts.configPath  } : {}),
         ...(opts.files       !== undefined ? { files:       opts.files       } : {}),

package/src/security/vault.ts

@@ -1,7 +1,6 @@
 import type { Vault } from '@matatbread/matbot-plugin-api';
-import { missingSecretError, applyCreateSecret, assertStorableKey, unreferenceableKey } from '@matatbread/matbot-plugin-api';
+import { applyResolve, applyCreateSecret, assertStorableKey, unreferenceableKey } from '@matatbread/matbot-plugin-api';
 
-const REF_RE = /\$\{([^}]+)\}/g;
 
 /**
  * Default vault implementation: a single flat namespace of secrets keyed by name.
@@ -58,19 +57,12 @@ export class VaultImpl implements Vault {
     return undefined;
   }
 
-  async resolve(ref: string): Promise<string> {
-    const errors: string[] = [];
-
-    const result = ref.replace(REF_RE, (_, name: string) => {
-      const value = this.store.get(name);
-      if (value === undefined) { errors.push(name); return ''; }
-      return value;
-    });
+  async readSecret(name: string): Promise<string | undefined> {
+    return this.store.get(name);
+  }
 
-    if (errors.length > 0) {
-      throw missingSecretError(errors);
-    }
-    return result;
+  resolve(ref: string): Promise<string> {
+    return applyResolve(this, ref);
   }
 
   scrub(text: string): string {

package/src/tool-registry.ts

@@ -1,32 +1,19 @@
 import { RegistryChangeKind } from '@matatbread/matbot-plugin-api';
-import type { Tool, ToolRegistry, Notifier, ToolContext, ToolEvent } from './types.js';
+import type { Tool, ToolRegistry, Notifier, ToolContext, ToolEvent, ToolInputError } from './types.js';
 
 /**
- * Structural contract for a registered input validator — duck-typed, never imported, exactly as
- * `ProfileDirectory` is: core must not depend on whichever plugin implements it (today
- * `@matatbread/matbot-tool-types`, from a tool's `ToolContract` params type), and the shape is the
- * whole agreement. `undefined` means NO OPINION — no contract for this tool, or one that cannot be
- * honestly validated — and is never read as "valid".
+ * The shape of the `ToolCallValidator` service — the single-valued predecessor of the `validate` hook,
+ * still consulted as one more opinion beside the hooks so a validator written against it keeps working.
+ * `undefined` means NO OPINION and is never read as "valid".
+ *
+ * @deprecated Register a `validate` hook instead. Removed in 0.5.0, with `ToolCallValidator`.
  */
 export interface ToolInputValidator {
   validateToolCall(tool: string, parameters: unknown): Promise<ToolInputError[] | undefined>;
 }
 
-/**
- * One rejected field. `path` is dotted, as a caller would WRITE the access (`.items[0].name`) rather
- * than as JSON Pointer — the reader is either a model repairing its own call or a developer looking at
- * a 422, and both write dots. `.` alone is the whole value.
- *
- * `value` is what was actually supplied there, and is what makes the difference between a message a
- * model can act on and one it has to guess at. Optional because a validator may not have it, and
- * `undefined` specifically means ABSENT: JSON carries no undefined, so there is nothing to show for a
- * missing property beyond saying it is missing.
- */
-export interface ToolInputError {
-  path:   string;
-  message: string;
-  value?: unknown;
-}
+/** Judges one call: every `validate` hook, and the `ToolCallValidator` service if one is registered. */
+export type ToolCallJudge = (tool: string, parameters: unknown, signal: AbortSignal) => Promise<ToolInputError[] | undefined>;
 
 /** Cap on the rendered value. Long enough to identify what was sent, short enough that a base64
  *  attachment or a large document cannot turn one rejected field into the bulk of a turn's context. */
@@ -56,17 +43,18 @@ function formatError(e: ToolInputError): string {
 }
 
 /**
- * Declared HERE, by the consumer, rather than by any of the plugins that implement it — `json-validation`
- * (against `inputSchema`) and `ts-validation` (against the `ToolContract` type) both register this key,
- * and two plugins declaring one key must declare it identically or the merge is a TS2717 in a file
- * neither owns. Core reads it, so core names it.
+ * Declared HERE, by the consumer, rather than by a plugin that implements it: two plugins declaring one
+ * key must declare it identically or the merge is a TS2717 in a file neither owns. Core reads it, so core
+ * names it.
  *
- * Exactly one is active, since the registry holds one value per key. A validator that loads over another
- * should capture the one it displaces and delegate to it when it has no opinion of its own — which is
- * how the typed and schema validators compose rather than shadow each other.
+ * Superseded by the `validate` hook, which matbot's own validators now use. A service key holds one value,
+ * so a second validator had to capture the first and delegate to it, which made the pair depend on load
+ * order and on each other. Still consulted, as one more opinion, so a validator registered here works.
  */
 declare module '@matatbread/matbot-plugin-api' {
   interface MatbotServices {
+    /** @deprecated Register a `validate` hook instead: several co-exist, where this key holds one. Still
+     *  consulted, as one more opinion beside the hooks; removed in 0.5.0. */
     ToolCallValidator?: ToolInputValidator;
   }
 }
@@ -80,32 +68,32 @@ declare module '@matatbread/matbot-plugin-api' {
 export const TOOL_INPUT_INVALID = 422;
 
 /**
- * Validation belongs at the executor, not in a `toolcall` hook, because the hook is a RUNNER channel:
+ * Validation belongs at the executor, not in a `toolcall` hook, because that hook is a RUNNER channel:
  * it guards the model's path and nothing else. `POST /tools/:name` and `invokeTool` both call
- * `tool.executor.execute` directly and fire no hooks, so a hook leaves two doors open and invites the
- * per-door duplication that then drifts. Wrapping here is the one place every door already passes
- * through.
+ * `tool.executor.execute` directly and fire no runner hooks, so a runner hook leaves two doors open and
+ * invites the per-door duplication that then drifts. Wrapping here is the one place every door already
+ * passes through — which is why the `validate` hook channel is dispatched from here, not by the runner.
  *
  * Wrapped at REGISTRATION rather than at `resolve`, so there is exactly one wrapper per tool and
  * `resolve(x) === resolve(x)` still holds.
  *
- * The validator is looked up per CALL, not captured: it may be registered long after the tools are
- * (plugin order), and it may be unloaded. No validator ⇒ the call passes straight through, so core
- * mandates no validation — it only honours one that is registered. The cost when a validator IS
+ * Validators are consulted per CALL, not captured: they are registered long after the tools are, and
+ * may be unloaded. None with an opinion ⇒ the call passes straight through, so core mandates no
+ * validation — it only honours what is registered. The cost when a validator IS
  * present is one generator frame plus a structural check (measured in the tens of nanoseconds against
  * tool work measured in milliseconds); the deliberate trade is that an INTERNAL call is validated too,
  * though a statically-typed call site should already be sound. That is not pure waste: `invokeTool`
  * with a dynamic name, a trigger's `invoke.params` (typed `object`) and a compiled skill's payload are
  * all internal callers whose input no compiler has checked.
  */
-function validatingTool(tool: Tool, lookup: () => ToolInputValidator | undefined): Tool {
+function validatingTool(tool: Tool, judge: ToolCallJudge): Tool {
   const inner = tool.executor;
   return {
     ...tool,
     executor: {
       execute(input: unknown, ctx: ToolContext): AsyncIterable<ToolEvent> {
         return (async function* () {
-          const errs = await lookup()?.validateToolCall(tool.name, input);
+          const errs = await judge(tool.name, input, ctx.signal);
           if (errs !== undefined && errs.length > 0) {
             const detail = errs.map(formatError).join('; ');
             yield { type: 'error', message: `Invalid input for tool "${tool.name}": ${detail}`, code: TOOL_INPUT_INVALID };
@@ -125,18 +113,22 @@ export class ToolRegistryImpl implements ToolRegistry {
   // proxy, not a resolved impl, so a later register('Notifier', …) takes effect here too. Optional: a
   // registry built without one (tests) simply announces nothing.
   private readonly notifier: Notifier | undefined;
-  // Host-injected, late-bound: a validator is typically registered by a plugin long after the builtin
-  // tools are seeded, so this is read per call rather than resolved here.
-  private readonly validator: (() => ToolInputValidator | undefined) | undefined;
+  // Host-injected, and consulted per call: validators are registered by plugins long after the builtin
+  // tools are seeded, and may be unloaded again.
+  private readonly judge: ToolCallJudge | undefined;
 
-  constructor(initial?: Iterable<Tool>, notifier?: Notifier, validator?: () => ToolInputValidator | undefined) {
-    this.validator = validator;
+  constructor(initial?: Iterable<Tool>, notifier?: Notifier, judge?: ToolCallJudge) {
+    this.judge = judge;
     if (initial !== undefined) for (const tool of initial) this.tools.set(tool.name, this.guard(tool));
     this.notifier = notifier;
   }
 
   private guard(tool: Tool): Tool {
-    return this.validator === undefined ? tool : validatingTool(tool, this.validator);
+    return this.judge === undefined ? tool : validatingTool(tool, this.judge);
+  }
+
+  async validate(name: string, parameters: unknown): Promise<ToolInputError[] | undefined> {
+    return this.judge?.(name, parameters, new AbortController().signal);
   }
 
   private announce(name: string, operation: 'added' | 'removed', pluginName?: string): void {