bare-agent 0.51.0 → 0.53.0

package/README.md

@@ -33,7 +33,7 @@ Some things an LLM can't judge about its own work. Building a harness or an exte
 
 ## Fast gut check — Jev
 
-An LLM call is slow, deliberate thinking (System 2). Jev, from TypeSafe, is the fast gut check (System 1): a classifier that returns a typed decision with a calibrated probability — roughly 200× faster and 400× cheaper than an LLM, per TypeSafe. bare-agent's `JevProvider` covers all three shapes — **yes/no**, **pick-one**, **score** — so your automation calls it like any other step: act when it's confident, escalate when it isn't. Injection-hardened by default; also usable as the `jev` check in the Evaluator.
+An LLM call is slow, deliberate thinking (System 2). Jev, from TypeSafe, is the fast gut check (System 1): a classifier that returns a typed decision with a calibrated probability — far faster and cheaper than an LLM call. bare-agent's `JevProvider` covers all three shapes — **yes/no**, **pick-one**, **score** — so your automation calls it like any other step: act when it's confident, escalate when it isn't. Injection-hardened by default; also usable as the `jev` check in the Evaluator.
 
 ## Break big tasks down — RLM
 

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.
@@ -513,11 +518,11 @@ new OpenAIProvider({ baseUrl: 'https://api.deepseek.com', model: 'deepseek-flash
 
 > **Fallback caveat:** per-call options (incl. `thinking`) are forwarded to EVERY provider in a `FallbackProvider` chain. For a mixed-vendor chain set `thinking` on each provider's constructor, not per-call.
 
-**Normalized `thinkingMode: 'on' | 'off'`.** Say "on"/"off"; bare-agent sends the right field for the provider/model (`AnthropicProvider`, `OpenAIProvider` incl. DeepSeek, `GeminiProvider`, `OllamaProvider`): constructor option, overridable per call (`generate(..., { thinkingMode })` / `loop.run(msgs, tools, { thinkingMode })`), `null` suppresses. It is a NEW field — the raw `thinking` option above is untouched, and setting both is a `ValidationError`. It tries the known request shapes (a 400 naming the field walks the ladder; the winner is cached), throws a `ValidationError` naming what it tried if every shape is rejected, and throws before sending when the model is measured as not switchable (`claude-opus-5-5` off, `gemini-3.1-pro-preview` off). Every reply is checked: `result.thinkingApplied` is `true` (accepted; for `'off'`, zero thinking seen), `false` (`'off'` sent but the model thought anyway — warns once, the result is kept), or `null` (cannot tell; e.g. OpenAI without `reasoning_tokens`). On `loop.run()` it is sticky-false: any round `false` ⇒ the run is `false`. Anthropic `'on'` + a non-default `temperature` (the API rejects it with thinking enabled): the temperature is dropped and retried once, `temperatureDropped: true`. `'on'` is never flagged (adaptive models may skip thinking). `thinkingSupport(provider, model)` from `bare-agent/providers` tells you, offline, what is known. DeepSeek `'on'` + a forced `toolChoice` is a `ValidationError`; CLIPipe has no mechanism and throws. Ollama's `think` is not live-verified.
+**Normalized `thinkingMode: 'on' | 'off'`.** Say "on"/"off"; bare-agent sends the right field for the provider/model (`AnthropicProvider`, `OpenAIProvider` incl. DeepSeek, `GeminiProvider`, `OllamaProvider`): constructor option, overridable per call (`generate(..., { thinkingMode })` / `loop.run(msgs, tools, { thinkingMode })`), `null` suppresses. It is a NEW field — the raw `thinking` option above is untouched, and setting both is a `ValidationError`. It tries the known request shapes (a client validation error — 400, or 422 — walks the ladder; the winning shape is cached) and **always runs the call** — callers need not care about providers. After the shapes, ONE plain request (no thinking field) decides: it succeeds ⇒ the setting was the problem and the result says `unsupported` (warns once); it fails too ⇒ a real error, thrown as the plain request's own (never a `ValidationError`). 5xx/429/timeouts/401/403/404 propagate at once with no ladder. A model measured as not switchable (`claude-opus-5-5` off, `gemini-3.1-pro-preview` off) goes out once WITHOUT a thinking field. "Unsupported" is never cached, so an unknown model that can't switch pays its refused shape requests on each call. Every reply carries `result.thinkingStatus`: `'applied'` (accepted; for `'off'`, zero thinking seen), `'unsupported'` (this provider/model can't do it — the call ran without our field), `'ignored'` (`'off'` accepted but the model thought anyway — warns once, result kept), or `'unknown'` (accepted, signal unreadable; e.g. OpenAI without `reasoning_tokens`). `result.thinkingApplied` is kept and derived (`true`/`false`/`false`/`null`). On `loop.run()` the WORST status across rounds wins (ignored > unsupported > unknown > applied). Still a `ValidationError`: a bad value, or raw `thinking` + `thinkingMode` together. Anthropic `'on'` + a non-default `temperature` (the API rejects it with thinking enabled): the temperature is dropped and retried once, `temperatureDropped: true`. `'on'` is never flagged (adaptive models may skip thinking). `thinkingSupport(provider, model, { baseUrl }?)` from `bare-agent/providers` (`baseUrl` makes an OpenAI-wire DeepSeek host answer with DeepSeek shapes, same detection as the request path) tells you, offline, what is known. DeepSeek `'on'` + a forced `toolChoice` can't think, so it is sent with `thinking:{type:'disabled'}` and reports `'unsupported'`; CLIPipe has no mechanism and runs unchanged, `'unsupported'`. In a `FallbackProvider` a not-switchable member just runs (no fall-through). Ollama's `think` is not live-verified.
 
 ```js
 const p = new AnthropicProvider({ apiKey, model: 'claude-sonnet-5', thinkingMode: 'off' });
-const r = await p.generate(msgs, [], {});            // r.thinkingApplied === true
+const r = await p.generate(msgs, [], {});            // r.thinkingStatus === 'applied' (r.thinkingApplied === true)
 await p.generate(msgs, [], { thinkingMode: 'on' });  // per-call override
 ```
 
@@ -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.51.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 });"
     },
     {
@@ -447,7 +447,7 @@
       "category": "providers",
       "when": "you need to know, before building a request, whether a provider/model can have thinking turned on or off and which request field does it — pure lookup, no network",
       "import": "import { thinkingSupport } from 'bare-agent/providers'",
-      "signature": "thinkingSupport(provider: 'anthropic'|'openai'|'deepseek'|'gemini'|'ollama'|'clipipe'|string, model?: string) => { switchable: boolean|'unverified', off: string|null, on: string|null, note: string }",
+      "signature": "thinkingSupport(provider: 'anthropic'|'openai'|'deepseek'|'gemini'|'ollama'|'clipipe'|string, model?: string, opts?: { baseUrl?: string }) => { switchable: boolean|'unverified', off: string|null, on: string|null, note: string }",
       "fails": "returns switchable:false for clipipe and unknown providers (never throws); 'unverified' means not measured, not unsupported; Ollama's shapes are not live-verified.",
       "example": "thinkingSupport('anthropic', 'claude-opus-5-5'); // { switchable: false, off: null, on: \"thinking:{type:'adaptive'}\", note: '...' }"
     },

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/loop.d.ts

@@ -167,7 +167,7 @@ export class Loop {
      *   thunk is re-evaluated each round (D4/eval-assist F2) so a tool set that grows mid-run — e.g. a skill
      *   unlocking its tools — is offered on the next round; a static array is resolved once at wire time.
      * @param {Record<string, any>} [options={}] - Per-run overrides (system, temperature, ctx, etc.).
-     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: GenerateResult['malformedToolCall'], temperatureDropped?: boolean, thinkingApplied?: boolean|null}>}
+     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: GenerateResult['malformedToolCall'], temperatureDropped?: boolean, thinkingApplied?: boolean|null, thinkingStatus?: 'applied'|'unsupported'|'ignored'|'unknown'}>}
      *   On halt the returned `error` is `halt:<rule>` (or `halt:unknown` if the
      *   thrown HaltError carried no `rule`), and `msgs` is sanitized so any
      *   dangling assistant `tool_calls` from the halted round are paired with
@@ -208,6 +208,7 @@ export class Loop {
         malformedToolCall?: GenerateResult["malformedToolCall"];
         temperatureDropped?: boolean;
         thinkingApplied?: boolean | null;
+        thinkingStatus?: "applied" | "unsupported" | "ignored" | "unknown";
     }>;
     _warnedTruncated: boolean | undefined;
     /**
@@ -236,7 +237,7 @@ export class Loop {
      * @param {string} text - User message.
      * @param {ToolDef[]} [tools=[]] - Tool definitions.
      * @param {Record<string, any>} [options={}] - Per-run overrides.
-     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: GenerateResult['malformedToolCall'], temperatureDropped?: boolean, thinkingApplied?: boolean|null}>}
+     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: GenerateResult['malformedToolCall'], temperatureDropped?: boolean, thinkingApplied?: boolean|null, thinkingStatus?: 'applied'|'unsupported'|'ignored'|'unknown'}>}
      */
     chat(text: string, tools?: ToolDef[], options?: Record<string, any>): Promise<{
         text: string;
@@ -251,6 +252,7 @@ export class Loop {
         malformedToolCall?: GenerateResult["malformedToolCall"];
         temperatureDropped?: boolean;
         thinkingApplied?: boolean | null;
+        thinkingStatus?: "applied" | "unsupported" | "ignored" | "unknown";
     }>;
     /**
      * Request a clean stop. The current tool call finishes; the loop then exits at the next boundary and

package/src/loop.js

@@ -2,6 +2,12 @@
 
 const { ToolError, HaltError } = require('./errors');
 const { classifyStopReason } = require('./provider-stop-reason');
+const { appliedOf } = require('./thinking-mode');
+
+// Worst-wins precedence for the run's `thinkingStatus`. Null-prototype so a provider-supplied
+// status string like 'constructor' cannot match an inherited key.
+/** @type {Record<string, number>} */
+const THINKING_STATUS_RANK = Object.assign(Object.create(null), { applied: 0, unknown: 1, unsupported: 2, ignored: 3 });
 
 /** @typedef {import('../types').Provider} Provider */
 /** @typedef {import('../types').Message} Message */
@@ -455,7 +461,7 @@ class Loop {
    *   thunk is re-evaluated each round (D4/eval-assist F2) so a tool set that grows mid-run — e.g. a skill
    *   unlocking its tools — is offered on the next round; a static array is resolved once at wire time.
    * @param {Record<string, any>} [options={}] - Per-run overrides (system, temperature, ctx, etc.).
-   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: GenerateResult['malformedToolCall'], temperatureDropped?: boolean, thinkingApplied?: boolean|null}>}
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: GenerateResult['malformedToolCall'], temperatureDropped?: boolean, thinkingApplied?: boolean|null, thinkingStatus?: 'applied'|'unsupported'|'ignored'|'unknown'}>}
    *   On halt the returned `error` is `halt:<rule>` (or `halt:unknown` if the
    *   thrown HaltError carried no `rule`), and `msgs` is sanitized so any
    *   dangling assistant `tool_calls` from the halted round are paired with
@@ -565,10 +571,12 @@ class Loop {
     // unsupported/deprecated) and retried without it. Surfaced on the result so an upstream receipt
     // (recurse's refineLeaf) can report the EFFECTIVE temperature rather than the ignored request.
     let temperatureDropped = false;
-    // Normalized thinkingMode (src/thinking-mode.js): the run's `thinkingApplied` verdict — sticky-false
-    // (any round false ⇒ false), else the latest round's true/null; undefined ⇒ the provider reported none (thinkingMode unset) ⇒ key absent.
-    /** @type {boolean|null|undefined} */
-    let lastThinkingApplied;
+    // Normalized thinkingMode (src/thinking-mode.js): the run's `thinkingStatus` is the WORST status across
+    // rounds (ignored > unsupported > unknown > applied); `thinkingApplied` is derived from it (applied⇒true,
+    // ignored/unsupported⇒false, unknown⇒null). undefined ⇒ no round carried either ⇒ both keys absent.
+    /** @type {'applied'|'unsupported'|'ignored'|'unknown'|undefined} */
+    let worstThinkingStatus;
+    const thinkingFields = () => worstThinkingStatus === undefined ? undefined : { thinkingStatus: worstThinkingStatus, thinkingApplied: appliedOf(worstThinkingStatus) };
     // BA-11: consecutive policy-deny counter (reset by any tool call that PASSES policy). When it reaches
     // this.maxConsecutiveDenials the run short-circuits cleanly — see the deny block below.
     let consecutiveDenials = 0;
@@ -601,7 +609,7 @@ class Loop {
         sealDanglingToolCalls(msgs, `[halted:${stuckTag}]`);
         this._reportError('stuck', new Error(`tool "${tc.name}" failed ${identicalErrors} times with identical arguments`), { rule: stuckTag, attempts: identicalErrors });
         this._safeEmit({ type: 'loop:done', data: { text: lastText, stuck: true, rule: stuckTag, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: stuckTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...(lastThinkingApplied !== undefined && { thinkingApplied: lastThinkingApplied }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: stuckTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...thinkingFields() };
       }
       return null;
     };
@@ -848,7 +856,7 @@ class Loop {
         this._reportError('provider', err, { round });
         if (this.throwOnError) throw err;
         // BA-5: a mid-run provider failure must not erase the work of the rounds that succeeded.
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...(lastThinkingApplied !== undefined && { thinkingApplied: lastThinkingApplied }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...thinkingFields() };
       }
 
       lastUsage = result.usage || lastUsage;
@@ -865,10 +873,12 @@ class Loop {
       lastMalformedToolCall = (result.malformedToolCall && typeof result.malformedToolCall === 'object')
         ? result.malformedToolCall : null;
       if (result.temperatureDropped) temperatureDropped = true;
-      // Sticky-false: once ANY round reports false (thinking happened despite 'off'), the run stays false;
-      // otherwise the latest round's true/null wins; a round without the field leaves it untouched.
-      if (result.thinkingApplied === true || result.thinkingApplied === false || result.thinkingApplied === null) {
-        if (lastThinkingApplied !== false) lastThinkingApplied = result.thinkingApplied;
+      // Worst-status-wins across rounds; a round carrying only the legacy `thinkingApplied` (a custom provider)
+      // is mapped true→applied, false→ignored, null→unknown.
+      {
+        const st = THINKING_STATUS_RANK[result.thinkingStatus] !== undefined ? result.thinkingStatus
+          : result.thinkingApplied === true ? 'applied' : result.thinkingApplied === false ? 'ignored' : result.thinkingApplied === null ? 'unknown' : undefined;
+        if (st !== undefined && (worstThinkingStatus === undefined || THINKING_STATUS_RANK[st] > THINKING_STATUS_RANK[worstThinkingStatus])) worstThinkingStatus = st;
       }
       // Publish the latest measured usage to ctx (non-enumerable, fail-open) so a transcript-bound seam —
       // e.g. F2 stash auto-compaction — can read EXACT provider-counted `inputTokens` to gauge context
@@ -953,7 +963,7 @@ class Loop {
         sealDanglingToolCalls(msgs, `[halted:${session.error}]`);
         this._reportError('session', new Error(`provider session terminated: ${session.error}`), { rule: session.error, sessionTurns: session.turns ?? null });
         this._safeEmit({ type: 'loop:done', data: { text: lastText, rule: session.error, sessionTurns: session.turns ?? null, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: session.error, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...(lastThinkingApplied !== undefined && { thinkingApplied: lastThinkingApplied }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: session.error, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...thinkingFields() };
       }
 
       // BA-13: classify this round's terminal signal against the neutral stop-reason vocabulary. BA-6
@@ -1018,7 +1028,7 @@ class Loop {
           msgs.push({ role: 'assistant', content: result.text });
         }
         this._safeEmit({ type: 'loop:done', data: { text: lastText, ...(terminal === 'truncated' && { truncated: true }), terminal, stopReason: lastStopReason, droppedToolCalls: dropped, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: errorTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...(lastThinkingApplied !== undefined && { thinkingApplied: lastThinkingApplied }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: errorTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...thinkingFields() };
       }
 
       // No tool calls — LLM gave a final text response
@@ -1038,7 +1048,7 @@ class Loop {
           try { await flush(msgs, ctx); }
           catch (err) { if (err instanceof HaltError) throw err; this._reportError('trim-flush', err, { round }); }
         }
-        return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...(lastThinkingApplied !== undefined && { thinkingApplied: lastThinkingApplied }) };
+        return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...thinkingFields() };
       }
 
       // Execute tool calls
@@ -1147,7 +1157,7 @@ class Loop {
               sealDanglingToolCalls(msgs, `[halted:${denyTag}]`);
               this._reportError('denied', new Error(`policy denied ${consecutiveDenials} consecutive tool calls (${tc.name})`), { rule: denyTag, denials: consecutiveDenials });
               this._safeEmit({ type: 'loop:done', data: { text: lastText, denied: true, rule: denyTag, cost: totalCost } });
-              return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: denyTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...(lastThinkingApplied !== undefined && { thinkingApplied: lastThinkingApplied }) };
+              return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: denyTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...thinkingFields() };
             }
             continue;
           }
@@ -1221,7 +1231,7 @@ class Loop {
         // BA-5: the rule tag survives on `error`; so does the work. A halt is how a bounded attempt is
         // SUPPOSED to end — the caller reads `error` to know it was bounded and `text` to learn from it.
         this._safeEmit({ type: 'loop:done', data: { text: lastText, halted: true, rule, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...(lastThinkingApplied !== undefined && { thinkingApplied: lastThinkingApplied }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...thinkingFields() };
       }
       throw err;
     }
@@ -1251,20 +1261,20 @@ class Loop {
             const rule = err.rule || 'unknown';
             this._reportError('halt', err, { rule, reason: err.decision?.reason ?? null });
             this._safeEmit({ type: 'loop:done', data: { text: lastText, halted: true, rule, cost: totalCost } });
-            return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...(lastThinkingApplied !== undefined && { thinkingApplied: lastThinkingApplied }) };
+            return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...thinkingFields() };
           }
           this._reportError('trim-flush', err, { phase: 'stop' });
         }
       }
       this._safeEmit({ type: 'loop:done', data: { text: lastText, stopped: true, cost: totalCost } });
-      return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...(lastThinkingApplied !== undefined && { thinkingApplied: lastThinkingApplied }) };
+      return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...thinkingFields() };
     }
 
     // Hard safety limit — should never fire under normal usage; bareguard's
     // limits.maxTurns (or the LLM's natural completion) ends the loop first.
     const warning = `[Loop] hit internal safety limit of ${HARD_ROUND_LIMIT} rounds. Wire bareguard for proper governance — see bare-agent/bareguard.`;
     this._safeEmit({ type: 'loop:done', data: { text: lastText, warning, cost: totalCost } });
-    return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: warning, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...(lastThinkingApplied !== undefined && { thinkingApplied: lastThinkingApplied }) };
+    return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: warning, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }), ...thinkingFields() };
   }
 
   /**
@@ -1337,7 +1347,7 @@ class Loop {
    * @param {string} text - User message.
    * @param {ToolDef[]} [tools=[]] - Tool definitions.
    * @param {Record<string, any>} [options={}] - Per-run overrides.
-   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: GenerateResult['malformedToolCall'], temperatureDropped?: boolean, thinkingApplied?: boolean|null}>}
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: GenerateResult['malformedToolCall'], temperatureDropped?: boolean, thinkingApplied?: boolean|null, thinkingStatus?: 'applied'|'unsupported'|'ignored'|'unknown'}>}
    */
   async chat(text, tools = [], options = {}) {
     this._history.push({ role: 'user', content: text });

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[];