@matatbread/matbot-plugin-api 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"
   },

package/src/contract-arms.ts

@@ -0,0 +1,44 @@
+// The `ToolContracts` arms for tools that carry their contract as a `toolContract` STRING, written out for a
+// file that declares them: the generated dts a body is checked against, the program that types them for
+// validation, a turn's own tools appended to a snippet. One implementation, because each of those must agree
+// on what a string means, and a fourth copy of the namespace rule would drift from the other three.
+//
+// A string may name types that exist nowhere else — a function package's own `interface HubReport`, carried
+// on `toolContractTypes`. Those are declared in a namespace of their own with an alias per tool beside them,
+// so the contract is written exactly as its author wrote it and still resolves, and two packages' `Report`s
+// never meet. Tools carrying identical declarations (one package's exports) share one namespace.
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+export interface ContractSource {
+  readonly name:      string;
+  readonly contract:  string;
+  readonly types?:    string | undefined;
+}
+
+export interface ContractArms {
+  /** Top-level declarations to place ahead of the `ToolContracts` augmentation; empty when nothing has types. */
+  readonly preamble:   string;
+  /** Per tool, the type to write as its `ToolContracts` arm: its own string, or the alias that wraps it. */
+  readonly arms:       ReadonlyMap<string, string>;
+  /** Per namespace in the preamble, the tools it serves — what a diagnostic inside it is attributed to. */
+  readonly namespaces: ReadonlyMap<string, readonly string[]>;
+}
+
+export function contractArms(tools: Iterable<ContractSource>): ContractArms {
+  const arms = new Map<string, string>();
+  const groups = new Map<string, { ns: string; members: [alias: string, tool: string, contract: string][] }>();
+  for (const t of tools) {
+    if (t.types === undefined || t.types.trim() === '') { arms.set(t.name, t.contract); continue; }
+    let group = groups.get(t.types);
+    if (group === undefined) { group = { ns: `ToolContractTypes${groups.size + 1}`, members: [] }; groups.set(t.types, group); }
+    const alias = IDENTIFIER.test(t.name) ? t.name : `Tool${group.members.length + 1}`;
+    group.members.push([alias, t.name, t.contract]);
+    arms.set(t.name, `${group.ns}.${alias}`);
+  }
+  const preamble = [...groups].map(([types, g]) =>
+    `declare namespace ${g.ns} {\n${types.split('\n').map(l => `  ${l}`).join('\n')}\n`
+    + g.members.map(([alias, , contract]) => `  export type ${alias} = ${contract};`).join('\n') + '\n}\n').join('');
+  const namespaces = new Map([...groups.values()].map(g => [g.ns, g.members.map(([, tool]) => tool)] as const));
+  return { preamble, arms, namespaces };
+}

package/src/fetch-origin.ts

@@ -0,0 +1,58 @@
+// `fetch`, with every URL a request reaches — the one asked for and each one a redirect leads to — put to
+// `admit` before anything is sent there. A gate on the first URL alone is a gate on nothing: an approved
+// host that answers 302 hands the request, and whatever it carries, to an origin nobody was asked about.
+//
+// So a `follow` request (the default) is followed here, one hop at a time, as the platform would: 303, and
+// 301/302 after a POST, become a bodiless GET; 307/308 resend the body; credentials are dropped on a change
+// of origin; twenty hops at most. What is lost is cosmetic: the final `Response` reports the last hop's URL
+// and `redirected: false`. A `manual` or `error` request is one hop, admitted and handed to `fetch` as is.
+//
+// A browser's `manual` redirect is opaque, with no Location to read, so there it is refused rather than
+// followed blind.
+
+const MAX_REDIRECTS = 20;
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+const BODY_HEADERS = ['content-type', 'content-length', 'content-encoding', 'content-language', 'content-location'];
+const CREDENTIAL_HEADERS = ['authorization', 'cookie', 'proxy-authorization'];
+
+export async function originGatedFetch(
+  admit: (url: URL) => Promise<void>,
+  input: RequestInfo | URL,
+  init?: RequestInit,
+  fetchImpl: typeof fetch = fetch,
+): Promise<Response> {
+  const first = new Request(input, init);
+  await admit(new URL(first.url));
+  if (first.redirect !== 'follow') return fetchImpl(first);
+
+  // Read once, up front: a Request body is a stream, and a 307 or 308 sends it again.
+  const payload = first.body === null ? null : await first.clone().arrayBuffer();
+  let current = first;
+  let res = await fetchImpl(first, { redirect: 'manual' });
+  for (let hops = 0; ; hops++) {
+    if (res.type === 'opaqueredirect') {
+      throw new TypeError(`A redirect from ${current.url} was not followed: this platform does not say where it leads. Request the destination directly.`);
+    }
+    const location = res.headers.get('location');
+    if (!REDIRECTS.has(res.status) || location === null) return res;
+    if (hops >= MAX_REDIRECTS) throw new TypeError(`Too many redirects from ${first.url}.`);
+    await res.body?.cancel();
+
+    const next = new URL(location, current.url);
+    const toGet = (res.status === 303 && current.method !== 'HEAD')
+               || ((res.status === 301 || res.status === 302) && current.method === 'POST');
+    const headers = new Headers(current.headers);
+    if (toGet) for (const h of BODY_HEADERS) headers.delete(h);
+    if (next.origin !== new URL(current.url).origin) for (const h of CREDENTIAL_HEADERS) headers.delete(h);
+
+    await admit(next);
+    current = new Request(next, {
+      method:   toGet ? 'GET' : current.method,
+      headers,
+      body:     toGet ? null : payload,
+      signal:   first.signal,
+      redirect: 'manual',
+    });
+    res = await fetchImpl(current);
+  }
+}

package/src/hooks.ts

@@ -1,12 +1,19 @@
 import type {
   Hook, HookPoint, HookRegistrar, Message, MessageContent, Session, DeferredScreen, TurnToolSource,
   ScreenContext, ContributeContext, ToolCallContext, ToolCallResult, ToolResultContext, FollowupContext,
+  ValidateContext, ToolInputError,
 } from './types.js';
 import { foldOntoUserTurn, createMessage } from './session.js';
 import { withUsageSite } from './usage-context.js';
 
 const HOOK_ERROR_CREATOR = 'matbot-hooks';
 
+// A turn tool is never registered, so `register` never stamps its plugin — and that stamp is what a
+// `ctx.gate` namespace is checked against. The hook that offered it IS stamped, so its tools take that,
+// and a `pluginName` the source wrote itself is dropped: the claim would otherwise be the plugin's own word.
+const ownedBy = (source: TurnToolSource, owner: string | undefined): TurnToolSource => async session =>
+  (await source(session)).map(({ pluginName: _, ...tool }) => owner !== undefined ? { ...tool, pluginName: owner } : tool);
+
 export class HookRegistry implements HookRegistrar {
   private readonly hooks = new Map<HookPoint, Hook[]>();
 
@@ -156,7 +163,7 @@ export class HookRegistry implements HookRegistrar {
       if (r.durable && r.durable.length) foldDurable(r.durable);
       if (r.markers && r.markers.length) appendMarkers(r.markers);
       if (r.deferred)                    deferred.push(r.deferred);
-      if (r.tools)                       tools.push(r.tools);
+      if (r.tools)                       tools.push(ownedBy(r.tools, hook.pluginName));
       if (r.abort) {
         const drained = this.drainFailureMarkers(session);
         return { session: drained.session, ephemeral, durable, markers: [...handlerMarkers, ...drained.markers], deferred, tools, abort: r.abort };
@@ -186,6 +193,24 @@ export class HookRegistry implements HookRegistrar {
     return {};
   }
 
+  // validate asks EVERY hook — no short-circuit — so neither the verdict nor the message depends on which
+  // validator happened to load first: refused if any refuses, with every refusal's errors (a field two
+  // validators both reject is said once). `[]` from any is "valid"; `undefined` from all is no opinion.
+  async runValidate(ctx: Omit<ValidateContext, 'removeHook'>): Promise<ToolInputError[] | undefined> {
+    let opinion: ToolInputError[] | undefined;
+    const seen = new Set<string>();
+    for (const hook of this.on('validate')) {
+      const r = await this.invoke(hook, ctx.signal, () => hook.handler({ ...ctx, removeHook: () => this.removeOne('validate', hook) }));
+      if (!r) continue;
+      opinion ??= [];
+      for (const e of r) {
+        const key = `${e.path}\0${e.message}`;
+        if (!seen.has(key)) { seen.add(key); opinion.push(e); }
+      }
+    }
+    return opinion;
+  }
+
   // toolresult folds the tool result through each hook — a transform pipeline (redaction, truncation);
   // a hook that returns nothing just observes (auditing). Returns the final result.
   async runToolResult(ctx: Omit<ToolResultContext, 'removeHook'>): Promise<unknown> {

package/src/index.ts

@@ -9,7 +9,7 @@
  */
 
 export type * from './types.js';
-export { CONFIRM_YES, CONFIRM_NO, optionValue, optionLabel, isTruncatedToolResult, renderToolCheck, renderToolCheckOmitted, FUNCTION_TIMEOUT } from './types.js';
+export { CONFIRM_YES, CONFIRM_NO, optionValue, optionLabel, isTruncatedToolResult, renderToolCheck, renderToolCheckOmitted, FUNCTION_TIMEOUT, importPermitted, importableByName, permitted, refused, refusalMessage } from './types.js';
 
 export * from './base64.js';
 export * from './bytes.js';
@@ -17,8 +17,11 @@ export * from './store-query.js';
 export * from './errors.js';
 export * from './vault.js';
 export * from './provider-patch.js';
+export * from './provider-models.js';
 export * from './session.js';
 export * from './invoke-tool.js';
+export * from './fetch-origin.js';
+export * from './contract-arms.js';
 
 // The plugin half of the machine: MatbotPlugin/MatbotServices/MatbotRuntime, the mount-table *consumer*
 // contract, and the API version a plugin declares. Host assembly is in ./host-machine.ts.

package/src/invoke-tool.ts

@@ -1,5 +1,5 @@
 import type { MatbotMachine, MatbotPlugin } from './plugin.js';
-import type { ToolContext, ToolEvent, ToolResultFor, ToolProxy, PromptFn, FormField, PermissionGate } from './types.js';
+import type { Tool, ToolContext, ToolEvent, ToolResultFor, ToolProxy, PromptFn, FormField, PermissionGate } from './types.js';
 import { askPermissionGate } from './permission-gate.js';
 
 /** The host's plugin hot-load ops, as both the runner and {@link invokeTool} hold them. */
@@ -33,21 +33,56 @@ export function bindPluginOps(host: PluginOps, prompt: PromptFn): Pick<ToolConte
  * stops a plugin addressing a gate it does not own — tool-name collision on `register` is already
  * resolved, so the name is not something a second plugin can quietly claim.
  *
+ * A request may name a `namespace` in place of the tool's name — for a tool whose name is chosen at RUN
+ * TIME, which is a function-tools function — and it is honoured only if `tools` resolves it to a tool
+ * stamped with the same plugin as this one. Both stamps are the host's (`register`, and the `screen` hook
+ * that offered a turn tool), so a plugin can name only a gate it already owns. Without `tools`, or for a
+ * tool known only by a bare name, there is nothing to check against, so a namespace is refused.
+ *
  * `ask` is the RAW per-turn prompt, never a stand-in that answers with a field's default: `undefined`
  * is how "no human is reachable" reaches the policy, and a substitute would make that undecidable.
  * `gate` is the registered `PermissionGate`; it is a non-optional service, but a hand-assembled
  * machine (a test, a minimal embedder) may still have none, so the asking default stands in.
  */
 export function bindGate(
-  gate:     PermissionGate | undefined,
-  toolName: string,
-  ask:      PromptFn | undefined,
+  gate:   PermissionGate | undefined,
+  tool:   string | Pick<Tool, 'name' | 'pluginName'>,
+  ask:    PromptFn | undefined,
+  tools?: { resolve(name: string): Pick<Tool, 'pluginName'> | null },
 ): Pick<ToolContext, 'gate'> {
+  const name  = typeof tool === 'string' ? tool : tool.name;
+  const owner = typeof tool === 'string' ? undefined : tool.pluginName;
   return {
-    gate: req => (gate ?? askPermissionGate).decide({ ...req, gate: `${toolName}.${req.gate}` }, ask),
+    gate: async ({ namespace, ...req }) => {
+      if (namespace !== undefined && namespace !== name
+          && (owner === undefined || tools?.resolve(namespace)?.pluginName !== owner)) {
+        throw new Error(`Tool "${name}" cannot ask permission under "${namespace}": a gate namespace must be a tool registered by the same plugin.`);
+      }
+      const qualified = { ...req, gate: `${namespace ?? name}.${req.gate}` };
+      const decision = await (gate ?? askPermissionGate).decide(qualified, ask);
+      if (!decision.allowed && decision.source === 'fallback') reportUnattended(name, qualified.gate, qualified.subject);
+      return decision;
+    },
   };
 }
 
+// When nobody can be asked (a background job, a trigger, `POST /tools/:name`), a gate refuses, and the model
+// is told so. Nobody else would be: the operation simply did not happen, in a process nobody is watching. So
+// it is logged, naming what a standing answer would have to say to allow it. At error level, because a
+// background job's process keeps only errors (its output is its result); and at most once an hour per gate
+// and subject, because a dashboard polling a gated tool would otherwise log every poll.
+const UNATTENDED_REPORT_MS = 60 * 60 * 1000;
+const unattendedReported = new Map<string, number>();
+function reportUnattended(tool: string, gate: string, subject: string): void {
+  const key = `${gate}\0${subject}`;
+  const now = Date.now();
+  if (now - (unattendedReported.get(key) ?? -Infinity) < UNATTENDED_REPORT_MS) return;
+  unattendedReported.set(key, now);
+  console.error(`[gate] Refused ${gate} for "${subject}" (tool ${tool}): nobody was there to ask. ` +
+                `To allow it unattended, give a standing answer for that gate and subject (e.g. answer "Always" ` +
+                `when it is next asked in the UI, or configure the permission policy).`);
+}
+
 /**
  * Inputs to {@link invokeTool} that a one-shot caller can't derive from the machine. A tool
  * forwarding a call to another tool should pass its own {@link ToolContext} straight through as
@@ -97,7 +132,7 @@ export function invokeTool<K extends string, const P>(
     // The raw `opts.prompt`, not the rejecting stand-in above: a gate must be able to tell "nobody is
     // here" from "a human answered", and `POST /tools/:name` reaching a privileged tool is exactly the
     // non-interactive case the request's `fallback` exists to answer.
-    ...bindGate(machine.PermissionGate, name, opts.prompt),
+    ...bindGate(machine.PermissionGate, tool, opts.prompt, machine.tools),
     ...(opts.provider      !== undefined ? { provider:   opts.provider      } : {}),
     ...(opts.turnTools     !== undefined ? { turnTools:  opts.turnTools     } : {}),
     ...(machine.workdir    !== undefined ? { workdir:    machine.workdir    } : {}),

package/src/permission-gate.ts

@@ -1,6 +1,6 @@
 import { CONFIRM_NO, CONFIRM_YES } from './types/messages.js';
 import type { FormField } from './types/messages.js';
-import type { PermissionGate } from './types/permission.js';
+import { permitted, refused, type PermissionGate } from './types/permission.js';
 
 /**
  * The bare asking `PermissionGate`: ask through the channel in scope, and answer `req.fallback` when
@@ -17,8 +17,11 @@ import type { PermissionGate } from './types/permission.js';
  */
 export const askPermissionGate: PermissionGate = {
   async decide(req, ask) {
-    if (ask === undefined) return req.fallback;
+    // Two layers, so two sources: nobody to ask is `fallback`, and anything a human answered — a no
+    // included — is `user`.
+    if (ask === undefined) return req.fallback ? permitted('fallback') : refused('fallback');
     const field: FormField = { name: 'confirm', label: req.label, type: 'confirm', default: CONFIRM_NO };
-    return (await ask(field)).trim().toLowerCase() === CONFIRM_YES;
+    const yes = (await ask(field)).trim().toLowerCase() === CONFIRM_YES;
+    return yes ? permitted('user') : refused('user');
   },
 };

package/src/provider-models.ts

@@ -0,0 +1,106 @@
+import type { ProviderAdapter, ProviderConfig } from './types.js';
+import type { Vault } from './types/vault.js';
+
+export const MODEL_LIST_TIMEOUT_MS = 8_000;
+
+export type ModelCheck =
+  | { kind: 'listed' }
+  | { kind: 'unlisted'; count: number; closest: string[] }
+  /** Nothing could be compared: no `models`, a missing key, a refusal, a timeout, an empty list. */
+  | { kind: 'unchecked'; reason: string };
+
+/**
+ * Whether `model` is one the endpoint lists. Not exact equality, because an endpoint accepts more names
+ * than it lists: Anthropic an undated alias of a dated id (`claude-sonnet-4-5` for
+ * `claude-sonnet-4-5-20250929`) and a `-latest` one, Ollama a bare name for its `:latest` tag. Gemini's
+ * lists say `models/<id>`, which either spelling of the model matches.
+ */
+export function modelListed(model: string, ids: readonly string[]): boolean {
+  const m = model.replace(/^models\//, '');
+  return ids.some(raw => {
+    const id = raw.replace(/^models\//, '');
+    return id === m || id === `${m}:latest`
+      || (id.startsWith(`${m}-`) && /^\d{8}$/.test(id.slice(m.length + 1)))
+      || (m.endsWith('-latest') && id.startsWith(m.slice(0, -'latest'.length)));
+  });
+}
+
+function editDistance(a: string, b: string): number {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(prev[j]! + 1, row[j - 1]! + 1, prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = row;
+  }
+  return prev[b.length]!;
+}
+
+/**
+ * The ids nearest `id`, best first. Shared name segments (family, size, quantisation) find a model's
+ * siblings from a partial name (`qwen3-4b`, `sonnet-4-6`); a spelling within two edits of an id comes
+ * ahead of them all, being what a typo looks like.
+ */
+export function closestIds(id: string, ids: readonly string[], n = 5): string[] {
+  const parts = (s: string): string[] => s.toLowerCase().split(/[-_.:/\s]+/).filter(Boolean);
+  const want = parts(id);
+  return ids
+    .map(candidate => {
+      const have  = parts(candidate);
+      const score = want.filter(w => have.some(h => h === w)).length * 2
+        + want.filter(w => have.some(h => h !== w && (h.includes(w) || w.includes(h)))).length;
+      return { id: candidate, score, dist: editDistance(id.toLowerCase(), candidate.toLowerCase()) };
+    })
+    .filter(x => x.score > 0 || x.dist <= 2)
+    .sort((a, b) => Number(a.dist > 2) - Number(b.dist > 2) || b.score - a.score || a.dist - b.dist || a.id.localeCompare(b.id))
+    .slice(0, n)
+    .map(x => x.id);
+}
+
+/**
+ * Asks the endpoint which models it serves and compares `config.model` against them, so a typo is caught
+ * where it is made rather than as a 404 on the next turn. Listing SENDS the profile's credential, so a
+ * caller asks only once that credential may go to `config.endpoint` — the same exposure the profile's
+ * own first turn has.
+ *
+ * Never throws, and `unchecked` is not a failure: most endpoints that cannot list (a gateway, a key not
+ * yet stored, a server with no `/models`) still serve the model fine.
+ */
+export async function checkProviderModel(
+  adapter:   Pick<ProviderAdapter, 'models'>,
+  config:    ProviderConfig,
+  vault:     Pick<Vault, 'resolve'>,
+  timeoutMs: number = MODEL_LIST_TIMEOUT_MS,
+): Promise<ModelCheck> {
+  if (adapter.models === undefined) return { kind: 'unchecked', reason: 'the adapter cannot list its models' };
+  let resolved: ProviderConfig;
+  try {
+    const credentials: Record<string, string> = {};
+    for (const [k, v] of Object.entries(config.credentials ?? {})) credentials[k] = await vault.resolve(v);
+    resolved = {
+      ...config,
+      ...(config.credentials !== undefined ? { credentials } : {}),
+      ...(config.endpoint    !== undefined ? { endpoint: await vault.resolve(config.endpoint) } : {}),
+    };
+  } catch (e) {
+    return { kind: 'unchecked', reason: e instanceof Error ? e.message : String(e) };
+  }
+
+  const signal = AbortSignal.timeout(timeoutMs);
+  let ids: readonly string[];
+  try {
+    // Raced as well as signalled: an adapter may ignore the signal, and a hung list must not hold up the tool.
+    ids = await Promise.race([
+      adapter.models(resolved, signal),
+      new Promise<never>((_, reject) => signal.addEventListener('abort', () => reject(new Error(`no answer within ${timeoutMs / 1000}s`)), { once: true })),
+    ]);
+  } catch (e) {
+    // An endpoint's error body is often pretty-printed JSON; the reason is shown on one line.
+    const why = (e instanceof Error ? e.message : String(e)).replace(/\s+/g, ' ');
+    return { kind: 'unchecked', reason: why.length > 200 ? `${why.slice(0, 200)}…` : why };
+  }
+  if (ids.length === 0) return { kind: 'unchecked', reason: 'the endpoint listed no models' };
+  if (modelListed(config.model, ids)) return { kind: 'listed' };
+  return { kind: 'unlisted', count: ids.length, closest: closestIds(config.model, ids) };
+}

package/src/provider-patch.ts

@@ -1,5 +1,11 @@
 import type { ProviderConfig } from './types.js';
 import type { ProviderPatch } from './types/builtin-tools.js';
+import type { VaultSpec } from './types/vault.js';
+
+/** The vault key a profile's own credential is stored under by default: `MATBOT_API_KEY_<PROFILE>`. */
+export function credentialKeyName(profile: string): string {
+  return `MATBOT_API_KEY_${profile.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+}
 
 /**
  * The `provider update` policy, written once so every implementer of it behaves identically — the same
@@ -12,10 +18,16 @@ import type { ProviderPatch } from './types/builtin-tools.js';
  * which is what makes a read-modify-write something a caller can actually carry out. (Contrast
  * `default_settings`, which merges per key: there the keys are matbot's own.)
  *
- * `credentials` and `module` are absent from `ProviderPatch` and therefore ride through untouched; see
- * that type for why neither belongs in an update.
+ * `credentials` and `module` are absent from `ProviderPatch`; see that type for why neither belongs in an
+ * update. `module` rides through untouched. `credentials` does too — unless the endpoint now names another
+ * ORIGIN (scheme, host and port; clearing it back to the adapter's default counts), because the credential
+ * is sent wherever the endpoint points: an endpoint change was a way to post the key to any host at all,
+ * with the update's own prompt never mentioning it. So the profile is pointed at fresh vault keys instead,
+ * none of which exists yet, and whoever means it to have a credential there supplies one out of band
+ * (`plugin store-key`). The old keys stay in the vault, since another profile may share them.
+ * {@link movedCredentialKeys} names the new ones.
  */
-export function applyProviderPatch(cur: ProviderConfig, patch: ProviderPatch): ProviderConfig {
+export function applyProviderPatch(cur: ProviderConfig, patch: ProviderPatch, vault: Pick<VaultSpec, 'hasKey'>): ProviderConfig {
   const next: ProviderConfig = { ...cur };
   // Spelled out per field rather than looped: `exactOptionalPropertyTypes` makes "assign, or delete if
   // null" a different statement for each type, and a loop only reaches them through a cast that would
@@ -24,9 +36,34 @@ export function applyProviderPatch(cur: ProviderConfig, patch: ProviderPatch): P
   if (patch.endpoint   !== undefined) { if (patch.endpoint   === null) delete next.endpoint;   else next.endpoint   = patch.endpoint;   }
   if (patch.parameters !== undefined) { if (patch.parameters === null) delete next.parameters; else next.parameters = patch.parameters; }
   if (patch.maxRounds  !== undefined) { if (patch.maxRounds  === null) delete next.maxRounds;  else next.maxRounds  = patch.maxRounds;  }
+  if (cur.credentials !== undefined && originOf(cur.endpoint) !== originOf(next.endpoint)) {
+    const base = credentialKeyName(cur.name);
+    const taken = new Set<string>();
+    const fresh: Record<string, string> = {};
+    for (const field of Object.keys(cur.credentials)) {
+      const stem = field === 'apiKey' ? base : `${base}_${field.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+      let key = stem;
+      for (let n = 2; vault.hasKey(key) || taken.has(key); n++) key = `${stem}_${n}`;
+      taken.add(key);
+      fresh[field] = `\${${key}}`;
+    }
+    next.credentials = fresh;
+  }
   return next;
 }
 
+/** The vault keys a patched profile now reads its credential from, where {@link applyProviderPatch} took
+ *  it off because the endpoint moved origin; empty when it did not. */
+export function movedCredentialKeys(cur: ProviderConfig, next: ProviderConfig): readonly string[] {
+  if (cur.credentials === next.credentials || next.credentials === undefined) return [];
+  return Object.values(next.credentials).map(v => v.slice(2, -1));
+}
+
+// An endpoint that is not a URL is compared as written: nothing can say it is the same place.
+function originOf(endpoint: string | undefined): string | undefined {
+  return endpoint !== undefined && URL.canParse(endpoint) ? new URL(endpoint).origin : endpoint;
+}
+
 /** The fields a patch actually changes, in a stable order — for a confirmation prompt or a result message. */
 export function patchedFields(patch: ProviderPatch): readonly ('model' | 'endpoint' | 'parameters' | 'maxRounds')[] {
   return (['model', 'endpoint', 'parameters', 'maxRounds'] as const).filter(f => patch[f] !== undefined);

package/src/types/builtin-tools.ts

@@ -184,7 +184,8 @@ export interface ProviderActionResult {
  * `provider list` does not report back (it projects to `hasCredentials`, and a secret must not ride the
  * transcript) — so a caller cannot read-modify-write it, and an `update` that accepted it would have to
  * guess between rewriting a `${NAME}` reference and replacing a literal. Credentials are
- * `plugin store-key`'s, which addresses the vault name directly. And **`module`**, because changing the
+ * `plugin store-key`'s, which addresses the vault name directly. (An `endpoint` moved to another origin does
+ * change them, by policy — see `applyProviderPatch`.) And **`module`**, because changing the
  * adapter re-opens every resolution question `add` answers (is it loaded, does it resolve by package
  * name, is it even a provider adapter); `remove` + `add` is the honest route for that.
  *

package/src/types/events.ts

@@ -17,6 +17,9 @@ export type TurnEvent =
   | { type: 'thinking';       delta: string;          traceId: string }
   | { type: 'system-context'; text: string;           traceId: string }
   | ({ type: 'usage';         traceId: string } & Usage)
+  // The provider's own pre-answer work (a local model downloading or loading) — its `progress`
+  // CompletionEvent, forwarded. Live-only; superseded by whatever the turn does next.
+  | { type: 'progress';       pct: number; message?: string; traceId: string }
 
   // ── tool execution ──
   | { type: 'tool:start';     callId: string; name: string; input: unknown; traceId: string }

package/src/types/hooks.ts

@@ -48,8 +48,12 @@ export interface RunConfig {
  *               ephemeral context — supersede rather than follow), and/or append durable `markers`
  *               to the committed session (LLM-invisible annotations — the second durable-write point
  *               after `screen`, safe because it too fires once per turn).
+ *   validate    the EXECUTOR, before every call through every door — the runner, `POST /tools/:name`,
+ *               `invokeTool` — and `tools.validate`. Not a runner channel, so it carries no session.
+ *               Every hook runs; the call is refused if ANY returns errors. `undefined` is no opinion,
+ *               never "valid". See {@link ValidateContext}.
  */
-export type HookPoint = 'screen' | 'contribute' | 'toolcall' | 'toolresult' | 'followup';
+export type HookPoint = 'screen' | 'contribute' | 'toolcall' | 'toolresult' | 'followup' | 'validate';
 
 export interface ScreenContext {
   session: Session;
@@ -181,6 +185,41 @@ export interface ToolResultContext {
   /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
   removeHook(): void;
 }
+/**
+ * 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;
+}
+
+/**
+ * A tool call about to execute, for a validator to judge — `json-validation` against the tool's
+ * `inputSchema`, `ts-validation` against its `ToolContract` params type. A hook rather than a service
+ * so several co-exist with no reference to each other: each is consulted, a call is refused if any
+ * refuses it, and unloading one removes only its own opinion. It was a single-valued service key, which
+ * forced the second validator to capture the first and delegate to it — so the pair depended on load
+ * order, and on each other.
+ *
+ * Return errors to refuse, `[]` to say the input is valid, or nothing for NO OPINION (no contract for
+ * this tool, or one that cannot be honestly validated). A throw is no opinion too, logged.
+ */
+export interface ValidateContext {
+  readonly tool:       string;
+  readonly parameters: unknown;
+  signal:  AbortSignal;
+  /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
+  removeHook(): void;
+}
+
 // The toolresult hook returns `{ result }` to replace the tool's result, or nothing to leave it
 // (and just observe) — a trivial single-field return, inlined in the Hook union like `contribute`'s.
 
@@ -235,4 +274,5 @@ export type Hook =
   | { on: 'contribute'; priority?: number; pluginName?: string; handler(ctx: ContributeContext): Message[]    | void | Promise<Message[]    | void> }
   | { on: 'toolcall';   priority?: number; pluginName?: string; handler(ctx: ToolCallContext):   ToolCallResult | void | Promise<ToolCallResult | void> }
   | { on: 'toolresult'; priority?: number; pluginName?: string; handler(ctx: ToolResultContext): { result: unknown } | void | Promise<{ result: unknown } | void> }
-  | { on: 'followup';   priority?: number; pluginName?: string; handler(ctx: FollowupContext):   FollowupResult | void | Promise<FollowupResult | void> };
+  | { on: 'followup';   priority?: number; pluginName?: string; handler(ctx: FollowupContext):   FollowupResult | void | Promise<FollowupResult | void> }
+  | { on: 'validate';   priority?: number; pluginName?: string; handler(ctx: ValidateContext):   ToolInputError[] | undefined | void | Promise<ToolInputError[] | undefined | void> };

package/src/types/permission.ts

@@ -26,6 +26,87 @@ export interface PermissionRequest {
   /** What this site does when nothing can be asked and nothing decides — today's non-interactive
    *  behaviour, stated once per site instead of implied at each. */
   fallback: boolean;
+  /**
+   * The standing answers this act may be remembered as, NARROWEST FIRST — what a policy offers beside
+   * "just this once", each as the subject it would store and the prose a human reads. A policy consults
+   * {@link subject} and then each of these in order, and may store whichever was chosen; absent, the
+   * only standing answer is the exact subject, labelled by the policy.
+   *
+   * The call site supplies the SUBJECTS because only it knows how its own generalise: a module specifier
+   * widens by protocol or by directory, a plugin specifier by registry scope, and neither rule is one a
+   * policy could derive without knowing the gate. Which is the point — a policy does **set membership**
+   * over strings it never parses, so no gate id is hardcoded in it and a gate this build never compiled
+   * against generalises the same way.
+   *
+   * It supplies the LABELS for the same reason it supplies {@link label}: a subject is a key, chosen to
+   * be stable and unambiguous, and keys make terrible prose. `#execute node:fs/` is a correct key and an
+   * unusable question. A policy rendering `Always allow "<subject>"` can only ever show the key, because
+   * saying it in English needs exactly the knowledge the subject was built to avoid requiring.
+   *
+   * A policy must never store a subject that was not offered here: that is what keeps this from widening
+   * the memory semantics of every other gate.
+   */
+  standing?: readonly { readonly subject: string; readonly label: string }[];
+}
+
+/**
+ * Which test in the cascade produced an answer — not *who* answered, but which of the layers a policy
+ * consults got there first: a human at the prompt, a standing answer out of configuration, or the call
+ * site's own `fallback` because nothing else could decide. matbot's own three are named here; the type
+ * stays **open**, because a replacement policy has layers of its own (`'user-stored-preference'`, an
+ * org directory, a rule table) and a closed union would mean a policy could not report truthfully
+ * without a plugin-api change. Treat an unrecognised source exactly as the prose helper does: report it.
+ */
+export type PermissionSource =
+  /** A human was asked and answered. */
+  | 'user'
+  /** A standing answer in force — an installation's configured floor or a remembered one; the settings
+   *  layering that holds them makes the two indistinguishable by construction, so they share a source. */
+  | 'configuration'
+  /** Nothing decided and nobody was reachable: {@link PermissionRequest.fallback} stands. */
+  | 'fallback'
+  | (string & {});
+
+/**
+ * The answer: whether the act may proceed, and which layer said so.
+ *
+ * `source` exists for the REPORT rather than the control flow — a refused tool call that says only
+ * "Cancelled." reads to a model as a malfunction, so it hunts for a workaround or a bug to fix. A
+ * denial that names its origin is a decision it can relay instead (see {@link refusalMessage}).
+ *
+ * Nothing branches on `source`, and a gate must not be given one to branch on: the outcome is
+ * `allowed`, and a call site that treated `'fallback'` differently from a human's "no" would be
+ * reintroducing the policy the gate exists to hold.
+ */
+export interface PermissionDecision {
+  allowed: boolean;
+  source:  PermissionSource;
+}
+
+/** The allow/deny pair, spelled once. */
+export const permitted = (source: PermissionSource): PermissionDecision => ({ allowed: true,  source });
+export const refused   = (source: PermissionSource): PermissionDecision => ({ allowed: false, source });
+
+/**
+ * What a refused call site tells the caller — including the model, which is the reader this exists for.
+ * A bare "Cancelled." is indistinguishable from a fault, and a model that reads a decision as a fault
+ * goes looking for the fault: it retries under another spelling, probes for a bug, or reaches for a
+ * route around the gate. So the prose names the layer that refused and says, for the two sources where
+ * it is true, that there is nothing here to work around.
+ *
+ * `act` names the operation in the caller's own words when it has them ("Install plugin \"@x/foo\"");
+ * the sentence stands without it. An unrecognised source is reported as itself rather than guessed at —
+ * a policy's own layer name is prose a human chose, and saying it is more use than "refused".
+ */
+export function refusalMessage(decision: PermissionDecision, act?: string): string {
+  const what = act !== undefined ? `${act}: cancelled` : 'Cancelled';
+  const stop = 'This is a decision, not a fault — do not retry it or look for a way around it.';
+  switch (decision.source) {
+    case 'user':          return `${what} — the user declined. ${stop}`;
+    case 'configuration': return `${what} — the installation's permission policy does not allow it. ${stop}`;
+    case 'fallback':      return `${what} — permission was required and nobody could be asked, so the non-interactive default applied. Nothing is broken; it needs a user present, or a standing answer in the installation's policy.`;
+    default:              return `${what} — refused by the permission policy (${decision.source}). ${stop}`;
+  }
 }
 
 /**
@@ -39,8 +120,8 @@ export interface PermissionRequest {
  * means **no human is reachable**; a policy that wants to behave differently then simply checks it.
  *
  * A gate that wants "my rules, else the previous behaviour" captures the gate it displaces and
- * delegates to it (the `ToolCallValidator` idiom), so a pair composes in either load order.
+ * delegates to it, so a pair composes in either load order.
  */
 export interface PermissionGate {
-  decide(req: PermissionRequest, ask: PromptFn | undefined): Promise<boolean>;
+  decide(req: PermissionRequest, ask: PromptFn | undefined): Promise<PermissionDecision>;
 }

package/src/types/provider.ts

@@ -217,6 +217,14 @@ export type CompletionEvent =
    * a larger budget) is a `followup` hook's business, not the harness's.
    */
   | { type: 'truncated';           reason: 'max-tokens' | 'stream-end'; raw?: string }
+  /**
+   * Progress on work the provider must finish before it can answer at all — an on-device model
+   * downloading or loading. `pct` is 0–100, as a tool's `progress` event. Live-only: forwarded as the
+   * turn's `progress` event and never persisted, being a fact about the moment rather than the reply.
+   * Not a substitute for `thinking`, which is the model's own output; putting a status line there made
+   * it read as something the model thought.
+   */
+  | { type: 'progress';            pct: number; message?: string }
   | ({ type: 'usage' } & Usage)
   | { type: 'done' };
 
@@ -256,4 +264,11 @@ export interface ProviderAdapter {
     signal:   AbortSignal
   ): AsyncIterable<CompletionEvent>;
   health(): Promise<HealthStatus>;
+  /**
+   * The model ids this adapter can run under `config`, for a person choosing one (the setup wizards) and
+   * for `checkProviderModel`, which catches a mistyped one. Absent where the adapter cannot enumerate
+   * them, and a rejection means the same: the caller asks for a model name instead, or accepts it
+   * unchecked. `config` carries resolved credentials, which a remote list is sent with.
+   */
+  models?(config: ProviderConfig, signal?: AbortSignal): Promise<string[]>;
 }

package/src/types/registries.ts

@@ -1,4 +1,4 @@
-import type { Hook } from './hooks.js';
+import type { Hook, ToolInputError } from './hooks.js';
 import type { Session } from './messages.js';
 import type { ProviderConfig } from './provider.js';
 import type { Tool } from './tools.js';
@@ -34,6 +34,11 @@ export interface ToolRegistry {
   resolve(name: string): Tool | null;
   list(): readonly Tool[];
   removeByPlugin(pluginName: string): void;
+  /** Judge `parameters` for the tool `name` exactly as its executor will before running it: every
+   *  `validate` hook. Errors refuse, `[]` is valid, `undefined` means nothing had an opinion. For a
+   *  caller that stores a call to make later (a trigger's `invoke`), so it can be refused while its
+   *  author is present. Optional: a registry stood up by hand need not validate. */
+  validate?(name: string, parameters: unknown): Promise<ToolInputError[] | undefined>;
 }
 
 /** What the runner tells a {@link ToolPresenter} about the call it's about to make. */

package/src/types/tools.ts

@@ -2,7 +2,7 @@ import type { FileHandle, FileStore } from './files.js';
 import type { FormField, MessageContent, Session } from './messages.js';
 import type { MatbotPlugin } from '../plugin.js';
 import type { JSONSchema } from './primitives.js';
-import type { PermissionRequest } from './permission.js';
+import type { PermissionDecision, PermissionRequest } from './permission.js';
 import type { Vault } from './vault.js';
 import type { SessionAppender } from './session-append.js';
 
@@ -230,15 +230,25 @@ export interface ToolContext {
   prompt:      PromptFn;
   /**
    * Ask permission for a privileged operation — install a plugin, remove a provider profile, add an
-   * MCP server. Resolves `true` to proceed. The call site declares *that* acceptance is needed; the
-   * registered {@link PermissionGate} decides *how* it is obtained (the default asks the user).
+   * MCP server. The call site declares *that* acceptance is needed; the registered
+   * {@link PermissionGate} decides *how* it is obtained (the default asks the user).
    *
    * `gate` is the SUFFIX (`'add'`): the host qualifies it with this tool's registered name, so one
    * policy covers both runtimes' implementations of a tool (node's `plugin` and the browser's) and a
    * plugin cannot address a gate it does not own. `fallback` is what happens when no human is
    * reachable and no policy decides.
+   *
+   * `namespace` replaces the tool's name as the qualifier, for a tool whose NAME is chosen at run time
+   * (a `function-tools` function asks under `tool_function`): qualified by a model-chosen name, every
+   * definition would mint its own gate id, so a standing answer filed under one could never cover
+   * another. It must name a tool registered by the SAME plugin as this one — the host checks, against
+   * the plugin it stamped on both — so it widens nothing: a plugin still cannot address another's gate.
+   *
+   * The outcome is `allowed`; `source` names the layer that answered, for the refusal to REPORT (see
+   * {@link refusalMessage}) — never to branch on. NOTE the shape: this resolves to an object, so
+   * `if (!await ctx.gate(…))` is always false. Test `.allowed`.
    */
-  gate(req: PermissionRequest): Promise<boolean>;
+  gate(req: PermissionRequest & { namespace?: string }): Promise<PermissionDecision>;
   /** Hot-load a plugin by specifier without restarting the process. Returns the loaded plugin.
    *  `refresh` (default false) forces a remote (github/http) plugin to be re-downloaded rather than
    *  re-loaded from its `.plugins/` cache — pass true to pick up changed upstream source. */
@@ -304,6 +314,12 @@ export interface Tool<R = unknown> {
    *  its contract as a `ToolContracts` augmentation instead and omits this. Foreign tools (e.g. MCP proxies)
    *  that have neither fall back to the loose `inputSchema`. */
   toolContract?: string;
+  /** Declarations (`interface`, `type`) that {@link toolContract} names and that exist nowhere else — a
+   *  function package's own types, which its exports' contracts refer to by name. In scope for this tool's
+   *  contract only: a consumer declares them in a namespace of their own beside the contract
+   *  (`contractArms`), so two tools' types of one name never meet. Absent ⇒ the contract names only
+   *  plugin-api types and TypeScript's own. */
+  toolContractTypes?: string;
   executor:     ToolExecutor<R>;
   pluginName?:  string;
 }

package/src/types/typescript.ts

@@ -18,25 +18,194 @@ export interface TypeScriptStripper {
 }
 
 /**
- * Optional, host-supplied: compiles already-stripped JavaScript into an async function whose SYNCHRONOUS
- * execution is bounded. Model-authored code (a `tool_function` body) runs on the one event loop every
- * session, frontend and schedule shares, so a loop that never awaits freezes all of them — and nothing
- * in-process can stop it, an abort signal included, since stopping needs the loop to yield. Only the
- * stretches between awaits are bounded: a body waiting on a slow tool call is not doing work.
+ * Optional, host-supplied: turns model-authored TypeScript into something runnable, and is the
+ * environment it runs in. How it gets there — strip and compile, transform, interpret — is its own
+ * business; the rest of this interface is one value it is GIVEN per call, and two facts about its
+ * environment that nothing else can know.
  *
- * Absent ⇒ a consumer compiles with `new AsyncFunction` and runs unbounded, which is all a platform with
- * no way to interrupt synchronous code (the browser) can do. An embedder may register its own.
+ * Its first job is bounding a body's SYNCHRONOUS execution. Model-authored code runs on the one event
+ * loop every session, frontend and schedule shares, so a loop that never awaits freezes all of them —
+ * and nothing in-process can stop it, an abort signal included, since stopping needs the loop to yield.
+ * Only the stretches between awaits are bounded: a body waiting on a slow tool call is not doing work.
+ *
+ * Absent ⇒ a consumer compiles the code itself however it can, which drops every part of this at once
+ * and not just the bound: nothing is withheld from the body, `import()` reaches whatever the platform
+ * natively resolves rather than the loader it was passed, and {@link FunctionRunSettings.permittedImports} has no carrier and
+ * so restricts nothing. That is all a platform with no way to interrupt synchronous code
+ * and no module hook (the browser) can do, and it is the browser's permanent state rather than a
+ * misconfiguration. It is node's DEFAULT too: no host seeds a runner, so until an installation loads one
+ * (`@matatbread/matbot-function-runner-node`, or its own) a body runs in the host's process with full
+ * access — unbounded, with every global, and with `import()` reaching node's own loader unasked. Nothing
+ * warns about that at boot, because it is the configured behaviour rather than a fault.
+ */
+/**
+ * One invocation's reading of a {@link FunctionRunner}'s configuration ({@link FunctionRunner.settings}).
+ * A runner may carry its own fields beside these — the node runner's time bound — and reads them back
+ * off the value handed to {@link FunctionRunner.compile}'s callable; a consumer reads only what is
+ * declared here and otherwise passes the value through untouched.
  */
+export interface FunctionRunSettings {
+  /**
+   * An optional RESTRICTION on what a body may import, as exact specifiers or prefixes (`['node:']`).
+   *
+   * **Absent ⇒ no restriction**, which is the default: every specifier may be asked about, and the
+   * per-import {@link PermissionGate} decision is the control. That way round because a gate that is
+   * never reached is not a gate — an allow-list defaulting to empty refuses before anyone can be asked,
+   * which is precisely the behaviour a permission prompt exists to replace. An empty array means the
+   * opposite of absent: nothing may be imported, and nobody is asked.
+   *
+   * What it is FOR is the case a prompt cannot express: a deployment that wants a module forbidden
+   * outright, with no human able to allow it. A policy has no stored "always deny" — a refusal is a
+   * decision about one act — so this is the only way to say "never", and it is installation authoring.
+   *
+   * It comes from the runner because the runner IS the execution environment, and because two consumers
+   * need one answer: the gate in front of the import, and the type index that declares the reachable set
+   * to the author. Each reads it once per invocation, through {@link FunctionRunner.settings}.
+   *
+   * An entry matches a specifier exactly, or as a prefix ending at a BOUNDARY — its own trailing `/` or
+   * `:`, or the next `/` in the specifier. So `node:` admits every builtin and `node:fs` admits
+   * `node:fs/promises`, while `lodash` does NOT admit `lodashhack`: a bare string prefix would let an
+   * entry admit a sibling whose name merely begins the same way, which is the whole value of naming one.
+   * It bounds what may be ASKED — it grants nothing by itself — and only ever among what
+   * {@link importableByName} admits, so an entry naming a path or a URL admits nothing.
+   */
+  readonly permittedImports?: readonly string[];
+}
+
+/** What one call of a compiled function is handed besides its own arguments. */
+export interface FunctionCall {
+  /** The consumer's gated loader for this invocation; see {@link FunctionRunner.compile}. */
+  readonly importModule: (spec: string, options?: ImportCallOptions) => Promise<unknown>;
+  /** What {@link FunctionRunner.settings} returned at the start of this invocation. Absent ⇒ the runner
+   *  applies its own defaults, as it must for a value it did not produce. */
+  readonly settings?: FunctionRunSettings;
+  /** What a body's own `fetch` and `WebSocket` should be: the consumer's, which put each origin they reach
+   *  to a {@link PermissionGate}, as `importModule` puts each module. A runner binds them in place of the
+   *  globals; absent, or a runner that does not, leaves the body the platform's. Their types are the
+   *  platform's own, so nothing a body is checked against changes. */
+  readonly fetch?: typeof fetch;
+  readonly WebSocket?: typeof WebSocket;
+}
+
 export interface FunctionRunner {
-  /** Compile `body` as the body of an async function taking `params`. Throws on a syntax error. A call
-   *  stopped at the limit rejects with an error whose `code` is {@link FUNCTION_TIMEOUT}. */
-  compile(params: readonly string[], body: string): (...args: unknown[]) => Promise<unknown>;
+  /**
+   * Compile `source` — a TypeScript expression evaluating to an async function — and return something
+   * that calls it. Throws on a syntax error. A call stopped at the limit rejects with an error whose
+   * `code` is {@link FUNCTION_TIMEOUT}.
+   *
+   * An EXPRESSION, complete with its own parameter list, rather than a body plus names to bind: a body is
+   * not valid alone — `return` at its top level is a syntax error — so every runner would have to wrap it
+   * before it could strip or parse it.
+   *
+   * TypeScript, not erased JavaScript, because erasing is part of running it.
+   *
+   * `call` is this one invocation's: the loader a body's `import(…)` should reach (the consumer's gated
+   * loader, which closes over that invocation) and the {@link FunctionRunSettings} the consumer read for
+   * it. A runner that rewrites `import(…)` resolves it to `importModule`; one that does not simply ignores
+   * it. How it gets into scope — a parameter the runner names itself, a closure — is internal, and nothing
+   * outside declares or sees it: the type-check runs on the source as the author wrote it, before any of
+   * this.
+   */
+  compile(source: string): (call: FunctionCall, ...args: unknown[]) => Promise<unknown>;
+  /**
+   * Read this runner's configuration for ONE invocation — a run, or a check — which the caller then holds
+   * for that invocation's whole extent and hands back on {@link FunctionCall.settings}.
+   *
+   * Read per invocation rather than once at boot, because whose settings they are is not something a
+   * runner can know: the settings store may be partitioned by principal or by nothing, which is the
+   * storage implementation's business. A boot read answered for the boot principal for ever after, and a
+   * per-principal cache would assume a partitioning nobody promised. An invocation, by contrast, has one
+   * principal throughout, so one read at its start is correct by construction, and every part of it — the
+   * gate, the type-check, the time bound — sees the same answer.
+   *
+   * Absent ⇒ nothing to configure: no restriction.
+   */
+  settings?(): Promise<FunctionRunSettings>;
+  /**
+   * Turn a granted specifier into a module — a builtin or an installed package, never a path or a URL
+   * (see {@link importableByName}). The runner's rather than a plain `import()` at the call site because
+   * where a package resolves FROM is the runner's business: node's resolves from the runner's own module.
+   * `options` is the import's second argument, passed through as written, so an import attribute
+   * (`{ with: { type: 'json' } }`) reaches the loader. Absent ⇒ the caller falls back to a dynamic import.
+   *
+   * It is reached only after the gate has allowed this specifier for this function, and it performs no
+   * check of its own — a capability, not a policy.
+   */
+  import?(spec: string, options?: ImportCallOptions): Promise<unknown>;
+  /**
+   * The spelling `spec` loads as, where the runner's platform has two for one module: node loads `os` as
+   * `node:os` whatever is installed, so asking about `os` and `node:os` separately asked twice about one
+   * module, and described a builtin as a package that "runs with matbot's full access" along with
+   * everything it imports. A consumer canonicalises BEFORE deciding, so one grant, one restriction and
+   * one label cover both spellings. Only a runner can answer, because the set of builtins is its
+   * platform's — `test` is a package to node, `node:test` the builtin.
+   *
+   * Absent ⇒ `spec` is taken as written.
+   */
+  canonicalImport?(spec: string): string;
+  /**
+   * Identifiers a body does NOT have — anything this runner withholds, shadows or never binds (node's
+   * withholds `process`, `globalThis`, `global`, `eval` and `Function`, and names the phantom
+   * `require`/`module`/`__dirname` too, which never existed in a bare function expression but whose node
+   * types would otherwise make one typecheck and then fail at the first call).
+   *
+   * Stated here because only the runner knows, and a checker grading a body must REJECT them: a name
+   * shadowed but not rejected typechecks and fails at the first call, which is the one failure a check
+   * gate exists to prevent. The second consumer of a list is why it is not kept privately, exactly as
+   * for {@link FunctionRunSettings.permittedImports}.
+   *
+   * Absent ⇒ nothing is claimed, not that nothing is withheld.
+   */
+  readonly withheldGlobals?: readonly string[];
 }
 
 /** The `code` on the error a {@link FunctionRunner} rejects with when it stops a run at its limit, so a
  *  consumer can tell a stopped runaway from an ordinary failure without matching message text. */
 export const FUNCTION_TIMEOUT = 'FUNCTION_TIMEOUT';
 
+
+/**
+ * Whether `spec` names a module the way a `tool_function` body may import one: a node builtin (`node:fs`)
+ * or an installed package (`lodash`, `@scope/pkg/sub`). Never a path, a URL or any other scheme.
+ *
+ * Downloading or placing code is what a plugin install is for. It is reviewed and versioned, and it has
+ * its own gate. A body is too lightweight a thing to recommend it from. Paths are refused for a second
+ * reason: they defeat {@link importPermitted}, which matches strings, so `./lib/../../x` "starts with"
+ * `./lib/` and resolves outside it. A `.` or `..` segment in a package subpath is refused for the same
+ * reason, because a package with no `exports` map resolves it as a path.
+ *
+ * The characters are an ALLOWLIST, because the resolver is a URL parser and decides what a dot segment is
+ * by its own rules: `%2e%2e`, `.%2E` and `.<tab>.` are all `..` to it (the parser strips tabs and
+ * newlines), and each one escaped the package from `typescript/…/package.json`. Enumerating encodings
+ * is a race against that spec; refusing `%`, whitespace and anything outside a package name's alphabet
+ * is not. No npm name contains any of them, and a subpath that needs one is not worth the hole.
+ *
+ * Shared because three places must agree: the gate in `function-tools`, the runner, and the type-check.
+ */
+export const importableByName = (spec: string): boolean =>
+  spec !== ''
+  && !/[^\w@.~+!$&'()*,;=:/-]/.test(spec)
+  && !/^[./]/.test(spec)
+  && (spec.startsWith('node:') || !/^[a-z][a-z0-9+.-]*:/i.test(spec))
+  && !spec.split('/').some(seg => seg === '.' || seg === '..');
+
+/**
+ * Whether {@link FunctionRunSettings.permittedImports} admits `spec` — the boundary rule that interface
+ * documents, as a function, because two packages read the same list and must agree: `function-tools`
+ * decides whether to ask about an import, and `tool-types` decides which modules to TYPE. They had a copy
+ * each, and they drifted exactly where it hurts — `node:fs` admitted `node:fs/promises` at the gate while
+ * the checker declared only `node:fs`, so a permitted subpath failed the check and needed `noTypeCheck`
+ * to run at all.
+ *
+ * A prefix must end at a boundary: its own trailing `/` or `:`, or the next `/` in the specifier. A bare
+ * `startsWith` let an entry admit a sibling whose name merely begins the same way, which is the whole
+ * value of naming one. A specifier {@link importableByName} refuses is never admitted, whatever the list
+ * says, since string matching cannot see what `..` does.
+ */
+export const importPermitted = (permits: readonly string[], spec: string): boolean =>
+  importableByName(spec) && permits.some(p => spec === p
+    || (p.endsWith('/') || p.endsWith(':') ? spec.startsWith(p) : spec.startsWith(`${p}/`)));
+
 /**
  * One finding from {@link ToolTypeIndex.check} — the record, not a rendering of it.
  *
@@ -47,7 +216,8 @@ export const FUNCTION_TIMEOUT = 'FUNCTION_TIMEOUT';
  * flattened `string[]` made every consumer do.
  */
 export interface ToolCheckDiagnostic {
-  /** The rule's one name, in every renderer: `TS2339`, or `CAST-GATE` for a structural cast-gate finding. */
+  /** The rule's one name, in every renderer: `TS2339`, or a structural rule's own name — `CAST-GATE`,
+   *  `ENV-GATE` for a global the runner does not define. */
   label:    string;
   /** The numeric code. Cast-gate findings use a private 9000x range — read {@link syn}, not the number. */
   code:     number;
@@ -91,6 +261,13 @@ export interface ToolCheckReport {
   diagnostics:  ToolCheckDiagnostic[];
   /** Present only when the cap hid some, tallied by the same `label` the detailed ones carry. */
   omitted?:     { count: number; byLabel: Record<string, number> };
+  /**
+   * The {@link ToolTypeIndex.environment} fingerprint this verdict was reached under — what the check
+   * depended on besides the snippet and the live tool types. A caller that PERSISTS a verdict stores it
+   * beside the source and compares it (string equality, never parsed) against the index's current one,
+   * so "this passed" can say which environment it passed in. Absent when nothing was checked.
+   */
+  environment?: string;
 }
 
 /**
@@ -150,4 +327,23 @@ export interface ToolTypeIndex {
    *  outgoing tool descriptions at the turn's dispatch edge. A tool with only a loose `inputSchema` (no
    *  contract) is absent. */
   wireContracts(): Promise<Record<string, { params: string; result: string }>>;
+  /**
+   * A fingerprint of everything a {@link check} verdict depends on APART from the snippet and the live
+   * tool types — in practice the `FunctionRunner` that will run the code: whether there is one, what it
+   * permits a body to import, and which globals it does not bind. Opaque: a consumer compares it for
+   * equality and never parses it.
+   *
+   * It exists because a stored verdict is a claim about an environment, and the environment can be
+   * swapped out from under it — unload the runner plugin, or narrow its permitted imports, and a body
+   * that passed stays marked as having passed while its `import(…)` is no longer gated, or no longer
+   * allowed at all. The tool types are deliberately NOT in it: those are live and `check` is how a
+   * caller re-verifies against them, whereas this names the thing a re-check cannot be prompted by.
+   *
+   * Stable across restarts, so never identity-derived, and derived at the point of use like everything
+   * else read off the runner — there is nothing here to invalidate or subscribe to.
+   *
+   * Optional, because an index written before it existed must degrade rather than throw: a caller with
+   * no fingerprint stores none, and compares nothing.
+   */
+  environment?(): Promise<string>;
 }

package/src/types/vault.ts

@@ -1,13 +1,17 @@
 // ── Vault ─────────────────────────────────────────────────────────────────────
 
 /**
- * The primitives a vault backend must implement. Resolution, redaction, and the three
- * low-level store operations the smart `createSecret` policy composes. A backend implements
- * `Vault` (which is `VaultSpec` plus that policy); plugins are handed a `Vault`.
+ * The primitives a vault backend must implement. Redaction, and the low-level store operations the
+ * `resolve` and `createSecret` policies compose. A backend implements `Vault` (which is `VaultSpec`
+ * plus those policies); plugins are handed a `Vault`.
  */
 export interface VaultSpec {
-  /** Resolve ${NAME} placeholders by looking up the named value; throws MissingSecretError for any miss. */
-  resolve(ref: string): Promise<string>;
+  /**
+   * The value stored under exactly `name`, or `undefined`. The literal read, as `writeSecret` is the
+   * literal write: a name is a name, with no placeholder syntax, so a caller holding one never encodes
+   * it into a `${NAME}` for `resolve` to parse back out — `A}${B` is simply absent, not two lookups.
+   */
+  readSecret(name: string): Promise<string | undefined>;
   scrub(text: string): string;
   /**
    * Store `value` under exactly `name`, overwriting. The literal write; no reference/dedup logic.
@@ -37,6 +41,11 @@ export interface VaultSpec {
 }
 
 export interface Vault extends VaultSpec {
+  /**
+   * Expand every `${NAME}` placeholder in `ref` with its stored value; throws `MissingSecretError`
+   * naming every miss. A backend's is `applyResolve(this, ref)`.
+   */
+  resolve(ref: string): Promise<string>;
   /**
    * Store a secret coming (often) from a user via the LLM, where we cannot tell a real value
    * from a key name they typed by mistake. Returns the key name callers MUST reference — not

package/src/vault.ts

@@ -1,5 +1,21 @@
 import type { VaultSpec } from './types.js';
-import { invalidSecretNameError } from './errors.js';
+import { invalidSecretNameError, missingSecretError } from './errors.js';
+
+const PLACEHOLDER = /\$\{([^}]+)\}/g;
+
+/**
+ * The `resolve` policy, written once over `readSecret` so the placeholder grammar has one home — it was
+ * a regex and a replace loop copied into every backend, so a backend's idea of `${NAME}` could drift
+ * from the rule below that says which names can be stored. A backend's `resolve` is just
+ * `applyResolve(this, ref)`.
+ */
+export async function applyResolve(spec: VaultSpec, ref: string): Promise<string> {
+  const names  = [...new Set(Array.from(ref.matchAll(PLACEHOLDER), m => m[1] ?? ''))];
+  const values = new Map(await Promise.all(names.map(async n => [n, await spec.readSecret(n)] as const)));
+  const missing = names.filter(n => values.get(n) === undefined);
+  if (missing.length > 0) throw missingSecretError(missing);
+  return ref.replace(PLACEHOLDER, (_, name: string) => values.get(name) ?? '');
+}
 
 /**
  * The rule every vault shares, whatever else it adds: a secret is only reachable through a