bare-agent 0.52.0 → 0.53.0

package/bareagent.context.md

@@ -72,7 +72,7 @@ Eight entry points:
 | Read/write files, list directories, run shell commands, grep | createShellTools (shell_read/grep/**write**/**edit**/run/exec) + Loop({ policy }) — gate `shell_write`/`shell_edit` via `fs.writeScope` with an actionTranslator |
 | Change one span of a big file without re-emitting the whole thing | `shell_edit({path, oldText, newText})` — anchored exact-once replace; the surgical alternative to whole-file `shell_write` (BA-13). Gate it as `{type:'edit'}` |
 | Auto-discover MCP servers from IDE configs | createMCPBridge |
-| Gate MCP tools with allow/deny lists | createMCPBridge + `.mcp-bridge.json` |
+| Gate MCP tools with allow/deny lists | createMCPBridge + `.mcp-bridge.json` (or per-run `{ allow }`) |
 | Gate every tool call with one policy hook | `wireGate(gate).policy` → `Loop({ policy })` |
 | Route policy decisions per user / tenant / chat | `wireGate(gate).policy` + `loop.run(msgs, tools, { ctx })` (ctx routes to bareguard's check via `_ctx`) |
 | Cap total USD spend per run | `new Gate({ budget: { maxCostUsd: 0.50 } })` |
@@ -431,7 +431,10 @@ every command it is about to spawn — `confirmServer` is how you actually *gate
 server that never answers can't hang the bridge or the loop. `opts.timeout`
 (default 15 s) bounds the handshake (`initialize` + `tools/list`);
 `opts.callTimeout` (default 120 s, `0` disables) bounds each `tools/call`. A
-timed-out tool call rejects with a `timed out after Nms` `ToolError` rather
+timed-out tool call rejects with a labelled `ToolError`
+(`MCP server "s" tool "t" timed out after Nms`, `context: { timeout: true, server, tool, timeoutMs, stderr }` —
+stderr is in `context`, not the message; `wireGate`'s `onToolResult` forwards only the
+non-stderr label fields to the audit row as an allow-listed `errorContext`) rather
 than blocking forever; a server that breaks its stdin pipe surfaces as a
 failed connection, never an uncaught `EPIPE` crash.
 
@@ -477,6 +480,8 @@ if (result.error?.startsWith('halt:')) {
 
 **Why four pieces (`policy` + `onLlmResult` + `onToolResult` + `filterTools`).** `policy` runs `gate.check` *before* every tool call. `onLlmResult` fires after every successful `provider.generate` — without it, `budget.maxCostUsd` never sees LLM cost and is silently undercounted for token-heavy / tool-light workloads (every chatbot). It also fires for the out-of-band `ctx.summarize` call (R-C6) tagged `kind:'summarize'`; main-loop rounds carry `kind:'turn'` — so summary-window tokens count against the budget too, and a consumer can tell the two apart. `onToolResult` fires after every `tool.execute` and carries the per-run `ctx` opaque blob into `gate.record` so per-principal accounting works. `filterTools` is a `gate.allows` pre-filter — denied tools are dropped from the catalog the LLM ever sees, no `gate.check` round-trip per call.
 
+`onToolResult` on a tool ERROR records `{error, durationMs}` plus an allow-listed `errorContext` copied from `error.context` — `timeout`/`denied` (boolean), `server`/`tool` (string, ≤200 chars), `timeoutMs` (finite number); wrong-typed values are dropped and `stderr`/everything else is never forwarded (the gate writes the record verbatim into the audit row). The key is absent when no allowed field is present.
+
 Halt-severity decisions exit the loop cleanly via a typed `HaltError` — full mechanics (sealed `msgs`, `halt:<rule>` error token, `loop:done{halted:true}` event, `throwOnError:true` interaction, `halt:unknown` coalesce) are in the **Halt decisions throw `HaltError`** paragraph below. Short version: check `result.error?.startsWith('halt:')` after the run.
 
 **A bound that fires PRESERVES the model's work (BA-5, v0.27+).** Every terminating path — governance halt, the deny-spin short-circuit, a provider error under `throwOnError:false`, `loop.stop()`, and the internal hard round limit — returns the **last non-empty assistant text** in `result.text` instead of `''`. If you drive bare-agent from an outer retry loop (`while not-done and under-cap: run the worker`), a bound firing is **normal termination**, not an exception, and that text is your only channel from attempt N to attempt N+1 — before this, a bounded attempt taught its successor nothing. Two rules: **`error` is the sole success signal** (a non-empty `text` never means the run converged — always branch on `error`), and `text` is `''` when the model genuinely produced none (no placeholder is invented, so you can trust emptiness). Under `recurse` this is what finally populates `best` on an incomplete node. Relatedly, **`loop.stop()` now returns `error: null`** — a deliberate stop is not a fault; it previously fell through to the hard-round-limit return and reported that safety warning as its error, indistinguishable from a runaway.
@@ -1508,7 +1513,7 @@ const { createMCPBridge } = require('bare-agent/mcp');
 const provider = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o-mini' });
 
 const bridge = await createMCPBridge();
-// bridge = { tools, servers, denied, systemContext, errors, close }
+// bridge = { tools, servers, denied, systemContext, errors, close }  (+ missing when `allow` is given)
 
 const loop = new Loop({
   provider,
@@ -1528,6 +1533,8 @@ try {
 
 **Governance via `.mcp-bridge.json`.** On first run, the bridge writes `.mcp-bridge.json` in the cwd listing every discovered server and tool with permission `"allow"`. Edit any entry to `"deny"` and the tool is dropped from the next run's tool array; the LLM sees it listed in `systemContext` as restricted, with instructions not to retry it. Re-discovery happens automatically after TTL expiry (default `24h`, settable via `ttl` field in the file).
 
+**Signed per-run allow-list (`allow`).** `createMCPBridge({ allow: { server: ['raw_tool_name', ...] } })` skips `.mcp-bridge.json` entirely (never read or written — no cache, no TTL; `bridgePath`/`refresh`/`servers` ignored), takes server definitions only from `discoverServers(configPaths)`, spawns only the named servers (still `confirmServer`-vetted), connects once and exposes signed ∩ listed. Everything else is absent from `tools`, the `metaTools` catalog and `systemContext` (no "Restricted tools" text, `denied: []`), nothing goes to stdout. The return gains `missing: [{server, tool}]` (signed tools the server did not list, or whose server was not found/failed/rejected) — never a throw. `mcp_invoke` of a listed-but-unsigned name throws `ToolError` with `context.denied === true`. Bad `allow` shape (including an empty tool list) throws `ValidationError`. In every mode (not only `allow`), a server whose `tools/list` reply has no `tools` array (e.g. `{}`) now fails its connect — it lands in `errors`, its child is killed — where it used to read as a working empty server.
+
 ```json
 {
   "discovered": "2026-04-13T12:00:00.000Z",
@@ -1596,6 +1603,8 @@ MCP tools arrive with the server name prepended (`beeperbox_send_message`, not `
 | `servers` | all discovered | Limit to a subset by name |
 | `timeout` | `15000` | Per-server init timeout in ms |
 | `refresh` | `false` | Force re-discovery regardless of TTL |
+| `allow` | none | Signed per-run allow-list `{ server: [rawToolNames] }` — in-memory, no `.mcp-bridge.json`; see "Signed per-run allow-list" above |
+| `callTimeout` | `120000` | Per-`tools/call` timeout in ms (`0` disables) |
 
 ### Recipe 10: beeperbox — multi-messenger reach via MCP bridge
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "files": [
     "index.js",
     "index.d.ts",

package/primitives.json

@@ -33,7 +33,7 @@
       "category": "mcp",
       "when": "you want the two bulk MCP meta-tools (mcp_discover, mcp_invoke) instead of exposing every discovered tool individually — one gate-check per invocation",
       "import": "import { buildMetaTools } from 'bare-agent/mcp'",
-      "signature": "buildMetaTools(tools: ToolDef[], discoveredAt?: string) => ToolDef[]",
+      "signature": "buildMetaTools(tools: ToolDef[], discoveredAt?: string, excluded?: Map<string, {server: string, tool: string}>) => ToolDef[]",
       "fails": "returns [mcp_discover, mcp_invoke]; a tool name does not travel as action.type (a deliberate v0.9 trade for one gate-check per call).",
       "example": "const metaTools = buildMetaTools(tools);"
     },
@@ -121,10 +121,10 @@
     {
       "name": "createMCPBridge",
       "category": "mcp",
-      "when": "you want to auto-discover MCP servers and expose them as bareagent tools in one call — with a trust hook gating command execution",
+      "when": "you want to auto-discover MCP servers and expose them as bareagent tools in one call — with a trust hook gating command execution, or a per-run signed `allow` list that exposes only the named tools",
       "import": "import { createMCPBridge } from 'bare-agent/mcp'",
-      "signature": "createMCPBridge(opts?: object) => Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, close: Function}>",
-      "fails": "a trust hook returning false skips a server (its command never runs) and a throw is fail-closed (deny); returns tools plus a close() to shut servers down.",
+      "signature": "createMCPBridge(opts?: object) => Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, missing?: Array<{server: string, tool: string}>, close: Function}>",
+      "fails": "a trust hook returning false skips a server (its command never runs) and a throw is fail-closed (deny); with `allow` it is in-memory only (no cache file read or written) and signed tools the server does not list land in `missing`, never a throw; returns tools plus a close() to shut servers down.",
       "example": "const { tools, close } = await createMCPBridge();\nconst loop = new Loop({ provider, tools });"
     },
     {

package/src/bareguard-adapter.d.ts

@@ -130,6 +130,10 @@ export type Annotation = {
  *   (`tools.allowlist:['shell_read']`) keeps matching even though `type` is now `'read'`. This
  *   activates `fs`/`bash` scoping automatically (`fs.readScope`/`fs.writeScope` deny by default
  *   when unset — see CHANGELOG) — override when a different shape is needed.
+ *   `onToolResult` on a tool error records `{error: message, durationMs}` plus, only when present, an
+ *   allow-listed `errorContext` copied from `error.context` (`timeout`/`denied` booleans, `server`/`tool`
+ *   strings capped at 200 chars, finite `timeoutMs`; wrong-typed values dropped) — so an MCP timeout is
+ *   distinguishable in the audit row. `stderr` and every other context field are NEVER forwarded.
  * @returns {{policy: Function, onLlmResult: Function, onToolResult: Function, filterTools: Function, wrapTool: Function, wrapTools: Function}}
  * @when you have a bareguard Gate and want to wire it into a Loop as the policy + metering chokepoint in one line
  * @fails never throws; a gate halt surfaces as a HaltError the Loop catches and exits cleanly, and a deny is an advisory string fed back to the model.

package/src/bareguard-adapter.js

@@ -41,6 +41,38 @@ function safeStringify(value) {
   }
 }
 
+// Keys of a tool error's `context` that onToolResult may forward to gate.record (and so into the
+// audit row), with the exact type each must have. ALLOW-LIST, never the whole object: MCP timeout
+// errors carry `stderr` (server output, possibly secret-bearing) in `context`, and gate.record writes
+// its result verbatim to the audit log. Anything not listed here, or of the wrong type, is dropped.
+const ERROR_CONTEXT_KEYS = /** @type {const} */ ({
+  timeout: 'boolean', denied: 'boolean', server: 'string', tool: 'string', timeoutMs: 'number',
+});
+const ERROR_CONTEXT_MAX_STR = 200;
+
+/**
+ * @param {any} error
+ * @returns {Record<string, boolean|string|number>|undefined} undefined when no allowed key is present
+ */
+function pickErrorContext(error) {
+  /** @type {Record<string, boolean|string|number>} */
+  const out = {};
+  try {
+    const ctx = error?.context;
+    if (ctx === null || typeof ctx !== 'object') return undefined;
+    for (const [key, type] of Object.entries(ERROR_CONTEXT_KEYS)) {
+      if (!Object.prototype.hasOwnProperty.call(ctx, key)) continue;
+      const v = ctx[key];
+      if (typeof v !== type) continue;
+      if (type === 'number' && !Number.isFinite(v)) continue;
+      out[key] = type === 'string' ? v.slice(0, ERROR_CONTEXT_MAX_STR) : v;
+    }
+  } catch {
+    return undefined; // a throwing getter / exotic context must never break the audit write
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 // Module-scope so a process that spawns many child agents (each with its own
 // wireGate call) only prints the wrapTool deprecation warning once.
 let warnedWrap = false;
@@ -98,6 +130,10 @@ let warnedWrap = false;
  *   (`tools.allowlist:['shell_read']`) keeps matching even though `type` is now `'read'`. This
  *   activates `fs`/`bash` scoping automatically (`fs.readScope`/`fs.writeScope` deny by default
  *   when unset — see CHANGELOG) — override when a different shape is needed.
+ *   `onToolResult` on a tool error records `{error: message, durationMs}` plus, only when present, an
+ *   allow-listed `errorContext` copied from `error.context` (`timeout`/`denied` booleans, `server`/`tool`
+ *   strings capped at 200 chars, finite `timeoutMs`; wrong-typed values dropped) — so an MCP timeout is
+ *   distinguishable in the audit row. `stderr` and every other context field are NEVER forwarded.
  * @returns {{policy: Function, onLlmResult: Function, onToolResult: Function, filterTools: Function, wrapTool: Function, wrapTools: Function}}
  * @when you have a bareguard Gate and want to wire it into a Loop as the policy + metering chokepoint in one line
  * @fails never throws; a gate halt surfaces as a HaltError the Loop catches and exits cleanly, and a deny is an advisory string fed back to the model.
@@ -201,8 +237,10 @@ function wireGate(gate, options = {}) {
   const onToolResult = async ({ name, args, result, error, durationMs, ctx }) => {
     const action = translate(name, args, ctx);
     if (error) {
+      const errorContext = pickErrorContext(error);
       await gate.record(action, {
         error: error?.message || String(error),
+        ...(errorContext && { errorContext }),
         durationMs: durationMs ?? null,
       });
     } else {

package/src/mcp-bridge.d.ts

@@ -52,7 +52,10 @@ export type DeniedTool = {
  * JSON-RPC stdio client over a spawned MCP server.
  */
 export type RpcClient = {
-    rpc: (method: string, params?: object, timeoutMs?: number) => Promise<any>;
+    rpc: (method: string, params?: object, timeoutMs?: number, label?: {
+        server: string;
+        tool: string;
+    }) => Promise<any>;
     notify: (method: string, params?: object) => void;
     child: import("node:child_process").ChildProcessWithoutNullStreams;
     stderr: string;
@@ -79,7 +82,16 @@ export type RpcClient = {
  * @param {boolean} [opts.includeProjectConfig=false] - Also scan the project-cwd `./.mcp.json`
  *   during default discovery. Off by default: a project config in an untrusted repo can auto-spawn
  *   arbitrary commands. Implied true when a `confirmServer` hook is present (it vets each command).
- * @param {string[]} [opts.servers] - Limit to these server names.
+ * @param {Record<string, string[]>} [opts.allow] - Signed allow-list `{ [serverName]: rawMcpToolNames[] }`
+ *   (raw MCP names, NOT the `server_tool` prefixed form; each list must be non-empty). Switches to an IN-MEMORY mode: never reads or
+ *   writes `.mcp-bridge.json` (no cache, no TTL; `bridgePath`/`refresh`/`servers` are ignored); server
+ *   definitions come only from `discoverServers(configPaths)`; only servers named here are spawned (still
+ *   vetted by `confirmServer`); each connects ONCE and exposes signed ∩ listed — every other tool is ABSENT
+ *   (not in `tools`, `metaTools` catalog or `systemContext`). Signed tools the server does not list (or whose
+ *   server was not found / failed / was rejected) come back in `missing`. `denied` is always `[]`, nothing is
+ *   written to stdout, and `mcp_invoke` on a listed-but-unsigned name throws `context.denied === true`.
+ *   Invalid shape throws `ValidationError` (type only, never values).
+ * @param {string[]} [opts.servers] - Limit to these server names (ignored when `allow` is given).
  * @param {number} [opts.timeout=15000] - Per-server handshake timeout in ms (initialize + tools/list).
  * @param {number} [opts.callTimeout=120000] - Per-invocation timeout in ms for tools/call. Bounds a
  *   server that accepts a tool call but never responds. Set 0 to disable (unbounded).
@@ -91,9 +103,9 @@ export type RpcClient = {
  *   discovered server is trusted — pass this to gate command execution. Presence
  *   of this hook also opts default discovery into the project-cwd `./.mcp.json`,
  *   since each command is then vetted regardless of source.
- * @returns {Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, close: Function}>}
- * @when you want to auto-discover MCP servers and expose them as bareagent tools in one call — with a trust hook gating command execution
- * @fails a trust hook returning false skips a server (its command never runs) and a throw is fail-closed (deny); returns tools plus a close() to shut servers down.
+ * @returns {Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, missing?: Array<{server: string, tool: string}>, close: Function}>}
+ * @when you want to auto-discover MCP servers and expose them as bareagent tools in one call — with a trust hook gating command execution, or a per-run signed `allow` list that exposes only the named tools
+ * @fails a trust hook returning false skips a server (its command never runs) and a throw is fail-closed (deny); with `allow` it is in-memory only (no cache file read or written) and signed tools the server does not list land in `missing`, never a throw; returns tools plus a close() to shut servers down.
  * @example
  *   const { tools, close } = await createMCPBridge();
  *   const loop = new Loop({ provider, tools });
@@ -102,6 +114,7 @@ export function createMCPBridge(opts?: {
     bridgePath?: string | undefined;
     configPaths?: string[] | undefined;
     includeProjectConfig?: boolean | undefined;
+    allow?: Record<string, string[]> | undefined;
     servers?: string[] | undefined;
     timeout?: number | undefined;
     callTimeout?: number | undefined;
@@ -117,6 +130,10 @@ export function createMCPBridge(opts?: {
         server: string;
         error: string;
     }>;
+    missing?: Array<{
+        server: string;
+        tool: string;
+    }>;
     close: Function;
 }>;
 /**
@@ -150,10 +167,16 @@ export function discoverServers(configPaths?: string[], { includeProjectConfig }
  *
  * @param {ToolDef[]} tools - The bulk-loaded, name-prefixed tools array.
  * @param {string} [discoveredAt] - ISO timestamp from .mcp-bridge.json.
+ * @param {Map<string, {server: string, tool: string}>} [excluded] - Allow mode only: names the server
+ *   LISTS but the signed allow-list excludes. mcp_invoke refuses them with `context.denied === true`;
+ *   they never appear in the catalog. Omitted ⇒ unchanged behaviour.
  * @returns {ToolDef[]} [mcp_discover, mcp_invoke]
  * @when you want the two bulk MCP meta-tools (mcp_discover, mcp_invoke) instead of exposing every discovered tool individually — one gate-check per invocation
  * @fails returns [mcp_discover, mcp_invoke]; a tool name does not travel as action.type (a deliberate v0.9 trade for one gate-check per call).
  * @example
  *   const metaTools = buildMetaTools(tools);
  */
-export function buildMetaTools(tools: ToolDef[], discoveredAt?: string): ToolDef[];
+export function buildMetaTools(tools: ToolDef[], discoveredAt?: string, excluded?: Map<string, {
+    server: string;
+    tool: string;
+}>): ToolDef[];

package/src/mcp-bridge.js

@@ -4,7 +4,7 @@ const { spawn } = require('node:child_process');
 const { readFileSync, writeFileSync, existsSync } = require('node:fs');
 const { join } = require('node:path');
 const { homedir } = require('node:os');
-const { ToolError } = require('./errors');
+const { ToolError, ValidationError } = require('./errors');
 
 /** @typedef {import('../types').ToolDef} ToolDef */
 
@@ -54,7 +54,7 @@ const { ToolError } = require('./errors');
 /**
  * JSON-RPC stdio client over a spawned MCP server.
  * @typedef {object} RpcClient
- * @property {(method: string, params?: object, timeoutMs?: number) => Promise<any>} rpc
+ * @property {(method: string, params?: object, timeoutMs?: number, label?: {server: string, tool: string}) => Promise<any>} rpc
  * @property {(method: string, params?: object) => void} notify
  * @property {import('node:child_process').ChildProcessWithoutNullStreams} child
  * @property {string} stderr
@@ -309,9 +309,11 @@ function createRpcClient(name, def) {
    * @param {string} method
    * @param {object} [params]
    * @param {number} [timeoutMs=0] - Reject if no response arrives within this many ms (0 = no limit).
+   * @param {{server: string, tool: string}} [label] - tools/call only: when given, a timeout throws a
+   *   labelled ToolError (`context: {timeout, server, tool, timeoutMs, stderr}`, stderr kept OUT of the message).
    * @returns {Promise<any>}
    */
-  function rpc(method, params = {}, timeoutMs = 0) {
+  function rpc(method, params = {}, timeoutMs = 0, label) {
     const id = nextId++;
     return new Promise((resolve, reject) => {
       if (!child.stdin.writable) {
@@ -321,7 +323,14 @@ function createRpcClient(name, def) {
       let timer = null;
       if (timeoutMs > 0) {
         timer = setTimeout(() => {
-          settle(id, false, new ToolError(`MCP server "${name}" "${method}" timed out after ${timeoutMs}ms. stderr: ${stderrBuf.slice(-500)}`));
+          if (label) {
+            settle(id, false, new ToolError(
+              `MCP server "${label.server}" tool "${label.tool}" timed out after ${timeoutMs}ms`,
+              { context: { timeout: true, server: label.server, tool: label.tool, timeoutMs, stderr: stderrBuf.slice(-500) } },
+            ));
+          } else {
+            settle(id, false, new ToolError(`MCP server "${name}" "${method}" timed out after ${timeoutMs}ms. stderr: ${stderrBuf.slice(-500)}`));
+          }
         }, timeoutMs);
         timer.unref?.();
       }
@@ -367,7 +376,7 @@ function unwrapContent(content) {
 /**
  * @param {string} serverName
  * @param {McpTool[]} mcpTools
- * @param {(method: string, params?: object, timeoutMs?: number) => Promise<any>} rpc
+ * @param {(method: string, params?: object, timeoutMs?: number, label?: {server: string, tool: string}) => Promise<any>} rpc
  * @param {number} [callTimeout=0] - Per-invocation timeout (ms) for tools/call; 0 = no limit.
  * @returns {ToolDef[]}
  */
@@ -377,7 +386,7 @@ function wrapTools(serverName, mcpTools, rpc, callTimeout = 0) {
     description: t.description || '',
     parameters: t.inputSchema || { type: 'object', properties: {} },
     execute: async (args) => {
-      const result = await rpc('tools/call', { name: t.name, arguments: args }, callTimeout);
+      const result = await rpc('tools/call', { name: t.name, arguments: args }, callTimeout, { server: serverName, tool: t.name });
       if (result.isError) {
         throw new ToolError(unwrapContent(result.content) || 'MCP tool error', {
           context: { server: serverName, tool: t.name },
@@ -451,7 +460,14 @@ async function connectAndListTools(name, def, timeout = 15000) {
     }, timeout);
     client.notify('notifications/initialized');
 
-    const { tools: mcpTools } = await client.rpc('tools/list', {}, timeout);
+    const listed = await client.rpc('tools/list', {}, timeout);
+    // A reply without a `tools` array is a protocol-violating server, not an empty one: fail the
+    // connect HERE (inside the try, so the child is reaped) rather than let every caller's
+    // `.map`/`.filter` throw after the child is already running but before it is tracked.
+    const mcpTools = listed && listed.tools;
+    if (!Array.isArray(mcpTools)) {
+      throw new Error(`MCP server "${name}" returned a malformed tools/list reply (no tools array)`);
+    }
 
     return { mcpTools, client };
   } catch (err) {
@@ -470,9 +486,10 @@ async function connectAndListTools(name, def, timeout = 15000) {
  * @param {string[]} servers
  * @param {ToolDef[]} tools
  * @param {DeniedTool[]} denied
+ * @param {boolean} [allowMode] - Signed allow-list mode: say nothing about restricted/other tools or the cache file.
  * @returns {string}
  */
-function buildSystemContext(servers, tools, denied) {
+function buildSystemContext(servers, tools, denied, allowMode = false) {
   /** @type {string[]} */
   const lines = [];
   lines.push(`MCP Bridge: ${tools.length} tools available from ${servers.length} server(s): ${servers.join(', ')}.`);
@@ -489,6 +506,8 @@ function buildSystemContext(servers, tools, denied) {
     lines.push(`  ${server}: ${toolNames.join(', ')}`);
   }
 
+  if (allowMode) return lines.join('\n');
+
   if (denied.length > 0) {
     lines.push(`Restricted tools (${denied.length}, not available to you):`);
     for (const d of denied) {
@@ -526,13 +545,16 @@ function buildSystemContext(servers, tools, denied) {
  *
  * @param {ToolDef[]} tools - The bulk-loaded, name-prefixed tools array.
  * @param {string} [discoveredAt] - ISO timestamp from .mcp-bridge.json.
+ * @param {Map<string, {server: string, tool: string}>} [excluded] - Allow mode only: names the server
+ *   LISTS but the signed allow-list excludes. mcp_invoke refuses them with `context.denied === true`;
+ *   they never appear in the catalog. Omitted ⇒ unchanged behaviour.
  * @returns {ToolDef[]} [mcp_discover, mcp_invoke]
  * @when you want the two bulk MCP meta-tools (mcp_discover, mcp_invoke) instead of exposing every discovered tool individually — one gate-check per invocation
  * @fails returns [mcp_discover, mcp_invoke]; a tool name does not travel as action.type (a deliberate v0.9 trade for one gate-check per call).
  * @example
  *   const metaTools = buildMetaTools(tools);
  */
-function buildMetaTools(tools, discoveredAt) {
+function buildMetaTools(tools, discoveredAt, excluded) {
   // Catalog descriptors: same info the LLM would see for bulk-loaded tools,
   // but exposed via mcp_discover instead of taking up tool-array slots upfront.
   const catalog = tools.map(t => {
@@ -596,6 +618,12 @@ function buildMetaTools(tools, discoveredAt) {
     },
     execute: async (/** @type {{ name: string, args?: object }} */ { name, args }) => {
       const tool = byName.get(name);
+      const ex = !tool && excluded ? excluded.get(name) : undefined;
+      if (ex) {
+        throw new ToolError(`mcp_invoke: "${name}" is not on this run's allowed list`, {
+          context: { denied: true, server: ex.server, tool: ex.tool },
+        });
+      }
       if (!tool) {
         throw new ToolError(`mcp_invoke: unknown tool "${name}". Call mcp_discover for the current catalog.`, {
           context: { name, knownNames: [...byName.keys()] },
@@ -608,6 +636,118 @@ function buildMetaTools(tools, discoveredAt) {
   return [mcpDiscover, mcpInvoke];
 }
 
+// --- Signed allow-list mode (opts.allow) ---
+
+/** @param {any} v @returns {string} */
+const typeName = (v) => (v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v);
+
+/**
+ * Validate `opts.allow`. Messages name the TYPE only — never echo a value.
+ * @param {any} allow
+ * @returns {Map<string, string[]>} server name -> de-duplicated signed raw tool names
+ */
+function validateAllow(allow) {
+  const bad = (/** @type {string} */ msg) =>
+    new ValidationError(`[MCP Bridge] ${msg}`, { context: { lib: 'bare-agent' } });
+  const proto = allow !== null && typeof allow === 'object' ? Object.getPrototypeOf(allow) : undefined;
+  if (typeof allow !== 'object' || allow === null || Array.isArray(allow) || (proto !== Object.prototype && proto !== null)) {
+    throw bad(`allow must be a plain object of { serverName: string[] } (got ${typeName(allow)})`);
+  }
+  const entries = Object.entries(allow);
+  if (entries.length === 0) throw bad('allow must name at least one server (got an empty object)');
+  /** @type {Map<string, string[]>} */
+  const out = new Map();
+  for (const [server, list] of entries) {
+    if (!Array.isArray(list)) throw bad(`allow values must be arrays of tool names (got ${typeName(list)})`);
+    if (list.length === 0) throw bad('allow values must be non-empty arrays of tool names (got an empty array)');
+    for (const t of list) {
+      if (typeof t !== 'string' || t === '') {
+        throw bad(`allow tool names must be non-empty strings (got ${t === '' ? 'empty string' : typeName(t)})`);
+      }
+    }
+    out.set(server, [...new Set(list)]);
+  }
+  return out;
+}
+
+/**
+ * allow-mode body of createMCPBridge: in memory only (no .mcp-bridge.json read or write, no TTL),
+ * server definitions come ONLY from discoverServers(), one connect per signed server, expose
+ * signed ∩ listed, silent on stdout, and the model is never told other tools exist.
+ * @param {Map<string, string[]>} allow
+ * @param {object} o
+ * @param {string[]} [o.configPaths]
+ * @param {boolean} o.includeProjectConfig
+ * @param {number} o.timeout
+ * @param {number} o.callTimeout
+ * @param {(name: string, def: ServerDef) => Promise<boolean>} o.vetServer
+ * @param {(specs: Array<{name: string, command: string, args?: string[]}>) => void} o.warnUnvettedSpawn
+ */
+async function createAllowBridge(allow, o) {
+  const discovered = discoverServers(o.configPaths, { includeProjectConfig: o.includeProjectConfig });
+  /** @type {Array<[string, ServerDef]>} */
+  const toConnect = [];
+  /** @type {Array<{server: string, error: string}>} */
+  const errors = [];
+  for (const name of allow.keys()) {
+    const def = discovered.get(name);
+    if (def) toConnect.push([name, def]);
+    else errors.push({ server: name, error: 'server not found in discovered MCP configs' });
+  }
+  o.warnUnvettedSpawn(toConnect.map(([name, def]) => ({ name, command: def.command, args: def.args })));
+
+  /** @type {ToolDef[]} */
+  const tools = [];
+  /** @type {import('node:child_process').ChildProcess[]} */
+  const children = [];
+  /** @type {string[]} */
+  const connected = [];
+  /** @type {Array<{server: string, tool: string}>} */
+  const missing = [];
+  /** @type {Map<string, {server: string, tool: string}>} */
+  const excluded = new Map();
+  /** @type {Set<string>} */
+  const listedOk = new Set();
+
+  await Promise.all(toConnect.map(async ([name, def]) => {
+    try {
+      if (!(await o.vetServer(name, def))) return;
+      const { mcpTools, client } = await connectAndListTools(name, def, o.timeout);
+      // Track the child BEFORE any processing so close() reaps it even if what follows throws.
+      children.push(client.child);
+      const signed = new Set(allow.get(name));
+      const listed = new Set(mcpTools.map(t => t.name));
+      tools.push(...wrapTools(name, mcpTools.filter(t => signed.has(t.name)), client.rpc, o.callTimeout));
+      for (const t of mcpTools) {
+        if (!signed.has(t.name)) excluded.set(`${name}_${t.name}`, { server: name, tool: t.name });
+      }
+      for (const t of signed) if (!listed.has(t)) missing.push({ server: name, tool: t });
+      connected.push(name);
+      listedOk.add(name);
+    } catch (err) {
+      errors.push({ server: name, error: err.message });
+    }
+  }));
+
+  // Every signed tool of a server that was not found / failed / was rejected by confirmServer is missing.
+  for (const [server, list] of allow) {
+    if (!listedOk.has(server)) for (const tool of list) missing.push({ server, tool });
+  }
+
+  if (errors.length > 0) console.warn('[MCP Bridge] Some servers failed to connect:', errors);
+
+  return {
+    tools,
+    metaTools: buildMetaTools(tools, undefined, excluded),
+    servers: connected,
+    denied: [],
+    systemContext: buildSystemContext(connected, tools, [], true),
+    errors,
+    missing,
+    close: async () => { await Promise.all(children.map(killServer)); },
+  };
+}
+
 // --- Main entry point ---
 
 /**
@@ -632,7 +772,16 @@ function buildMetaTools(tools, discoveredAt) {
  * @param {boolean} [opts.includeProjectConfig=false] - Also scan the project-cwd `./.mcp.json`
  *   during default discovery. Off by default: a project config in an untrusted repo can auto-spawn
  *   arbitrary commands. Implied true when a `confirmServer` hook is present (it vets each command).
- * @param {string[]} [opts.servers] - Limit to these server names.
+ * @param {Record<string, string[]>} [opts.allow] - Signed allow-list `{ [serverName]: rawMcpToolNames[] }`
+ *   (raw MCP names, NOT the `server_tool` prefixed form; each list must be non-empty). Switches to an IN-MEMORY mode: never reads or
+ *   writes `.mcp-bridge.json` (no cache, no TTL; `bridgePath`/`refresh`/`servers` are ignored); server
+ *   definitions come only from `discoverServers(configPaths)`; only servers named here are spawned (still
+ *   vetted by `confirmServer`); each connects ONCE and exposes signed ∩ listed — every other tool is ABSENT
+ *   (not in `tools`, `metaTools` catalog or `systemContext`). Signed tools the server does not list (or whose
+ *   server was not found / failed / was rejected) come back in `missing`. `denied` is always `[]`, nothing is
+ *   written to stdout, and `mcp_invoke` on a listed-but-unsigned name throws `context.denied === true`.
+ *   Invalid shape throws `ValidationError` (type only, never values).
+ * @param {string[]} [opts.servers] - Limit to these server names (ignored when `allow` is given).
  * @param {number} [opts.timeout=15000] - Per-server handshake timeout in ms (initialize + tools/list).
  * @param {number} [opts.callTimeout=120000] - Per-invocation timeout in ms for tools/call. Bounds a
  *   server that accepts a tool call but never responds. Set 0 to disable (unbounded).
@@ -644,9 +793,9 @@ function buildMetaTools(tools, discoveredAt) {
  *   discovered server is trusted — pass this to gate command execution. Presence
  *   of this hook also opts default discovery into the project-cwd `./.mcp.json`,
  *   since each command is then vetted regardless of source.
- * @returns {Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, close: Function}>}
- * @when you want to auto-discover MCP servers and expose them as bareagent tools in one call — with a trust hook gating command execution
- * @fails a trust hook returning false skips a server (its command never runs) and a throw is fail-closed (deny); returns tools plus a close() to shut servers down.
+ * @returns {Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, missing?: Array<{server: string, tool: string}>, close: Function}>}
+ * @when you want to auto-discover MCP servers and expose them as bareagent tools in one call — with a trust hook gating command execution, or a per-run signed `allow` list that exposes only the named tools
+ * @fails a trust hook returning false skips a server (its command never runs) and a throw is fail-closed (deny); with `allow` it is in-memory only (no cache file read or written) and signed tools the server does not list land in `missing`, never a throw; returns tools plus a close() to shut servers down.
  * @example
  *   const { tools, close } = await createMCPBridge();
  *   const loop = new Loop({ provider, tools });
@@ -693,6 +842,15 @@ async function createMCPBridge(opts = {}) {
     );
   };
 
+  if (opts.allow !== undefined) {
+    const allow = validateAllow(opts.allow);
+    return createAllowBridge(allow, {
+      configPaths: opts.configPaths,
+      includeProjectConfig: opts.includeProjectConfig === true || !!confirmServer,
+      timeout, callTimeout, vetServer, warnUnvettedSpawn,
+    });
+  }
+
   let config = readBridgeConfig(bridgePath);
   const needsRefresh = opts.refresh || !config || isExpired(config);
 
@@ -731,8 +889,8 @@ async function createMCPBridge(opts = {}) {
           // decision, not a connection failure, so it must not land in `errors`.
           if (!(await vetServer(name, def))) return;
           const result = await connectAndListTools(name, def, timeout);
-          freshTools.set(name, result.mcpTools);
           connectResults.set(name, result.client);
+          freshTools.set(name, result.mcpTools);
         } catch (err) {
           errors.push({ server: name, error: err.message });
         }
@@ -742,20 +900,25 @@ async function createMCPBridge(opts = {}) {
         console.warn('[MCP Bridge] Some servers failed to connect:', errors);
       }
 
-      // Only write config when at least one server connected successfully.
-      // If all servers failed, retain the existing config unchanged so
-      // user-curated allow/deny settings are not destroyed on transient failures.
-      if (freshTools.size > 0) {
-        config = mergeBridgeConfig(config, new Map(toDiscover), freshTools);
-        writeBridgeConfig(bridgePath, config);
-        console.log(`[MCP Bridge] Wrote ${bridgePath}`);
-      } else if (!config) {
-        return { tools: [], servers: [], systemContext: '', denied: [], close: async () => {} };
-      }
+      // Discovery connections are killed in `finally`: a throw from the config merge/write (e.g. an
+      // unwritable bridgePath) must not strand the live children held only in connectResults.
+      try {
+        // Only write config when at least one server connected successfully.
+        // If all servers failed, retain the existing config unchanged so
+        // user-curated allow/deny settings are not destroyed on transient failures.
+        if (freshTools.size > 0) {
+          config = mergeBridgeConfig(config, new Map(toDiscover), freshTools);
+          writeBridgeConfig(bridgePath, config);
+          console.log(`[MCP Bridge] Wrote ${bridgePath}`);
+        } else if (!config) {
+          return { tools: [], servers: [], systemContext: '', denied: [], close: async () => {} };
+        }
 
-      // Close the discovery connections — we'll reconnect below using the config
-      for (const client of connectResults.values()) {
-        await killServer(client.child);
+      } finally {
+        // Close the discovery connections — we'll reconnect below using the config
+        for (const client of connectResults.values()) {
+          await killServer(client.child);
+        }
       }
     }
   }
@@ -808,13 +971,14 @@ async function createMCPBridge(opts = {}) {
       // Denied by confirmServer: skip silently (the caller's decision, not a failure).
       if (!(await vetServer(name, serverConf))) return;
       const { mcpTools, client } = await connectAndListTools(name, serverConf, timeout);
+      // Track the child BEFORE any processing so close() reaps it even if what follows throws.
+      children.push(client.child);
 
       // Only wrap tools that are allowed in config
       const allowed = mcpTools.filter(t => allowedToolNames.includes(t.name));
       const wrapped = wrapTools(name, allowed, client.rpc, callTimeout);
 
       tools.push(...wrapped);
-      children.push(client.child);
       connected.push(name);
 
       // Track denied tools with descriptions from the server