@matatbread/matbot-plugin-api 0.4.19 → 0.4.20

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.19",
+  "version": "0.4.20",
   "engines": {
     "node": ">=24.0.0"
   },

package/src/hooks.ts

@@ -7,6 +7,12 @@ 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 +162,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 };

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';

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,18 +33,33 @@ 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.`);
+      }
+      return (gate ?? askPermissionGate).decide({ ...req, gate: `${namespace ?? name}.${req.gate}` }, ask);
+    },
   };
 }
 
@@ -97,7 +112,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/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/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}`;
+  }
 }
 
 /**
@@ -42,5 +123,5 @@ export interface PermissionRequest {
  * delegates to it (the `ToolCallValidator` idiom), 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' };
 

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. */

package/src/types/typescript.ts

@@ -18,25 +18,188 @@ 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;
+}
+
 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`, `Buffer`, `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 +210,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 +255,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 +321,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