bare-agent 0.52.0 → 0.54.0

package/bareagent.context.md

@@ -20,7 +20,7 @@ Eight entry points:
 - `require('bare-agent/stores')` — SQLite (FTS5), JsonFile
 - `require('bare-agent/transports')` — JsonlTransport
 - `require('bare-agent/tools')` — createBrowsingTools, createMobileTools, createShellTools, resolveToolPath, createSpawnTool, createDeferTool, spawnChild, readDeferQueue, liteCtxMcpBridgeConfig
-- `require('bare-agent/mcp')` — createMCPBridge (returns `tools` + `metaTools`), discoverServers, buildMetaTools
+- `require('bare-agent/mcp')` — createMCPBridge (returns `tools` + `metaTools`), discoverServers, buildMetaTools, listServerTools
 - `require('bare-agent/bareguard')` — wireGate (one-line bareguard Gate integration), defaultActionTranslator
 
 **TypeScript:** bareagent is pure JS + JSDoc but ships `.d.ts` declarations (generated from that JSDoc, v0.11+). Every entry point above resolves types automatically — `import { Loop } from 'bare-agent'` and `import { OpenAI } from 'bare-agent/providers'` give full autocomplete and type-checking, including required-option enforcement (e.g. `new Loop({})` is a type error: `provider` is required). No `@types/bare-agent` needed. Shared shapes (`Provider`, `Message`, `ToolDef`, `ToolCall`, `Usage`, `GenerateResult`, `Store`) are exported from the package's `types/`. The repo itself runs `tsc --checkJs` in CI on every push/PR so the JSDoc and the code can't drift.
@@ -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 } })` |
@@ -429,9 +429,12 @@ every command it is about to spawn — `confirmServer` is how you actually *gate
 
 **RPC timeouts (Unreleased).** Every JSON-RPC round-trip is now bounded, so a
 server that never answers can't hang the bridge or the loop. `opts.timeout`
-(default 15 s) bounds the handshake (`initialize` + `tools/list`);
+(default 15 s) bounds the handshake (`initialize` and each `tools/list` page);
 `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,10 @@ 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.
+
+**Annotations, listing, pagination, `errors` (Unreleased).** If a server sends `annotations` on a tool (`readOnlyHint`, `destructiveHint`, ...), each bridged tool (`ToolDef.annotations`) and each `mcp_discover` catalog entry carries them as the same unmodified object, in every mode; the key is absent when none was sent (a non-object value — null/array/string — is dropped). They are server hints, never authorization, and `systemContext` does not mention them. `listServerTools({ server, configPaths?, confirmServer?, includeProjectConfig?, timeout? })` (`bare-agent/mcp`) returns `[{name, description, annotations?}]` for one server so you can pick an `allow` list: no bridge, never reads or writes `.mcp-bridge.json`, nothing on stdout, vetted by `confirmServer` exactly like `createMCPBridge`, and the child is always killed. It throws (never returns `[]`) on server not found, declined/throwing `confirmServer`, connect/handshake failure, timeout or a malformed reply; one total deadline of 4 x `timeout` bounds the call (a small `timeout` shrinks it proportionally). `tools/list` follows `nextCursor` in every mode; more than 100 pages or a repeated cursor fails that server's connect (in `errors`; in `allow` mode its signed tools land in `missing`) rather than returning a truncated catalog. In bulk mode `errors` is always present and lists each server that did not connect this run, once (first failure message wins); a server that failed discovery but connected from the cached definition is not in `errors` but draws one separate `console.warn` saying the config edit was not applied.
+
 ```json
 {
   "discovered": "2026-04-13T12:00:00.000Z",
@@ -1596,6 +1605,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.54.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 });"
     },
     {
@@ -262,6 +262,15 @@
       "fails": "never throws and never calls the gate; surfaces fail-open (a non-honored verdict surfaces) and bounds fields against the sink's silent caps with a visible clip marker.",
       "example": "gate.annotate(judgeToAnnotation(await judge({ request, artifact, provider })));"
     },
+    {
+      "name": "listServerTools",
+      "category": "mcp",
+      "when": "you want to list one MCP server's tools and their annotation hints before deciding what to allow — no bridge, no cache file, no tools kept alive",
+      "import": "import { listServerTools } from 'bare-agent/mcp'",
+      "signature": "listServerTools(opts: object) => Promise<Array<{name: string, description: string, annotations?: Record<string, any>}>>",
+      "fails": "throws (never returns []) when the server is not found, confirmServer declines or throws, the connect/handshake fails or times out, the total deadline trips, or the reply is malformed; the child is always reaped.",
+      "example": "const tools = await listServerTools({ server: 'files', configPaths: [cfg] });"
+    },
     {
       "name": "litectxCorpus",
       "category": "integration",

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

@@ -15,6 +15,11 @@ export type McpTool = {
     name: string;
     description?: string | undefined;
     inputSchema?: Record<string, any> | undefined;
+    /**
+     * - Server-supplied behavioural HINTS (readOnlyHint,
+     * destructiveHint, ...). Untrusted metadata from the server: never an authorization signal.
+     */
+    annotations?: Record<string, any> | undefined;
 };
 /**
  * Per-server entry persisted in .mcp-bridge.json.
@@ -52,7 +57,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 +87,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 +108,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 +119,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;
@@ -113,10 +131,14 @@ export function createMCPBridge(opts?: {
     servers: string[];
     systemContext: string;
     denied: DeniedTool[];
-    errors?: Array<{
+    errors: Array<{
         server: string;
         error: string;
     }>;
+    missing?: Array<{
+        server: string;
+        tool: string;
+    }>;
     close: Function;
 }>;
 /**
@@ -150,10 +172,51 @@ 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[];
+/**
+ * List one configured MCP server's tools WITHOUT building a bridge: discover, vet, connect, list
+ * (following pagination), then always kill the child. Never reads or writes `.mcp-bridge.json`
+ * and prints nothing to stdout. `annotations` are the server's own HINTS, passed through unmodified
+ * (key absent when the server sent none) — never an authorization signal.
+ *
+ * Total wall-clock ceiling is DERIVED: 4 × `timeout` (initialize + three maximally slow pages) over
+ * the connect + list, excluding `confirmServer` (caller code, possibly interactive). On trip the
+ * child is killed and a TimeoutError naming the total deadline rejects. A SMALL `timeout` shrinks the
+ * total proportionally (timeout 500 ⇒ 2s total), so a server with many pages near that speed can trip it.
+ * A non-object `annotations` value from the server is treated as absent (dropped).
+ *
+ * @param {object} opts
+ * @param {string} opts.server - Server name as it appears in the discovered configs.
+ * @param {string[]} [opts.configPaths] - Explicit config paths; omitted ⇒ trusted $HOME/IDE defaults.
+ * @param {(name: string, def: ServerDef) => boolean | Promise<boolean>} [opts.confirmServer] - Same semantics as createMCPBridge: `=== true` proceeds, a throw denies. Implies includeProjectConfig.
+ * @param {boolean} [opts.includeProjectConfig=false] - Also scan `./.mcp.json` during default discovery.
+ * @param {number} [opts.timeout=15000] - Per-round-trip bound in ms (initialize and each tools/list page).
+ * @returns {Promise<Array<{name: string, description: string, annotations?: Record<string, any>}>>}
+ * @when you want to list one MCP server's tools and their annotation hints before deciding what to allow — no bridge, no cache file, no tools kept alive
+ * @fails throws (never returns []) when the server is not found, confirmServer declines or throws, the connect/handshake fails or times out, the total deadline trips, or the reply is malformed; the child is always reaped.
+ * @example
+ *   const tools = await listServerTools({ server: 'files', configPaths: [cfg] });
+ */
+export function listServerTools(opts: {
+    server: string;
+    configPaths?: string[] | undefined;
+    confirmServer?: ((name: string, def: ServerDef) => boolean | Promise<boolean>) | undefined;
+    includeProjectConfig?: boolean | undefined;
+    timeout?: number | undefined;
+}): Promise<Array<{
+    name: string;
+    description: string;
+    annotations?: Record<string, any>;
+}>>;

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, TimeoutError } = require('./errors');
 
 /** @typedef {import('../types').ToolDef} ToolDef */
 
@@ -23,6 +23,8 @@ const { ToolError } = require('./errors');
  * @property {string} name
  * @property {string} [description]
  * @property {Record<string, any>} [inputSchema]
+ * @property {Record<string, any>} [annotations] - Server-supplied behavioural HINTS (readOnlyHint,
+ *   destructiveHint, ...). Untrusted metadata from the server: never an authorization signal.
  */
 
 /**
@@ -54,7 +56,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 +311,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 +325,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?.();
       }
@@ -361,13 +372,21 @@ function unwrapContent(content) {
 
 // --- Tool wrapping ---
 
+/**
+ * A server "sent annotations" only when it sent a non-null, non-array object. A non-object
+ * `annotations` value (null, array, string, ...) is treated as absent (dropped), so the key stays absent downstream.
+ * @param {any} a
+ * @returns {boolean}
+ */
+const hasAnnotations = (a) => a !== null && typeof a === 'object' && !Array.isArray(a);
+
 // Runtime arg-dependent policy has moved to Loop-level (new Loop({ policy })).
 // mcp-bridge retains only the static .mcp-bridge.json allow/deny filter below —
 // that decides which tools are exposed to the Loop in the first place.
 /**
  * @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[]}
  */
@@ -376,8 +395,10 @@ function wrapTools(serverName, mcpTools, rpc, callTimeout = 0) {
     name: `${serverName}_${t.name}`,
     description: t.description || '',
     parameters: t.inputSchema || { type: 'object', properties: {} },
+    // Server `annotations` ride through as the SAME object, unmodified; key ABSENT when none sent.
+    ...(hasAnnotations(t.annotations) && { annotations: t.annotations }),
     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 },
@@ -431,29 +452,79 @@ async function killServer(child) {
 
 // --- Connect + list tools from a server ---
 
+// tools/list pagination cap. A server that keeps handing out cursors past this is faulty or
+// hostile; we THROW (never truncate silently — a partial catalog reads as a complete one).
+const MAX_LIST_PAGES = 100;
+
 /**
  * @param {string} name
  * @param {ServerDef} def
- * @param {number} [timeout]
+ * @param {number} [timeout] - Bound on EACH round-trip (initialize, every tools/list page).
+ * @param {{ deadlineMs?: number }} [o] - Optional ONE total wall-clock ceiling over the whole
+ *   connect+list (internal; used by listServerTools). On trip the child is killed and a labelled
+ *   TimeoutError rejects. The timer is always cleared.
  * @returns {Promise<{mcpTools: McpTool[], client: RpcClient}>}
  */
-async function connectAndListTools(name, def, timeout = 15000) {
+async function connectAndListTools(name, def, timeout = 15000, o = {}) {
   const client = createRpcClient(name, def);
+  /** @type {NodeJS.Timeout | undefined} */
+  let deadlineTimer;
 
   try {
-    // Both handshake round-trips are bounded by `timeout`. tools/list used to be
-    // unbounded — a server that answered initialize but never replied to
-    // tools/list would hang discovery (and the whole bridge) indefinitely.
-    await client.rpc('initialize', {
-      protocolVersion: '2024-11-05',
-      capabilities: {},
-      clientInfo: { name: 'bare-agent', version: '0.5.0' },
-    }, timeout);
-    client.notify('notifications/initialized');
-
-    const { tools: mcpTools } = await client.rpc('tools/list', {}, timeout);
-
-    return { mcpTools, client };
+    const work = (async () => {
+      // Every round-trip is bounded by `timeout`. tools/list used to be
+      // unbounded — a server that answered initialize but never replied to
+      // tools/list would hang discovery (and the whole bridge) indefinitely.
+      await client.rpc('initialize', {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'bare-agent', version: '0.5.0' },
+      }, timeout);
+      client.notify('notifications/initialized');
+
+      // Follow `nextCursor` until the server stops sending one. 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.
+      /** @type {McpTool[]} */
+      const mcpTools = [];
+      /** @type {Set<string>} */
+      const seenCursors = new Set();
+      /** @type {string | undefined} */
+      let cursor;
+      for (let pages = 1; ; pages++) {
+        const listed = await client.rpc('tools/list', cursor === undefined ? {} : { cursor }, timeout);
+        if (!listed || !Array.isArray(listed.tools)) {
+          throw new Error(`MCP server "${name}" returned a malformed tools/list reply (no tools array)`);
+        }
+        mcpTools.push(...listed.tools);
+        const next = listed.nextCursor;
+        if (typeof next !== 'string' || next === '') break;
+        if (seenCursors.has(next)) {
+          throw new Error(`MCP server "${name}" repeated a tools/list cursor (pagination loop)`);
+        }
+        if (pages >= MAX_LIST_PAGES) {
+          throw new Error(`MCP server "${name}" exceeded the tools/list page cap (${MAX_LIST_PAGES} pages); refusing to return a truncated catalog`);
+        }
+        seenCursors.add(next);
+        cursor = next;
+      }
+
+      return { mcpTools, client };
+    })();
+
+    if (!o.deadlineMs) return await work;
+    // The loser of the race must not surface as an unhandled rejection.
+    work.catch(() => {});
+    const deadline = new Promise((_, reject) => {
+      deadlineTimer = setTimeout(() => {
+        reject(new TimeoutError(
+          `MCP server "${name}" exceeded the total deadline of ${o.deadlineMs}ms for connect + tools/list`,
+          { context: { timeout: true, bound: 'deadline', server: name, deadlineMs: o.deadlineMs } },
+        ));
+      }, o.deadlineMs);
+    });
+    return await Promise.race([work, deadline]);
   } catch (err) {
     // Connect failed (init timeout, tools/list error, etc.) — the child was
     // spawned but never returned to the caller, so the caller can't track it
@@ -461,6 +532,8 @@ async function connectAndListTools(name, def, timeout = 15000) {
     // alive and hangs the process on exit (notably node:test's file wrapper).
     await killServer(client.child);
     throw err;
+  } finally {
+    clearTimeout(deadlineTimer);
   }
 }
 
@@ -470,9 +543,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 +563,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 +602,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 => {
@@ -543,6 +622,7 @@ function buildMetaTools(tools, discoveredAt) {
       schema: t.parameters || { type: 'object', properties: {} },
       server: sep > 0 ? t.name.slice(0, sep) : t.name,
       tool: sep > 0 ? t.name.slice(sep + 1) : '',
+      ...(hasAnnotations(t.annotations) && { annotations: t.annotations }),
     };
   });
   const byName = new Map(tools.map(t => [t.name, t]));
@@ -596,6 +676,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 +694,157 @@ function buildMetaTools(tools, discoveredAt) {
   return [mcpDiscover, mcpInvoke];
 }
 
+// --- Server vetting (shared by createMCPBridge and listServerTools) ---
+
+/**
+ * Vet a server before spawning its command. `=== true` proceeds; anything else, or a throw, denies
+ * (fail-closed). No hook ⇒ trust all.
+ * @param {((name: string, def: ServerDef) => boolean | Promise<boolean>) | null} confirmServer
+ * @returns {(name: string, def: ServerDef) => Promise<boolean>}
+ */
+function makeVetServer(confirmServer) {
+  return async (name, def) => {
+    if (!confirmServer) return true;
+    try { return (await confirmServer(name, def)) === true; }
+    catch { return false; }
+  };
+}
+
+/**
+ * Connecting to a server EXECUTES its `command`. The project-cwd `.mcp.json` is excluded from
+ * default discovery (see TRUSTED_CONFIG_PATHS / includeProjectConfig), so the untrusted-repo
+ * path is closed by default; this warning (stderr) covers the residual case where home/IDE configs
+ * (or an explicit opt-in) contribute commands and no confirmServer hook is present to vet them.
+ * Warns ONCE per returned function, BEFORE the first spawn.
+ * @param {Function | null} confirmServer
+ * @returns {(specs: Array<{name: string, command: string, args?: string[]}>) => void}
+ */
+function makeUnvettedWarner(confirmServer) {
+  let warned = false;
+  return (specs) => {
+    if (confirmServer || warned || specs.length === 0) return;
+    warned = true;
+    const cmds = specs.map(s => `${s.name} → ${s.command} ${(s.args || []).join(' ')}`.trim());
+    console.warn(
+      `[MCP Bridge] spawning ${specs.length} server command(s) without a confirmServer hook:\n  ` +
+      cmds.join('\n  ') +
+      `\n  Pass { confirmServer } to vet each command before it runs.`,
+    );
+  };
+}
+
+// --- 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 +869,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 +890,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 });
@@ -667,35 +913,44 @@ async function createMCPBridge(opts = {}) {
   // Vet a server before spawning its command. Fail-closed: an undefined hook
   // trusts all (unchanged behavior); a throw denies.
   const confirmServer = typeof opts.confirmServer === 'function' ? opts.confirmServer : null;
-  /** @param {string} name @param {ServerDef} def @returns {Promise<boolean>} */
-  const vetServer = async (name, def) => {
-    if (!confirmServer) return true;
-    try { return (await confirmServer(name, def)) === true; }
-    catch { return false; }
-  };
-
-  // Connecting to a server EXECUTES its `command`. The project-cwd `.mcp.json` is excluded from
-  // default discovery (see TRUSTED_CONFIG_PATHS / includeProjectConfig), so the untrusted-repo
-  // path is closed by default; this warning covers the residual case where home/IDE configs (or an
-  // explicit opt-in) contribute commands and no confirmServer hook is present to vet them.
-  // Warn ONCE per call, BEFORE the first spawn — and the first spawn is the
-  // discovery phase on a cold/refresh run, not the main-connect phase below.
-  let warnedUnvetted = false;
-  /** @param {Array<{name: string, command: string, args?: string[]}>} specs */
-  const warnUnvettedSpawn = (specs) => {
-    if (confirmServer || warnedUnvetted || specs.length === 0) return;
-    warnedUnvetted = true;
-    const cmds = specs.map(s => `${s.name} → ${s.command} ${(s.args || []).join(' ')}`.trim());
-    console.warn(
-      `[MCP Bridge] spawning ${specs.length} server command(s) without a confirmServer hook:\n  ` +
-      cmds.join('\n  ') +
-      `\n  Pass { confirmServer } to vet each command before it runs.`,
-    );
-  };
+  const vetServer = makeVetServer(confirmServer);
+  const warnUnvettedSpawn = makeUnvettedWarner(confirmServer);
+
+  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);
 
+  // Per-server connect failures from BOTH passes (discovery, then main), first message wins. `errors`
+  // is derived from this once, at return time: servers that did not end up connected, once each.
+  /** @type {Map<string, string>} */
+  const failures = new Map();
+  /** @param {string} name @param {unknown} err */
+  const noteFailure = (name, err) => {
+    if (failures.has(name)) return;
+    const message = err && typeof err === 'object' && 'message' in err && typeof err.message === 'string' ? err.message : String(err);
+    failures.set(name, message);
+  };
+  /** The one place `errors` is computed (and the failure warns issued). @param {string[]} connected */
+  const finalErrors = (connected) => {
+    const up = new Set(connected);
+    const errors = [...failures].filter(([name]) => !up.has(name)).map(([server, error]) => ({ server, error }));
+    if (errors.length > 0) console.warn('[MCP Bridge] Some servers failed to connect:', errors);
+    // Discovery failed but the cached definition connected: not an error, yet the config edit was not applied.
+    const cachedUsed = [...failures].filter(([name]) => up.has(name)).map(([server, error]) => ({ server, error }));
+    if (cachedUsed.length > 0) console.warn('[MCP Bridge] Discovery failed for server(s) that connected from the cached definition (config edit not applied):', cachedUsed);
+    return errors;
+  };
+  /** Early return: nothing connected. */
+  const nothingConnected = () => ({ tools: [], servers: [], systemContext: '', denied: [], errors: finalErrors([]), close: async () => {} });
+
   if (needsRefresh) {
     // Discover from IDE configs. The project-cwd `.mcp.json` is excluded by default (untrusted-repo
     // RCE vector); it is scanned only on explicit opt-in, or when a `confirmServer` hook is present
@@ -703,9 +958,7 @@ async function createMCPBridge(opts = {}) {
     const includeProjectConfig = opts.includeProjectConfig === true || !!confirmServer;
     const discovered = discoverServers(opts.configPaths, { includeProjectConfig });
 
-    if (discovered.size === 0 && !config) {
-      return { tools: [], servers: [], systemContext: '', denied: [], close: async () => {} };
-    }
+    if (discovered.size === 0 && !config) return nothingConnected();
 
     // Only attempt connection when discovery found something.
     // If discovered.size === 0 but config exists, fall through and use the existing config
@@ -715,9 +968,6 @@ async function createMCPBridge(opts = {}) {
       const freshTools = new Map();
       /** @type {Map<string, RpcClient>} */
       const connectResults = new Map();
-      /** @type {Array<{server: string, error: string}>} */
-      const errors = [];
-
       const reqServers = opts.servers;
       const toDiscover = reqServers
         ? [...discovered.entries()].filter(([n]) => reqServers.includes(n))
@@ -731,40 +981,39 @@ 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 });
+          noteFailure(name, err);
         }
       }));
 
-      if (errors.length > 0) {
-        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 nothingConnected();
+        }
 
-      // 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);
+        }
       }
     }
   }
 
   // At this point config is guaranteed non-null: it either existed, was just
   // written by the refresh branch, or we returned early above.
-  if (!config) {
-    return { tools: [], servers: [], systemContext: '', denied: [], close: async () => {} };
-  }
+  if (!config) return nothingConnected();
   /** @type {BridgeConfig} */
   const cfg = config;
 
@@ -774,9 +1023,7 @@ async function createMCPBridge(opts = {}) {
     ? reqServers2.filter(n => cfg.servers[n])
     : Object.keys(cfg.servers);
 
-  if (serverNames.length === 0) {
-    return { tools: [], servers: [], systemContext: '', denied: [], close: async () => {} };
-  }
+  if (serverNames.length === 0) return nothingConnected();
 
   // Warn before the main-connect spawn too. On a warm run (config exists, no
   // refresh) this is the first and only spawn; on a cold run the discovery phase
@@ -792,8 +1039,6 @@ async function createMCPBridge(opts = {}) {
   const connected = [];
   /** @type {DeniedTool[]} */
   const denied = [];
-  /** @type {Array<{server: string, error: string}>} */
-  const errors = [];
 
   await Promise.all(serverNames.map(async (name) => {
     const serverConf = cfg.servers[name];
@@ -808,13 +1053,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
@@ -824,14 +1070,10 @@ async function createMCPBridge(opts = {}) {
         }
       }
     } catch (err) {
-      errors.push({ server: name, error: err.message });
+      noteFailure(name, err);
     }
   }));
 
-  if (errors.length > 0) {
-    console.warn('[MCP Bridge] Some servers failed to connect:', errors);
-  }
-
   const systemContext = buildSystemContext(connected, tools, denied);
   if (connected.length > 0) console.log(systemContext);
 
@@ -843,11 +1085,99 @@ async function createMCPBridge(opts = {}) {
     servers: connected,
     denied,
     systemContext,
-    errors,
+    errors: finalErrors(connected),
     close: async () => {
       await Promise.all(children.map(killServer));
     },
   };
 }
 
-module.exports = { createMCPBridge, discoverServers, buildMetaTools };
+// --- listServerTools: one-shot read-only listing ---
+
+// Total-deadline multiplier for listServerTools. `timeout` bounds EACH round-trip; a server that
+// answers every page just under it could otherwise stretch a call to (1 + pages) × timeout. The one
+// total ceiling is 4 × timeout = initialize plus three further maximally-slow round-trips: a normal
+// server answers in milliseconds and a handful of pages never approaches it, while a server that
+// needs more than that is slow enough to treat as faulty. Derived, not a new option.
+const LIST_DEADLINE_MULTIPLIER = 4;
+
+/**
+ * @param {string} msg
+ * @returns {ValidationError}
+ */
+const listBad = (msg) => new ValidationError(`[MCP Bridge] listServerTools: ${msg}`, { context: { lib: 'bare-agent' } });
+
+/**
+ * List one configured MCP server's tools WITHOUT building a bridge: discover, vet, connect, list
+ * (following pagination), then always kill the child. Never reads or writes `.mcp-bridge.json`
+ * and prints nothing to stdout. `annotations` are the server's own HINTS, passed through unmodified
+ * (key absent when the server sent none) — never an authorization signal.
+ *
+ * Total wall-clock ceiling is DERIVED: 4 × `timeout` (initialize + three maximally slow pages) over
+ * the connect + list, excluding `confirmServer` (caller code, possibly interactive). On trip the
+ * child is killed and a TimeoutError naming the total deadline rejects. A SMALL `timeout` shrinks the
+ * total proportionally (timeout 500 ⇒ 2s total), so a server with many pages near that speed can trip it.
+ * A non-object `annotations` value from the server is treated as absent (dropped).
+ *
+ * @param {object} opts
+ * @param {string} opts.server - Server name as it appears in the discovered configs.
+ * @param {string[]} [opts.configPaths] - Explicit config paths; omitted ⇒ trusted $HOME/IDE defaults.
+ * @param {(name: string, def: ServerDef) => boolean | Promise<boolean>} [opts.confirmServer] - Same semantics as createMCPBridge: `=== true` proceeds, a throw denies. Implies includeProjectConfig.
+ * @param {boolean} [opts.includeProjectConfig=false] - Also scan `./.mcp.json` during default discovery.
+ * @param {number} [opts.timeout=15000] - Per-round-trip bound in ms (initialize and each tools/list page).
+ * @returns {Promise<Array<{name: string, description: string, annotations?: Record<string, any>}>>}
+ * @when you want to list one MCP server's tools and their annotation hints before deciding what to allow — no bridge, no cache file, no tools kept alive
+ * @fails throws (never returns []) when the server is not found, confirmServer declines or throws, the connect/handshake fails or times out, the total deadline trips, or the reply is malformed; the child is always reaped.
+ * @example
+ *   const tools = await listServerTools({ server: 'files', configPaths: [cfg] });
+ */
+async function listServerTools(opts) {
+  if (opts === null || typeof opts !== 'object' || Array.isArray(opts)) {
+    throw listBad(`opts must be an object (got ${typeName(opts)})`);
+  }
+  const { server, configPaths, confirmServer, includeProjectConfig, timeout = 15000 } = opts;
+  if (typeof server !== 'string' || server === '') {
+    throw listBad(`server must be a non-empty string (got ${server === '' ? 'empty string' : typeName(server)})`);
+  }
+  if (configPaths !== undefined) {
+    if (!Array.isArray(configPaths)) throw listBad(`configPaths must be an array of strings (got ${typeName(configPaths)})`);
+    for (const p of configPaths) {
+      if (typeof p !== 'string' || p === '') throw listBad(`configPaths entries must be non-empty strings (got ${p === '' ? 'empty string' : typeName(p)})`);
+    }
+  }
+  if (confirmServer !== undefined && typeof confirmServer !== 'function') {
+    throw listBad(`confirmServer must be a function (got ${typeName(confirmServer)})`);
+  }
+  if (typeof timeout !== 'number' || !Number.isFinite(timeout) || timeout <= 0) {
+    throw listBad(`timeout must be a positive finite number (got ${typeName(timeout)})`);
+  }
+
+  const confirm = typeof confirmServer === 'function' ? confirmServer : null;
+  const discovered = discoverServers(configPaths, { includeProjectConfig: includeProjectConfig === true || !!confirm });
+  const def = discovered.get(server);
+  if (!def) {
+    throw new ToolError(`MCP server "${server}" not found in discovered MCP configs`, { context: { server, notFound: true } });
+  }
+  makeUnvettedWarner(confirm)([{ name: server, command: def.command, args: def.args }]);
+  if (!(await makeVetServer(confirm)(server, def))) {
+    throw new ToolError(`MCP server "${server}" was not approved by confirmServer`, { context: { server, denied: true } });
+  }
+
+  const { mcpTools, client } = await connectAndListTools(server, def, timeout, { deadlineMs: timeout * LIST_DEADLINE_MULTIPLIER });
+  try {
+    return mcpTools.map(t => {
+      if (t === null || typeof t !== 'object' || typeof t.name !== 'string' || t.name === '') {
+        throw new ToolError(`MCP server "${server}" returned a malformed tools/list entry (no string name)`, { context: { server } });
+      }
+      return {
+        name: t.name,
+        description: t.description || '',
+        ...(hasAnnotations(t.annotations) && { annotations: t.annotations }),
+      };
+    });
+  } finally {
+    await killServer(client.child);
+  }
+}
+
+module.exports = { createMCPBridge, discoverServers, buildMetaTools, listServerTools };

package/src/mcp.d.ts

@@ -1,4 +1,5 @@
 import { createMCPBridge } from "./mcp-bridge";
 import { discoverServers } from "./mcp-bridge";
 import { buildMetaTools } from "./mcp-bridge";
-export { createMCPBridge, discoverServers, buildMetaTools };
+import { listServerTools } from "./mcp-bridge";
+export { createMCPBridge, discoverServers, buildMetaTools, listServerTools };

package/src/mcp.js

@@ -1,5 +1,5 @@
 'use strict';
 
-const { createMCPBridge, discoverServers, buildMetaTools } = require('./mcp-bridge');
+const { createMCPBridge, discoverServers, buildMetaTools, listServerTools } = require('./mcp-bridge');
 
-module.exports = { createMCPBridge, discoverServers, buildMetaTools };
+module.exports = { createMCPBridge, discoverServers, buildMetaTools, listServerTools };

package/types/index.d.ts

@@ -224,6 +224,8 @@ export interface ToolDef {
   name: string;
   description?: string;
   parameters?: Record<string, any>;
+  /** MCP tools only: the server's own behavioural hints (readOnlyHint, ...), passed through unmodified. Untrusted metadata, never an authorization signal. Absent when the server sent none; a non-object value from the server is treated as absent. */
+  annotations?: Record<string, any>;
   execute(args: any): any | Promise<any>;
 }